MCP Debug Recorder

debug-recorder-mcp

Local-first debug memory for MCP clients.

Record incidents, commands, failed attempts, successful fixes, diagnostics, and searchable debugging history in SQLite.

Published docs · Usage · Client recipes · Security · Release flow

Why this exists

Debugging knowledge usually disappears into chat windows, terminals, and commit history. debug-recorder-mcp gives MCP-enabled agents and IDEs a durable local memory so they can answer:

“Have I fixed this before?”

It stores each debugging session, error, command, attempted fix, working fix, tags, and context in a local SQLite database. Search combines SQLite FTS5 with fuzzy reranking, reusable presets, pagination metadata, related-session groups, and optional Markdown exports.

Highlights

• Local-first storage: no external database or hosted service required.
• MCP-native tools: stdio server for desktop MCP clients plus optional Streamable HTTP mode.
• Search that survives messy errors: FTS5 + Fuse.js reranking for stack traces, typos, Unicode, and punctuation-heavy logs.
• Reusable search presets: save common filters and limits for recurring incident patterns.
• Safe operations: redaction-before-store option, explicit destructive confirmations, local HTTP host/origin/auth/body-limit hardening.
• Diagnostics: get_diagnostics returns redacted runtime, schema, package, and health signals for support without leaking raw paths, tokens, stack traces, or command output.
• Release-grade packaging: audit, coverage, fuzzing, package-size gates, SBOM/VEX policy, install-script approvals, provenance-ready release workflow, and MCP Registry readiness checks.

Quick start

Requires Node.js 22 LTS or 24 LTS and npm 10+.

npx debug-recorder-mcp

Default database path:

~/.debug-recorder-mcp/sessions.db

Use a custom database path:

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

MCP client setup

Desktop MCP clients

{

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

VS Code / GitHub Copilot

Create or update .vscode/mcp.json:

{

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

More setup examples are in Client setup recipes.

Available MCP tools

Real usage examples

Have I seen this before?

Ask your MCP client:

I am getting TypeError: Cannot read properties of undefined. Have I seen this before?

The client can call find_similar_errors, then inspect the best match with get_session_context.

Record an active incident

1. Call start_debug_session with the problem title and error details.
2. Add terminal commands with record_command.
3. Add each attempted fix with add_fix.
4. Improve title, notes, or tags with update_session.
5. Close the incident with close_session.

Back up or migrate history

1. Call export_sessions with format: "json". The response is marked with format: "json" and contains the full sessions, fixes, and commands arrays.
2. Store the returned object in your backup system.
3. Restore later by passing that object as import_sessions.payload.

For a lightweight inventory, call export_sessions with format: "summary". Summary responses are marked with format: "summary", include aggregate stats and abbreviated session rows, and are not restore payloads.

HTTP transport

The package also supports local Streamable HTTP:

npm run start:http

Useful routes:

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

HTTP mode is local-first by default. It binds to 127.0.0.1, creates an isolated stateless MCP server/transport per request, validates Host, validates browser Origin when present, and enforces a JSON body-size limit before the MCP transport receives the request.

For deliberate non-loopback exposure, set all of these:

HOST=0.0.0.0

DEBUG_RECORDER_REMOTE_HTTP=true DEBUG_RECORDER_HTTP_TOKEN=replace-with-a-long-random-token DEBUG_RECORDER_ALLOWED_HOSTS=debug-recorder.example.com DEBUG_RECORDER_ALLOWED_ORIGINS=https://debug-recorder.example.com npm run start:http

Wildcard origins are rejected for remote mode. The static bearer token is private/shared-secret mode: every caller shares one identity, one authority level, and one SQLite dataset. It is suitable for loopback, an encrypted trusted network, or a private authenticating proxy, but it is not OAuth and does not provide per-user scopes or revocation.

Public multi-user HTTP is not supported by the current release. The accepted target architecture uses an external authorization server and MCP-aware gateway with protected-resource discovery, audience-bound tokens, scopes, rate limits, audit events, and subject-aware storage. See Public HTTP authorization and ADR-0006.

Configuration

Boolean configuration also accepts false, 0, and no; values are case-insensitive, whitespace is ignored, and unsupported values fail fast. Diagnostics reports the resolved effective values rather than re-reading changed environment strings.

Data and privacy

• Database: local SQLite via better-sqlite3.
• Search index: SQLite FTS5 virtual table.
• Default path: ~/.debug-recorder-mcp/sessions.db.
• Redaction: optional before-store redaction plus diagnostics redaction.
• Deletion: destructive operations require explicit confirmation.
• Maintenance: see [Storage retention and maintenance](./docs/st