mcp-debug-recorder

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 get_session_context.

Record an active incident

• Call start_debug_session
• Add terminal commands with record_command
• Add each attempted fix with add_fix
• Use update_session when the title or notes become clearer
• Close the session with close_session

Back up your local debug history

• Call export_sessions with format: "json"
• Save the returned JSON in your preferred backup system
• Restore later with import_sessions

Data Storage

• Default path: ~/.mcp-debug-recorder/sessions.db
• Portable SQLite storage with better-sqlite3
• FTS5-backed search index for large histories
• No external database server required

Note: better-sqlite3 uses a native addon. If you see binding errors, run npm rebuild better-sqlite3 for your Node version.

HTTP Transport

The package also supports Streamable HTTP:

npm run start:http

Useful routes:

• GET /health
• GET /version
• MCP endpoint: POST/GET/DELETE /mcp

HTTP transport is intended for loopback/local use by default. For non-local deployments, bind it behind an authenticated reverse proxy and do not expose it directly to the internet.

Development

npm ci
npm run lint
npm test
npm run build
npm run test:e2e
npm run docs:api

For release verification:

npm run format:check
npm run test:coverage
npm run prepublishOnly

Additional project docs:

• Usage
• Configuration
• Architecture
• Search Algorithm
• Release Flow
• Security Policy
• Contributing
• Versioning Policy
• Roadmap