McReplay · 麦回放

把一次麦当劳 MCP 查询变成可复现的本地结构测试。

面向维护麦当劳 MCP Skill、解析器和演示应用的个人开发者：删除响应真实值，保留结构，比较变化，再通过标准 MCP 在本地回放。

解决什么问题

“昨天能解析，今天为什么空了？”字段类型改变、活动字段消失、文本返回变空，都可能让已有解析器失效。McReplay 把这些变化变成可定位、可复现的测试结果。

开发流程：在 AI 客户端中查询 → 本地提取结构 → 比较变化 → 回放样本，运行适配器回归测试。

• 结构观察包：识别完整 JSON、代码围栏 JSON、## Original Response 后的 JSON，以及未解析文本与空文本。

• 变化检测：工具删除、必填参数增加、字段消失、类型和封装变化；区分 breaking、review、info。

• 本地 MCP 回放：官方 Python MCP SDK、stdio 协议；复用已记录的三种只读工具。

• 本地接收工具与 Skill：接收一次正常官方查询的结果，在内存中删除原值后写入文件。

• 可用于 CI：离线命令、明确退出码和独立 HTML 报告。

支持的工具包括 now-time-info、campaign-calendar、list-nutrition-foods。三项工具已于 2026-10-24 完成官方认证查询、结构提取与本地 MCP 回放验证，详见 实测记录。

Related MCP server: data-transformer

30 秒离线试用

运行环境：Python 3.11+，Linux 或 macOS。

git clone https://github.com/YoyoLin008/mcreplay.git
cd mcreplay
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
mcreplay demo --out-dir demo-output

打开 demo-output/report.html，查看三处预设的结构变化。演示使用合成样本；每次运行选择一个新输出目录。

mcreplay compare demo-output/before.json demo-output/after.json
# 该演示包含破坏性变化，因此 compare 预期退出码为 2。

可运行 python examples/check_adapter.py demo-output/before.json 查看独立 SDK 适配器通过；将文件换成 after.json 会检测到刻意加入的类型变化并退出 2。

退出码：0 无变化或仅信息项；2 有破坏性风险；3 仅需人工复核；1 输入或执行失败。

回放官方实测结构

仓库附带由三项官方查询提取的结构样本，可直接运行：

python examples/check_recorded_structure.py

该检查通过标准 MCP 客户端完成三项样本的接收和回放，并验证时间、活动及营养响应的字段格式。

三个实际开发工作流

1. 修改解析器前，先比较样本

mcreplay import private/export-before.json --out private/before.json
mcreplay import private/export-after.json --out private/after.json
mcreplay compare private/before.json private/after.json --html private/report.html

导入格式与字段含义见 集成文档。输入与输出保存在本地 private/ 目录，每次导入使用新的输出文件名。

2. 用本地样本测试 MCP 客户端

在客户端中添加以下 stdio 连接，并替换为本机的绝对路径：

{
  "mcpServers": {
    "mcreplay-offline": {
      "command": "/absolute/path/to/.venv/bin/mcreplay",
      "args": ["replay", "/absolute/path/to/demo-output/before.json"]
    }
  }
}

选择 mcreplay-offline 连接，调用已记录的工具，即可把结构样本送入适配器测试。

3. 在正常 AI 客户端中保存一次结构观察

将仓库的 skills/mcreplay/ 作为一个技能目录导入支持 SKILL.md 的客户端（目录位置按客户端文档设置）；详细步骤见 Skill。连接官方 MCP 及本地接收服务：

先在项目目录运行 mkdir -m 700 private，再将下面的绝对路径替换为本机实际路径。接收服务要求父目录已存在，输出文件尚未存在。

{
  "mcpServers": {
    "mcreplay-local": {
      "command": "/absolute/path/to/.venv/bin/mcreplay",
      "args": ["capture", "--out", "/absolute/path/to/private/observation.json"]
    }
  }
}

向客户端明确提出：“查询一次当前麦当劳活动，并用 McReplay 保存其结构供我本地测试。”Skill 执行这次只读查询，再将完整 CallToolResult 交给本地 record_mcd_observation。一次接收服务只写一个新文件；需要新观察时配置新路径并重启。

官方连接使用 https://mcp.mcd.cn、Streamable HTTP 和 Bearer Token。配置示例见 mcp-config.example.json；环境变量展开方式因客户端而异，须按客户端文档配置。凭证保存在客户端的安全配置中。

架构

用户明确查询 → 正常 AI MCP 客户端 → 官方 MCP（三种只读工具）
                         │ 完整结果，瞬时传递
                         ▼
                 本地 capture / import
                  验证 → 删除值 → 结构包
                            ├─ compare → 终端 / HTML / CI 退出码
                            └─ replay → 本地 stdio MCP → 适配器

CLI 负责导入和比较，MCP 服务负责接收和回放。字符串、数字、布尔值替换为占位符，字段结构与 MCP 协议标记保留。

测试与开发

# requirements.lock 记录本次验证的完整运行依赖版本（不含工具开发依赖）
python -m pip install -r requirements.lock
python -m pip install -e '.[dev]'
pytest -q
ruff check .
python -m build

120 项测试覆盖值删除、异常输入、结构差异和本地 MCP 协议路径。测试结果与集成验证进度见 QA 记录。

使用文档

• MCP 集成与数据格式

• 比较规则与支持范围

• 本地数据管理

• 参与开发

研究、许可与致谢

选题前检查了全部 33 个官方文档工具和 10 个参赛项目的 README 与实现：能力矩阵、竞争研究、加权选题、PRD。

代码采用 MIT 许可。感谢麦当劳中国开放 MCP 文档、MCP Python SDK 维护者和公开记录问题的开发者。