内容
# MCP 飞行记录器
[简体中文](./README.zh-CN.md) | English
> **MCP 飞行记录器是一款用于 MCP stdio 服务器的飞行记录器和重放调试器。**
MCP 飞行记录器位于 AI 代理（Claude Desktop、Claude Code、Cursor 等）和 Model Context Protocol stdio 服务器之间。它在两个方向上透明地转发每个 JSON-RPC 消息，同时记录结构化跟踪、风险注释的 HTML 时间线报告和可重放的日志。
它旨在用于三种工作流程：
- **观察** - 精确查看您的代理要求 MCP 服务器执行的操作。
- **审计** - 一目了然地标记危险访问（`.env`、`rm -rf`、`DROP TABLE`等）。
- **重现** - 差异化两个运行，或在新服务器上重放捕获的跟踪以比较行为。
无需守护进程，无需云端，无需 GUI 应用程序。只需一个 CLI，您就可以将其插入到任何 MCP stdio 服务器前面。
## 安装
```bash
npm install -g mcp-flight-recorder
# 或本地安装
npm install --save-dev mcp-flight-recorder
```
您也可以在不安装的情况下运行它：
```bash
npx mcp-flight-recorder wrap --trace ./trace.json -- <real-mcp-server-cmd>
```
## 快速入门
```bash
mcp-flight-recorder wrap \
--trace ./traces/fs.json \
--report ./traces/fs.html \
-- npx -y @modelcontextprotocol/server-filesystem .
```
`mcp-flight-recorder` 成为您的客户端与之通信的 MCP 服务器。它将启动真正的服务器作为子进程，转发两个方向上的每个行，并记录流量。当客户端断开连接时，跟踪 JSON 和 HTML 报告将被写入磁盘。
默认情况下，MCP 飞行记录器会编辑常见的包含机密的字段，如 `authorization`、`token`、`apiKey`、`password`、`secret` 和 `private_key`，并省略原始 JSON-RPC 行的已持久跟踪。仅在需要逐字节有效载荷捕获进行私有本地调试时，才使用 `--unsafe-raw`。
> **stdout 是神圣的。** 在 `wrap` 模式下，mcp-flight-recorder 永远不会向 stdout 写入除有效 MCP JSON-RPC 之外的任何内容。所有日志都输出到 stderr，并带有 `[mcp-flight-recorder]` 或 `[mcp-flight-recorder:server]` 前缀。
## 与 Claude Desktop / Claude Code 结合使用
在您的 MCP 配置中添加一个条目（路径必须为绝对路径）：
```json
{
"mcpServers": {
"filesystem-traced": {
"command": "npx",
"args": [
"-y", "mcp-flight-recorder",
"wrap",
"--trace", "/abs/path/traces/fs.json",
"--report", "/abs/path/traces/fs.html",
"--",
"npx", "-y", "@modelcontextprotocol/server-filesystem", "/abs/path/project"
]
}
}
}
```
参见 [`examples/claude-desktop-config.json`](./examples/claude-desktop-config.json)。
## CLI
### `mcp-flight-recorder wrap`
```bash
mcp-flight-recorder wrap --trace <path> [--report <path>] [--unsafe-raw] -- <server-cmd> [args...]
```
通过 mcp-flight-recorder 运行 MCP stdio 服务器。
默认跟踪是经过编辑的，以便更安全地共享。 `--unsafe-raw` 存储未编辑的有效载荷和原始 JSON-RPC 行。
### `mcp-flight-recorder report`
```bash
mcp-flight-recorder report ./trace.json --out ./report.html [--unsafe-raw]
```
从保存的跟踪中重新渲染 HTML 报告。 HTML 是一个自包含的文件 - 无需 CDN、无需字体、无需 JS 框架。 现有的跟踪文件在渲染时再次编辑，除非传递 `--unsafe-raw`。
### `mcp-flight-recorder diff`
```bash
mcp-flight-recorder diff ./old-trace.json ./new-trace.json [--unsafe-raw]
```
打印一份 Markdown 差异报告，显示：
- 添加/删除的 `tools/call`
- 调用参数发生变化的调用
- 新的/已解决的风险标志
- 侧边栏总结数字
差异输出默认编辑公共秘密字段。
### `mcp-flight-recorder replay`
```bash
mcp-flight-recorder replay ./trace.json -- <server-cmd> [args...]
```
将跟踪中的每个 `client_to_server` 请求/通知重放给新启动的服务器，然后打印一份 Markdown 摘要：
- 发送了多少条消息
- 收到了多少条消息
- 哪些请求 ID 从未得到响应
- 与原始跟踪相比，响应错误状态发生变化
重放是尽力而为的，不会保留原始时间。
如果跟踪是使用默认编辑捕获的，则重放使用编辑后的有效载荷。 使用 `wrap --unsafe-raw` 捕获时，需要精确重放敏感字段，并且跟踪将保持私密。
## 跟踪模式
跟踪是一个具有以下结构的单个 JSON 文件：
```jsonc
{
"version": "0.1.0",
"startedAt": "2026-04-29T12:00:00.000Z",
"endedAt": "2026-04-29T12:00:42.000Z",
"command": { "executable": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },
"summary": {
"messageCount": 42, "requestCount": 21, "responseCount": 20,
"notificationCount": 1, "toolCallsCount": 7,
"failedCount": 0, "riskCount": 2, "durationMs": 42000
},
"events": [
{
"seq": 1, "timestamp": "...", "direction": "client_to_server",
"jsonrpc": "2.0", "id": 1, "kind": "request", "method": "tools/call",
"params": { "name": "read_file", "arguments": { "path": ".env" } },
"result": null, "error": null,
"riskFlags": [{ "code": "sensitive_file", "severity": "high", "message": "..." }]
}
],
"calls": [
{
"id": 1, "method": "tools/call", "toolName": "read_file",
"startedAt": "...", "endedAt": "...", "durationMs": 42,
"params": { /* ... */ }, "result": { /* ... */ }, "error": null,
"riskFlags": [/* ... */]
}
]
}
```
`events` 是时间线。 `calls` 是按请求 ID 键控的派生视图，其中包含合并的响应。 默认情况下，原始 JSON-RPC 行被省略； 它们仅在捕获具有 `wrap --unsafe-raw` 的跟踪时才存在。
## 敏感数据
MCP 流量可能包括提示、文件内容、私有路径、API 密钥和其他机密。 在审查之前，请将跟踪、报告、差异和重放摘要视为敏感工件。 存储库 `.gitignore` 排除常见的跟踪和凭证文件模式，但您仍应在共享或提交它们之前检查工件。
## 风险检测
MCP 飞行记录器扫描每条消息以查找已知的风险模式，并用 `riskFlags` 标记它们。 它故意是一个简单的、基于正则表达式的扫描器 - 快速、可预测且易于扩展。 类别：
| 代码 | 严重程度 | 示例 |
| ------------------- | -------- | -------------------------------------- |
| `sensitive_file` | 高 | `.env`、`id_rsa`、`credentials` 等 |
| `dangerous_shell` | 高/中 | `rm -rf`、`curl … \| bash`、`chmod 777` |
| `dangerous_sql` | 高 | `DROP TABLE`、`DELETE FROM`、`TRUNCATE` |
| `sensitive_sql` | 中 | `SELECT * FROM users` |
| `dependency_change` | 中 | `package.json`、`pnpm-lock.yaml` 等 |
| `network_egress` | 低 | `https://…`、`curl`、`wget` |
预计会有误报。 目标是：没有任何风险的事情都不会被忽略。
## 路线图
- [ ] 可插拔的风险规则（从 JSON/TS 文件加载）
- [ ] 流式 JSONL 跟踪输出（按大小轮换）
- [ ] HTTP/SSE 传输（除了 stdio 之外）
- [ ] 可配置的编辑规则
- [ ] 带有断言模式的工具感知重放
欢迎提出问题和 PR。
## 贡献
```bash
npm install
npm run build
npm test
```
## 许可证
MIT
## 社区支持
- [LinuxDo](https://linux.do)
