Crate par_term_mcp

Expand description

Minimal MCP (Model Context Protocol) server over stdio.

Reads line-delimited JSON-RPC 2.0 from stdin and writes responses to stdout. Exposes tools for par-term ACP integrations:

config_update: writes configuration changes to a file for the main app to pick up
terminal_screenshot: requests a live terminal screenshot from the app via a file-based IPC handshake (with an optional fallback image path for non-GUI test harnesses)
shader_diagnostics: requests live shader state and last compile/reload errors from the running app via file-based IPC

§Module layout

jsonrpc — JSON-RPC 2.0 wire types, response helpers, and stdout framing
ipc — IPC path resolution, atomic writes, and restricted-permission helpers
tools — tool registration, descriptors, and dispatch
tools::config_update — config_update tool handler
tools::screenshot — terminal_screenshot tool handler
tools::diagnostics — shader_diagnostics tool handler

§SEC-008: Trust Boundary — stdin/stdout IPC Channel

This MCP server communicates over stdin and stdout using JSON-RPC 2.0. There is no authentication, encryption, or integrity verification on this IPC channel. Any process that can write to the MCP server’s stdin can invoke any tool (including config_update, which writes to the user’s configuration file on disk).

The stdin/stdout channel is a trust boundary. Only trusted MCP client processes (i.e., ACP agents that par-term itself has spawned) should be connected to this server. The caller is responsible for ensuring that:

The MCP server process is only spawned by par-term’s ACP subsystem.
The stdin pipe is not shared with or writable by untrusted processes.
Agent TOML files (which define which agents are launched) are treated as a trust boundary — only install agents from sources you trust.

The file-based IPC paths used for screenshot and diagnostics requests use restrictive permissions (0o600) to prevent unauthorized reads or writes, but the stdin/stdout channel itself has no such protection.

Re-exports§

pub use ipc::screenshot_request_path;
pub use ipc::screenshot_response_path;
pub use ipc::shader_diagnostics_request_path;
pub use ipc::shader_diagnostics_response_path;

Modules§

ipc: IPC file path resolution and file helpers.
jsonrpc: JSON-RPC 2.0 wire types and response helpers.
tools: Tool registration, descriptors, and dispatch for the MCP server.

Structs§

ShaderDiagnostics: Live shader diagnostics returned by the GUI app.
ShaderDiagnosticsEntry: Per-shader diagnostics included in ShaderDiagnosticsResponse.
ShaderDiagnosticsRequest: Shader diagnostics request written by the MCP server for the GUI app to fulfill.
ShaderDiagnosticsResponse: Shader diagnostics response written by the GUI app for the MCP server to read.
TerminalScreenshotRequest: Screenshot request written by the MCP server for the GUI app to fulfill.
TerminalScreenshotResponse: Screenshot response written by the GUI app for the MCP server to read.

Constants§

CONFIG_UPDATE_FILENAME: Default config update filename (relative to config dir).
CONFIG_UPDATE_PATH_ENV: Environment variable for overriding the config update file path.
SCREENSHOT_FALLBACK_PATH_ENV: Optional environment variable for a static fallback screenshot file path. Used by the ACP harness to test the screenshot tool flow without a GUI.
SCREENSHOT_REQUEST_FILENAME: Default screenshot request filename (relative to config dir).
SCREENSHOT_REQUEST_PATH_ENV: Environment variable for screenshot request IPC file path.
SCREENSHOT_RESPONSE_FILENAME: Default screenshot response filename (relative to config dir).
SCREENSHOT_RESPONSE_PATH_ENV: Environment variable for screenshot response IPC file path.
SHADER_DIAGNOSTICS_REQUEST_FILENAME: Default shader diagnostics request filename (relative to config dir).
SHADER_DIAGNOSTICS_REQUEST_PATH_ENV: Environment variable for shader diagnostics request IPC file path.
SHADER_DIAGNOSTICS_RESPONSE_FILENAME: Default shader diagnostics response filename (relative to config dir).
SHADER_DIAGNOSTICS_RESPONSE_PATH_ENV: Environment variable for shader diagnostics response IPC file path.

Functions§

run_mcp_server: Run the MCP server loop. Reads JSON-RPC messages from stdin until the stream is closed or an I/O error occurs, then returns normally so that callers can run destructors and exit cleanly.
set_app_version: Set the application version (should be called from the main crate with the root crate’s VERSION constant before running the MCP server).