mcptape 0.1.0__py3-none-any.whl

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/__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/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/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

mcptape/proxy.py

@@ -0,0 +1,187 @@
+"""REC mode: a transparent recording proxy between an MCP client and a server.
+
+    MCP client ⇄ mcptape rec ⇄ real MCP server
+
+mcptape spawns the real server as a child process and pumps JSON-RPC lines
+both ways unchanged. Every message is filed to the tape:
+
+* client→server requests are recorded with their ``params``;
+* each response is recorded with an echo of the request it answers (looked
+  up by JSON-RPC ``id``), so every trace line is self-contained;
+* server→client notifications are recorded in place and re-emitted on
+  replay; server→client *requests* (sampling, elicitation, ...) are passed
+  through and recorded too -- but a session containing them cannot be
+  replayed (the tape would have to impersonate the client), which replay
+  reports up front.
+
+Tracing must never break a session: a malformed line is forwarded untouched
+and counted as a warning, and the trace is saved even if the session dies
+mid-flight. The child's stderr is inherited, not recorded (servers log
+there; logs are not the tape).
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import threading
+import time
+
+from .trace import Event, RunStore
+
+
+def classify(msg: dict) -> tuple[str, str]:
+    """(direction-agnostic kind, method) of a parsed JSON-RPC message.
+
+    request: has method + id · notification: method, no id · response: id, no method.
+    """
+    if "method" in msg:
+        return ("request", msg["method"]) if "id" in msg else ("notification", msg["method"])
+    return ("response", None)
+
+
+class RecordingProxy:
+    """Pump lines between client streams and the child server, filing the tape."""
+
+    def __init__(self, client_in, client_out, command: list[str]):
+        self.client_in, self.client_out = client_in, client_out
+        self.command = list(command)
+        self.events: list[Event] = []
+        self.lock = threading.Lock()
+        self.pending_c2s: dict = {}   # id -> (method, params, started)
+        self.pending_s2c: dict = {}   # id -> (method, params)
+        self.warnings = 0
+        self.protocol_version = None
+        self.server_info = None
+        self.client_info = None
+        self._child = None
+
+    # -- tape helpers ------------------------------------------------------
+    def _append(self, event: Event) -> None:
+        with self.lock:
+            event.i = len(self.events)
+            self.events.append(event)
+
+    def _record(self, *, dir: str, kind: str, method=None,
+                id=None, params=None, payload=None, for_method=None,
+                for_params=None, wall_ms=0.0) -> None:
+        self._append(Event(dir=dir, kind=kind, method=method, id=id,
+                           params=params, payload=payload, for_method=for_method,
+                           for_params=for_params, wall_ms=wall_ms))
+
+    # -- pumps -------------------------------------------------------------
+    def run(self, root=None) -> int:
+        """Run the session; returns the child's exit code."""
+        self._child = subprocess.Popen(
+            self.command, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+            stderr=None, encoding="utf-8")
+        reader = threading.Thread(target=self._pump_server_to_client, daemon=True)
+        reader.start()
+        try:
+            self._pump_client_to_server()
+        finally:
+            try:
+                self._child.stdin.close()
+            except (OSError, ValueError):
+                pass
+            try:
+                self._child.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                self._child.kill()
+        reader.join(timeout=5)
+        return self._child.returncode if self._child.returncode is not None else 0
+
+    def _send(self, line: str, stream) -> None:
+        stream.write(line + "\n")
+        stream.flush()
+
+    def _pump_client_to_server(self) -> None:
+        for raw in self.client_in:
+            line = raw.rstrip("\r\n")
+            if not line.strip():
+                continue
+            started = time.perf_counter()
+            msg = None
+            try:
+                msg = json.loads(line)
+            except ValueError:
+                with self.lock:
+                    self.warnings += 1
+            if isinstance(msg, dict):
+                kind, method = classify(msg)
+                if kind == "request":
+                    with self.lock:
+                        self.pending_c2s[msg.get("id")] = (method, msg.get("params"), started)
+                        if method == "initialize":
+                            self.client_info = (msg.get("params") or {}).get("clientInfo")
+                    self._record(dir="c2s", kind="request", method=method,
+                                 id=msg.get("id"), params=msg.get("params"),
+                                 wall_ms=0.0)
+                elif kind == "response":
+                    with self.lock:
+                        origin = self.pending_s2c.pop(msg.get("id"), None)
+                    self._record(dir="c2s", kind="response", id=msg.get("id"),
+                                 payload={k: msg[k] for k in ("result", "error") if k in msg},
+                                 for_method=origin[0] if origin else None,
+                                 for_params=origin[1] if origin else None,
+                                 wall_ms=(time.perf_counter() - started) * 1000)
+                else:
+                    self._record(dir="c2s", kind="notification", method=method,
+                                 params=msg.get("params"))
+            self._send(line, self._child.stdin)
+        # client half-closed: let the server finish and exit on its own
+
+    def _pump_server_to_client(self) -> None:
+        child_out = self._child.stdout
+        for raw in child_out:
+            line = raw.rstrip("\r\n")
+            if not line.strip():
+                continue
+            msg = None
+            try:
+                msg = json.loads(line)
+            except ValueError:
+                with self.lock:
+                    self.warnings += 1
+            if isinstance(msg, dict):
+                kind, method = classify(msg)
+                if kind == "response":
+                    with self.lock:
+                        origin = self.pending_c2s.pop(msg.get("id"), None)
+                    if origin:
+                        rm, params, started = origin
+                        if rm == "initialize":
+                            result = msg.get("result") or {}
+                            self.protocol_version = result.get("protocolVersion")
+                            self.server_info = result.get("serverInfo")
+                        self._record(dir="s2c", kind="response", id=msg.get("id"),
+                                     payload={k: msg[k] for k in ("result", "error") if k in msg},
+                                     for_method=rm, for_params=params,
+                                     wall_ms=(time.perf_counter() - started) * 1000)
+                    else:  # orphan response -- keep it on tape, unexplained
+                        self._record(dir="s2c", kind="response", id=msg.get("id"),
+                                     payload={k: msg[k] for k in ("result", "error") if k in msg})
+                elif kind == "request":   # server asks the client (sampling, ...)
+                    with self.lock:
+                        self.pending_s2c[msg.get("id")] = (method, msg.get("params"))
+                    self._record(dir="s2c", kind="request", method=method,
+                                 id=msg.get("id"), params=msg.get("params"))
+                else:
+                    self._record(dir="s2c", kind="notification", method=method,
+                                 params=msg.get("params"))
+            self._send(line, self.client_out)
+
+    # -- persistence -------------------------------------------------------
+    def save(self, root=None, name: str = "session") -> str:
+        store = RunStore(root) if root else RunStore()
+        run_dir = store.new_run_dir(name)
+        RunStore.write_run(run_dir, self.events, {
+            "name": name,
+            "server_command": self.command,
+            "protocol_version": self.protocol_version,
+            "server_info": self.server_info,
+            "client_info": self.client_info,
+            "exchanges": sum(1 for e in self.events if e.kind == "request" and e.dir == "c2s"),
+            "warnings": self.warnings,
+        })
+        return str(run_dir)

