Debug Recorder

npm version License npm downloads LobeHub Glama

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

1. Call start_debug_session
2. Add terminal commands with record_command
3. Add each attempted fix with add_fix
4. Use update_session when the title or notes become clearer
5. Close the session with close_session

Back up your local debug history

1. Call export_sessions with format: "json"
2. Save the returned JSON in your preferred backup system
3. 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

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
• Versioning Policy
• Roadmap