YoyoLin008/mcreplay

选用指南

AI 根据 README 整理 · 2026/10/25 03:26:11

适用场景

适用于需要验证麦当劳MCP查询结果结构变化、进行适配器回归测试或本地回放MCP样本的场景。

查看 README 依据

# McReplay · 麦回放 **把一次麦当劳 MCP 查询变成可复现的本地结构测试。** 面向维护麦当劳 MCP Skill、解析器和演示应用的个人开发者：删除响应真实值，保留结构，比较变化，再通过标准 MCP 在本地回放。  ## 解决什么问题 “昨天能解析，今天为什么空了？”字段类型改变、活动字段消失、文本返回变空，都可能让已有解析器失效。McReplay 把这些变化变成可定位、可复现的测试结果。 开发流程：在 AI 客户端中查询 → 本地提取结构 → 比较变化 → 回放样本，运行适配器回归测试。 - **结构观察包**：识别完整 JSON、代码围栏 JSON、`## Original Response` 后的 JSON，以及未解析文本与空文本。 - **变化检测**：工具删除、必填参数增加、字段消失、类型和封装变化；区分 `breaking`、`review`、`info`。 - **本地 MCP 回放**：官方 Python MCP SDK、stdio 协议；复用已记录的三种只读工具。 - **本地接收工具与 Skill**：接收一次正常官方查询的结果，在内存中删除原值后写入文件。 - **可用于 CI**：离线命令、明确退出码和独立 HTML 报告。

目标用户

面向维护麦当劳MCP Skill、解析器和演示应用的个人开发者。

查看 README 依据

# McReplay · 麦回放 **把一次麦当劳 MCP 查询变成可复现的本地结构测试。** 面向维护麦当劳 MCP Skill、解析器和演示应用的个人开发者：删除响应真实值，保留结构，比较变化，再通过标准 MCP 在本地回放。  ## 解决什么问题 “昨天能解析，今天为什么空了？”字段类型改变、活动字段消失、文本返回变空，都可能让已有解析器失效。McReplay 把这些变化变成可定位、可复现的测试结果。 开发流程：在 AI 客户端中查询 → 本地提取结构 → 比较变化 → 回放样本，运行适配器回归测试。 - **结构观察包**：识别完整 JSON、代码围栏 JSON、`## Original Response` 后的 JSON，以及未解析文本与空文本。 - **变化检测**：工具删除、必填参数增加、字段消失、类型和封装变化；区分 `breaking`、`review`、`info`。 - **本地 MCP 回放**：官方 Python MCP SDK、stdio 协议；复用已记录的三种只读工具。 - **本地接收工具与 Skill**：接收一次正常官方查询的结果，在内存中删除原值后写入文件。 - **可用于 CI**：离线命令、明确退出码和独立 HTML 报告。

使用方式

通过命令行使用，提供demo、compare、import、replay等子命令，也可作为MCP服务通过stdio协议连接。

查看 README 依据

支持的工具包括 `now-time-info`、`campaign-calendar`、`list-nutrition-foods`。三项工具已于 2026-10-24 完成官方认证查询、结构提取与本地 MCP 回放验证，详见 [实测记录](docs/LIVE_VERIFICATION.md)。 ## 30 秒离线试用 运行环境：Python 3.11+，Linux 或 macOS。 ```bash 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`，查看三处预设的结构变化。演示使用合成样本；每次运行选择一个新输出目录。 ```bash mcreplay compare demo-output/before.json demo-output/after.json # 该演示包含破坏性变化，因此 compare 预期退出码为 2。 ```

导入格式与字段含义见 [集成文档](MCP_INTEGRATION.md#本地导入格式)。输入与输出保存在本地 `private/` 目录，每次导入使用新的输出文件名。 ### 2. 用本地样本测试 MCP 客户端 在客户端中添加以下 stdio 连接，并替换为本机的绝对路径： ```json { "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](skills/mcreplay/SKILL.md)。连接官方 MCP 及本地接收服务：

部署要求

需要Python 3.11+，Linux或macOS。

查看 README 依据

支持的工具包括 `now-time-info`、`campaign-calendar`、`list-nutrition-foods`。三项工具已于 2026-10-24 完成官方认证查询、结构提取与本地 MCP 回放验证，详见 [实测记录](docs/LIVE_VERIFICATION.md)。 ## 30 秒离线试用 运行环境：Python 3.11+，Linux 或 macOS。 ```bash 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`，查看三处预设的结构变化。演示使用合成样本；每次运行选择一个新输出目录。 ```bash mcreplay compare demo-output/before.json demo-output/after.json # 该演示包含破坏性变化，因此 compare 预期退出码为 2。 ```

已知限制

演示使用合成样本，每次运行需选择新输出目录；接收服务要求父目录已存在且输出文件尚未存在。

查看 README 依据

支持的工具包括 `now-time-info`、`campaign-calendar`、`list-nutrition-foods`。三项工具已于 2026-10-24 完成官方认证查询、结构提取与本地 MCP 回放验证，详见 [实测记录](docs/LIVE_VERIFICATION.md)。 ## 30 秒离线试用 运行环境：Python 3.11+，Linux 或 macOS。 ```bash 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`，查看三处预设的结构变化。演示使用合成样本；每次运行选择一个新输出目录。 ```bash mcreplay compare demo-output/before.json demo-output/after.json # 该演示包含破坏性变化，因此 compare 预期退出码为 2。 ```

先在项目目录运行 `mkdir -m 700 private`，再将下面的绝对路径替换为本机实际路径。接收服务要求父目录已存在，输出文件尚未存在。 ```json { "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](mcp-config.example.json)；环境变量展开方式因客户端而异，须按客户端文档配置。凭证保存在客户端的安全配置中。 ## 架构 ```text