MCP Background Task Server

# MCP Background Task Server A Model Context Protocol (MCP) server that enables running and managing long-running background tasks from within Claude Desktop or other MCP-compatible clients. ## Features - **Run Background Tasks**: Execute long-running commands (like `npm run dev`, servers, builds) in the background - **Task Management**: Start, stop, and list running background tasks - **Interactive Communication**: Send data to task stdin and retrieve stdout/stderr output - **Process Monitoring**: Track task states, PIDs, and exit codes - **Graceful Shutdown**: Automatically cleanup all background processes when the server stops ## Available Tools ### `run-background-task` Starts a new background task with a unique name. **Parameters:** - `name` (string): Unique identifier for the task - `shell` (string): Shell command to run in background ### `stop-background-task` Stops a running background task by name. **Parameters:** - `name` (string): Name of the task to stop ### `list-background-tasks` Lists all currently running background tasks with their PIDs and states. ### `get-task-stdout` Retrieves the stdout output from a background task. **Parameters:** - `name` (string): Name of the task ### `get-task-stderr` Retrieves the stderr output from a background task. **Parameters:** - `name` (string): Name of the task ### `send-to-task-stdin` Sends data to the stdin of a running background task (useful for interactive commands). **Parameters:** - `name` (string): Name of the task - `data` (string): Data to send to stdin ## Installation 1. Clone this repository: ```bash git clone <repository-url> cd mcp-bgtask ``` 2. Install dependencies: ```bash pnpm install ``` 3. Build the project: ```bash pnpm run build ``` ## Usage ### Development ```bash pnpm run start ``` ### Production ```bash pnpm run build node dist/index.js ``` ### Development with Inspector ```bash pnpm run dev ``` ## Configuration To use this MCP server with Claude Desktop, add it to your `claude_desktop_config.json`: ```json { "mcpServers": { "bgtask": { "command": "node", "args": ["/path/to/mcp-bgtask/dist/index.js"], "cwd": "/path/to/mcp-bgtask" } } } ``` Replace `/path/to/mcp-bgtask` with the actual path to your project directory. ## Example Use Cases 1. **Development Server**: Start a development server and monitor its output ``` run-background-task: name="dev-server", shell="npm run dev" ``` 2. **Build Process**: Run a long build process and check its progress ``` run-background-task: name="build", shell="npm run build:watch" ``` 3. **Interactive Commands**: Run interactive CLI tools and send input ``` run-background-task: name="cli-tool", shell="my-interactive-cli" send-to-task-stdin: name="cli-tool", data="user input\n" ``` 4. **Log Monitoring**: Monitor logs from running processes ``` get-task-stdout: name="dev-server" get-task-stderr: name="dev-server" ``` ## Architecture The server is built using: - **Model Context Protocol SDK**: For MCP server implementation - **Node.js Child Process**: For spawning and managing background processes - **Zod**: For input validation and schema definition - **TypeScript**: For type safety and better development experience ### Key Components - **Child Class**: Manages individual background processes with state tracking - **Process Map**: Maintains a registry of all running tasks - **Signal Handlers**: Ensures graceful cleanup on server termination ## Development ### Scripts - `pnpm run start`: Run the server in development mode - `pnpm run build`: Build for production - `pnpm run type-check`: Run TypeScript type checking - `pnpm run dev`: Run with MCP inspector for debugging ### Testing The project includes Vitest configuration for testing. Run tests with: ```bash pnpm test ``` ## Error Handling The server includes robust error handling for: - Duplicate task names - Missing tasks - Process communication failures - Stdin/stdout availability issues ## Security Considerations ⚠️ **Warning**: This server can execute arbitrary shell commands. Only use it in trusted environments and be careful about what commands you run through it. ## License ISC ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Submit a pull request ## Troubleshooting ### Common Issues 1. **Task not starting**: Check if the shell command is valid and executable 2. **No output**: Some commands may not produce output immediately; check stderr as well 3. **Process not stopping**: Some processes may need specific signals; the server uses SIGTERM by default ### Debugging Use the MCP inspector for debugging: ```bash pnpm run dev ``` Then open the provided URL in your browser to inspect MCP communications.