mcptape 0.1.0__tar.gz

mcptape-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 E'Angelo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcptape-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: mcptape
+Version: 0.1.0
+Summary: Tape recorder for the Model Context Protocol: record any MCP server once, replay it offline forever, diff what drifted. Zero dependencies.
+Author: E'Angelo
+License: MIT
+Project-URL: Repository, https://github.com/EAnge1o/mcptape
+Project-URL: Issues, https://github.com/EAnge1o/mcptape/issues
+Keywords: mcp,model-context-protocol,agent,replay,testing,record
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# mcptape
+
+<img src="docs/logo.svg" alt="mcptape" width="420" align="center" />
+
+[![ci](https://github.com/EAnge1o/mcptape/actions/workflows/ci.yml/badge.svg)](https://github.com/EAnge1o/mcptape/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mcptape)](https://pypi.org/project/mcptape/)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://python.org/)
+[![Dependency](https://img.shields.io/badge/dependencies-0-informational.svg)]()
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**mcptape** is a **tape recorder for the Model Context Protocol**: wrap any MCP server, record a session once (REC ⏺), replay it offline forever (PLAY ▶), and diff exactly where the tool behavior drifted (⏩).
+
+> Your agent talks to MCP servers — filesystem, browser, search, your own tools. Those servers change, their tools change, their results change, and your agent breaks in ways you cannot reproduce without paying for a dozen live runs. mcptape records the whole session — every `tools/call`, every result, every notification — as local JSONL. From then on, replay serves the recorded results offline for free and byte-identically, and one command diffs two recordings to the first drifted call.
+
+Zero dependencies: pure Python standard library. Nothing leaves your machine — a trace is a local file.
+
+![mcptape demo: record / replay / diff, rendered from real command output](docs/demo.svg)
+
+*(The screenshot is rendered from real command output by `docs/make_demo_svg.py` — not staged.)*
+
+中文文档：[README.zh-CN.md](README.zh-CN.md)
+
+## How it works
+
+```mermaid
+flowchart LR
+    A["MCP client<br/>(your agent)"] -->|"stdio"| B["mcptape rec<br/>transparent proxy ⏺"]
+    B -->|"stdio"| C["real MCP server"]
+    B --> D[".mcptape/runs/<br/>trace.jsonl + meta.json"]
+    A -->|"stdio"| E["mcptape play<br/>served from tape ▶"]
+    D -.->|"byte-for-byte"| E
+    F["second recording"] --> G["mcptape diff<br/>first drifted call"]
+    E -.-> G
+    G -->|"exit 0 / 1 / 2"| H["CI ✅ ❌"]
+```
+
+In **rec** mode mcptape is a transparent proxy: it spawns the real server, forwards every JSON-RPC line both ways unchanged, and files each message to the tape. Your agent cannot tell it is being recorded.
+
+In **play** mode mcptape *is* the server: it answers `initialize`, `tools/list` and `tools/call` from the tape — no child process, no network, identical results.
+
+## 30 seconds
+
+```bash
+pip install mcptape
+
+# 1. record a session: put mcptape between your client and any MCP server
+python examples/demo_client.py -- mcptape rec --name demo-stable -- python examples/demo_server.py
+
+# 2. replay it offline -- same results, no server process, $0.00
+python examples/demo_client.py -- mcptape play demo-stable
+
+# 3. the server changes; record again and diff
+MCPTAPE_DEMO_DRIFT=1 python examples/demo_client.py -- mcptape rec --name demo-drift -- python examples/demo_server.py
+mcptape diff demo-stable demo-drift
+```
+
+Real output (paste the commands and you get this verbatim):
+
+```
+=== replay ===
+server: demo-tools
+tools: echo, add
+echo: tapedeck, but for MCP
+add(2, 3): 5
+
+=== diff demo-stable demo-drift ===
+run A: demo-stable (11 events)
+run B: demo-drift (11 events)
+event 10 (s2c response):
+  result changed
+  A: {"result": {"content": [{"type": "text", "text": "5"}]}}
+  B: {"result": {"content": [{"type": "text", "text": "6"}]}}
+  context (events …i):
+    c2s/request tools/call
+    s2c/notification notifications/message
+```
+
+`diff` exit codes are designed for CI: `0` identical, `1` output drift, `2` structural drift.
+
+## In your agent config
+
+`rec` is one config edit away from any stdio-based MCP client (Claude Desktop, Claude Code, Cursor, ...):
+
+```json
+{
+  "mcpServers": {
+    "my-tools": {
+      "command": "mcptape",
+      "args": ["rec", "--name", "daily-run", "--", "python", "-m", "my_tools"]
+    }
+  }
+}
+```
+
+Flip `"rec"` to `"play", "daily-run"` and the agent runs against the tape — full regression pass with zero live calls. The client cannot tell the difference: same tools, same results, same notifications.
+
+## Why matching is by content, not position
+
+tapedeck aligns calls by position; MCP clients pipeline and run tool calls **in parallel**, so positional alignment would false-positive on every concurrent session. mcptape matches each incoming call against the earliest *unconsumed* recorded exchange with the same method and JSON-equal arguments. Identical repeated calls consume identical recorded entries in order; reordered or parallel calls match freely; a call whose arguments changed matches nothing — that is the drift, reported with the exact arguments.
+
+`initialize` is matched leniently on parameters (client name/version/protocol bumps are not behavior drift) and its recorded capabilities answer is served verbatim.
+
+## Why not LangSmith / LangFuse / OTel platforms
+
+| | Cloud observability | **mcptape** |
+|---|---|---|
+| Position | watch runs (dashboard) | **reproduce runs (recorder)** |
+| Replay | re-calls the tools (state changed, money spent) | **replays recorded results (free, deterministic)** |
+| Data | uploaded to a third party | **local files only** |
+| Dependencies | SDK + reporting config | zero, two commands |
+
+Complementary, not competing: platforms show trends; mcptape does forensics and regression. The same role [tapedeck](https://github.com/EAnge1o/tapedeck) plays for model calls, one layer down.
+
+## CLI
+
+```text
+mcptape rec --name RUN -- <server command>   # proxy + record a live session
+mcptape play RUN [--lenient]                 # serve a recording as an MCP server
+mcptape diff A B                             # first drift + context; exit 0/1/2
+mcptape ls                                   # list recorded runs
+mcptape report RUN                           # per-message table
+```
+
+![mcptape ls and report, rendered from real command output](docs/ls.svg)
+
+## Trace format
+
+One directory per run, two plain files:
+
+```
+.mcptape/runs/20261031-011921-demo-stable/
+    meta.json     # server command, protocol version, counts
+    trace.jsonl   # one JSON-RPC message per line, with request echoes
+```
+
+```json
+{"v": 1, "i": 10, "dir": "s2c", "kind": "response", "id": 4,
+ "payload": {"result": {"content": [{"type": "text", "text": "5"}]}},
+ "for_method": "tools/call", "for_params": {"name": "add", "arguments": {"a": 2, "b": 3}},
+ "wall_ms": 0.9}
+```
+
+Every response carries an echo of the request it answers, so each line is self-contained — replay and diff never need to join across lines.
+
+## Honest boundaries
+
+- **stdio transport only (v0.1).** HTTP/SSE-based MCP servers are not wrapped yet; streamable-HTTP support is on the roadmap.
+- **Sessions with server-initiated requests cannot be replayed.** If the server asked the client to sample or elicit, the tape would have to impersonate the client — `play` refuses such recordings up front (exit 2); `diff` still works on them.
+- **Replay is deterministic only up to the tape.** Client-side logic that reads the clock, uses randomness, or branches on anything outside the session may take a different path than during recording — that is true of every record/replay tool and is exactly what `diff` between two real recordings is for.
+- **Server-side state is frozen at record time.** Replaying a `tools/call` that wrote a file serves the recorded result without writing again; replay never touches the real world. If you need the side effects re-applied, that is a live run, not a replay.
+- **No monkeypatching.** `rec` is a proxy process; the client config opts in explicitly.
+
+## Roadmap
+
+- [ ] streamable-HTTP transport wrapping
+- [ ] `--subset` replay (serve only named tools from the tape, live for the rest)
+- [ ] trace signing (tamper-evident hash chain)
+- [ ] OTel GenAI span import/export
+
+## The tape suite
+
+The same "record once, replay forever" idea, at three layers:
+
+- **[tapedeck](https://github.com/EAnge1o/tapedeck)** — model & tool calls *inside* your agent (Python, PyPI)
+- **mcptape** — the MCP tool-protocol boundary (this repo)
+- **[mocktape](https://github.com/EAnge1o/mocktape)** — HTTP traffic behind your frontend (TypeScript, npm)
+
+Design trade-offs live in the source docstrings; every image in this README is rendered from real command output.

mcptape-0.1.0/README.md

@@ -0,0 +1,168 @@
+# mcptape
+
+<img src="docs/logo.svg" alt="mcptape" width="420" align="center" />
+
+[![ci](https://github.com/EAnge1o/mcptape/actions/workflows/ci.yml/badge.svg)](https://github.com/EAnge1o/mcptape/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mcptape)](https://pypi.org/project/mcptape/)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://python.org/)
+[![Dependency](https://img.shields.io/badge/dependencies-0-informational.svg)]()
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**mcptape** is a **tape recorder for the Model Context Protocol**: wrap any MCP server, record a session once (REC ⏺), replay it offline forever (PLAY ▶), and diff exactly where the tool behavior drifted (⏩).
+
+> Your agent talks to MCP servers — filesystem, browser, search, your own tools. Those servers change, their tools change, their results change, and your agent breaks in ways you cannot reproduce without paying for a dozen live runs. mcptape records the whole session — every `tools/call`, every result, every notification — as local JSONL. From then on, replay serves the recorded results offline for free and byte-identically, and one command diffs two recordings to the first drifted call.
+
+Zero dependencies: pure Python standard library. Nothing leaves your machine — a trace is a local file.
+
+![mcptape demo: record / replay / diff, rendered from real command output](docs/demo.svg)
+
+*(The screenshot is rendered from real command output by `docs/make_demo_svg.py` — not staged.)*
+
+中文文档：[README.zh-CN.md](README.zh-CN.md)
+
+## How it works
+
+```mermaid
+flowchart LR
+    A["MCP client<br/>(your agent)"] -->|"stdio"| B["mcptape rec<br/>transparent proxy ⏺"]
+    B -->|"stdio"| C["real MCP server"]
+    B --> D[".mcptape/runs/<br/>trace.jsonl + meta.json"]
+    A -->|"stdio"| E["mcptape play<br/>served from tape ▶"]
+    D -.->|"byte-for-byte"| E
+    F["second recording"] --> G["mcptape diff<br/>first drifted call"]
+    E -.-> G
+    G -->|"exit 0 / 1 / 2"| H["CI ✅ ❌"]
+```
+
+In **rec** mode mcptape is a transparent proxy: it spawns the real server, forwards every JSON-RPC line both ways unchanged, and files each message to the tape. Your agent cannot tell it is being recorded.
+
+In **play** mode mcptape *is* the server: it answers `initialize`, `tools/list` and `tools/call` from the tape — no child process, no network, identical results.
+
+## 30 seconds
+
+```bash
+pip install mcptape
+
+# 1. record a session: put mcptape between your client and any MCP server
+python examples/demo_client.py -- mcptape rec --name demo-stable -- python examples/demo_server.py
+
+# 2. replay it offline -- same results, no server process, $0.00
+python examples/demo_client.py -- mcptape play demo-stable
+
+# 3. the server changes; record again and diff
+MCPTAPE_DEMO_DRIFT=1 python examples/demo_client.py -- mcptape rec --name demo-drift -- python examples/demo_server.py
+mcptape diff demo-stable demo-drift
+```
+
+Real output (paste the commands and you get this verbatim):
+
+```
+=== replay ===
+server: demo-tools
+tools: echo, add
+echo: tapedeck, but for MCP
+add(2, 3): 5
+
+=== diff demo-stable demo-drift ===
+run A: demo-stable (11 events)
+run B: demo-drift (11 events)
+event 10 (s2c response):
+  result changed
+  A: {"result": {"content": [{"type": "text", "text": "5"}]}}
+  B: {"result": {"content": [{"type": "text", "text": "6"}]}}
+  context (events …i):
+    c2s/request tools/call
+    s2c/notification notifications/message
+```
+
+`diff` exit codes are designed for CI: `0` identical, `1` output drift, `2` structural drift.
+
+## In your agent config
+
+`rec` is one config edit away from any stdio-based MCP client (Claude Desktop, Claude Code, Cursor, ...):
+
+```json
+{
+  "mcpServers": {
+    "my-tools": {
+      "command": "mcptape",
+      "args": ["rec", "--name", "daily-run", "--", "python", "-m", "my_tools"]
+    }
+  }
+}
+```
+
+Flip `"rec"` to `"play", "daily-run"` and the agent runs against the tape — full regression pass with zero live calls. The client cannot tell the difference: same tools, same results, same notifications.
+
+## Why matching is by content, not position
+
+tapedeck aligns calls by position; MCP clients pipeline and run tool calls **in parallel**, so positional alignment would false-positive on every concurrent session. mcptape matches each incoming call against the earliest *unconsumed* recorded exchange with the same method and JSON-equal arguments. Identical repeated calls consume identical recorded entries in order; reordered or parallel calls match freely; a call whose arguments changed matches nothing — that is the drift, reported with the exact arguments.
+
+`initialize` is matched leniently on parameters (client name/version/protocol bumps are not behavior drift) and its recorded capabilities answer is served verbatim.
+
+## Why not LangSmith / LangFuse / OTel platforms
+
+| | Cloud observability | **mcptape** |
+|---|---|---|
+| Position | watch runs (dashboard) | **reproduce runs (recorder)** |
+| Replay | re-calls the tools (state changed, money spent) | **replays recorded results (free, deterministic)** |
+| Data | uploaded to a third party | **local files only** |
+| Dependencies | SDK + reporting config | zero, two commands |
+
+Complementary, not competing: platforms show trends; mcptape does forensics and regression. The same role [tapedeck](https://github.com/EAnge1o/tapedeck) plays for model calls, one layer down.
+
+## CLI
+
+```text
+mcptape rec --name RUN -- <server command>   # proxy + record a live session
+mcptape play RUN [--lenient]                 # serve a recording as an MCP server
+mcptape diff A B                             # first drift + context; exit 0/1/2
+mcptape ls                                   # list recorded runs
+mcptape report RUN                           # per-message table
+```
+
+![mcptape ls and report, rendered from real command output](docs/ls.svg)
+
+## Trace format
+
+One directory per run, two plain files:
+
+```
+.mcptape/runs/20261031-011921-demo-stable/
+    meta.json     # server command, protocol version, counts
+    trace.jsonl   # one JSON-RPC message per line, with request echoes
+```
+
+```json
+{"v": 1, "i": 10, "dir": "s2c", "kind": "response", "id": 4,
+ "payload": {"result": {"content": [{"type": "text", "text": "5"}]}},
+ "for_method": "tools/call", "for_params": {"name": "add", "arguments": {"a": 2, "b": 3}},
+ "wall_ms": 0.9}
+```
+
+Every response carries an echo of the request it answers, so each line is self-contained — replay and diff never need to join across lines.
+
+## Honest boundaries
+
+- **stdio transport only (v0.1).** HTTP/SSE-based MCP servers are not wrapped yet; streamable-HTTP support is on the roadmap.
+- **Sessions with server-initiated requests cannot be replayed.** If the server asked the client to sample or elicit, the tape would have to impersonate the client — `play` refuses such recordings up front (exit 2); `diff` still works on them.
+- **Replay is deterministic only up to the tape.** Client-side logic that reads the clock, uses randomness, or branches on anything outside the session may take a different path than during recording — that is true of every record/replay tool and is exactly what `diff` between two real recordings is for.
+- **Server-side state is frozen at record time.** Replaying a `tools/call` that wrote a file serves the recorded result without writing again; replay never touches the real world. If you need the side effects re-applied, that is a live run, not a replay.
+- **No monkeypatching.** `rec` is a proxy process; the client config opts in explicitly.
+
+## Roadmap
+
+- [ ] streamable-HTTP transport wrapping
+- [ ] `--subset` replay (serve only named tools from the tape, live for the rest)
+- [ ] trace signing (tamper-evident hash chain)
+- [ ] OTel GenAI span import/export
+
+## The tape suite
+
+The same "record once, replay forever" idea, at three layers:
+
+- **[tapedeck](https://github.com/EAnge1o/tapedeck)** — model & tool calls *inside* your agent (Python, PyPI)
+- **mcptape** — the MCP tool-protocol boundary (this repo)
+- **[mocktape](https://github.com/EAnge1o/mocktape)** — HTTP traffic behind your frontend (TypeScript, npm)
+
+Design trade-offs live in the source docstrings; every image in this README is rendered from real command output.

mcptape-0.1.0/mcptape/__init__.py

@@ -0,0 +1,26 @@
+"""mcptape -- a tape recorder for the Model Context Protocol.
+
+Wrap any MCP server with ``mcptape rec`` and its session lands on a local
+JSONL tape; replay it later with ``mcptape play`` and every tool call is
+served from the tape -- offline, free, byte-identical. Diff two recordings
+to find the first call where behavior drifted.
+
+    mcptape rec  --name run1 -- python my_mcp_server.py
+    mcptape play run1
+    mcptape diff run1 run2
+
+Zero dependencies: pure Python standard library. Sister of tapedeck
+(model calls) and mocktape (HTTP traffic) -- one metaphor per layer.
+"""
+
+from .diff import diff_runs
+from .proxy import RecordingProxy
+from .replay import ReplayingServer
+from .trace import DEFAULT_ROOT, Event, RunStore
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "RecordingProxy", "ReplayingServer", "Event", "RunStore", "diff_runs",
+    "DEFAULT_ROOT", "__version__",
+]

mcptape-0.1.0/mcptape/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m mcptape`` -- delegates to the CLI."""
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

mcptape-0.1.0/mcptape/cli.py

@@ -0,0 +1,167 @@
+"""``mcptape`` CLI: rec / play / diff / ls / report.
+
+    mcptape rec  --name run1 -- python my_mcp_server.py      # tape a live session
+    mcptape play run1                                        # serve it offline
+    mcptape diff run1 run2                                   # first drift, exit-coded
+
+``rec`` is a transparent proxy: the MCP client talks to mcptape's stdio,
+mcptape talks to the real server spawned behind ``--``. ``play`` replaces
+the server entirely -- no child, no network, byte-identical results.
+
+Exit codes on ``play``: 0 clean, 1 drift, 2 structural/unreplayable.
+Exit codes on ``diff``: 0 same, 1 output drift, 2 structural drift.
+Everything human-readable goes to stderr; stdout is the MCP wire.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .diff import EXIT_OUTPUT_DRIFT, EXIT_SAME, EXIT_STRUCTURE_DRIFT, diff_runs
+from .proxy import RecordingProxy
+from .replay import ReplayingServer
+from .trace import DEFAULT_ROOT, RunStore
+
+
+class _LineWriter:
+    """Binary-stream writer: encodes text as UTF-8 without touching line endings.
+
+    Callers (proxy/replay ``_send``) already append exactly one ``\\n``; adding
+    another here would double-space the MCP wire on every message.
+    """
+
+    def __init__(self, buffer):
+        self.buffer = buffer
+
+    def write(self, text: str) -> None:
+        self.buffer.write(text.encode("utf-8"))
+        self.buffer.flush()
+
+    def flush(self) -> None:
+        self.buffer.flush()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mcptape",
+        description="Tape recorder for the Model Context Protocol: record once, "
+                    "replay forever, diff what drifted.")
+    parser.add_argument("--root", type=Path, default=DEFAULT_ROOT,
+                        help=f"run storage root (default {DEFAULT_ROOT})")
+    parser.add_argument("--version", action="version", version=f"mcptape {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_rec = sub.add_parser("rec", help="proxy a live MCP server and record the session")
+    p_rec.add_argument("--name", default="session")
+    p_rec.add_argument("server_command", nargs=argparse.REMAINDER,
+                       help="server command to spawn, after --")
+
+    p_play = sub.add_parser("play", help="serve a recorded session as an MCP server")
+    p_play.add_argument("run")
+    p_play.add_argument("--lenient", action="store_true",
+                        help="on drift, serve the next recorded exchange (debugging only)")
+
+    p_diff = sub.add_parser("diff", help="compare two runs; exit 1 output drift, 2 structural")
+    p_diff.add_argument("a")
+    p_diff.add_argument("b")
+    p_diff.add_argument("--context", type=int, default=2)
+
+    sub.add_parser("ls", help="list recorded runs")
+
+    p_report = sub.add_parser("report", help="per-message table for one run")
+    p_report.add_argument("run")
+
+    return parser
+
+
+def cmd_rec(args) -> int:
+    command = [c for c in args.server_command if c != "--"]
+    if not command:
+        print("error: no server command given after --", file=sys.stderr)
+        return EXIT_STRUCTURE_DRIFT
+    proxy = RecordingProxy(sys.stdin, _LineWriter(sys.stdout.buffer), command)
+    try:
+        code = proxy.run(root=args.root)
+    except KeyboardInterrupt:
+        code = 130
+    run_dir = proxy.save(root=args.root, name=args.name)
+    exchanges = sum(1 for e in proxy.events if e.kind == "request" and e.dir == "c2s")
+    print(f"[recorded {len(proxy.events)} messages -> {run_dir} | {exchanges} exchanges]",
+          file=sys.stderr)
+    return code if code is not None else 0
+
+
+def cmd_play(args) -> int:
+    store = RunStore(args.root)
+    run_dir = store.resolve(args.run)
+    events, meta = RunStore.read_run(run_dir)
+    server = ReplayingServer(sys.stdin, _LineWriter(sys.stdout.buffer), events,
+                             lenient=args.lenient, label=meta.get("name", args.run))
+    return server.serve()
+
+
+def cmd_diff(args) -> int:
+    store = RunStore(args.root)
+    a_dir, b_dir = store.resolve(args.a), store.resolve(args.b)
+    events_a, meta_a = RunStore.read_run(a_dir)
+    events_b, meta_b = RunStore.read_run(b_dir)
+    result = diff_runs(events_a, events_b, meta_a, meta_b, context=args.context)
+    print("\n".join(result["lines"]))
+    if result["same"]:
+        return EXIT_SAME
+    return EXIT_STRUCTURE_DRIFT if result["structural"] else EXIT_OUTPUT_DRIFT
+
+
+def cmd_ls(args) -> int:
+    store = RunStore(args.root)
+    runs = store.list_runs()
+    if not runs:
+        print(f"no runs under {store.root}")
+        return 0
+    width = max(len(r.name) for r in runs) + 2
+    print(f"{'run':<{width}} {'exchanges':>9} {'messages':>8}  name")
+    for run_dir in runs:
+        try:
+            events, meta = RunStore.read_run(run_dir)
+        except (ValueError, OSError):
+            continue
+        exchanges = sum(1 for e in events if e.kind == "request" and e.dir == "c2s")
+        print(f"{run_dir.name:<{width}} {exchanges:>9} {len(events):>8}  {meta.get('name', '')}")
+    return 0
+
+
+def cmd_report(args) -> int:
+    store = RunStore(args.root)
+    run_dir = store.resolve(args.run)
+    events, meta = RunStore.read_run(run_dir)
+    print(f"run {run_dir.name}")
+    print(f"  server: {' '.join(meta.get('server_command', [])) or '?'}  "
+          f"protocol: {meta.get('protocol_version', '?')}")
+    print(f"  {'#':>3}  {'dir':<4} {'kind':<13} {'method':<28} usage")
+    for e in events:
+        name = e.method or (e.for_method or "")
+        print(f"  {e.i:>3}  {e.dir:<4} {e.kind:<13} {name:<28}"
+              + (f"  id={e.id}" if e.id is not None else ""))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "rec":
+        return cmd_rec(args)
+    if args.command == "play":
+        return cmd_play(args)
+    if args.command == "diff":
+        return cmd_diff(args)
+    if args.command == "ls":
+        return cmd_ls(args)
+    if args.command == "report":
+        return cmd_report(args)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mcptape-0.1.0/mcptape/diff.py

@@ -0,0 +1,93 @@
+"""Diff two recorded MCP sessions: the first divergence, with context.
+
+Position-based comparison (two recordings of the same scripted session line
+up step for step, like tapedeck's runs). Exit codes are the CI contract:
+
+* ``0`` -- identical sessions;
+* ``1`` -- output drift: same call at the same position, different
+  arguments or a different result;
+* ``2`` -- structural drift: sessions have different lengths, or the same
+  position holds different kinds/methods (calls added, removed, reordered).
+"""
+from __future__ import annotations
+
+import json
+
+EXIT_SAME = 0
+EXIT_OUTPUT_DRIFT = 1
+EXIT_STRUCTURE_DRIFT = 2
+
+
+def _short(value, limit: int = 120) -> str:
+    text = json.dumps(value, ensure_ascii=False) if not isinstance(value, str) else value
+    return text if len(text) <= limit else text[:limit] + "…"
+
+
+def diff_runs(events_a, events_b, meta_a: dict, meta_b: dict, context: int = 2) -> dict:
+    lines: list[str] = []
+    lines.append(f"run A: {meta_a.get('name', '?')} ({len(events_a)} events)")
+    lines.append(f"run B: {meta_b.get('name', '?')} ({len(events_b)} events)")
+
+    result = {"same": True, "structural": False, "first_divergence": None, "reason": None,
+              "lines": lines}
+
+    def divergence(i: int, why: str, detail: list[str], structural: bool) -> None:
+        result["same"] = False
+        result["first_divergence"] = i
+        result["reason"] = why
+        result["structural"] = structural
+        lines.append(f"event {i} ({events_a[i].dir} {events_a[i].kind}):")
+        lines.append(f"  {why}")
+        lines.extend(detail)
+        ctx = [f"    {e.dir}/{e.kind} {e.method or e.for_method or ''}" for e in
+               events_a[max(0, i - context):i]]
+        if ctx:
+            lines.append("  context (events …i):")
+            lines.extend(ctx)
+
+    n = max(len(events_a), len(events_b))
+    for i in range(n):
+        if i >= len(events_a) or i >= len(events_b):
+            longer = "A" if len(events_a) > len(events_b) else "B"
+            divergence(min(i, len(events_a) - 1) if events_a else 0,
+                       "structural",
+                       [f"  run {longer} continues past the other "
+                        f"({abs(len(events_a) - len(events_b))} extra event(s))"],
+                       structural=True)
+            break
+        a, b = events_a[i], events_b[i]
+        if (a.dir, a.kind, a.method) != (b.dir, b.kind, b.method):
+            divergence(i, "structural",
+                       [f"  A: {a.dir} {a.kind} {a.method or ''}",
+                        f"  B: {b.dir} {b.kind} {b.method or ''}"],
+                       structural=True)
+            break
+        if a.kind == "request":
+            if not _eq(a.params, b.params):
+                divergence(i, "arguments changed",
+                           [f"  A: params {_short(a.params)}",
+                            f"  B: params {_short(b.params)}"], structural=False)
+                break
+        elif a.kind == "response":
+            if not _eq(a.payload, b.payload):
+                divergence(i, "result changed",
+                           [f"  A: {_short(a.payload)}",
+                            f"  B: {_short(b.payload)}"], structural=False)
+                break
+        elif a.kind == "notification":
+            if not _eq(a.params, b.params):
+                divergence(i, "notification changed",
+                           [f"  A: {_short(a.params)}",
+                            f"  B: {_short(b.params)}"], structural=False)
+                break
+
+    if result["same"]:
+        lines.append("sessions are identical")
+    return result
+
+
+def _eq(a, b) -> bool:
+    try:
+        return json.loads(json.dumps(a)) == json.loads(json.dumps(b))
+    except (TypeError, ValueError):
+        return a == b