Cursor integration

Bridge Cursor's agent-trace records into SteelSpine's signed audit chain. AI vs human code attribution becomes auditable evidence.

Two adapters · MCP server (8 tools) + agent-trace ingestion

What this does

SteelSpine ships two Cursor adapters that complement each other:

MCP server exposes SteelSpine's audit and inspection tools so Cursor's AI assistant can directly query your captured runs from inside the IDE. Read-only.
Agent-trace adapter ingests Cursor's AI vs human code attribution records (cursor/agent-trace) into the signed audit chain. Runs as a background watcher.

Both work in the same project. Together they cover both the runtime (what AI is doing right now in the IDE, queryable by the assistant) and the post-hoc audit surface (what AI contributed, captured for compliance).

MCP server setup (recommended primary path)

The SteelSpine MCP server exposes 8 inspection tools to Cursor's AI assistant: status, run-list, run-show, compare, verify, what, search, patterns. Cursor's AI can call them directly during a coding session.

Step 1: Configure the MCP server in your project

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "steelspine": {
      "command": "python3",
      "args": ["/home/<your-user>/.prime/adapters/cursor/bin/steelspine_mcp_server.py"]
    }
  }
}

Replace <your-user> with your actual username (find with whoami). Restart Cursor.

Step 2: Verify the server is loaded

In Cursor's settings or MCP panel, the steelspine server should appear with 8 available tools. If missing, check Cursor's MCP error logs.

Test the server directly from the command line:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | python3 ~/.prime/adapters/cursor/bin/steelspine_mcp_server.py

Returns a proper response with protocolVersion, serverInfo, and capabilities.

Step 3: Use it from Cursor

Ask the AI assistant questions like:

"What's the status of my SteelSpine installation?"
"Show me my last 10 captured agent runs."
"Compare runs run_0047 and run_0046 — where did they diverge?"
"Verify the integrity of run_0050."
"What failed in the last 7 days?"
"Search captured runs for 'tool_call_failed'."

The AI calls the MCP tools, gets real data from your SteelSpine installation, and reasons about it inside the IDE.

Agent-trace adapter setup (post-hoc audit ingestion)

The compliance value: when a regulator or auditor asks "show me all AI-generated code in this codebase over the past 6 months," you can produce a signed deliverable that maps every contribution to its model, its conversation, its commit, and its timestamp, with cryptographic proof the chain was not altered.

Quick setup (agent-trace adapter)

1. The adapter ships at ~/.prime/adapters/cursor/bin/steelspine_cursor_adapter.py. No external dependencies; uses Python 3.10+ standard library only.

2. Make sure SteelSpine is running. The adapter posts events to http://localhost:8765/emit by default.

3. Run the adapter in watch mode against your repo:

python3 ~/.prime/adapters/cursor/bin/steelspine_cursor_adapter.py \
    --watch /path/to/your/repo \
    --poll 5

4. Verify with a one-shot test on a single agent-trace file:

python3 ~/.prime/adapters/cursor/bin/steelspine_cursor_adapter.py \
    --once /path/to/trace.agent-trace.json \
    --dry-run

The --dry-run flag prints events to stdout instead of POSTing, useful for validating before going live.

How agent-trace records map to SteelSpine events

For each agent-trace record, the adapter emits one SteelSpine event per (file × conversation × range) tuple. Each event preserves:

Field	Source
`trace_record_id`	agent-trace record UUID
`trace_timestamp`	agent-trace record timestamp (RFC 3339)
`file_path`	Path of attributed file
`contributor_type`	`human`, `ai`, `mixed`, or `unknown`
`contributor_model`	Model identifier (e.g., `claude-3.5-sonnet`, `gpt-4o`)
`contributor_url`	Conversation URL if recorded
`start_line` / `end_line`	Attributed line range
`lines_attributed`	Convenience field, end_line - start_line + 1
`metadata`	Original agent-trace metadata block (preserved)

What the integration does NOT do (be explicit with your auditor)

Does not emit events for code changes lacking an agent-trace record. Those records must be produced by Cursor or another agent-trace-compatible tool.
Does not validate the cryptographic integrity of the agent-trace record itself. The agent-trace spec v0.1.0 / v1.0.0 does not require signing. The signing comes from SteelSpine after ingestion.
Does not parse git notes or database-stored agent-trace records. Only file-on-disk patterns are supported today (*.agent-trace.json or .agent-trace/*.json).
Does not back-fill historical traces from before the watcher started.

Runtime validation status

The adapter is syntactically valid Python and has been tested against synthetic agent-trace records that conform to spec v1.0.0. End-to-end validation against:

A live Cursor Enterprise session emitting real agent-trace records to disk
A running SteelSpine instance receiving the emitted events at /emit
The resulting events surviving the full verify-run --compliance-html audit deliverable

... is the next validation step. Treat as v0.1 reference implementation until that end-to-end test passes.

Configuration reference

Flag	Default	Purpose
`--watch DIR`	(none)	Directory to watch for agent-trace files
`--once FILE`	(none)	Process one file and exit
`--endpoint URL`	`http://localhost:8765/emit`	SteelSpine HTTP API endpoint
`--poll SECONDS`	5	Poll interval when watching
`--dry-run`	false	Print events to stdout instead of POSTing
`--verbose / -v`	false	Debug logging

Pairing with other SteelSpine integrations

The Cursor adapter handles code-attribution events. For full coverage of an AI engineering workflow, pair with:

Claude Code (OTEL): captures runtime AI agent activity. Cursor adapter captures code-attribution. Together they cover both what Cursor wrote AND what Claude Code did.
Docker: steelspine watch covers containerized agent runtimes.
Git / CI: steelspine compare --strict gates PRs on agent regression. See /docs/ci-cd.html.

Troubleshooting

Adapter starts but no events appear in SteelSpine: Verify SteelSpine's HTTP API is reachable. curl -X POST http://localhost:8765/emit -H 'Content-Type: application/json' -d '{"source":"test","event_type":"ping"}' should succeed.

Adapter finds no files: Verify the watch path contains *.agent-trace.json files at any depth, or a .agent-trace/ directory with *.json files. Check that Cursor is configured to emit agent-trace records to disk (Enterprise plan default; other plans may need explicit configuration).

Parse errors: Run with --verbose for debug-level logging. Confirm the record matches agent-trace spec v0.1.0 or v1.0.0.