# 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.