Debug Recorder

debug-recorder-mcp

为 MCP 客户端提供本地优先的调试记忆。
在 SQLite 中记录事件、命令、失败的尝试、成功的修复、诊断信息以及可搜索的调试历史。

已发布的文档 · 使用方法 · 客户端配置示例 · 安全 · 发布流程

为什么开发这个项目

调试知识通常会散落在聊天窗口、终端和提交历史中。debug-recorder-mcp 为启用 MCP 的 Agent 和 IDE 提供持久的本地记忆，让它们能够回答：

“我以前修复过这个问题吗？”

它会将每次调试会话、错误、命令、尝试过的修复、有效的修复、标签和上下文存储在本地 SQLite 数据库中。搜索结合了 SQLite FTS5 与模糊重排、可复用预设、分页元数据、相关会话分组，以及可选的 Markdown 导出。

亮点

• 本地优先存储： 无需外部数据库或托管服务。
• 原生支持 MCP 的工具： 面向桌面 MCP 客户端的 stdio 服务，另提供可选的 Streamable HTTP 模式。
• 轻松搜索杂乱的错误： 使用 FTS5 + Fuse.js 重排，支持堆栈跟踪、拼写错误、Unicode 和标点繁多的日志。
• 可复用的搜索预设： 为反复出现的事件模式保存常用筛选条件和限制。
• 安全操作： 提供存储前脱敏选项、明确的破坏性操作确认，以及本地 HTTP 主机、来源、身份验证和请求体大小限制加固。
• 诊断： get_diagnostics 会返回经过脱敏的运行时、架构、软件包和健康状况信号，方便支持排查，同时不会泄露原始路径、令牌、堆栈跟踪或命令输出。
• 达到发布标准的软件包： 包含审计、覆盖率、模糊测试、软件包大小门槛、SBOM/VEX 策略、安装脚本审批、支持来源证明的发布工作流，以及 MCP Registry 就绪情况检查。

快速开始

需要 Node.js 22 LTS 或 24 LTS，以及 npm 10+。

npx debug-recorder-mcp

默认数据库路径：

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

使用自定义数据库路径：

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

MCP 客户端设置

桌面 MCP 客户端

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

VS Code / GitHub Copilot

创建或更新 .vscode/mcp.json：

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

更多设置示例请参阅客户端设置指南。

可用的 MCP 工具

工具	用途
start_debug_session	开始跟踪新的问题或事故。
add_fix	记录失败或成功的修复尝试。
record_command	保存命令、输出、退出代码和会话链接。
close_session	将会话标记为已解决或已放弃。
update_session	编辑标题、描述或标签。
delete_session	在明确确认后永久删除会话。
search_sessions	使用 FTS5、模糊重排、分页、相关分组和可选的 Markdown 导出搜索历史记录。
save_search_preset	保存可重复使用的查询、筛选条件和条数上限。
list_search_presets	列出已保存的搜索预设。
remove_search_preset	按名称移除已保存的搜索预设。
find_similar_errors	查询之前是否出现过类似错误。
get_session	获取完整详情、修复记录和命令。
get_session_context	获取适合 AI 阅读的会话摘要。
list_sessions	按筛选条件浏览会话。
get_stats	汇总调试历史记录。
get_diagnostics	返回经过脱敏的运行诊断快照。
export_sessions	导出完整 JSON 备份或轻量级摘要清单。
import_sessions	导入经过验证的导出数据。

实际使用示例

我以前遇到过这个问题吗？

向 MCP 客户端询问：

我遇到了 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。响应会标记为 format: "json"，并包含完整的 sessions、fixes 和 commands 数组。
2. 将返回的对象存储到备份系统中。
3. 之后通过将该对象作为 import_sessions.payload 传入来恢复。

如需轻量级清单，请使用 format: "summary" 调用 export_sessions。 摘要响应会标记为 format: "summary"，包含汇总的 stats 和简略的会话行，不能用作恢复负载。

HTTP 传输

该软件包还支持本地 Streamable HTTP：

npm run start:http

常用路由：

• GET /health
• GET /version
• MCP 端点：POST /mcp

HTTP 模式默认优先使用本地连接。它会绑定到 127.0.0.1，为每个请求创建独立的无状态 MCP 服务/传输，验证 Host，在存在浏览器 Origin 时进行验证，并在 MCP 传输接收请求前强制执行 JSON 请求体大小限制。

如需有意对非环回地址开放，请设置以下所有项：

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

远程模式不允许使用通配符来源。静态 Bearer 令牌属于私有/共享密钥模式：所有调用者共用一个身份、一种权限级别和一个 SQLite 数据集。此模式适用于环回连接、加密的可信网络或私有认证代理，但它不是 OAuth，也不提供按用户划分的作用域或撤销机制。

当前版本不支持面向公众的多用户 HTTP。已接受的目标架构采用外部授权服务器和支持 MCP 的网关，并具备受保护资源发现、受众绑定令牌、作用域、速率限制、审计事件和感知主体的存储功能。请参阅 公共 HTTP 授权和 ADR-0006。

配置

变量	说明
DEBUG_RECORDER_DB	覆盖 SQLite 数据库路径。
HOST	HTTP 绑定主机。默认为 127.0.0.1。
PORT	HTTP 端口。默认为 3000。
DEBUG_RECORDER_HTTP_TOKEN	私有/共享密钥令牌；非环回 HTTP 必需，不是 OAuth。
DEBUG_RECORDER_ALLOWED_HOSTS	以逗号分隔的 HTTP Host 允许列表。
DEBUG_RECORDER_ALLOWED_ORIGINS	以逗号分隔的浏览器 Origin 允许列表。
DEBUG_RECORDER_MAX_BODY_BYTES	HTTP JSON 请求体大小限制。默认为 1048576。
DEBUG_RECORDER_REMOTE_HTTP	将其设为 true、1 或 yes，以启用非环回 HTTP。
DEBUG_RECORDER_REDACT_BEFORE_STORE	将其设为 true、1 或 yes，以启用存储前脱敏。
LOG_LEVEL	结构化日志的最低级别：debug、info、warn 或 error。
FUZZY_THRESHOLD	覆盖 Fuse.js 重排序阈值。

布尔配置还接受 false、0 和 no；值不区分大小写，空格会被忽略，不受支持的值会导致程序立即失败。Diagnostics 报告的是已解析的有效值，而不是重新读取已更改的环境字符串。

数据与隐私

• 数据库：通过 better-sqlite3 使用本地 SQLite。
• 搜索索引：SQLite FTS5 虚拟表。
• 默认路径：~/.debug-recorder-mcp/sessions.db。
• 脱敏：可选择在存储前进行脱敏，并对诊断信息进行脱敏。
• 删除：破坏性操作需要明确确认。
• 维护：请参阅存储保留与维护。

better-sqlite3 使用原生插件。如果 Node 版本变更导致绑定失败，请运行 npm rebuild better-sqlite3。

Docker

docker build -t debug-recorder-mcp:local .
docker run --rm -p 127.0.0.1:3000:3000 \
  -e HOST=0.0.0.0 \
  -e DEBUG_RECORDER_REMOTE_HTTP=true \
  -e DEBUG_RECORDER_HTTP_TOKEN=replace-with-a-long-random-token \
  -e DEBUG_RECORDER_ALLOWED_HOSTS=127.0.0.1:3000,localhost:3000 \
  -e DEBUG_RECORDER_ALLOWED_ORIGINS=http://127.0.0.1:3000,http://localhost:3000 \
  debug-recorder-mcp:local

该镜像使用 npm ci 安装依赖，保留经过审核的原生安装脚本，移除开发依赖，并以非 root 用户 node 运行。

文档

已发布的文档由 npm run docs:site 生成，并发布到 GitHub Pages：

https://oaslananka.github.io/debug-recorder-mcp/

重要文档：

• 使用方法
• 客户端配置指南
• 配置
• 架构
• 安全
• 公共 HTTP 授权
• 运维
• 故障排查
• 存储保留
• 测试
• 发布流程
• 安装脚本策略
• SBOM/VEX 策略
• 架构决策记录

开发

npm ci
npm run format:check
npm run lint
npm run check:dead-code
npm run test:coverage
npm run test:fuzz
npm run build
npm run test:e2e
npm run audit
npm run check:install-scripts
npm pack --dry-run
npm run check:package-size
npm run check:version
npm run check:mcp
npm run check:security-policy
npm run check:sbom
npm run docs:site

完整的本地检查：

npm run ci:local

发布准备：

npm run prepublishOnly
npm run check:mcp-registry

发布与 npm 发布

常规发布工作流使用 Release Please，构建发布资源，生成 SBOM/校验和，为 tarball 生成证明，上传 GitHub Release 资源，并通过来源证明发布到 npm。

首次创建 npm 软件包时，请使用手动的 Initial npm Token Publish 工作流和仓库机密 NPM_TOKEN。软件包创建完成且配置好 npm 可信发布后，常规 Release 工作流即可通过 GitHub OIDC 发布。详情请参阅发布流程。

许可证

根据 MIT License 发布。package.json 还声明了 "license": "MIT"，且 npm 软件包包含 LICENSE。

赞助

如果此项目为你节省了调试时间，请在此支持开发：

• Buy Me a Coffee：https://www.buymeacoffee.com/oaslananka
• GitHub Sponsors：https://github.com/sponsors/oaslananka

赞助元数据可在 .github/FUNDING.yml 和 package.json 中找到。

Agent 插件与运行时配置

本仓库负责 debug-recorder-mcp 的产品级 Agent 插件、MCP 运行时配置和产品专属技能。中央的 agent-tools 仓库应收录此插件，但清单和工作流说明保存在此处，以便与实际的 MCP 服务软件包保持同步。

文件	用途
.claude-plugin/plugin.json	符合 Claude Code 要求的产品插件清单。
.mcp.json	Claude Code 项目本地 MCP 服务配置。
.codex/config.example.toml	Codex CLI MCP 配置示例。
.vscode/mcp.example.json	VS Code / GitHub Copilot 工作区 MCP 配置示例。
opencode.example.jsonc	OpenCode 项目 MCP 配置示例。
.opencode/skills/	OpenCode 原生镜像技能定义。
docs/agent-runtime-config.md	Agent 运行时设置与验证说明。

在本地验证插件打包：

claude plugin validate .