终端管理服务

{
	"terminalId": "[mcp] bright-otter",
	"cwd": "/Users/me",
	"created": true,
	"hint": "Use terminal_send to run commands, then terminal_read to fetch output.",
	"next": ["terminal_send", "terminal_read", "terminal_list"]
}

{
	"terminalId": "[mcp] bright-otter",
	"status": "created",
	"cwd": "/Users/me",
	"hint": "Use terminal_read to fetch output.",
	"next": ["terminal_read", "terminal_clear", "terminal_interrupt"]
}

{
	"terminalId": "[mcp] bright-otter",
	"status": "sent",
	"bytes": 15,
	"hint": "Call terminal_read to view buffered output."
}

{
	"output": "HELLO_WORLD\n",
	"lines": 1,
	"terminalId": "[mcp] bright-otter",
	"empty": false,
	"hint": "Use lines parameter to tail recent output."
}

{
	"output": "",
	"lines": 0,
	"terminalId": "[mcp] bright-otter",
	"empty": true,
	"hint": "Buffer empty. Use terminal_send to execute a command."
}

{
	"error": "text required",
	"hint": "Provide shell input in the \"text\" parameter."
}

// Example payload
{
	"terminalId": "[mcp] bright-otter",
	"since_ts": "2025-09-28T12:34:56.789Z",
	"limit": 100,
	"types": ["cmd", "stdout"]
}

{
	"events": [
		{"terminalId": "[mcp] bright-otter", "type": "cmd", "text": "echo hi", "ts": "..."},
		{"terminalId": "[mcp] bright-otter", "type": "stdout", "text": "hi\n", "ts": "..."}
	],
	"count": 2
}

{
	"terminalId": "[mcp] bright-otter",
	"disposed": true,
	"exitCode": 0
}

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

python server.py

# Run smoke test (basic functionality)
python test_smoke.py

# Run comprehensive test suite
python -m pytest test_terminal.py -v

# Run all tests
python -m pytest -v

# payload example sent to the MCP server
payload = {"name": "repo-pty", "cwd": "/path/to/repo"}
# server returns: {"terminalId": "repo-pty", "cwd": "/path/to/repo"}

# calling terminal_send with only text
# returns: {"terminalId": "mcp-terminal-...,", "status": "created", "cwd": "/home/user"}

# terminal_read(terminalId, {"strip_ansi": True, "lines": 200})

{
	"servers": {
		"terminal-mcp": {
			"command": "/path/to/your/venv/bin/python",
			"args": ["/path/to/terminal-mcp-server/server.py"],
			"type": "stdio",
			"description": "MCP stdio server exposing terminal commands",
			"dev": { "watch": "/path/to/terminal-mcp-server/app/**/*.py" }
		}
	}
}

## Adding This Server To `mcp.json` (Expanded Guide)

Below are several common configuration patterns you can paste into your client-side `mcp.json` (used by MCP Inspector, compatible agents, or orchestration layers). Adjust paths to match your system.

### 1. Local Clone + Virtualenv (Recommended for Development)
Clone the repository and create a virtual environment in the project root:

