mcp-debug-recorder

mcp-debug-recorder answers a simple question fast: have I fixed this before?

It records debug sessions, terminal commands, failed attempts, and successful fixes in a local SQLite database so your MCP client can query your own debugging history in natural language.

Quick Start

npx mcp-debug-recorder

By default, data is stored at ~/.mcp-debug-recorder/sessions.db.

Architecture

src/
├── db.ts           - openDb(), createTestDb(), versioned MIGRATIONS[]
├── store.ts        - Store class with dependency-injected SQLite access
├── search.ts       - FTS5 + Fuse.js hybrid search
├── tools/          - MCP tool handlers grouped by session/search/admin concerns
├── types.ts        - Zod schemas and TypeScript types
├── mcp.ts          - MCP server wiring + tool registration
├── server-http.ts  - Streamable HTTP transport
├── logging.ts      - Structured logging with secret redaction
└── version.ts      - Package version helper

Schema versioning

The database schema is versioned via PRAGMA user_version. Migrations run automatically on startup, so upgrading does not require manual SQL.

Adding a custom database path

DEBUG_RECORDER_DB=/path/to/custom.db npx mcp-debug-recorder

Configuration

Environment variables

• DEBUG_RECORDER_DB: override the SQLite database path
• PORT: override the HTTP server port for Streamable HTTP mode
• LOG_LEVEL: minimum structured log level (debug, info, warn, error)
• FUZZY_THRESHOLD: override the Fuse.js threshold used during reranking

Available Tools

• start_debug_session: start tracking a new issue
• add_fix: record a failed or successful fix attempt
• record_command: save a terminal command and its output
• close_session: mark a session as resolved or abandoned
• update_session: edit title, description, or tags
• delete_session: permanently delete a session with explicit confirmation
• search_sessions: search historical sessions with FTS5 + fuzzy reranking
• find_similar_errors: ask whether you have seen a similar error before
• get_session: fetch full session details
• get_session_context: fetch an AI-friendly summary of a session
• list_sessions: browse sessions with filters
• get_stats: summarize your debug history
• export_sessions: export your local history for backup or migration
• import_sessions: import a previously exported JSON payload

Client Setup

Claude Desktop

{
  "mcpServers": {
    "mcp-debug-recorder": {
      "command": "npx",
      "args": ["mcp-debug-recorder"]
    }
  }
}

VS Code / GitHub Copilot

Create or update .vscode/mcp.json:

{
  "servers": {
    "mcp-debug-recorder": {
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-debug-recorder"]
    }
  }
}

Codex CLI

codex mcp add mcp-debug-recorder -- npx mcp-debug-recorder
codex mcp list

Gemini CLI

gemini mcp add mcp-debug-recorder npx mcp-debug-recorder
gemini mcp list

Antigravity

antigravity --add-mcp "{\"name\":\"mcp-debug-recorder\",\"command\":\"npx\",\"args\":[\"mcp-debug-recorder\"]}"

Real Usage Examples

Have I seen this before?

"I'm getting TypeError: Cannot read properties of undefined, have I seen this before?"

Call find_similar_errors with the current error text, then inspect the best match with `g

... View full README on GitHub