@spect8/mcp

Local MCP server + Claude Code hooks that capture Cursor / Claude Code tool calls and token usage, and forward them to a Spect8 ingest API.

Install

npm install -g @spect8/mcp
# or invoke on demand:
npx -y @spect8/mcp

One-time config

Create ~/.spect8/config.json:

{
  "ingest_url": "https://spect8-api.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).

Cursor wiring

Copy examples/cursor/mcp.json to ~/.cursor/mcp.json (or your project's .cursor/mcp.json) and fill in the placeholders.

Claude Code wiring

Copy examples/claude/hooks.json to ~/.claude/hooks.json (or your project-local .claude/hooks.json) and fill in the placeholders. The hook binary runs via npx so global install is not required.

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 an offline SQLite queue (~/.spect8/ offline_queue.db) 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