MCP代理的时间旅行调试
MCP代理缺少调试器
*如果你正在试验MCP代理并发现这很有用， 一⭐ 帮助他人发现项目。*
代理很难调试。
常见问题：
- 工具调用失败，但您无法再现它
- 工作流依赖于外部API
- 调试需要重新运行代理
- 失败是不确定的
mcp时间旅行通过记录mcp会话并确定地重放它们来解决这个问题。
mcp时间旅行是一个透明的代理，位于AI代理（Claude Code、Cursor等）和真实的mcp服务器之间。它通过完整的输入/输出和定时元数据捕获每个工具调用。录制的会话可以确定地重放，可以交互式地逐步调试，也可以用快速摘要视图进行检查。
特性
- 透明MCP代理
- 工具会话的确定性回放
- 交互式步骤调试器
- 调试期间修改输入/输出
- 离线工作
- 无需对现有MCP服务器进行更改
兼容：
- 克劳德代码
- 光标
- 任何使用stdio的MCP服务器
快速开始
录制会话
npx mcp-time-travel record --server my-server这将代理代理和真实MCP服务器之间的所有流量，将每次工具调用记录到磁盘上。
重播会话
npx mcp-time-travel replay 将记录的响应作为功能齐全的MCP服务器提供。不需要真正的服务器——离线工作。
调试会话
npx mcp-time-travel debug 交互式调试步骤。检查每个工具调用，修改输入，覆盖输出。
检查会话
npx mcp-time-travel inspect 打印带有工具调用频率、条形图和时间线的非交互式摘要，非常适合截图和快速评论。
列出会话
npx mcp-time-travel list释放
对更改已发货包裹行为的拉取请求使用Changeset：
npm run changeset选择合适的semver凹凸：
patch用于修复和小的行为更改minor用于向后兼容功能major为了打破变化
仅文档、仅工作流和仅测试拉取请求不需要变更集。
发布管理在 main合并可发布的工作更新或打开发布PR。合并该发布PR会碰撞包版本，更新更新日志，创建GitHub release和标签，并将包发布到npm。手动版本编辑、标签和GitHub发布不再是正常流程的一部分。
配置
record 和 replay 是 MCP服务器 --它们需要在MCP配置中有一个条目，以便您的代理（Claude Code、Cursor等）可以连接到它们。
list, inspect，以及 debug 是 CLI命令 --直接在终端中运行它们。不需要配置。
用克劳德码录音
将真实服务器和录制代理添加到MCP配置中（项目范围 .mcp.json 或全球 ~/.claude/mcp.json):
{
"mcpServers": {
"my-server": {
"command": "npx",
"args": ["my-mcp-server"]
},
"my-server-recorded": {
"command": "npx",
"args": ["mcp-time-travel", "record", "--server", "my-server"]
}
}
}这 --server 标志指向同一配置文件中的另一个条目——mcp时间旅行读取它以生成真实的服务器。使用 my-server-recorded Claude Code中的服务器记录会话。
检查和调试（CLI）
录制后，直接在终端中使用CLI：
npx mcp-time-travel list # find your session ID
npx mcp-time-travel inspect # summary, top tools, timeline
npx mcp-time-travel debug # interactive step-through用Claude代码回放
在MCP配置中添加重播条目：
{
"mcpServers": {
"my-server-replay": {
"command": "npx",
"args": ["mcp-time-travel", "replay", "SESSION_ID"]
}
}
}重新启动Claude代码并使用 my-server-replay它为记录的响应提供服务，不需要真正的服务器。
CLI参考
record
npx mcp-time-travel record --server [options]
Options:
--server Server name in the config file (required)
--config
Path to MCP config JSON (default: .mcp.json or ~/.claude/mcp.json)
--session Custom session ID (default: auto-generated)
--output Output directory (default: .mcp-time-travel/)replay
npx mcp-time-travel replay [options]
Options:
--dir Sessions directory (default: .mcp-time-travel/)
--override JSON file with input/output overridesinspect
npx mcp-time-travel inspect [options]
Options:
--dir Sessions directory (default: .mcp-time-travel/)debug
npx mcp-time-travel debug [options]
Options:
--dir Sessions directory (default: .mcp-time-travel/)
--step Start at step N (default: 1)
Interactive commands:
n / next Next tool call
p / prev Previous tool call
l / list List all tool calls
g Go to step N
m / modify Edit input JSON
o / override Override output JSON
h / help Show help
q / quit Exitlist
npx mcp-time-travel list [options]
Options:
--dir Sessions directory (default: .mcp-time-travel/)会话存储
会话存储在 .mcp-time-travel/sessions//:
.mcp-time-travel/
sessions/
/
metadata.json # Session info, timestamps, tool list
recording.jsonl # Tool calls as newline-delimited JSON元数据.json
{
"id": "20260312-100000-abc",
"serverName": "my-server",
"serverConfig": { "command": "node", "args": ["server.js"] },
"startTime": "2026-03-12T10:00:00.000Z",
"endTime": "2026-03-12T10:05:00.000Z",
"toolCount": 5,
"tools": ["read_file", "write_file", "run_query"]
}录制.jsonl
每一行都是一个JSON对象：
{"seq": 1, "timestamp": "2026-03-12T10:00:01.000Z", "type": "tool_call", "tool": "read_file", "input": {"path": "/foo/bar.ts"}, "output": {"content": [{"type": "text", "text": "..."}]}, "latency_ms": 42, "is_error": false}超控系统
创建一个JSON文件以在回放期间覆盖特定的工具调用响应：
{
"overrides": [
{ "seq": 3, "output": { "content": [{ "type": "text", "text": "modified response" }] } },
{ "seq": 5, "input": { "query": "SELECT * FROM users LIMIT 1" } }
]
}与...一起使用 --override:
npx mcp-time-travel replay SESSION_ID --override overrides.json在回放过程中，如果当前序列号存在覆盖，它将替换记录的数据。
运作原理
记录模式
Agent (Claude Code, Cursor, etc.)
| stdio (JSON-RPC)
v
mcp-time-travel (proxy)
| ├── Intercepts tools/call messages
| ├── Logs to .mcp-time-travel/sessions//recording.jsonl
| └── Forwards everything to real server
v
Real MCP Server (child process, stdio)代理从Claude Code读取真实的服务器配置 mcpServers 格式化，将服务器作为子进程生成，并通过管道传输所有JSON-RPC流量。工具调用与输入、输出和延迟一起被捕获。所有其他消息都保持不变。
重播模式
Agent
| stdio (JSON-RPC)
v
mcp-time-travel (replay server)
| ├── Reads recording.jsonl
| ├── tools/list → returns recorded tool list
| └── tools/call → returns recorded output (matched by sequence)
|
(no real server needed)完全替换真实服务器。工具调用按序列号匹配——第N个调用返回第N个记录的响应。如果代理发送的工具名称与预期不同，则会记录警告，但仍会返回记录的输出，以保持重播的确定性。
调试模式
Terminal
|
mcp-time-travel debug
| ├── Reads recording.jsonl
| ├── Displays each call interactively
| └── Allows modify/skip/override不是MCP服务器，而是用于检查和修改记录会话的独立终端UI。
许可证
麻省理工学院
贡献
欢迎发布问题和PR。
如果你使用MCP代理并遇到调试问题，我很想听听你是如何使用MCP时间旅行的。