cursor-background-agent-mcp-server/README.md

MCP Server for Cursor Background Agents API - run autonomous coding agents from any MCP client

# Cursor Background Agents MCP Server

A clean, modular, and extensible Model Context Protocol (MCP) server that provides access to the Cursor Background Agents API. Built with TypeScript following SOLID principles and clean architecture patterns.

## Overview

This MCP server enables AI applications to interact with Cursor's Background Agents API, allowing them to:

- Launch autonomous coding agents on GitHub repositories
- Monitor agent status and progress
- Add follow-up instructions to running agents
- Retrieve agent conversation history
- List available AI models for agents

## Features

- ✅ **MCP Compliant**: Fully implements the MCP specification
- ✅ **Clean Architecture**: Modular design with clear separation of concerns
- ✅ **Type Safe**: Written in TypeScript with comprehensive type definitions
- ✅ **Input Validation**: JSON Schema validation using AJV
- ✅ **Error Handling**: MCP-compliant structured error responses
- ✅ **Comprehensive Tests**: 54+ unit tests with high coverage
- ✅ **Well Documented**: Clear documentation and examples

## Architecture

```
src/
├── domain/          # Core business logic and types
├── application/     # Use cases and service interfaces
├── infrastructure/  # External API clients and adapters
└── presentation/    # HTTP endpoints and controllers
```

The server follows clean architecture principles with clear dependency inversion:
- **Domain**: Pure business logic, no external dependencies
- **Application**: Orchestrates domain logic and defines interfaces
- **Infrastructure**: Implements external integrations (Cursor API)
- **Presentation**: Handles HTTP requests and responses

## Installation & Usage

### Option 1: Use with VS Code / Kilo Code Extension (Recommended)

