{"_id":"@chatflowdev/waylaidwanderer-background-process-mcp","name":"@chatflowdev/waylaidwanderer-background-process-mcp","dist-tags":{"latest":"1.2.16"},"versions":{"1.2.16":{"name":"@chatflowdev/waylaidwanderer-background-process-mcp","version":"1.2.16","description":"A Model Context Protocol (MCP) server that provides background process management capabilities. This server enables LLMs to start, stop, and monitor long-running command-line processes.","main":"index.js","type":"module","bin":{"waylaidwanderer-background-process-mcp":"bin/bgpm"},"scripts":{"test":"vitest","build":"tsc","start:server":"node dist/server.js","start:ui":"node dist/cli.js ui --port 31337","dev:server":"tsc && node dist/server.js","dev:ui":"tsc && node dist/cli.js ui --port 31337","changeset":"changeset","version":"changeset version","release":"pnpm build && changeset publish","package":"node ./.github/create-archive.js","lint":"eslint . --fix"},"keywords":["mcp","background-process","process-manager","llm","ai-agent","tui"],"author":{"name":"Joel","url":"waylaidwanderer"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/waylaidwanderer/background-process-mcp.git"},"publishConfig":{"access":"public"},"packageManager":"pnpm@10.16.1","imports":{"es-toolkit/compat":"es-toolkit/compat/index.js"},"dependencies":{"@inkjs/ui":"^2.0.0","fastmcp":"^3.17.0","ink":"^6.3.1","minimist":"^1.2.8","node-pty":"^1.0.0","portfinder":"^1.0.38","react":"^19.1.1","string-width":"^8.1.0","strip-ansi":"^7.1.2","tree-kill":"^1.2.2","uuid":"^13.0.0","ws":"^8.18.3","zod":"3.25.76"},"devDependencies":{"@changesets/cli":"^2.29.7","@eslint/compat":"^1.4.0","@eslint/js":"^9.36.0","@stylistic/eslint-plugin":"^3.1.0","@types/archiver":"^6.0.2","@types/minimist":"^1.2.5","@types/node":"^24.5.2","@types/react":"^19.1.13","@types/uuid":"^11.0.0","@types/ws":"^8.18.1","@typescript-eslint/parser":"^8.44.1","archiver":"^7.0.1","esbuild":"^0.25.12","eslint":"^9.36.0","eslint-config-airbnb-extended":"^2.3.1","eslint-import-resolver-typescript":"^4.4.4","eslint-plugin-import-x":"^4.16.1","eslint-plugin-n":"^17.23.1","eslint-plugin-react":"^7.37.5","eslint-plugin-react-hooks":"^5.2.0","node-abi":"^4.17.0","tsx":"^4.20.5","typescript":"^5.9.2","typescript-eslint":"^8.44.1","vitest":"^3.2.4"},"_id":"@chatflowdev/waylaidwanderer-background-process-mcp@1.2.16","bugs":{"url":"https://github.com/waylaidwanderer/background-process-mcp/issues"},"homepage":"https://github.com/waylaidwanderer/background-process-mcp#readme","_integrity":"sha512-XxwmZmoKPlFUv53N0DN5ruIHy/xRYqnQ/NB3to+JWc6yR/HrTTDLTcylVm66lHHqb+stKlzJkoB4Sv3cgj/uJA==","_resolved":"/app/auto-mcp-upload/data/13072/chatflowdev-waylaidwanderer-background-process-mcp-1.2.16.tgz","_from":"file:/app/auto-mcp-upload/data/13072/chatflowdev-waylaidwanderer-background-process-mcp-1.2.16.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-XxwmZmoKPlFUv53N0DN5ruIHy/xRYqnQ/NB3to+JWc6yR/HrTTDLTcylVm66lHHqb+stKlzJkoB4Sv3cgj/uJA==","shasum":"e22c9ef86b324d17f6de0ae676fd2db82bef66d4","tarball":"https://registry.npmjs.org/@chatflowdev/waylaidwanderer-background-process-mcp/-/waylaidwanderer-background-process-mcp-1.2.16.tgz","fileCount":22,"unpackedSize":80771,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDH4c9JQnY4Xajxj1wPnEJhCGFoG8te7FZRDSEA3wl0NwIgQLbomQDwA5FyWxWAFH9seMr9IZ303ytXSLP4h56Pc9E="}]},"_npmUser":{"name":"chatflowdev","email":"chatflowdev@gmail.com"},"directories":{},"maintainers":[{"name":"chatflowdev","email":"chatflowdev@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/waylaidwanderer-background-process-mcp_1.2.16_1772266667483_0.5205502126576647"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-28T08:17:47.381Z","1.2.16":"2026-02-28T08:17:47.658Z","modified":"2026-02-28T08:17:47.877Z"},"maintainers":[{"name":"chatflowdev","email":"chatflowdev@gmail.com"}],"description":"A Model Context Protocol (MCP) server that provides background process management capabilities. This server enables LLMs to start, stop, and monitor long-running command-line processes.","homepage":"https://github.com/waylaidwanderer/background-process-mcp#readme","keywords":["mcp","background-process","process-manager","llm","ai-agent","tui"],"repository":{"type":"git","url":"git+https://github.com/waylaidwanderer/background-process-mcp.git"},"author":{"name":"Joel","url":"waylaidwanderer"},"bugs":{"url":"https://github.com/waylaidwanderer/background-process-mcp/issues"},"license":"MIT","readme":"# Background Process MCP\n\nA Model Context Protocol (MCP) server that provides background process management capabilities. This server enables LLMs to start, stop, and monitor long-running command-line processes.\n\n## Motivation\n\nSome AI agents, like Claude Code, can manage background processes natively, but many others can't. This project provides that capability as a standard tool for other agents like Google's Gemini CLI. It works as a separate service, making long-running task management available to a wider range of agents. I also added a TUI because I wanted to be able to monitor the processes myself.\n\n## Screenshot\n\n![\"TUI](\"./public/tui-screenshot.png\")
\n\n## Getting Started\n\nTo get started, install the Background Process MCP server in your preferred client.\n\n**Standard Config**\n\nThis configuration works for most MCP clients:\n\n```json\n{\n \"mcpServers\": {\n \"backgroundProcess\": {\n \"command\": \"npx\",\n \"args\": [\n \"@waylaidwanderer/background-process-mcp@latest\"\n ]\n }\n }\n}\n```\n\nTo connect to a standalone server, add the `--port` argument to the `args` array (e.g., `...mcp@latest\", \"--port\", \"31337\"]`).\n\n\nClaude Code
\n\nUse the Claude Code CLI to add the Background Process MCP server:\n\n```bash\nclaude mcp add backgroundProcess npx @waylaidwanderer/background-process-mcp@latest\n```\n \n\n\nClaude Desktop
\n\nFollow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use the standard config above.\n\n \n\n\nCodex
\n\nCreate or edit the configuration file `~/.codex/config.toml` and add:\n\n```toml\n[mcp_servers.backgroundProcess]\ncommand = \"npx\"\nargs = [\"@waylaidwanderer/background-process-mcp@latest\"]\n```\n\nFor more information, see the [Codex MCP documentation](https://github.com/openai/codex/blob/main/codex-rs/config.md#mcp_servers).\n\n \n\n\nCursor
\n\n#### Click the button to install:\n\n[![\"Install](\"https://cursor.com/deeplink/mcp-install-dark.svg\")
](https://cursor.com/en/install-mcp?name=Background%20Process%20MCP&config=eyJjb21tYW5kIjoibnB4IEB3YXlsYWlkd2FuZGVyZXIvYmFja2dyb3VuZC1wcm9jZXNzLW1jcEBsYXRlc3QifQ==)\n\n#### Or install manually:\n\nGo to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name it `backgroundProcess`, use `command` type with the command `npx @waylaidwanderer/background-process-mcp@latest`.\n\n \n\n\nGemini CLI
\n\nFollow the MCP install [guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson), use the standard config above.\n\n \n\n\nGoose
\n\n#### Click the button to install:\n\n[](https://block.github.io/goose/extension?cmd=npx&arg=%40waylaidwanderer%2Fbackground-process-mcp%24latest&id=backgroundProcess&name=Background%20Process%20MCP&description=Manage%20long-running%20command-line%20processes.)\n\n#### Or install manually:\n\nGo to `Advanced settings` -> `Extensions` -> `Add custom extension`. Name it `backgroundProcess`, use type `STDIO`, and set the `command` to `npx @waylaidwanderer/background-process-mcp@latest`. Click \"Add Extension\".\n \n\n\nLM Studio
\n\n#### Click the button to install:\n\n[](https://lmstudio.ai/install-mcp?name=backgroundProcess&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAd2F5bGFpZHdhbmRlcmVyL2JhY2tncm91bmQtcHJvY2Vzcy1tY3BAbGF0ZXN0Il19)\n\n#### Or install manually:\n\nGo to `Program` in the right sidebar -> `Install` -> `Edit mcp.json`. Use the standard config above.\n \n\n\nopencode
\n\nFollow the MCP Servers [documentation](https://opencode.ai/docs/mcp-servers/). For example in `~/.config/opencode/opencode.json`:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"mcp\": {\n \"backgroundProcess\": {\n \"type\": \"local\",\n \"command\": [\n \"npx\",\n \"@waylaidwanderer/background-process-mcp@latest\"\n ],\n \"enabled\": true\n }\n }\n}\n```\n \n\n\nQodo Gen
\n\nOpen [Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen) chat panel in VSCode or IntelliJ → Connect more tools → + Add new MCP → Paste the standard config above.\n\nClick `Save`.\n \n\n\nVS Code (for GitHub Copilot)
\n\n#### Click the button to install:\n\n[![\"Install](\"https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF\")
](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22backgroundProcess%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22%40waylaidwanderer%2Fbackground-process-mcp%40latest%22%5D%7D) [![\"Install](\"https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5\")
](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22backgroundProcess%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22%40waylaidwanderer%2Fbackground-process-mcp%40latest%22%5D%7D)\n\n#### Or install manually:\n\nFollow the MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), use the standard config above. You can also install the server using the VS Code CLI:\n\n```bash\n# For VS Code\ncode --add-mcp '{\"name\":\"backgroundProcess\",\"command\":\"npx\",\"args\":[\"@waylaidwanderer/background-process-mcp@latest\"]}'\n```\n \n\n\nWindsurf
\n\nFollow Windsurf MCP [documentation](https://docs.windsurf.com/windsurf/cascade/mcp). Use the standard config above.\n\n \n\n## Tools\n\nThe following tools are exposed by the MCP server.\n\n\nProcess Management
\n\n- **start_process**\n - Description: Starts a new process in the background.\n - Parameters:\n - `command` (string): The shell command to execute.\n - Returns: A confirmation message with the new process ID.\n\n- **stop_process**\n - Description: Stops a running process.\n - Parameters:\n - `processId` (string): The UUID of the process to stop.\n - Returns: A confirmation message.\n\n- **clear_process**\n - Description: Clears a stopped process from the list.\n - Parameters:\n - `processId` (string): The UUID of the process to clear.\n - Returns: A confirmation message.\n\n- **get_process_output**\n - Description: Gets the recent output for a process. Can specify `head` for the first N lines or `tail` for the last N lines.\n - Parameters:\n - `processId` (string): The UUID of the process to get output from.\n - `head` (number, optional): The number of lines to get from the beginning of the output.\n - `tail` (number, optional): The number of lines to get from the end of the output.\n - Returns: The requested process output as a single string.\n\n- **list_processes**\n - Description: Gets a list of all processes being managed by the Core Service.\n - Parameters: None\n - Returns: A JSON string representing an array of all process states.\n\n- **get_server_status**\n - Description: Gets the current status of the Core Service.\n - Parameters: None\n - Returns: A JSON string containing server status information (version, port, PID, uptime, process counts).\n\n \n\n## Architecture\n\nThe project has three components:\n\n1. **Core Service (`src/server.ts`)**: A standalone WebSocket server that uses `node-pty` to manage child process lifecycles. It is the single source of truth for all process states. It is designed to be standalone so that other clients beyond the official TUI and MCP can be built for it.\n\n2. **MCP Client (`src/mcp.ts`)**: Exposes the Core Service functionality as a set of tools for an LLM agent. It can connect to an existing service or spawn a new one.\n\n3. **TUI Client (`src/tui.ts`)**: An `ink`-based terminal UI that connects to the Core Service to display process information and accept user commands.\n\n## Manual Usage\n\nIf you wish to run the server and TUI manually outside of an MCP client, you can use the following commands.\n\nFor a shorter command, you can install the package globally:\n\n```bash\npnpm add -g @waylaidwanderer/background-process-mcp\n```\n\nThis will give you access to the `bgpm` command.\n\n### 1. Run the Core Service\n\nStart the background service manually:\n\n```bash\n# With npx\nnpx @waylaidwanderer/background-process-mcp server\n\n# Or, if installed globally\nbgpm server\n```\n\nThe server will listen on an available port (defaulting to `31337`) and output a JSON handshake with the connection details.\n\n### 2. Use the TUI\n\nConnect the TUI to a running server via its port:\n\n```bash\n# With npx\nnpx @waylaidwanderer/background-process-mcp ui --port \n\n# Or, if installed globally\nbgpm ui --port \n```","readmeFilename":"README.md","_rev":"1-a460c14e3e2b6c971d8f111a8e0513c7"}