mcp-debug-recorder

mcp-debug-recorder beantwortet schnell eine einfache Frage: Habe ich das schon einmal behoben?

Es zeichnet Debug-Sitzungen, Terminalbefehle, fehlgeschlagene Versuche und erfolgreiche Korrekturen in einer lokalen SQLite-Datenbank auf, sodass Ihr MCP-Client Ihre eigene Debugging-Historie in natürlicher Sprache abfragen kann.

Schnellstart

npx mcp-debug-recorder

Standardmäßig werden die Daten unter ~/.mcp-debug-recorder/sessions.db gespeichert.

Architektur

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-Versionierung

Das Datenbankschema wird über PRAGMA user_version versioniert. Migrationen werden beim Start automatisch ausgeführt, sodass für Upgrades kein manuelles SQL erforderlich ist.

Hinzufügen eines benutzerdefinierten Datenbankpfads

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

Konfiguration

Umgebungsvariablen

• DEBUG_RECORDER_DB: Überschreibt den Pfad zur SQLite-Datenbank

• PORT: Überschreibt den HTTP-Server-Port für den Streamable HTTP-Modus

• LOG_LEVEL: Minimales strukturiertes Log-Level (debug, info, warn, error)

• FUZZY_THRESHOLD: Überschreibt den Fuse.js-Schwellenwert, der beim Reranking verwendet wird

Verfügbare Tools

• start_debug_session: Startet die Nachverfolgung eines neuen Problems

• add_fix: Zeichnet einen fehlgeschlagenen oder erfolgreichen Korrekturversuch auf

• record_command: Speichert einen Terminalbefehl und dessen Ausgabe

• close_session: Markiert eine Sitzung als gelöst oder abgebrochen

• update_session: Bearbeitet Titel, Beschreibung oder Tags

• delete_session: Löscht eine Sitzung dauerhaft mit expliziter Bestätigung

• search_sessions: Durchsucht historische Sitzungen mit FTS5 + Fuzzy-Reranking

• find_similar_errors: Fragt ab, ob Sie schon einmal einen ähnlichen Fehler gesehen haben

• get_session: Ruft vollständige Sitzungsdetails ab

• get_session_context: Ruft eine KI-freundliche Zusammenfassung einer Sitzung ab

• list_sessions: Durchstöbert Sitzungen mit Filtern

• get_stats: Fasst Ihre Debug-Historie zusammen

• export_sessions: Exportiert Ihre lokale Historie für Backups oder Migrationen

• import_sessions: Importiert ein zuvor exportiertes JSON-Payload

Client-Einrichtung

Claude Desktop

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

VS Code / GitHub Copilot

Erstellen oder aktualisieren Sie .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\"]}"

Echte Anwendungsbeispiele

Habe ich das schon einmal gesehen?

"Ich erhalte TypeError: Cannot read properties of undefined, habe ich das schon einmal gesehen?"

Rufen Sie find_similar_errors mit dem aktuellen Fehlertext auf und untersuchen Sie dann die beste Übereinstimmung mit get_session_context.

Aufzeichnung eines aktiven Vorfalls

1. Rufen Sie start_debug_session auf

2. Fügen Sie Terminalbefehle mit record_command hinzu

3. Fügen Sie jeden Korrekturversuch mit add_fix hinzu

4. Verwenden Sie update_session, wenn Titel oder Notizen klarer werden

5. Schließen Sie die Sitzung mit close_session

Sichern Ihrer lokalen Debug-Historie

1. Rufen Sie export_sessions mit format: "json" auf

2. Speichern Sie das zurückgegebene JSON in Ihrem bevorzugten Backup-System

3. Stellen Sie es später mit import_sessions wieder her

Datenspeicherung

• Standardpfad: ~/.mcp-debug-recorder/sessions.db

• Portabler SQLite-Speicher mit better-sqlite3

• FTS5-basierter Suchindex für große Historien

• Kein externer Datenbankserver erforderlich

Hinweis: better-sqlite3 verwendet ein natives Addon. Wenn Sie Bindungsfehler sehen, führen Sie npm rebuild better-sqlite3 für Ihre Node-Version aus.

HTTP-Transport

Das Paket unterstützt auch Streamable HTTP:

npm run start:http

Nützliche Routen:

• GET /health

• GET /version

• MCP-Endpunkt: POST/GET/DELETE /mcp

Entwicklung

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

Zur Überprüfung der Veröffentlichung:

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

Zusätzliche Projektdokumentation:

• Nutzung

• Konfiguration

• Architektur

• Suchalgorithmus

• Release-Ablauf

• Versionierungsrichtlinie

• Roadmap