nearxos
1d71b3f822
Surface Cursor run progress to stderr and response payloads, enforce CURSOR_TIMEOUT_SECONDS, validate git repos before delegate, and fix resume session cwd persistence. Includes docs, tests, and packaging. Co-authored-by: Cursor <cursoragent@cursor.com>
105 lines
3.2 KiB
Markdown
105 lines
3.2 KiB
Markdown
# Configuration
|
|
|
|
Environment variables use the `CURSOR_` prefix (via `pydantic-settings`).
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `CURSOR_API_KEY` | *(empty)* | Cursor user API key. Prefer `~/.hermes/.env` when using Hermes launcher. |
|
|
| `CURSOR_DEFAULT_MODEL` | `composer-2.5` | Default Cursor model for delegations. |
|
|
| `CURSOR_DEFAULT_CWD` | `~/Projects` | Default project root when `cwd` is omitted. |
|
|
| `CURSOR_TIMEOUT_SECONDS` | `1800` | Max seconds per delegation/resume run before cancel + error. |
|
|
| `CURSOR_REQUIRE_GIT_REPO` | `true` | When true, `cwd` must be inside a git work tree before delegate. |
|
|
| `CURSOR_SESSIONS_PATH` | `~/.local/share/cursor-mcp/sessions.json` | Persisted session index for resume. |
|
|
| `CURSOR_AUDIT_LOG_PATH` | `~/.local/share/cursor-mcp/audit.jsonl` | JSONL audit trail. |
|
|
|
|
## Hermes registration
|
|
|
|
Recommended launcher (loads `CURSOR_*` from `~/.hermes/.env`):
|
|
|
|
```yaml
|
|
mcp_servers:
|
|
cursor:
|
|
command: /Users/nearxos/.hermes/mcp_servers/cursor-mcp-env.sh
|
|
enabled: true
|
|
timeout: 1900
|
|
env:
|
|
CURSOR_DEFAULT_CWD: /Users/nearxos/Projects
|
|
CURSOR_DEFAULT_MODEL: composer-2.5
|
|
CURSOR_TIMEOUT_SECONDS: 1800
|
|
CURSOR_REQUIRE_GIT_REPO: true
|
|
```
|
|
|
|
Set Hermes MCP `timeout` slightly above `CURSOR_TIMEOUT_SECONDS` so the server can return a structured timeout error.
|
|
|
|
## Progress streaming
|
|
|
|
During long runs, cursor-mcp writes human-readable lines to **stderr**:
|
|
|
|
```text
|
|
[cursor-mcp] status: running
|
|
[cursor-mcp] delta: started read_file
|
|
[cursor-mcp] step: tool call: edit_file
|
|
```
|
|
|
|
Hermes captures these in `~/.hermes/logs/mcp-stderr.log`.
|
|
|
|
The tool response JSON also includes:
|
|
|
|
```json
|
|
{
|
|
"status": "finished",
|
|
"progress": [
|
|
{"ts": "...", "kind": "status", "message": "running"},
|
|
{"ts": "...", "kind": "delta", "message": "started read_file", "tool": "read_file"}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Git validation
|
|
|
|
When `CURSOR_REQUIRE_GIT_REPO=true` (default), delegate tools fail fast if `cwd` is not a git repo:
|
|
|
|
```text
|
|
Working directory is not a git repository: /path. Initialize git or set CURSOR_REQUIRE_GIT_REPO=false
|
|
```
|
|
|
|
Successful validation adds repo metadata to the response `git` field (`root`, `branch`, `commit`, `dirty`).
|
|
|
|
For scratch prototypes:
|
|
|
|
```bash
|
|
export CURSOR_REQUIRE_GIT_REPO=false
|
|
```
|
|
|
|
## Timeouts
|
|
|
|
On timeout the server attempts `run.cancel()` and returns:
|
|
|
|
```text
|
|
Cursor run timed out after 1800s (run_id=...)
|
|
```
|
|
|
|
Tune per environment:
|
|
|
|
- Fast patches: `CURSOR_TIMEOUT_SECONDS=600`
|
|
- Large refactors: `CURSOR_TIMEOUT_SECONDS=3600`
|
|
|
|
## Session resume
|
|
|
|
`cursor_delegate_session` and `cursor_resume` store sessions in `CURSOR_SESSIONS_PATH`.
|
|
|
|
Each entry includes `agent_id`, `cwd`, `task_summary`, and `updated_at`.
|
|
|
|
`cursor_resume` uses the stored `cwd` when updating session history (fixed in 1.1.0).
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Fix |
|
|
|---------|-----|
|
|
| `CURSOR_API_KEY is not set` | Add to `~/.hermes/.env`, restart Hermes desktop |
|
|
| `not a git repository` | `git init` in project or disable `CURSOR_REQUIRE_GIT_REPO` |
|
|
| Timeout errors | Increase `CURSOR_TIMEOUT_SECONDS` or narrow task scope |
|
|
| No progress in logs | Ensure stderr is captured; check `mcp-stderr.log` |
|
|
|
|
See also the Hermes skill `autonomous-ai-agents/cursor-delegation`.
|