spect8-mcp

Local MCP server + IDE instructions/hooks that capture Cursor, Kiro, Claude Code, and other MCP-aware agent activity, then forward it to a Spect8 ingest API.

Install

npx -y spect8-mcp setup --ide cursor

You can also install globally:

npm install -g spect8-mcp
spect8 setup --ide cursor

One-time config

Create ~/.spect8/config.json:

{
  "ingest_url": "https://spect8-backend-1d0b24fd600a.herokuapp.com",
  "ingest_hmac_key": "<32-byte hex shared secret>",
  "developer_id": "dev-your-id",
  "ide_name": "cursor"
}

All fields can also be supplied via env vars (same uppercase names prefixed with SPECT8_, e.g. SPECT8_INGEST_URL).

For manual key-based setup:

spect8 setup <mcp_key> [ingest_url] --ide cursor

Cursor wiring

spect8 install cursor
spect8 doctor cursor

Kiro wiring

spect8 setup <mcp_key> [ingest_url] --ide kiro
spect8 install kiro
spect8 doctor kiro

Claude Code wiring

spect8 install claude-code
spect8 doctor claude-code

Instruction files

For IDEs that rely on project instructions:

spect8 install rules

This writes Spect8 instructions to .cursorrules, .kiro/steering/spect8.md, and .github/copilot-instructions.md.

AI-assisted setup prompt

To generate a prompt a user can paste into their IDE agent:

spect8 prompt --ide cursor --token <short-lived-setup-token>

Provided tools

• start_task(task_label) - emits prompt_start + start_task events.
• end_task() - emits an end_task event for the active task.
• get_score([session_id]) - fetches the caller's live posterior score and, when a session id is supplied, the latest session score.

Transport

• HMAC-SHA256 signed POSTs (X-Spect8-Signature + X-Spect8-Timestamp) reaching /api/v1/events and /api/v1/token_events.
• 500 ms / 50 event batcher with a durable JSON offline queue (~/.spect8/offline_queue.json) so no event is lost across network blips.

Local data we read

• Cursor: ~/Library/Application Support/Cursor/User/globalStorage/state.vscdb (read-only) - tails cursorDiskKV.bubbleId:*.
• Claude Code: ~/.claude/projects/**/*.jsonl - extracts message.usage.input_tokens / output_tokens.

Development

cd spect8-mcp
npm install
npm run build
npm test