把一次麦当劳 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 回放验证，详见 实测记录。
运行环境：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 客户端完成三项样本的接收和回放，并验证时间、活动及营养响应的字段格式。
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/ 目录，每次导入使用新的输出文件名。
在客户端中添加以下 stdio 连接，并替换为本机的绝对路径：
{
"mcpServers": {
"mcreplay-offline": {
"command": "/absolute/path/to/.venv/bin/mcreplay",
"args": ["replay", "/absolute/path/to/demo-output/before.json"]
}
}
}选择 mcreplay-offline 连接，调用已记录的工具，即可把结构样本送入适配器测试。
将仓库的 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 build120 项测试覆盖值删除、异常输入、结构差异和本地 MCP 协议路径。测试结果与集成验证进度见 QA 记录。
选题前检查了全部 33 个官方文档工具和 10 个参赛项目的 README 与实现：能力矩阵、竞争研究、加权选题、PRD。
代码采用 MIT 许可。感谢麦当劳中国开放 MCP 文档、MCP Python SDK 维护者和公开记录问题的开发者。