mcp2term

An implementation of a Model Context Protocol (MCP) server that grants safe, auditable access to a system shell. The server streams stdout and stderr in real time while capturing rich metadata for plugins and downstream consumers.

Features

• Full command execution with configurable shell, working directory, environment variables, and timeouts.

• Live streaming of stdout and stderr via MCP log notifications so clients observe progress as it happens.

• Robust chunked streaming that handles large stdout/stderr volumes without blocking or truncation.

• Plugin architecture that exposes every function, class, and variable defined in the package, enabling extensions to observe command lifecycles or inject custom behaviour.

• Remote file management tools allowing safe file creation, printing, line-range replacement, exact line lookups, and unified diff patching via the manage_file tool and filetool client command.

• Automatic ngrok tunneling so HTTP transports are reachable without additional manual setup.

• Typed lifespan context shared with MCP tools for dependency access and lifecycle management.

• Structured tool responses including timing information to make results easy for agents to consume.

• Console mirroring so operators always see the command stream, stdout, and stderr on the hosting terminal by default.

• Automatic launch-directory export that prepends the directory the server was started from to PYTHONPATH so Python tooling invoked through run_command can immediately resolve local packages.

Installation

The project targets Python 3.12 or newer.

Configuration

ServerConfig reads settings from environment variables:

Running the server

Change --transport to sse or streamable-http to use the corresponding MCP transports. --log-level controls verbosity and --mount-path overrides the HTTP mount location when relevant.

While the server is running it mirrors every executed command, stdout chunk, and stderr chunk to the hosting console. Set MCP2TERM_CONSOLE_ECHO=false to suppress the mirroring when embedding the server into log-sensitive environments.

When running with the streamable-http transport the MCP endpoint is served from the /mcp path (or --mount-path plus /mcp when a custom mount is provided). The CLI prints the fully qualified URL, including the /mcp suffix, to make tunnelling targets such as ngrok easy to copy.

MCP tools

The server exposes two tools for remote command management:

run_command(command: str, working_directory: Optional[str], environment: Optional[dict[str, str]], timeout: Optional[float]], command_id: Optional[str])

The tool returns structured JSON containing:

• command_id: unique identifier assigned to the invocation

• command: executed command string

• working_directory: resolved working directory

• return_code: process exit code (non-zero for failure)

• stdout / stderr: aggregated output

• started_at / finished_at: ISO 8601 timestamps

• duration: execution duration in seconds

• timed_out: boolean flag indicating whether a timeout occurred

While a command runs the server emits stdout and stderr chunks as MCP log messages, preserving ordering through asynchronous streaming. Clients can reuse command_id values when making follow-up requests.

cancel_command(command_id: str, signal_value: Optional[str | int])

Sending cancel_command forwards a signal (defaulting to SIGINT) to the running process identified by command_id. The response includes the numeric signal, its symbolic signal_name, and a delivered flag confirming whether the process was still active when the signal was sent.

send_stdin(command_id: str, data: Optional[str], eof: bool = False)

Use send_stdin to stream additional input to an interactive command. The tool accepts optional text payloads and an eof flag that closes the stdin pipe once all required data has been delivered. The response reports whether the input was accepted so clients can retry or surface helpful diagnostics.

manage_file(path: str, *, operation: str, content: Optional[str] = None, pattern: Optional[str] = None, line: Optional[int] = None, start_line: Optional[int] = None, end_line: Optional[int] = None, encoding: str = "utf-8", create_parents: bool = False, overwrite: bool = False, create_if_missing: bool = True, escape_profile: str = "auto", follow_symlinks: bool = True, use_regex: bool = False, ignore_case: bool = False, max_replacements: Optional[int] = None, anchor: Optional[str] = None, anchor_use_regex: bool = False, anchor_ignore_case: bool = False, anchor_after: bool = False, anchor_occurrence: Optional[int] = None)

manage_file powers the filetool client command and exposes a broad suite of line-aware editing operations. The escape_profile parameter controls how inline --content payloads are normalised before they reach the server:

• auto (default) mirrors the original behaviour and expands \n, \t, \r, and \0 sequences when the payload would otherwise be a single line.

• none disables all inline decoding so payloads arrive exactly as typed, perfect for binary-friendly workflows or when backslashes carry semantic meaning.

• Additional profiles can be registered by extensions to enforce organisation-specific escaping rules. The selected profile is forwarded to plugins via the FileOperationEvent payload so observability tooling can respond appropriately.

Recent updates add top-of-file editing and pattern-driven substitutions to the toolbox:

• prepend injects content at the start of a file and respects --create-if-missing so you can bootstrap brand new files with headers in a single command.

• insert now accepts literal or regex anchors via --anchor, --anchor-after, --anchor-ignore-case, and --anchor-occurrence, making it easy to land changes relative to sentinel text without counting lines.

• substitute --pattern PATTERN --content TEXT performs literal or regex-based replacements while streaming structured metadata (matched pattern, replacement counts, and flags such as --ignore-case or --max-replacements) back to the caller.

Example usages:

Plugins

Plugins implement the PluginProtocol (via a module-level PLUGIN object) and can register CommandStreamListener instances to observe command lifecycle events. When the server starts it loads modules listed in MCP2TERM_PLUGINS, exposing the entire mcp2term namespace through the plugin registry for inspection or extension.

A minimal plugin skeleton:

Listeners registered through register_file_operation_listener receive FileOperationEvent instances containing the original request arguments, the resolved path, the FileOperationResult, and any warning emitted during processing. This makes it straightforward to build auditing, notification, or synchronization plugins that react to remote edits in real time without modifying the core server.

Development

Run the test suite with:

Tests are parameterised to run with or without dependency stubbing, ensuring full execution paths remain verified.

Ngrok integration

By default mcp2term opens an ngrok tunnel whenever you run the server with the sse or streamable-http transports. The tunnel exposes the local HTTP endpoint using the ngrok agent that must already be authenticated (for example via ngrok config add-authtoken). Unless overridden, the server now requests the reserved domain alpaca-model-easily.ngrok-free.app so clients always receive a predictable hostname.

Control the integration with the following environment variables:

Use the --disable-ngrok flag when running mcp2term to opt out of tunneling for a single invocation. The configuration also records the directory where the server process was launched and exports it to PYTHONPATH. This mirrors running export PYTHONPATH=$(pwd) before starting the server so that any Python code executed via run_command inherits the same module search path even when the working directory is overridden.