1. **Get your Cursor API key** from [Cursor Dashboard → Integrations](https://cursor.com/dashboard?tab=integrations)

2. **Add to your MCP settings** in VS Code:
   - Open VS Code
   - Go to the Kilo Code extension settings
   - Add this configuration to your `mcp_settings.json`:

```json
{
  "cursor-background-agents": {
    "command": "npx",
    "args": [
      "-y",
      "cursor-background-agent-mcp-server"
    ],
    "env": {
      "CURSOR_API_KEY": "your-actual-cursor-api-key-here"
    },
    "disabled": false,
    "autoApprove": [
      "launchAgent",
      "listAgents",
      "listModels"
    ],
    "alwaysAllow": [
      "getAgentStatus",
      "getAgentConversation",
      "listAgents",
      "listModels",
      "listRepositories"
    ]
  }
}
```

3. **Start using the tools** in your Kilo Code chat! The server will automatically start when needed.

### Option 2: Manual Installation

For development or standalone usage:

1. Clone the repository:
```bash
git clone <repository-url>
cd cursor-background-agent-mcp
```

2. Install dependencies:
```bash
npm install
```

3. Set environment variables:
```bash
export CURSOR_API_KEY="your-cursor-api-key"
```

4. Build the project:
```bash
npm run build
```

5. Run as MCP STDIO server:
```bash
npm run mcp
```

Or run as HTTP server:
```bash
npm start
```

## Usage

### Using with VS Code

Once configured in your `mcp_settings.json`, you can use these tools directly in Kilo Code:

```
@kilo launch a new Cursor agent to add TypeScript types to my React components

@kilo check the status of my running Cursor agents

@kilo list all available AI models for Cursor agents
```

### MCP Protocol Details

The server implements the Model Context Protocol via STDIO for VS Code integration, and also exposes HTTP endpoints for direct API access:

#### STDIO Mode (for MCP clients like VS Code)
- **Tools**: `launchAgent`, `listAgents`, `listModels`, `addFollowup`, `getAgentConversation`, `getAgentStatus`
- **Resources**: None currently (extensible)
- **Transport**: JSON-RPC over STDIO

#### HTTP Mode (for direct API access)
- **GET** `/manifest` - Get available tools and schemas
- **POST** `/tool-invoke` - Invoke a tool
- **POST** `/resource` - Access a resource

### Available Tools

#### `launchAgent`
Start a new background agent to work on a repository.

**Input:**
```json
{
  "prompt": {
    "text": "string",
    "images": [
      {
        "data": "base64-string",
        "dimension": { "width": 1024, "height": 768 }
      }
    ]
  },
  "source": {
    "repository": "https://github.com/org/repo",
    "ref": "main"
  }
}
```

**Output:**
```json
{
  "id": "bc_abc123",
  "name": "Add README Documentation",
  "status": "CREATING",
  "source": { "repository": "...", "ref": "main" },
  "target": {
    "branchName": "cursor/add-readme-1234",
    "url": "https://cursor.com/agents?id=bc_abc123",
    "autoCreatePr": false
  },
  "createdAt": "2024-01-15T10:30:00Z"
}
```

#### `listAgents`
Retrieve all background agents for the authenticated user.

**Input:** `{}` (empty object)

**Output:**
```json
{
  "agents": [
    {
      "id": "bc_abc123",
      "name": "Add README Documentation",
      "status": "RUNNING",
      "summary": "Added README.md with installation instructions",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "nextCursor": "bc_def456"
}
```

#### `listModels`
Get available AI models for background agents.

**Input:** `{}` (empty object)

**Output:**
```json
{
  "models": [
    { "name": "gpt-4", "recommended": true },
    { "name": "gpt-3.5", "recommended": false }
  ]
}
```

#### `addFollowup`
Send additional instructions to a running agent.

**Input:**
```json
{
  "agentId": "bc_abc123",
  "prompt": {
    "text": "Also add a section about troubleshooting"
  }
}
```

#### `getAgentConversation`
Retrieve conversation history of an agent.

**Input:**
```json
{
  "agentId": "bc_abc123"
}
```

#### `getAgentStatus`
Get current status and results of an agent.

**Input:**
```json
{
  "agentId": "bc_abc123"
}
```

## Development

### Running Tests

```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage
```

### Project Structure

```
src/
├── domain/
│   ├── index.ts           # Domain types and interfaces
│   ├── manifest.ts        # Tool/resource definitions
│   └── errors.ts          # MCP error handling
├── application/
│   ├── index.ts           # Application interfaces
│   └── toolExecutionService.ts # Tool execution logic
├── infrastructure/
│   ├── index.ts           # Infrastructure interfaces
│   └── cursorApiClient.ts # Cursor API HTTP client
├── presentation/
│   ├── manifestController.ts        # GET /manifest
│   ├── toolInvocationController.ts  # POST /tool-invoke
│   └── resourceAccessController.ts  # POST /resource
└── server.ts              # Main server setup
```

### Adding New Tools

1. **Define the tool schema** in `src/domain/manifest.ts`:
```typescript
{
  name: "newTool",
  description: "Description of the new tool",
  inputSchema: { /* JSON Schema */ },
  outputSchema: { /* JSON Schema */ }
}
```

2. **Implement the tool logic** in `src/application/toolExecutionService.ts`:
```typescript
case "newTool":
  return this.handleNewTool(input);
```

3. **Add corresponding API method** in `src/infrastructure/cursorApiClient.ts` if needed.

4. **Write tests** in `src/__tests__/` following existing patterns.

### Error Handling

The server implements MCP-compliant error handling with structured error responses:

```typescript
{
  "error": {
    "code": "TOOL_NOT_FOUND",
    "message": "Tool 'invalidTool' not found",
    "details": { /* optional additional context */ }
  }
}
```

Error codes include:
- `TOOL_NOT_FOUND` / `RESOURCE_NOT_FOUND`
- `INVALID_INPUT` / `INVALID_OUTPUT`
- `SERVICE_UNAVAILABLE`
- `AUTHENTICATION_FAILED`
- `RATE_LIMITED`
- `TIMEOUT`
- `INTERNAL_ERROR`

## Configuration

Environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `CURSOR_API_KEY` | Your Cursor API key (required) | - |
| `PORT` | Server port | 3000 |

## API Reference

For detailed API documentation, see the [Cursor Background Agents API docs](https://docs.cursor.com/en/background-agent/api/overview).

## Publishing

This package is published to npm via automated GitHub Actions workflows. For detailed publishing instructions, see [PUBLISHING.md](PUBLISHING.md).

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/new-feature`
3. Make changes following the existing patterns
4. Add tests for new functionality
5. Run tests: `npm test`
6. Submit a pull request

### Code Style

- Follow TypeScript best practices
- Use meaningful names for variables, functions, and classes
- Keep functions small and single-purpose
- Add JSDoc comments for public APIs
- Follow clean architecture principles

## License

MIT License - see [LICENSE](LICENSE) file for details.