```bash
git clone https://github.com/your-org/terminal-mcp-server.git
cd terminal-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Then point `mcp.json` at the python executable and `server.py`:

```jsonc
{
	"servers": {
		"terminal-mcp": {
			"command": "/absolute/path/to/terminal-mcp-server/.venv/bin/python",
			"args": ["/absolute/path/to/terminal-mcp-server/server.py"],
			"type": "stdio",
			"description": "Local terminal management MCP server (dev virtualenv)",
			"dev": { "watch": "/absolute/path/to/terminal-mcp-server/app/**/*.py" }
		}
	}
}
```

Tip: Run `pwd` inside the repo to copy the absolute path; then append `/.venv/bin/python` and `/server.py` accordingly.

### 2. Editable Install in a Shared Environment
If this repo is part of a monorepo or shared dev environment you may prefer an editable install:

```bash
pip install -e /absolute/path/to/terminal-mcp-server
```

Then you can invoke using module-style execution (optional). Update `mcp.json`:

```jsonc
{
	"servers": {
		"terminal-mcp": {
			"command": "/path/to/python",
			"args": ["/absolute/path/to/terminal-mcp-server/server.py"],
			"type": "stdio",
			"description": "Terminal MCP (editable install)"
		}
	}
}
```

### 3. Windows (PowerShell) Example
Paths differ and the virtualenv python lives under `Scripts`:

```jsonc
{
	"servers": {
		"terminal-mcp": {
			"command": "C:/path/to/terminal-mcp-server/.venv/Scripts/python.exe",
			"args": ["C:/path/to/terminal-mcp-server/server.py"],
			"type": "stdio",
			"description": "Terminal MCP on Windows"
		}
	}
}
```

### 4. Using `uv` (Fast Python Installer)
If you prefer `uv` for environment management (https://github.com/astral-sh/uv):

```bash
uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt
```

Then the `mcp.json` is the same as (1) – just ensure you still reference the venv Python path.

### 5. Multiple Terminal Servers (Namespacing)
You can register more than one server (e.g. one for local machine and one for a remote wrapper) by adding multiple entries under `servers`:

```jsonc
{
	"servers": {
		"terminal-local": { "command": "/local/venv/bin/python", "args": ["/local/terminal-mcp/server.py"], "type": "stdio" },
		"terminal-alt":   { "command": "/alt/venv/bin/python",   "args": ["/alt/terminal-mcp/server.py"],   "type": "stdio" }
	}
}
```

### 6. Environment Variables (Optional)
You can influence runtime behavior via environment variables in future expansions or by wrapping the command. For event log control today:

| Variable | Purpose | Default |
|----------|---------|---------|
| `TERMINAL_MCP_EVENT_LOG_ENABLED` | Enable/disable persistent event log | `1` |
| `TERMINAL_MCP_EVENT_DIR` | Custom directory for the event log | `.terminal-mcp/` under repo |
| `TERMINAL_MCP_EVENT_LOG` | Override full path to event log file | `<EVENT_DIR>/events.log` |

If your MCP host supports per-server environment injection you may extend the `servers.terminal-mcp` object with an `env` field (syntax depends on the host). Example (conceptual):

```jsonc
{
	"servers": {
		"terminal-mcp": {
			"command": "/venv/bin/python",
			"args": ["/repo/server.py"],
			"type": "stdio",
			"env": {
				"TERMINAL_MCP_EVENT_LOG_ENABLED": "0"
			}
		}
	}
}
```

### 7. Verifying Setup
After editing `mcp.json`, restart your MCP-enabled client / inspector and look for a server named "terminal-mcp" (or the name you chose). List tools; you should see:

```
terminal_create, terminal_send, runCommand, terminal_read, terminal_interrupt, terminal_clear, terminal_dispose, terminal_list, terminal_events
```

Run a quick sanity cycle:
1. Call `terminal_create` (optionally with `{ "payload": { "verbose": true } }`).
2. Call `terminal_send` with a simple command (e.g. `echo hello`).
3. Call `terminal_read` to confirm output buffering.
4. Poll `terminal_events` to observe `create`, `cmd`, and `stdout` entries.
5. Call `terminal_dispose` (verbose) to verify `exitCode` appears.

### 8. Troubleshooting
| Symptom | Likely Cause | Fix |
|---------|--------------|-----|
| No tools appear | Wrong path to python or server file | Verify absolute paths in `command` and `args` |
| Empty output after send | Command still running / buffering | Add a short sleep then `terminal_read`; or run simpler command |
| Missing events | Pagination cursor set too high | Remove `after` or lower it; check `oldestSeq/newestSeq` in response |
| Permission error launching | CWD or python not accessible | Use a directory you own; ensure executable bit | 

If issues persist, run the server manually (`python server.py`) and observe stderr/stdout for import or runtime errors.

---

This section aims to make integration copy/paste friendly. If you use a different MCP host that requires a slightly different schema, adapt the key names but keep the `command`, `args`, and `type: stdio` trio intact.