mcptape/replay.py

@@ -0,0 +1,169 @@
+"""PLAY mode: serve a recorded MCP session without any live server.
+
+    MCP client ⇄ mcptape play ⇄ the tape (no child process)
+
+The replaying side answers each incoming client request with the recorded
+response, re-emitting the server notifications that were recorded inside
+that exchange. Responses are served with the *incoming* request's id --
+client ids may differ between the recorded and replayed session, results
+may not.
+
+Matching is **by content, not position**: MCP clients pipeline and run tool
+calls in parallel, so positional alignment (tapedeck's rule) would
+false-positive. A request matches the earliest *unconsumed* tape exchange
+with the same method and JSON-equal params; matched exchanges are marked
+consumed, so identical repeated calls consume identical repeated tape
+entries in order. ``initialize`` is matched leniently on params -- client
+name/version/protocol bumps are not behavior drift, and the recorded
+capabilities answer is still served verbatim.
+
+Exit codes (CI contract, same as tapedeck): 0 clean replay, 1 content
+drift (a call's arguments matched no recorded exchange), 2 structural
+(unreached recorded exchanges, or a recording that cannot be replayed at
+all -- e.g. it contains server-initiated requests).
+
+Everything human-readable goes to **stderr**; stdout is the wire.
+"""
+from __future__ import annotations
+
+import json
+import sys
+
+from .trace import Event
+
+DRIFT_CODE = -32000
+
+
+def _eq(a, b) -> bool:
+    try:
+        return json.loads(json.dumps(a)) == json.loads(json.dumps(b))
+    except (TypeError, ValueError):
+        return a == b
+
+
+class ReplayingServer:
+    def __init__(self, client_in, client_out, events: list[Event],
+                 lenient: bool = False, label: str = "session"):
+        self.client_in, self.client_out = client_in, client_out
+        self.events = events
+        self.lenient = lenient
+        self.label = label
+        self.request_indices = [e.i for e in events if e.dir == "c2s" and e.kind == "request"]
+        self.consumed: set[int] = set()
+        self.emitted_notes: set[int] = set()
+        self.served = 0
+        self.notifications = 0
+        self.drifts: list[str] = []
+
+    # -- tape queries ------------------------------------------------------
+    def _response_of(self, request_i: int) -> int | None:
+        req = self.events[request_i]
+        for j in range(request_i + 1, len(self.events)):
+            e = self.events[j]
+            if e.dir == "s2c" and e.kind == "response" and e.id == req.id:
+                return j
+        return None
+
+    def _match(self, method: str, params) -> int | None:
+        """Earliest unconsumed tape request matching this call."""
+        for j in self.request_indices:
+            if j in self.consumed:
+                continue
+            e = self.events[j]
+            if e.method == method and (method == "initialize" or _eq(e.params, params)):
+                return j
+        return None
+
+    # -- wire helpers ------------------------------------------------------
+    def _send(self, obj: dict) -> None:
+        self.client_out.write(json.dumps(obj, ensure_ascii=False) + "\n")
+        self.client_out.flush()
+
+    def _flush_notifications(self, upto: int) -> None:
+        """Emit every recorded s2c notification before ``upto``, in tape order."""
+        for k in range(0, min(upto, len(self.events))):
+            if k in self.emitted_notes:
+                continue
+            e = self.events[k]
+            if e.dir == "s2c" and e.kind == "notification":
+                self._send({"jsonrpc": "2.0", "method": e.method, "params": e.params})
+                self.emitted_notes.add(k)
+                self.notifications += 1
+
+    # -- main loop ---------------------------------------------------------
+    def serve(self) -> int:
+        if any(e.dir == "s2c" and e.kind == "request" for e in self.events):
+            print("mcptape: this recording contains server-initiated requests "
+                  "(sampling / elicitation / roots); replay cannot impersonate the "
+                  "client side of those. Use `mcptape diff` on such recordings.",
+                  file=sys.stderr)
+            return 2
+
+        for raw in self.client_in:
+            line = raw.rstrip("\r\n")
+            if not line.strip():
+                continue
+            try:
+                msg = json.loads(line)
+            except ValueError:
+                continue
+            if not isinstance(msg, dict):
+                continue
+            if "method" in msg and "id" in msg:
+                kind, method = "request", msg["method"]
+            elif "method" in msg:
+                kind, method = "notification", msg["method"]
+            else:
+                kind, method = "response", None
+
+            if kind == "notification":
+                continue                      # client-side notices need no tape
+            if kind == "response":
+                print("mcptape: ignoring client response -- recording has no "
+                      "server-initiated requests", file=sys.stderr)
+                continue
+
+            j = self._match(method, msg.get("params"))
+            if j is None and self.lenient:
+                j = next((k for k in self.request_indices if k not in self.consumed), None)
+                if j is not None:
+                    print(f"mcptape: lenient -- serving {self.events[j].method} "
+                          f"for drifted {method}", file=sys.stderr)
+            if j is None:
+                detail = f"{method} params={json.dumps(msg.get('params'), ensure_ascii=False)[:160]}"
+                self.drifts.append(detail)
+                print(f"mcptape: replay drift -- no recorded exchange matches {detail}",
+                      file=sys.stderr)
+                self._send({"jsonrpc": "2.0", "id": msg.get("id"), "error": {
+                    "code": DRIFT_CODE,
+                    "message": f"mcptape replay drift: no recorded exchange matches {method}",
+                }})
+                continue
+
+            response_i = self._response_of(j)
+            # every notification recorded by now that has not been replayed
+            # yet goes out first -- this matches the live ordering semantics
+            self._flush_notifications(response_i if response_i is not None else j)
+            payload = (self.events[response_i].payload if response_i is not None else None) \
+                or {"result": None}
+            self._send({"jsonrpc": "2.0", "id": msg.get("id"), **payload})
+            self.consumed.add(j)
+            self.served += 1
+
+        return self._finish()
+
+    def _finish(self) -> int:
+        unconsumed = [j for j in self.request_indices if j not in self.consumed]
+        if self.drifts:                 # drift is the actionable signal for CI
+            code = 1
+        elif unconsumed:
+            first = self.events[unconsumed[0]]
+            print(f"mcptape: {len(unconsumed)} recorded exchange(s) were never "
+                  f"replayed, first: {first.method}", file=sys.stderr)
+            code = 2
+        else:
+            code = 0
+        print(f"[replayed {self.label!r}: served {self.served} exchanges, "
+              f"{self.notifications} notifications, "
+              f"{len(self.drifts)} drift(s), 0 live calls]", file=sys.stderr)
+        return code

