Skip to main content
Glama

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.

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.

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.

Illustrated preview of the three changes detected in the demo

Related MCP server: data-transformer

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

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

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

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

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.

{
  "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

  2. Add the skills/mcreplay/ 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/.

{
  "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

Official MCP response -> local capture or import -> structural snapshot
                                                    |-> compare -> terminal, HTML, or JSON
                                                    `-> replay  -> local MCP client

Development

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 · QA and integration checks

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 · Project research · Project selection · Product requirements

The original project code and documentation are available under the MIT 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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      A local-first, deterministic, read-only MCP server that audits test suites for false-green tests, tautological assertions, and mock-contract drift, ensuring tests truly validate production code. It provides tools to detect test fidelity issues, verify mock drift, and synthesize strict mock contracts.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides safe, deterministic inspection, transformation, validation, and diffing of structured data (JSON, CSV, YAML, Parquet) via schema-aware MCP tools.
      4
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides MCP tools for local code validation with execution evidence, enabling users to run planned checks on projects and receive JSON results that distinguish passing, failing, and incomplete outcomes.
      340 npm
      MIT