MCP Time Travel

MCP代理的时间旅行调试

MCP代理缺少调试器

*如果你正在试验MCP代理并发现这很有用， 一⭐ 帮助他人发现项目。*

mcp-time-travel demo

代理很难调试。

常见问题：

• 工具调用失败，但您无法再现它
• 工作流依赖于外部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 overrides

inspect

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       Exit

list

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时间旅行的。