mcp-replay

# mcp-replay Static-page renderer for [mcp-tape](https://github.com/craigm26/mcp-tape) JSON-RPC traces. Lives at **[mcpreplay.dev](https://mcpreplay.dev)**. ## Strategic context `mcp-replay` (this) and [`mcp-tape`](https://github.com/craigm26/mcp-tape) are the free, open-source halves of an MCP-observability product family. The JSONL trace format is deliberately [open and stable](docs/format.md) — anyone can write a producer or consumer; we don't have to be the only ones. Internal strategy + team-product roadmap lives in a private companion document. ## Load a trace Three ways, no server staging required. **1. Local file (recommended for private traces).** Open [mcpreplay.dev](https://mcpreplay.dev), click **Open local trace…**, pick the `.jsonl` file. Or drag-and-drop it anywhere on the page. The trace stays in your browser — nothing is uploaded. **2. Public URL.** Pass `?trace=<https-url>`: ``` https://mcpreplay.dev/?trace=https://example.com/path/to/trace.jsonl ``` Traces must be reachable via HTTPS or same-origin. [PlatAtlas](https://platatlas.com) hosts uploaded traces at `https://<sub>.platatlas.com/api/traces/<uuid>`. Traces uploaded with `mcp-tape upload --public` are world-readable by UUID and serve the right CORS headers for cross-origin fetch — just paste the URL `mcp-tape` prints into the `?trace=` parameter. **3. Merge multiple traces.** Select multiple files in the picker, drop multiple files at once, or join URLs with `;`: ``` https://mcpreplay.dev/?trace=https://example.com/a.jsonl;https://example.com/b.jsonl ``` All entries are interleaved by timestamp; each is tagged with its source so you can attribute calls back to the right server. ## Live mode Watch a session unfold in real time while mcp-tape is still recording. Run `mcp-tape --serve` and open `https://mcpreplay.dev/?live=ws://127.0.0.1:7777` — the page hydrates from a snapshot of everything-so-far, then streams new frames as they land. Loopback only; no remote-host connections accepted. See [docs/live-mode.md](docs/live-mode.md) for setup, port-conflict behavior, the `--no-file` flag, per-OS Claude Desktop paths, and troubleshooting. ## End-to-end with mcp-tape 1. `npm i -g mcp-tape` 2. `mcp-tape install` — wraps every MCP server in your Claude Code / Claude Desktop config 3. Use Claude normally; traces appear in `./mcp-traces/` per session 4. Drag the `.jsonl` file onto mcpreplay.dev to inspect 5. Share by sending the `.jsonl` file — your collaborator drops it in the same way `mcp-tape uninstall` reverses step 2 when you're done. The renderer is a single static HTML page — no backend, no build step, no runtime dependencies. ## Views | View | Question it answers | |---|---| | Timeline | What happened, in order? | | Tools | Which tools did the agent invoke, how often, how long, how often did they error? | | Calls | For each `tools/call`, what were the arguments, what came back, and how long did it take? | | Raw | The trace bytes themselves, line-numbered. | ## Trace format One JSON object per line. See [docs/format.md](docs/format.md) for the v1 spec and [docs/format-extensions.md](docs/format-extensions.md) for non-MCP producers (robot stacks like RCAN, agent runtimes, custom harnesses). The extension is compatible — it adds optional fields and extends two existing surfaces (`dir` value-space and conditional `end.exitCode`) — and v1-tolerant renderers handle extension traces via §"Version policy"'s ignore-unknown-values rule. The format is open and stable — any producer can emit it. [mcp-tape](https://github.com/craigm26/mcp-tape) is the reference producer; the file matrix is documented enough that any team can reach the format without depending on a specific tool. ## Local development ```bash npm run dev # serves the static site at http://localhost:8787 ``` Open `http://localhost:8787/?trace=examples/filesystem-short.jsonl` to see the demo trace. ## Deployment Cloudflare Pages, project `mcp-replay`, custom domain `mcpreplay.dev`. Deploys run locally with wrangler (uses your `wrangler login` session): ```bash npx wrangler pages deploy . --project-name=mcp-replay --branch=main ``` ## License MIT