mcp-debug-recorder

mcp-debug-recorder 可以快速回答一个简单的问题：我以前修复过这个问题吗？

它将调试会话、终端命令、失败尝试和成功修复记录在本地 SQLite 数据库中，以便您的 MCP 客户端可以使用自然语言查询您自己的调试历史记录。

快速开始

npx mcp-debug-recorder

默认情况下，数据存储在 ~/.mcp-debug-recorder/sessions.db 中。

架构

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

模式版本控制

数据库模式通过 PRAGMA user_version 进行版本控制。迁移会在启动时自动运行，因此升级不需要手动执行 SQL。

添加自定义数据库路径

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

配置

环境变量

• DEBUG_RECORDER_DB：覆盖 SQLite 数据库路径

• PORT：覆盖 Streamable HTTP 模式的 HTTP 服务器端口

• LOG_LEVEL：最低结构化日志级别（debug、info、warn、error）

• FUZZY_THRESHOLD：覆盖重排序期间使用的 Fuse.js 阈值

可用工具

• start_debug_session：开始跟踪一个新问题

• add_fix：记录一次失败或成功的修复尝试

• record_command：保存终端命令及其输出

• close_session：将会话标记为已解决或已放弃

• update_session：编辑标题、描述或标签

• delete_session：在明确确认后永久删除会话

• search_sessions：使用 FTS5 + 模糊重排序搜索历史会话

• find_similar_errors：询问您以前是否见过类似的错误

• get_session：获取完整的会话详情

• get_session_context：获取会话的 AI 友好摘要

• list_sessions：通过过滤器浏览会话

• get_stats：总结您的调试历史

• export_sessions：导出您的本地历史记录以进行备份或迁移

• import_sessions：导入之前导出的 JSON 有效负载

客户端设置

Claude Desktop

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

VS Code / GitHub Copilot

创建或更新 .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\"]}"

实际使用示例

我以前见过这个吗？

“我遇到了 TypeError: Cannot read properties of undefined，我以前见过这个吗？”

使用当前错误文本调用 find_similar_errors，然后使用 get_session_context 检查最佳匹配项。

记录一个活跃事件

1. 调用 start_debug_session

2. 使用 record_command 添加终端命令

3. 使用 add_fix 添加每次尝试的修复

4. 当标题或备注变得更清晰时，使用 update_session

5. 使用 close_session 关闭会话

备份您的本地调试历史

1. 使用 format: "json" 调用 export_sessions

2. 将返回的 JSON 保存到您首选的备份系统中

3. 稍后使用 import_sessions 恢复

数据存储

• 默认路径：~/.mcp-debug-recorder/sessions.db

• 使用 better-sqlite3 的便携式 SQLite 存储

• 针对大型历史记录的 FTS5 支持的搜索索引

• 无需外部数据库服务器

注意：better-sqlite3 使用原生插件。如果您看到绑定错误，请针对您的 Node 版本运行 npm rebuild better-sqlite3。

HTTP 传输

该包还支持 Streamable HTTP：

npm run start:http

有用的路由：

• GET /health

• GET /version

• MCP 端点：POST/GET/DELETE /mcp

开发

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

用于发布验证：

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

其他项目文档：

• 用法

• 配置

• 架构

• 搜索算法

• 发布流程

• 版本控制策略

• 路线图