mcptape/trace.py

@@ -0,0 +1,149 @@
+"""Trace model and run storage.
+
+One run per directory, two plain files -- the flight-recorder contract from
+tapedeck, applied to MCP sessions::
+
+    .mcptape/runs/<timestamp>-<name>/
+        meta.json     # server command, protocol version, counts
+        trace.jsonl   # one JSON-RPC message per line, with echoes
+
+Event kinds on the tape:
+
+* ``request``      -- a JSON-RPC request; ``params`` recorded verbatim.
+* ``response``     -- the matching response; ``payload`` is the raw
+  ``{"result": ...}`` / ``{"error": {...}}`` object, plus an echo of the
+  request's ``method`` and ``params`` so every line is self-contained
+  (replay and diff never need to join across lines).
+* ``notification`` -- a JSON-RPC notification, either direction.
+
+MCP stdio framing is newline-delimited JSON-RPC (one message per line, no
+embedded newlines) -- the trace stores one *logical* message per line too.
+"""
+from __future__ import annotations
+
+import json
+import re
+import socket
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+SCHEMA_VERSION = 1
+DEFAULT_ROOT = Path(".mcptape") / "runs"
+
+_RUN_DIR_RE = re.compile(r"^\d{8}-\d{6}(?:-\d+)?-(?P<name>.+)$")
+
+
+def _run_name_of(dir_name: str) -> str | None:
+    """Extract the run name from '<stamp>-<name>' (or '<stamp>-<n>-<name>')."""
+    match = _RUN_DIR_RE.match(dir_name)
+    return match.group("name") if match else None
+
+
+def _jsonable(value):
+    """Best-effort JSON encoding so tracing never crashes a live session."""
+    try:
+        json.dumps(value)
+        return value
+    except (TypeError, ValueError):
+        return repr(value)
+
+
+@dataclass
+class Event:
+    """One JSON-RPC message on the tape."""
+
+    i: int = 0                     # assigned by the recorder on append
+    dir: str = ""                  # "c2s" | "s2c"
+    kind: str = ""                 # "request" | "response" | "notification"
+    method: str | None = None      # request / notification
+    id: int | str | None = None    # request / response
+    params: Any = None             # request / notification
+    payload: Any = None            # response: {"result": ...} | {"error": {...}}
+    for_method: str | None = None  # response echo
+    for_params: Any = None         # response echo
+    wall_ms: float = 0.0
+
+    def to_json(self) -> str:
+        return json.dumps({
+            "v": SCHEMA_VERSION, "i": self.i, "dir": self.dir, "kind": self.kind,
+            "method": self.method, "id": self.id, "params": _jsonable(self.params),
+            "payload": _jsonable(self.payload), "for_method": self.for_method,
+            "for_params": _jsonable(self.for_params), "wall_ms": round(self.wall_ms, 3),
+        }, ensure_ascii=False)
+
+    @classmethod
+    def from_json(cls, line: str) -> "Event":
+        d = json.loads(line)
+        if d.get("v") != SCHEMA_VERSION:
+            raise ValueError(f"unsupported trace schema version: {d.get('v')!r}")
+        return cls(i=d["i"], dir=d["dir"], kind=d["kind"], method=d.get("method"),
+                   id=d.get("id"), params=d.get("params"), payload=d.get("payload"),
+                   for_method=d.get("for_method"), for_params=d.get("for_params"),
+                   wall_ms=d.get("wall_ms", 0.0))
+
+
+@dataclass
+class RunStore:
+    """Locate, list, read, and write runs under a root (default .mcptape/runs)."""
+
+    root: Path = DEFAULT_ROOT
+
+    def new_run_dir(self, name: str) -> Path:
+        stamp = time.strftime("%Y%m%d-%H%M%S")
+        run_dir = self.root / f"{stamp}-{name}"
+        n = 2
+        while run_dir.exists():                     # same-second reruns
+            run_dir = self.root / f"{stamp}-{n}-{name}"
+            n += 1
+        run_dir.mkdir(parents=True)
+        return run_dir
+
+    def resolve(self, ref: str) -> Path:
+        """Accept an exact run directory, a path, or a unique name prefix.
+
+        Prefixes match either the full directory name (``20261031-``) or the
+        run name embedded in it (``runA``), whichever the user knows.
+        """
+        candidate = Path(ref)
+        if (candidate / "trace.jsonl").exists():
+            return candidate
+        matches = [
+            p for p in self.list_runs()
+            if p.name.startswith(ref) or (_run_name_of(p.name) or "").startswith(ref)
+        ]
+        if not matches:
+            raise FileNotFoundError(f"no run matches {ref!r} under {self.root} "
+                                    f"(found {len(self.list_runs())} runs)")
+        if len(matches) > 1:
+            names = ", ".join(m.name for m in matches[:5])
+            raise ValueError(f"run prefix {ref!r} is ambiguous: {names}")
+        return matches[0]
+
+    def list_runs(self) -> list[Path]:
+        if not self.root.is_dir():
+            return []
+        return sorted(d for d in self.root.iterdir()
+                      if d.is_dir() and (d / "trace.jsonl").exists())
+
+    @staticmethod
+    def write_run(run_dir: Path, events: list[Event], meta: dict) -> Path:
+        run_dir.mkdir(parents=True, exist_ok=True)
+        meta = {"schema_version": SCHEMA_VERSION, "recorded_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+                "host": socket.gethostname(), "python": ".".join(map(str, __import__("sys").version_info[:3])),
+                **meta}
+        (run_dir / "meta.json").write_text(
+            json.dumps(meta, ensure_ascii=False, indent=2), encoding="utf-8")
+        with open(run_dir / "trace.jsonl", "w", encoding="utf-8") as f:
+            for e in events:
+                f.write(e.to_json() + "\n")
+        return run_dir
+
+    @staticmethod
+    def read_run(run_dir: Path) -> tuple[list[Event], dict]:
+        events = [Event.from_json(line) for line in
+                  (run_dir / "trace.jsonl").read_text(encoding="utf-8").splitlines()
+                  if line.strip()]
+        meta_path = run_dir / "meta.json"
+        meta = json.loads(meta_path.read_text(encoding="utf-8")) if meta_path.exists() else {}
+        return events, meta

