# cursor-mcp

MCP server for Hermes (and other MCP clients) to delegate coding tasks to **Cursor** via the [Cursor SDK](https://cursor.com/docs/sdk/python).

## Features

- **Delegate** one-shot coding tasks (`cursor_delegate`)
- **Session** + **resume** for multi-step work (`cursor_delegate_session`, `cursor_resume`)
- **Progress streaming** to stderr + `progress` array in responses
- **Timeout** enforcement via `CURSOR_TIMEOUT_SECONDS`
- **Git validation** before delegate (configurable)
- Session index for follow-up work

## Quick start

### 1. Install

```bash
cd ~/Projects/cursor-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
```

### 2. Configure API key

Create a user API key in **Cursor Dashboard → API Keys**, then add to `~/.hermes/.env`:

```bash
CURSOR_API_KEY=your-key-here
```

### 3. Register with Hermes

```bash
hermes mcp add cursor \
  --command ~/.hermes/mcp_servers/cursor-mcp-env.sh \
  --env CURSOR_DEFAULT_CWD=/Users/you/Projects \
  --env CURSOR_DEFAULT_MODEL=composer-2.5 \
  --timeout 1900
```

Or add manually to `~/.hermes/config.yaml` — see [docs/CONFIGURATION.md](docs/CONFIGURATION.md).

### 4. Verify

```bash
hermes mcp test cursor
```

## MCP tools

| Tool | Use when |
|------|----------|
| `cursor_delegate` | One-shot task (bug fix, small change) |
| `cursor_delegate_session` | Multi-step work; returns `agent_id` |
| `cursor_resume` | Follow-up on existing Cursor session |
| `cursor_test_connection` | Verify API key + project path |
| `cursor_list_sessions` | Recent delegations with `agent_id` |
| `cursor_get_config` | Non-secret config + recent sessions |

## Response shape (v1.1+)

Delegation tools return JSON including:

```json
{
  "status": "finished",
  "run_id": "...",
  "agent_id": "...",
  "result": "...",
  "duration_ms": 64200,
  "git": {"branch": "main", "commit": "abc1234", "dirty": false},
  "progress": [
    {"kind": "status", "message": "running"},
    {"kind": "delta", "message": "started edit_file", "tool": "edit_file"}
  ]
}
```

Live progress also appears on stderr as `[cursor-mcp] ...` (Hermes: `~/.hermes/logs/mcp-stderr.log`).

## Configuration

See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for all `CURSOR_*` environment variables.

## Hermes skill

Use the `cursor-delegation` skill in the `senior-coder` profile for prompt templates and orchestration patterns.

## Development

```bash
.venv/bin/python -m unittest discover -s tests -v
```

## Notes

- Runs Cursor's **local** agent loop against files on disk — does not control the open Cursor IDE window.
- Billing follows your Cursor plan (SDK usage).
- Node.js 22+ is required by the Cursor SDK runtime.

## License

MIT