McReplay
by YoyoLin008
README.md
# McReplay
**Catch breaking changes in McDonald's China MCP integrations with reproducible local tests.**
McReplay turns Model Context Protocol (MCP) responses into fixtures for testing skills, parsers, and adapters. It replaces response values with placeholders, compares snapshots for structural changes, and replays fixtures through a local MCP server. If a field disappears or an integer becomes a string, you can see where the change happened and reproduce it in an adapter test.
## Quick start
Use Python 3.11 or later on Linux or macOS. The demo runs offline after installation and uses synthetic data.
```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
```
Open `demo-output/report.html` to see three intentional breaking changes. The time field changes from an integer to a string, the campaign end date disappears, and the nutrition response changes from text to empty text. Use a fresh output directory each time you run `demo`. The CLI prompts and HTML report labels are currently in Chinese.
```bash
mcreplay compare demo-output/before.json demo-output/after.json
# Expected exit code: 2 (breaking changes).
```
To try an adapter test over MCP, run `python examples/check_adapter.py demo-output/before.json`. The check passes for `before.json`. With `after.json`, it detects the deliberate change to the `timestamp` field and exits with code `2`.

## Supported tools
McReplay supports calls with empty arguments (`{}`) for these three read-only tools.
| Tool | Response |
| --- | --- |
| `now-time-info` | Current time |
| `campaign-calendar` | Campaign calendar |
| `list-nutrition-foods` | Nutrition information for common menu items |
All three tools were queried on the official service on October 24, 2026. The resulting structures were captured and verified through local MCP replay. To run the same capture and replay checks **offline** using the bundled fixtures, run the following command from the repository root. [Live verification record](docs/LIVE_VERIFICATION.md)
```bash
python examples/check_recorded_structure.py
```
## Import and compare snapshots
`import` reads a JSON export of tool definitions and observations and saves it as a `mcreplay/v1` snapshot. It replaces strings, numbers, and booleans with placeholders while preserving field structure and MCP markers such as `isError`. It handles plain JSON, fenced JSON, JSON after an `## Original Response` heading, plain text, and empty text. [Import format and example](MCP_INTEGRATION.md#本地导入格式)
```bash
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
```
Keep exports and reports in the Git-ignored `private/` directory. Create the directory first and use new paths for output files. Raw export files remain on disk after import. Field names and tool definitions are retained, so review them before sharing a snapshot. [Local data handling](SECURITY.md)
`compare` checks for removed tools, newly required parameters, missing fields, changes in field types, and changes in how responses are wrapped. It prints findings in the terminal and can generate a standalone HTML report with `--html` or emit JSON with `--json`. [Comparison rules and limitations](docs/limitations.md)
| Exit code | Meaning |
| --- | --- |
| `0` | No changes or only informational findings |
| `1` | Invalid input or execution error |
| `2` | At least one potentially breaking change |
| `3` | Findings need review, with no breaking changes detected |
## Replay a fixture in an MCP client
McReplay uses the MCP Python SDK to serve responses over `stdio`. Add the following server to your client configuration and replace both paths with absolute paths on your machine.
```json
{
"mcpServers": {
"mcreplay-offline": {
"command": "/absolute/path/to/.venv/bin/mcreplay",
"args": ["replay", "/absolute/path/to/demo-output/before.json"]
}
}
}
```
Select `mcreplay-offline` in your client and call a tool included in the snapshot. The local server returns a fixture with placeholder values, so your adapter can exercise the same response structure without contacting the official service.
## Capture a response from the official service
1. Configure the official McDonald's China MCP server in your AI client. It uses `https://mcp.mcd.cn`, Streamable HTTP, and a bearer token. Keep the token in your client's secure configuration and follow the client's instructions for environment variable expansion. [Example configuration](mcp-config.example.json)
2. Add the [`skills/mcreplay/`](skills/mcreplay/SKILL.md) Skill to a client that supports `SKILL.md`. In the repository root, run `mkdir -m 700 private` if the directory does not already exist.
3. Add the local capture server below. Set absolute paths for the executable and a new output file inside `private/`.
```json
{
"mcpServers": {
"mcreplay-local": {
"command": "/absolute/path/to/.venv/bin/mcreplay",
"args": ["capture", "--out", "/absolute/path/to/private/observation.json"]
}
}
}
```
You can ask the client, “Check the current McDonald's campaigns and use McReplay to save the response structure for local testing.” The Skill passes the complete `CallToolResult` to `record_mcd_observation`. The capture server replaces the response values in memory before saving the snapshot. Each capture server instance writes one file. For another capture, set a new output path and restart the connection. [MCP integration guide](MCP_INTEGRATION.md)
```text
Official MCP response -> local capture or import -> structural snapshot
|-> compare -> terminal, HTML, or JSON
`-> replay -> local MCP client
```
## Development
```bash
python -m pip install -r requirements.lock
python -m pip install -e '.[dev]'
pytest -q
ruff check .
ruff format --check .
python -m build
```
The tests cover value replacement, malformed inputs, structural comparisons, and local MCP capture and replay. The linked project guides and verification records are currently in Chinese. [Contributing](CONTRIBUTING.md) · [QA and integration checks](docs/QA.md)
## Project background and license
McReplay grew out of a review of 33 tools documented by the official MCP project and 10 contest projects. [Capability matrix](docs/capability-matrix.md) · [Project research](docs/competitive-research.md) · [Project selection](docs/product-selection.md) · [Product requirements](docs/PRD.md)
The original project code and documentation are available under the [MIT License](LICENSE). Thanks to McDonald's China for publishing its MCP documentation, to the MCP Python SDK maintainers, and to developers who documented the integration issues that informed this project.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues