# 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

```bash
pip install -e .
```

The project targets Python 3.12 or newer.

## Configuration

`ServerConfig` reads settings from environment variables:

| Variable | Description | Default |
| --- | --- | --- |
| `MCP2TERM_SHELL` | Shell executable used for commands. | `/bin/bash` |
| `MCP2TERM_WORKDIR` | Working directory for commands. | Current directory |
| `MCP2TERM_INHERIT_ENV` | When `true`, inherit the parent environment. | `true` |
| `MCP2TERM_EXTRA_ENV` | JSON object merged into the command environment. | `{}` |
| `MCP2TERM_PLUGINS` | Comma-separated dotted module paths to load as plugins. | *(none)* |
| `MCP2TERM_COMMAND_TIMEOUT` | Default timeout in seconds for commands. | unlimited |
| `MCP2TERM_STREAM_CHUNK_SIZE` | Bytes read from stdout/stderr per chunk while streaming. | `65536` |
| `MCP2TERM_LONG_COMMAND_NOTICE_DELAY` | Seconds to wait before emitting long-running command notices. | `2.0` |
| `MCP2TERM_LONG_COMMAND_NOTICE_INTERVAL` | Interval in seconds between long-running command notices. | `5.0` |
| `MCP2TERM_CONSOLE_ECHO` | Mirror commands and output to the server console (`true`/`false`). | `true` |
| `MCP2TERM_CHAT_TERMINAL` | Set to `disabled` to suppress the console-integrated messaging bridge. Legacy values are accepted but ignored. | *(unused)* |

## Running the server

```bash
mcp2term --transport stdio
```

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:

```bash
# Create a multi-line file from a single-shell command using the default profile.
filetool write docs/roadmap.txt --content 'phase-one\\nphase-two\\nphase-three'

# Append literal escape sequences without rewriting them by selecting the "none" profile.
filetool append docs/roadmap.txt --content 'literal\\nvalue' --escape-profile none

# Use stdin for bulk updates while still labelling the request for plugins.
cat release.diff | filetool patch docs/roadmap.txt --stdin --escape-profile auto
```

## 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:

```python
from dataclasses import dataclass

from mcp2term.plugin import CommandStreamListener, PluginProtocol, PluginRegistry

@dataclass
class EchoListener(CommandStreamListener):
    async def on_command_stdout(self, event):
        print(event.data, end="")

    async def on_command_start(self, event):
        print(f"Starting: {event.request.command}")

    async def on_command_stderr(self, event):
        print(f"[stderr] {event.data}", end="")

    async def on_command_complete(self, event):
        print(f"Finished with {event.return_code}")


class ShellEchoPlugin(PluginProtocol):
    name = "shell-echo"
    version = "1.0.0"

    def activate(self, registry: PluginRegistry):
        registry.register_command_listener(EchoListener())

        class AuditListener:
            async def on_file_operation(self, event):
                print(f"{event.operation} {event.path}: {event.result.message}")

        registry.register_file_operation_listener(AuditListener())


PLUGIN = ShellEchoPlugin()
```

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:

```bash
pytest
```

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:

| Variable | Description | Default |
| --- | --- | --- |
| `MCP2TERM_NGROK_ENABLE` | Enable or disable automatic tunnel creation. | `true` |
| `MCP2TERM_NGROK_TRANSPORTS` | Comma-separated transports that should be tunnelled (`stdio`, `sse`, `streamable-http`). | `sse,streamable-http` |
| `MCP2TERM_NGROK_BIN` | Path to the `ngrok` executable. | `ngrok` |
| `MCP2TERM_NGROK_API_URL` | Base URL for the local ngrok API. | `http://127.0.0.1:4040` |
| `MCP2TERM_NGROK_REGION` | Optional ngrok region to target. | *(none)* |
| `MCP2TERM_NGROK_LOG_LEVEL` | ngrok log level (`debug`, `info`, `warn`, `error`). | `info` |
| `MCP2TERM_NGROK_EXTRA_ARGS` | JSON array of additional CLI arguments passed to ngrok. | `[]` |
| `MCP2TERM_NGROK_ENV` | JSON object merged into the ngrok process environment. | `{}` |
| `MCP2TERM_NGROK_START_TIMEOUT` | Seconds to wait for tunnel provisioning. | `15` |
| `MCP2TERM_NGROK_POLL_INTERVAL` | Seconds between tunnel status checks. | `0.5` |
| `MCP2TERM_NGROK_REQUEST_TIMEOUT` | HTTP timeout for API calls. | `5` |
| `MCP2TERM_NGROK_SHUTDOWN_TIMEOUT` | Seconds to wait for ngrok to terminate gracefully. | `5` |
| `MCP2TERM_NGROK_CONFIG` | Optional path to an ngrok configuration file. | *(none)* |
| `MCP2TERM_NGROK_HOSTNAME` / `MCP2TERM_NGROK_DOMAIN` / `MCP2TERM_NGROK_EDGE` | Custom host bindings to request from ngrok. | `alpaca-model-easily.ngrok-free.app` for domain |

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.