process-runner-mcp

# process-runner-mcp An MCP server for managing long-running development processes. Start, stop, restart, and monitor shell processes (e.g. `npm run dev`, `cargo watch`) from an AI assistant via the [Model Context Protocol](https://modelcontextprotocol.io) — so the assistant remembers the processes it starts and can check in on them at any time. ## Features - **5 MCP tools**: `start_process`, `stop_process`, `restart_process`, `list_processes`, `read_logs` - **Web UI**: browser-based log viewer with live streaming at `http://localhost:3834` - **CLI**: `list`, `logs` (with `--follow`), and `stop` subcommands - **Session recovery**: re-adopts still-running processes after a server restart - **Safe process teardown**: kills the entire process group tree, not just the parent PID - **Durable log storage**: in-memory ring buffer + per-process log files + SQLite ## Installation ```bash cargo install --path . ``` Or build manually: ```bash cargo build --release # binary at: ./target/release/process-runner-mcp ``` ## MCP Client Setup The server communicates over stdio (JSON-RPC). Register it with your AI client: **OpenCode** (`~/.config/opencode/config.json`): ```json { "mcp": { "process-runner": { "type": "local", "command": "process-runner-mcp", "args": [] } } } ``` **Claude Desktop** (`claude_desktop_config.json`): ```json { "mcpServers": { "process-runner": { "command": "process-runner-mcp", "args": [] } } } ``` ## CLI Usage These subcommands connect to a running server instance: ```bash # List all managed processes process-runner-mcp list # Show last 100 log lines for a process process-runner-mcp logs <name> # Show last N lines process-runner-mcp logs <name> -n 50 # Follow live log output (like tail -f) process-runner-mcp logs <name> --follow # Stop a process process-runner-mcp stop <name> ``` ## Web UI While the server is running, open `http://localhost:3834` for a browser-based log viewer with live SSE streaming. ## Configuration | Option | Flag | Environment variable | Default | |---|---|---|---| | HTTP port | `--port <PORT>` | `PROCESS_RUNNER_PORT` | `3834` | ```bash process-runner-mcp serve --port 4000 # or PROCESS_RUNNER_PORT=4000 process-runner-mcp ``` ## Runtime Data All runtime data is stored under `$XDG_RUNTIME_DIR/process-runner-mcp/` (falls back to `/tmp/process-runner-mcp/`): ``` process-runner-mcp/ ├── server.json # port + PID (used by CLI for discovery) ├── server.log # server diagnostic log ├── process-runner.db # SQLite database (WAL mode) └── logs/ └── <process-name>/ ├── stdout.log └── stderr.log ```