mcptape-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+mcptape/__init__.py,sha256=twoUaXJRyduN8_r3YGV3LNei-qabiOwLe2sATWHM_sw,876
+mcptape/__main__.py,sha256=vItpNJ92gAIHg_Mp6EIWZqD8uv6wDWFp7DV0my4tnC4,136
+mcptape/cli.py,sha256=3pwUJAAIwWGuXQxtoDo0jdA_MBOGs7COQFVWZmvhYx8,6216
+mcptape/diff.py,sha256=4sN9FAsDebhotvZFcyYtilhK4CYoH_swzV0spgLLuzM,3768
+mcptape/proxy.py,sha256=EEFU8xg1naK7XgsFb4_IZ9M_QtbAcRnp1VtLdtYhlF0,8444
+mcptape/replay.py,sha256=y9b7JYxCRiDl_o3D0kpI82lIIKIJSgszJIy26i-9WTg,7307
+mcptape/trace.py,sha256=25_qZ71IaoKrr8dfNV1VN85fsKhE4e77BQjVhzESyw0,5939
+mcptape-0.1.0.dist-info/licenses/LICENSE,sha256=PJ8Bq6AhOU6v_87BCQQ3Sehg9wUXTbQeKLHbdsxXLgc,1065
+mcptape-0.1.0.dist-info/METADATA,sha256=-RL-EWiIiDFGYn8CgJ4seca1mbSDfONLWeLvNI9EzhQ,9073
+mcptape-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+mcptape-0.1.0.dist-info/entry_points.txt,sha256=r68hxNoUwQ42pLjSD8P7rhLLH6zKv4uO3IQKG2IZYUw,45
+mcptape-0.1.0.dist-info/top_level.txt,sha256=QspY_xG-YSXseRxgw4tLLPYWLx60gJewY6z7ejK1X4o,8
+mcptape-0.1.0.dist-info/RECORD,,

mcptape-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mcptape-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcptape = mcptape.cli:main

mcptape-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcptape