mcp_backgroundr by drhurd - MCP Server

Background Task MCP Server

This project exposes a Model Context Protocol (MCP) server that lets MCP‑aware clients launch, monitor, and terminate long‑lived shell commands. It is a handy way to keep language servers or other developer tools running in the background from within an AI assistant or any other MCP client.

Prerequisites

Rust toolchain (1.80+ recommended).
Whatever background tools you plan to start, e.g.:
- Python: install a language server such as pyright-langserver (npm install -g pyright) or pylsp (pip install "python-lsp-server[all]").
- Rust: make sure rust-analyzer is available (rustup component add rust-analyzer).

Building and Running the MCP Server

cargo build --release
./target/release/mcp_backgroundr

Alternatively, run it directly without a separate build step:

cargo run --release

The server speaks MCP over stdio, so keep the process running and connect to it from your MCP client of choice (for example, npx @modelcontextprotocol/client-cli --stdio).

Available Tools

Tool name	Purpose
`run_background_task`	Launches a shell command and starts capturing stdout/stderr.
`get_task_status`	Returns the command, lifecycle state, exit code, and recent output.
`end_background_task`	Requests that a running task be terminated.

Output is truncated to the most recent lines (configurable per request) to keep responses compact. You can poll get_task_status until a task finishes.

Example: Python Language Server (`pylsp`)

Many LSP servers support TCP mode, which plays nicely with the background task model because editors can attach later using the advertised port. The Python Language Server (pylsp) makes this easy:

Install pylsp if you have not already: pip install "python-lsp-server[all]".

Ask the MCP server to start it in TCP mode:

{
  "command": "pylsp --tcp --host 127.0.0.1 --port 2087"
}

Configure your editor (or any LSP-aware client) to connect to tcp://127.0.0.1:2087.
Call get_task_status in your MCP client to view logs or confirm that the server is still running. Use end_background_task when you are done.

Example: Rust Language Server (`rust-analyzer`)

rust-analyzer speaks JSON-RPC over stdio only, so we launch it behind a small TCP shim so editors can attach while the MCP server keeps the process alive. A common option is socat:

Ensure both rust-analyzer and socat are installed. A typical setup is:

rustup component add rust-analyzer
brew install socat  # or use your package manager of choice

Start the bridge via the MCP server:
```
{
  "command": "socat TCP-LISTEN:9257,reuseaddr,fork EXEC:'rust-analyzer',pty,stderr"
}
```
- socat opens tcp://127.0.0.1:9257 and spawns rust-analyzer for each connection.
- pty makes sure the stdio-based protocol still works, while the MCP server captures useful stderr logs for inspection.
Point your editor at tcp://127.0.0.1:9257 as a Rust LSP endpoint.
Use get_task_status and end_background_task as needed.

Monitoring and Cleanup

Use get_task_status to tail recent stdout/stderr, inspect the exit code, or confirm whether a kill request has been issued.
When a task no longer needs to run, call end_background_task with the associated task_id. If the process exits on its own, the task status will automatically move to completed or failed.
Tasks are evicted from the in-memory store only when the server process exits; restart the MCP server to clear the slate.

Developing the Server

This is a standard Tokio-based Rust project. Run cargo test or cargo fmt before submitting changes, and restart your MCP client after every rebuild so it loads the new binary.