mcp-debug-recorder

mcp-debug-recorder responde a una pregunta sencilla rápidamente: ¿he solucionado esto antes?

Registra sesiones de depuración, comandos de terminal, intentos fallidos y correcciones exitosas en una base de datos SQLite local para que tu cliente MCP pueda consultar tu propio historial de depuración en lenguaje natural.

Inicio rápido

npx mcp-debug-recorder

Por defecto, los datos se almacenan en ~/.mcp-debug-recorder/sessions.db.

Arquitectura

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

Versionado del esquema

El esquema de la base de datos se versiona mediante PRAGMA user_version. Las migraciones se ejecutan automáticamente al iniciar, por lo que actualizar no requiere SQL manual.

Añadir una ruta de base de datos personalizada

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

Configuración

Variables de entorno

• DEBUG_RECORDER_DB: sobrescribe la ruta de la base de datos SQLite

• PORT: sobrescribe el puerto del servidor HTTP para el modo HTTP Streamable

• LOG_LEVEL: nivel mínimo de registro estructurado (debug, info, warn, error)

• FUZZY_THRESHOLD: sobrescribe el umbral de Fuse.js utilizado durante la reordenación

Herramientas disponibles

• start_debug_session: iniciar el seguimiento de un nuevo problema

• add_fix: registrar un intento de corrección fallido o exitoso

• record_command: guardar un comando de terminal y su salida

• close_session: marcar una sesión como resuelta o abandonada

• update_session: editar título, descripción o etiquetas

• delete_session: eliminar permanentemente una sesión con confirmación explícita

• search_sessions: buscar sesiones históricas con FTS5 + reordenación difusa

• find_similar_errors: preguntar si has visto un error similar antes

• get_session: obtener detalles completos de la sesión

• get_session_context: obtener un resumen de la sesión apto para IA

• list_sessions: explorar sesiones con filtros

• get_stats: resumir tu historial de depuración

• export_sessions: exportar tu historial local para copia de seguridad o migración

• import_sessions: importar un payload JSON exportado previamente

Configuración del cliente

Claude Desktop

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

VS Code / GitHub Copilot

Crea o actualiza .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\"]}"

Ejemplos de uso real

¿He visto esto antes?

"Estoy recibiendo TypeError: Cannot read properties of undefined, ¿he visto esto antes?"

Llama a find_similar_errors con el texto del error actual, luego inspecciona la mejor coincidencia con get_session_context.

Registrar un incidente activo

1. Llama a start_debug_session

2. Añade comandos de terminal con record_command

3. Añade cada intento de corrección con add_fix

4. Usa update_session cuando el título o las notas sean más claros

5. Cierra la sesión con close_session

Haz una copia de seguridad de tu historial de depuración local

1. Llama a export_sessions con format: "json"

2. Guarda el JSON devuelto en tu sistema de copia de seguridad preferido

3. Restáuralo más tarde con import_sessions

Almacenamiento de datos

• Ruta por defecto: ~/.mcp-debug-recorder/sessions.db

• Almacenamiento SQLite portátil con better-sqlite3

• Índice de búsqueda respaldado por FTS5 para historiales grandes

• No requiere servidor de base de datos externo

Nota: better-sqlite3 utiliza un complemento nativo. Si ves errores de enlace, ejecuta npm rebuild better-sqlite3 para tu versión de Node.

Transporte HTTP

El paquete también admite HTTP Streamable:

npm run start:http

Rutas útiles:

• GET /health

• GET /version

• Punto final MCP: POST/GET/DELETE /mcp

Desarrollo

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

Para la verificación de la versión:

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

Documentación adicional del proyecto:

• Uso

• Configuración

• Arquitectura

• Algoritmo de búsqueda

• Flujo de lanzamiento

• Política de versionado

• Hoja de ruta