内容
# debug-recorder-mcp
<p align="center">
<strong>本地优先的MCP客户端调试内存。</strong><br />
在SQLite中记录事件、命令、失败尝试、成功修复、诊断和可搜索的调试历史。
</p>
<p align="center">
<a href="https://www.npmjs.com/package/debug-recorder-mcp"><img alt="npm版本" src="https://img.shields.io/npm/v/debug-recorder-mcp.svg" /></a>
<a href="https://www.npmjs.com/package/debug-recorder-mcp"><img alt="npm下载量" src="https://img.shields.io/npm/dm/debug-recorder-mcp.svg" /></a>
<a href="https://github.com/oaslananka/debug-recorder-mcp/actions/workflows/ci.yml"><img alt="持续集成" src="https://img.shields.io/github/actions/workflow/status/oaslananka/debug-recorder-mcp/ci.yml?branch=main&label=ci" /></a>
<a href="https://github.com/oaslananka/debug-recorder-mcp/actions/workflows/release.yml"><img alt="发布" src="https://img.shields.io/github/actions/workflow/status/oaslananka/debug-recorder-mcp/release.yml?branch=main&label=release" /></a>
<a href="https://github.com/oaslananka/debug-recorder-mcp/actions/workflows/docs.yml"><img alt="文档" src="https://img.shields.io/github/actions/workflow/status/oaslananka/debug-recorder-mcp/docs.yml?branch=main&label=docs" /></a>
<a href="https://github.com/oaslananka/debug-recorder-mcp/actions/workflows/codeql.yml"><img alt="CodeQL" src="https://img.shields.io/github/actions/workflow/status/oaslananka/debug-recorder-mcp/codeql.yml?branch=main&label=codeql" /></a>
<a href="./LICENSE"><img alt="许可证：MIT" src="https://img.shields.io/badge/license-MIT-green.svg" /></a>
<a href="https://www.buymeacoffee.com/oaslananka"><img alt="赞助" src="https://img.shields.io/badge/sponsor-Buy%20me%20a%20coffee-FFDD00?logo=buymeacoffee&logoColor=111827" /></a>
</p>
<p align="center">
<a href="https://oaslananka.github.io/debug-recorder-mcp/">已发布文档</a>
· <a href="./docs/usage.md">用法</a>
· <a href="./docs/client-recipes.md">客户端配方</a>
· <a href="./docs/security.md">安全</a>
· <a href="./docs/release-flow.md">发布流程</a>
</p>
<p align="center">
<a href="https://www.buymeacoffee.com/oaslananka">
<img src="https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=%E2%98%95&slug=oaslananka&button_colour=FFDD00&font_colour=000000&font_family=Arial&outline_colour=000000&coffee_colour=ffffff" alt="给我买杯咖啡" />
</a>
</p>
## 为什么存在
调试知识通常会消失在聊天窗口、终端和提交历史中。`debug-recorder-mcp` 为启用MCP的代理和IDE提供了一个持久的本地内存，以便它们能够回答：
> “我以前是否修复过这个问题？”
它将每个调试会话、错误、命令、尝试的修复、有效的修复、标签和上下文存储在本地SQLite数据库中。搜索结合了SQLite FTS5和模糊重新排序、可重复使用的预设、分页元数据、相关会话组和可选的Markdown导出。
## 亮点
- **本地优先存储：** 不需要外部数据库或托管服务。
- **MCP原生工具：** 适用于桌面MCP客户端的标准输入/输出服务器和可选的Streamable HTTP模式。
- **存活messy错误的搜索：** FTS5 + Fuse.js重新排序，用于堆栈跟踪、拼写错误、Unicode和标点符号繁重的日志。
- **可重复使用的搜索预设：** 保存常见的过滤器和限制，用于重复出现的事件模式。
- **安全操作：** 存储前删除、显式破坏性确认、本地HTTP主机/源/身份验证/正文限制强化。
- **诊断：** `get_diagnostics` 返回已编辑的运行时、模式、包和健康信号，用于支持而不泄露原始路径、令牌、堆栈跟踪或命令输出。
- **发布级打包：** 审计、覆盖率、模糊测试、包大小门控、SBOM/VEX策略、安装脚本批准、 provenance-ready发布工作流和MCP注册表就绪检查。
## 快速开始
需要Node.js **22 LTS** 或 **24 LTS** 和npm **10+**。
```bash
npx debug-recorder-mcp
```
默认数据库路径：
```text
~/.debug-recorder-mcp/sessions.db
```
使用自定义数据库路径：
```bash
DEBUG_RECORDER_DB=/path/to/custom.db npx debug-recorder-mcp
```
## MCP客户端设置
### 桌面MCP客户端
```json
{
"mcpServers": {
"debug-recorder-mcp": {
"command": "npx",
"args": ["debug-recorder-mcp"]
}
}
}
```
### VS Code / GitHub Copilot
创建或更新 `.vscode/mcp.json`：
```json
{
"servers": {
"debug-recorder-mcp": {
"type": "stdio",
"command": "npx",
"args": ["debug-recorder-mcp"]
}
}
}
```
更多设置示例请参见 [客户端设置配方](./docs/client-recipes.md)。
## 可用的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` | 导出本地历史记录以备备份或迁移。 |
| `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. 使用JSON输出调用 `export_sessions`。
2. 在备份系统中存储返回的有效载荷。
3. 使用 `import_sessions` 恢复。
## HTTP传输
软件包还支持本地Streamable HTTP：
```bash
npm run start:http
```
有用路由：
- `GET /health`
- `GET /version`
- MCP端点：`POST /mcp`
HTTP模式默认情况下是本地优先的。它绑定到 `127.0.0.1`，为每个请求创建隔离的无状态MCP服务器/传输，验证 `Host`，在存在时验证浏览器 `Origin`，并在MCP传输接收请求之前强制执行JSON正文大小限制。
对于刻意的非环回暴露，请设置所有这些：
```bash
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
```
远程模式拒绝通配符源。
## 配置
| 变量 | 描述 |
| --- | --- |
| `DEBUG_RECORDER_DB` | 重写SQLite数据库路径。 |
| `HOST` | HTTP绑定主机。默认为 `127.0.0.1`。 |
| `PORT` | HTTP端口。默认为 `3000`。 |
| `DEBUG_RECORDER_HTTP_TOKEN` | 本地HTTP的选项承载令牌；非环回HTTP必填。 |
| `DEBUG_RECORDER_ALLOWED_HOSTS` | 以逗号分隔的HTTP `Host`允许列表。 |
| `DEBUG_RECORDER_ALLOWED_ORIGINS` | 以逗号分隔的浏览器 `Origin`允许列表。 |
| `DEBUG_RECORDER_MAX_BODY_BYTES` | HTTP JSON正文限制。默认为 `1048576`。 |
| `DEBUG_RECORDER_REMOTE_HTTP` | 绑定到非环回主机之前必须为 `true`。 |
| `DEBUG_RECORDER_REDACT_BEFORE_STORE` | 设置为 `true` 以在持久化前编辑常见机密模式。 |
| `LOG_LEVEL` | 最小结构化日志级别：`debug`、`info`、`warn`或 `error`。 |
| `FUZZY_THRESHOLD` | 重写Fuse.js重新排序阈值。 |
## 数据和隐私
- 数据库：通过 `better-sqlite3` 实现的本地SQLite。
- 搜索索引：SQLite FTS5虚拟表。
- 默认路径：`~/.debug-recorder-mcp/sessions.db`。
- 编辑：存储前可选编辑 + 诊断编辑。
- 删除：破坏性操作需要明确确认。
- 维护：参见 [存储保留和维护](./docs/storage-retention.md)。
> `better-sqlite3` 使用原生插件。如果Node版本更改且绑定失败，请运行 `npm rebuild better-sqlite3`。
## Docker
```bash
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：
```text
https://oaslananka.github.io/debug-recorder-mcp/
```
重要文档：
- [用法](./docs/usage.md)
- [客户端设置配方](./docs/client-recipes.md)
- [配置](./docs/configuration.md)
- [架构](./docs/architecture.md)
- [安全](./docs/security.md)
- [操作](./docs/operations.md)
- [故障排除](./docs/troubleshooting.md)
- [存储保留](./docs/storage-retention.md)
- [测试](./docs/testing.md)
- [发布流程](./docs/release-flow.md)
- [安装脚本策略](./docs/install-script-policy.md)
- [SBOM/VEX策略](./docs/security-sbom-vex.md)
- [架构决策记录](./docs/adr/README.md)
## 开发
```bash
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 docs:site
```
完整本地门控：
```bash
npm run ci:local
```
发布就绪：
```bash
npm run prepublishOnly
npm run check:mcp-registry
```
## 发布和npm发布
正常的发布工作流程使用Release Please，构建发布资产，生成SBOM/校验和，证明tarball，上传GitHub Release资产，并使用provenance发布到npm。
对于第一个npm包创建，请使用带有存储库机密 `NPM_TOKEN` 的手动 **Initial npm Token Publish** 工作流程。创建包并配置npm信任发布后，可以通过GitHub OIDC发布常规 **Release** 工作流程。详细信息请参见 [发布流程](./docs/release-flow.md)。
## 许可证
在 [MIT License](./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` 中。
