@adityachilka/mcp-devtools 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya Chilka
+
+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.

package/README.md

@@ -0,0 +1,140 @@
+<div align="center">
+
+# mcp-devtools
+
+**Chrome DevTools for the Model Context Protocol.**
+
+Stop tailing logs. See every tool call your agent makes, why it failed, how long it took, and what it cost — all in a local browser window.
+
+[![npm](https://img.shields.io/npm/v/mcp-devtools?style=flat-square&color=000)](https://www.npmjs.com/package/mcp-devtools)
+[![license](https://img.shields.io/npm/l/mcp-devtools?style=flat-square&color=000)](./LICENSE)
+[![ci](https://img.shields.io/github/actions/workflow/status/adityachilka1/mcp-devtools/ci.yml?style=flat-square&label=ci&color=000)](https://github.com/adityachilka1/mcp-devtools/actions)
+[![stars](https://img.shields.io/github/stars/adityachilka1/mcp-devtools?style=flat-square&color=000)](https://github.com/adityachilka1/mcp-devtools/stargazers)
+<!-- Discord server coming soon — open an issue or Discussion for now -->
+
+
+<sub>Inspect · Profile · Replay · Diff</sub>
+
+</div>
+
+---
+
+## Why
+
+You're building an MCP server (or just running one) and something is off — the wrong tool fires, a call takes 14 seconds, your agent loops, your token bill triples overnight. Today's options: `console.log`, the official MCP Inspector (CLI-only, single-server), or grep through 40 MB of JSON-RPC logs.
+
+`mcp-devtools` is the local-first inspector and profiler that should have shipped with the protocol. Point any MCP client at it instead of your real server, and watch every request and response stream into a browser UI you can search, filter, replay, and diff.
+
+## Install
+
+```bash
+npm install -g mcp-devtools
+# or
+pnpm add -g mcp-devtools
+```
+
+## Quick start — proxy mode (recommended)
+
+`mcp-devtools` sits between your client (Claude Desktop, Cowork, Cursor, your own agent) and your real MCP server. Zero changes to the server.
+
+```bash
+mcp-devtools proxy \
+  --upstream "node ./my-mcp-server.js" \
+  --port 7456
+```
+
+Then point your client at `http://localhost:7456`. Open `http://localhost:7456/inspect` in your browser.
+
+You get:
+
+- **Timeline** — every `initialize`, `tools/list`, `tools/call`, `resources/read`, and notification in chronological order.
+- **Tool view** — for any `tools/call`, the inputs (with schema validation), the response, the latency, and the LLM-attributed token cost.
+- **Schema explorer** — live view of the server's declared tools, resources, and prompts.
+- **Replay** — click any past call, edit the arguments, hit run. Re-hits the upstream and shows the diff against the original response.
+- **Time travel** — scrub a slider to see the protocol state at any point in the session.
+
+## Quick start — embed mode
+
+Already have a Node/TypeScript MCP server? Add five lines.
+
+```ts
+import { createServer } from "@modelcontextprotocol/sdk/server";
+import { devtools } from "mcp-devtools/embed";
+
+const server = createServer({ name: "my-server", version: "1.0.0" });
+// ... register your tools ...
+
+devtools.attach(server, { port: 7456 });
+```
+
+The DevTools UI is now available at `http://localhost:7456/inspect` whenever your server is running.
+
+## Quick start — record mode
+
+Record a session and share the trace file with a teammate or in a bug report.
+
+```bash
+mcp-devtools record --upstream "node ./my-mcp-server.js" --out session.mcptrace
+mcp-devtools open session.mcptrace      # opens the UI on the recorded trace
+```
+
+`.mcptrace` files are gzipped JSONL — diffable, grep-able, and small.
+
+## Features
+
+| | |
+|---|---|
+| Live request/response timeline | Schema visualizer (tools, resources, prompts) |
+| Per-tool latency histograms | Token attribution (per call, per session) |
+| Error grouping and stack traces | Replay any call with modified args |
+| Time-travel slider | Diff between two recorded sessions |
+| Works with stdio AND streamable HTTP | Browser-only — no telemetry, nothing leaves your machine |
+| Export `.mcptrace` files | Open-source, MIT, self-hostable |
+
+## Architecture
+
+```
+┌────────────────┐   stdio/http     ┌──────────────────┐   stdio/http   ┌─────────────────┐
+│   MCP client   │ ────────────────▶│   mcp-devtools   │ ──────────────▶│   upstream MCP  │
+│ (Claude, etc.) │                  │   proxy + UI     │                │   server        │
+└────────────────┘ ◀────────────────└──────────────────┘ ◀──────────────└─────────────────┘
+                                            │
+                                            ▼
+                                   ┌──────────────────┐
+                                   │  local browser   │
+                                   │  http://:7456    │
+                                   └──────────────────┘
+```
+
+Single binary. No daemon. No cloud. No login.
+
+## Integration guides
+
+Step-by-step setup for popular MCP clients:
+
+- [Claude Desktop](./docs/integrations/claude-desktop.md)
+- [Cursor](./docs/integrations/cursor.md)
+- [Cline (VS Code)](./docs/integrations/cline.md)
+
+All three follow the same wrapper pattern — point your client at `mcp-devtools proxy` instead of your real server, and the inspector picks up everything.
+
+## Roadmap
+
+See [ROADMAP.md](./ROADMAP.md) for the full picture. The short version:
+
+- [x] **v0.1** — stdio proxy, recorder, embed API, browser UI
+- [ ] **v0.1.x** — `--quiet`, color-coded timeline, signed binaries, Bun support
+- [ ] **v0.2** — streamable HTTP transport, replay with diff, schema explorer
+- [ ] **v0.3** — OpenTelemetry export, VS Code extension, cost dashboard
+
+## Contributing
+
+We love contributions — see [CONTRIBUTING.md](./CONTRIBUTING.md). Good first issues are labeled [`good-first-issue`](https://github.com/adityachilka1/mcp-devtools/labels/good-first-issue). Open an issue or [start a Discussion](https://github.com/adityachilka1/mcp-devtools/discussions) before anything ambitious — Discord server coming soon.
+
+## Acknowledgements
+
+Built by [@adityachilka1](https://github.com/adityachilka1). Inspired by Chrome DevTools, React DevTools, and the official [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
+
+## License
+
+[MIT](./LICENSE) © 2026 Aditya Chilka.

package/dist/chunk-3V7Q2E62.js

@@ -0,0 +1,101 @@
+// src/trace-store.ts
+import { appendFile, mkdir } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+var MAX_FRAMES = 1e4;
+var TraceStore = class {
+  buf = [];
+  nextId = 1;
+  logPath;
+  initialized = false;
+  constructor(opts) {
+    const dir = opts?.logDir ?? join(homedir(), ".mcp-devtools");
+    this.logPath = join(dir, `session-${Date.now()}.jsonl`);
+  }
+  record(input) {
+    const entry = {
+      id: this.nextId++,
+      direction: input.direction,
+      ts: Date.now(),
+      frame: input.frame
+    };
+    this.buf.push(entry);
+    if (this.buf.length > MAX_FRAMES) this.buf.shift();
+    void this.persist(entry);
+    return entry.id;
+  }
+  /** All frames in chronological order. */
+  all() {
+    return this.buf.slice();
+  }
+  /** Frames since (exclusive) the given id. Used by the UI's live stream. */
+  since(id) {
+    return this.buf.filter((f) => f.id > id);
+  }
+  async persist(entry) {
+    if (!this.initialized) {
+      await mkdir(join(homedir(), ".mcp-devtools"), { recursive: true });
+      this.initialized = true;
+    }
+    await appendFile(this.logPath, `${JSON.stringify(entry)}
+`).catch(() => {
+    });
+  }
+};
+
+// src/ui-server.ts
+import { dirname, join as join2 } from "path";
+import { fileURLToPath } from "url";
+import fastifyStatic from "@fastify/static";
+import websocketPlugin from "@fastify/websocket";
+import fastify from "fastify";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+async function startUiServer({ port, store, events }) {
+  const app = fastify({ logger: false });
+  await app.register(websocketPlugin);
+  await app.register(fastifyStatic, {
+    root: join2(__dirname, "..", "ui"),
+    prefix: "/inspect/"
+  });
+  app.get("/api/frames", async (req) => {
+    const since = Number(req.query.since ?? 0);
+    return store.since(since);
+  });
+  app.get("/ws", { websocket: true }, (socket) => {
+    const send = (id) => {
+      const payload = JSON.stringify({ type: "frame", frames: store.since(id - 1) });
+      socket.send(payload);
+    };
+    const onFrame = (id) => send(id);
+    events.on("frame", onFrame);
+    socket.on("close", () => events.off("frame", onFrame));
+  });
+  await app.listen({ port, host: "127.0.0.1" });
+  return app;
+}
+
+// src/util/log.ts
+import kleur from "kleur";
+var quiet = false;
+var log = {
+  info: (msg) => {
+    if (quiet) return;
+    process.stderr.write(`${kleur.dim("mcp-devtools")} ${msg}
+`);
+  },
+  warn: (msg) => {
+    process.stderr.write(`${kleur.yellow("warn")} ${msg}
+`);
+  },
+  err: (msg) => {
+    process.stderr.write(`${kleur.red("error")} ${msg}
+`);
+  }
+};
+
+export {
+  TraceStore,
+  startUiServer,
+  log
+};
+//# sourceMappingURL=chunk-3V7Q2E62.js.map

package/dist/chunk-3V7Q2E62.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/trace-store.ts","../src/ui-server.ts","../src/util/log.ts"],"sourcesContent":["/**\n * In-memory ring buffer for MCP frames. The store keeps the last N frames\n * (default: 10,000) so a long-running session doesn't blow up RAM. Frames are\n * also written incrementally to an on-disk JSONL file under `~/.mcp-devtools/`\n * so that opening a stale tab still shows the full history.\n */\nimport { appendFile, mkdir } from \"node:fs/promises\";\nimport { homedir } from \"node:os\";\nimport { join } from \"node:path\";\nimport type { JsonRpcFrame } from \"./jsonrpc.js\";\n\nexport interface StoredFrame {\n  id: number;\n  direction: \"in\" | \"out\";\n  ts: number;\n  frame: JsonRpcFrame;\n}\n\nexport interface RecordInput {\n  direction: \"in\" | \"out\";\n  frame: JsonRpcFrame;\n}\n\nconst MAX_FRAMES = 10_000;\n\nexport class TraceStore {\n  private buf: StoredFrame[] = [];\n  private nextId = 1;\n  private logPath: string;\n  private initialized = false;\n\n  constructor(opts?: { logDir?: string }) {\n    const dir = opts?.logDir ?? join(homedir(), \".mcp-devtools\");\n    this.logPath = join(dir, `session-${Date.now()}.jsonl`);\n  }\n\n  record(input: RecordInput): number {\n    const entry: StoredFrame = {\n      id: this.nextId++,\n      direction: input.direction,\n      ts: Date.now(),\n      frame: input.frame,\n    };\n    this.buf.push(entry);\n    if (this.buf.length > MAX_FRAMES) this.buf.shift();\n    void this.persist(entry);\n    return entry.id;\n  }\n\n  /** All frames in chronological order. */\n  all(): StoredFrame[] {\n    return this.buf.slice();\n  }\n\n  /** Frames since (exclusive) the given id. Used by the UI's live stream. */\n  since(id: number): StoredFrame[] {\n    return this.buf.filter((f) => f.id > id);\n  }\n\n  private async persist(entry: StoredFrame): Promise<void> {\n    if (!this.initialized) {\n      await mkdir(join(homedir(), \".mcp-devtools\"), { recursive: true });\n      this.initialized = true;\n    }\n    await appendFile(this.logPath, `${JSON.stringify(entry)}\\n`).catch(() => {\n      /* never throw from the recorder — the proxy must keep running */\n    });\n  }\n}\n","import type { EventEmitter } from \"node:events\";\nimport { dirname, join } from \"node:path\";\n/**\n * Local UI server. Serves the static browser bundle from `ui/` and exposes a\n * WebSocket at `/ws` that streams new frames to the inspector in real time.\n */\nimport { fileURLToPath } from \"node:url\";\nimport fastifyStatic from \"@fastify/static\";\nimport websocketPlugin from \"@fastify/websocket\";\nimport fastify from \"fastify\";\nimport type { TraceStore } from \"./trace-store.js\";\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\n\nexport interface UiServerOptions {\n  port: number;\n  store: TraceStore;\n  events: EventEmitter;\n}\n\nexport async function startUiServer({ port, store, events }: UiServerOptions) {\n  const app = fastify({ logger: false });\n\n  await app.register(websocketPlugin);\n  // After the build, this file lives in `dist/ui-server.js` and `ui/` lives\n  // beside `dist/` at the package root, so `../ui` resolves correctly.\n  await app.register(fastifyStatic, {\n    root: join(__dirname, \"..\", \"ui\"),\n    prefix: \"/inspect/\",\n  });\n\n  app.get(\"/api/frames\", async (req) => {\n    const since = Number((req.query as { since?: string }).since ?? 0);\n    return store.since(since);\n  });\n\n  // @fastify/websocket v11: handler receives the WebSocket directly.\n  app.get(\"/ws\", { websocket: true }, (socket /* WebSocket */) => {\n    const send = (id: number) => {\n      const payload = JSON.stringify({ type: \"frame\", frames: store.since(id - 1) });\n      socket.send(payload);\n    };\n    const onFrame = (id: number) => send(id);\n    events.on(\"frame\", onFrame);\n    socket.on(\"close\", () => events.off(\"frame\", onFrame));\n  });\n\n  await app.listen({ port, host: \"127.0.0.1\" });\n  return app;\n}\n","/**\n * Tiny stderr logger — never write progress to stdout (that's the MCP wire).\n *\n * `setQuiet(true)` suppresses `log.info()`. Warnings and errors are never\n * silenced — those carry information the user cannot live without.\n */\nimport kleur from \"kleur\";\n\nlet quiet = false;\n\n/** Toggle the info-channel silence. Idempotent. */\nexport const setQuiet = (q: boolean): void => {\n  quiet = q;\n};\n\n/** For tests + introspection. Not for hot paths. */\nexport const isQuiet = (): boolean => quiet;\n\nexport const log = {\n  info: (msg: string): void => {\n    if (quiet) return;\n    process.stderr.write(`${kleur.dim(\"mcp-devtools\")} ${msg}\\n`);\n  },\n  warn: (msg: string): void => {\n    process.stderr.write(`${kleur.yellow(\"warn\")} ${msg}\\n`);\n  },\n  err: (msg: string): void => {\n    process.stderr.write(`${kleur.red(\"error\")} ${msg}\\n`);\n  },\n};\n"],"mappings":"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","names":["join"]}

package/dist/cli.js

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { cac } from "cac";
+
+// src/proxy.ts
+import { spawn as spawn2 } from "child_process";
+import { EventEmitter } from "events";
+
+// src/jsonrpc.ts
+var pending = "";
+function parseFrames(chunk) {
+  pending += chunk.toString("utf8");
+  const frames = [];
+  let nl = pending.indexOf("\n");
+  while (nl !== -1) {
+    const line = pending.slice(0, nl).trim();
+    pending = pending.slice(nl + 1);
+    if (line) {
+      try {
+        frames.push(JSON.parse(line));
+      } catch (err) {
+        frames.push({ _raw: line, _parseError: err.message });
+      }
+    }
+    nl = pending.indexOf("\n");
+  }
+  return frames;
+}
+
+// src/trace-store.ts
+import { appendFile, mkdir } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+var MAX_FRAMES = 1e4;
+var TraceStore = class {
+  buf = [];
+  nextId = 1;
+  logPath;
+  initialized = false;
+  constructor(opts) {
+    const dir = opts?.logDir ?? join(homedir(), ".mcp-devtools");
+    this.logPath = join(dir, `session-${Date.now()}.jsonl`);
+  }
+  record(input) {
+    const entry = {
+      id: this.nextId++,
+      direction: input.direction,
+      ts: Date.now(),
+      frame: input.frame
+    };
+    this.buf.push(entry);
+    if (this.buf.length > MAX_FRAMES) this.buf.shift();
+    void this.persist(entry);
+    return entry.id;
+  }
+  /** All frames in chronological order. */
+  all() {
+    return this.buf.slice();
+  }
+  /** Frames since (exclusive) the given id. Used by the UI's live stream. */
+  since(id) {
+    return this.buf.filter((f) => f.id > id);
+  }
+  async persist(entry) {
+    if (!this.initialized) {
+      await mkdir(join(homedir(), ".mcp-devtools"), { recursive: true });
+      this.initialized = true;
+    }
+    await appendFile(this.logPath, `${JSON.stringify(entry)}
+`).catch(() => {
+    });
+  }
+};
+
+// src/ui-server.ts
+import { dirname, join as join2 } from "path";
+import { fileURLToPath } from "url";
+import fastifyStatic from "@fastify/static";
+import websocketPlugin from "@fastify/websocket";
+import fastify from "fastify";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+async function startUiServer({ port, store, events }) {
+  const app = fastify({ logger: false });
+  await app.register(websocketPlugin);
+  await app.register(fastifyStatic, {
+    root: join2(__dirname, "..", "ui"),
+    prefix: "/inspect/"
+  });
+  app.get("/api/frames", async (req) => {
+    const since = Number(req.query.since ?? 0);
+    return store.since(since);
+  });
+  app.get("/ws", { websocket: true }, (socket) => {
+    const send = (id) => {
+      const payload = JSON.stringify({ type: "frame", frames: store.since(id - 1) });
+      socket.send(payload);
+    };
+    const onFrame = (id) => send(id);
+    events.on("frame", onFrame);
+    socket.on("close", () => events.off("frame", onFrame));
+  });
+  await app.listen({ port, host: "127.0.0.1" });
+  return app;
+}
+
+// src/util/log.ts
+import kleur from "kleur";
+var quiet = false;
+var setQuiet = (q) => {
+  quiet = q;
+};
+var log = {
+  info: (msg) => {
+    if (quiet) return;
+    process.stderr.write(`${kleur.dim("mcp-devtools")} ${msg}
+`);
+  },
+  warn: (msg) => {
+    process.stderr.write(`${kleur.yellow("warn")} ${msg}
+`);
+  },
+  err: (msg) => {
+    process.stderr.write(`${kleur.red("error")} ${msg}
+`);
+  }
+};
+
+// src/util/open.ts
+import { spawn } from "child_process";
+async function openBrowserAt(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
+}
+
+// src/proxy.ts
+async function startProxy(opts) {
+  if (opts.transport === "http") {
+    throw new Error("HTTP transport is on the v0.2 roadmap. Use stdio for now.");
+  }
+  const store = new TraceStore();
+  const events = new EventEmitter();
+  const parts = splitCommand(opts.upstreamCommand);
+  const cmd = parts[0];
+  if (!cmd) throw new Error("empty --upstream command");
+  const args = parts.slice(1);
+  const child = spawn2(cmd, args, {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: { ...process.env, MCP_DEVTOOLS_PROXIED: "1" }
+  });
+  log.info(`upstream \u2192 ${opts.upstreamCommand} (pid ${child.pid})`);
+  process.stdin.on("data", (chunk) => {
+    child.stdin.write(chunk);
+    for (const frame of parseFrames(chunk)) {
+      const id = store.record({ direction: "out", frame });
+      events.emit("frame", id);
+    }
+  });
+  process.stdin.on("end", () => child.stdin.end());
+  child.stdout.on("data", (chunk) => {
+    process.stdout.write(chunk);
+    for (const frame of parseFrames(chunk)) {
+      const id = store.record({ direction: "in", frame });
+      events.emit("frame", id);
+    }
+  });
+  child.stderr.on("data", (chunk) => process.stderr.write(chunk));
+  child.on("exit", (code) => {
+    log.info(`upstream exited with code ${code}`);
+    process.exit(code ?? 0);
+  });
+  await startUiServer({ port: opts.port, store, events });
+  log.info(`inspector ready \u2192 http://localhost:${opts.port}/inspect`);
+  if (opts.openBrowser) {
+    await openBrowserAt(`http://localhost:${opts.port}/inspect`);
+  }
+}
+function splitCommand(s) {
+  return s.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+}
+
+// src/recorder.ts
+import { spawn as spawn3 } from "child_process";
+import { createWriteStream } from "fs";
+import { createGzip } from "zlib";
+async function startRecorder(opts) {
+  const gz = createGzip();
+  const out = createWriteStream(opts.outPath);
+  gz.pipe(out);
+  const parts = opts.upstreamCommand.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+  const cmd = parts[0];
+  if (!cmd) throw new Error("empty --upstream command");
+  const args = parts.slice(1);
+  const child = spawn3(cmd, args, { stdio: ["pipe", "pipe", "pipe"] });
+  log.info(`recording \u2192 ${opts.outPath}`);
+  let seq = 0;
+  const write = (direction, chunk) => {
+    for (const frame of parseFrames(chunk)) {
+      gz.write(`${JSON.stringify({ id: ++seq, ts: Date.now(), direction, frame })}
+`);
+    }
+  };
+  process.stdin.on("data", (c) => {
+    child.stdin.write(c);
+    write("out", c);
+  });
+  process.stdin.on("end", () => child.stdin.end());
+  child.stdout.on("data", (c) => {
+    process.stdout.write(c);
+    write("in", c);
+  });
+  child.stderr.on("data", (c) => process.stderr.write(c));
+  child.on("exit", (code) => {
+    gz.end();
+    out.on("finish", () => process.exit(code ?? 0));
+  });
+}
+
+// src/util/validate-port.ts
+function basePortError(got) {
+  return `error: --port must be between 1024 and 65535 (got ${String(got)})`;
+}
+function validatePort(raw) {
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    return { ok: false, message: basePortError(raw) };
+  }
+  if (port < 1024) {
+    return {
+      ok: false,
+      message: `${basePortError(raw)}; ports below 1024 usually require root, pick a higher port`
+    };
+  }
+  return { ok: true, value: port };
+}
+
+// src/viewer.ts
+import { EventEmitter as EventEmitter2 } from "events";
+import { createReadStream } from "fs";
+import { createInterface } from "readline";
+import { createGunzip } from "zlib";
+async function openTrace({ tracePath, port }) {
+  const store = new TraceStore();
+  const events = new EventEmitter2();
+  const rl = createInterface({
+    input: createReadStream(tracePath).pipe(createGunzip()),
+    crlfDelay: Number.POSITIVE_INFINITY
+  });
+  for await (const line of rl) {
+    if (!line.trim()) continue;
+    const row = JSON.parse(line);
+    store.record({ direction: row.direction, frame: row.frame });
+  }
+  await startUiServer({ port, store, events });
+  log.info(`viewing ${tracePath} \u2192 http://localhost:${port}/inspect`);
+  await openBrowserAt(`http://localhost:${port}/inspect`);
+}
+
+// src/cli.ts
+var VERSION = "0.1.0";
+var cli = cac("mcp-devtools");
+cli.command("proxy", "Start a transparent MCP proxy with a live inspector UI").option("--upstream <cmd>", "Command that launches the upstream MCP server").option("--port <port>", "Port for the UI and proxy endpoint", { default: 7456 }).option("--transport <type>", "stdio | http", { default: "stdio" }).option("--no-open", "Don't auto-open the browser").option("--quiet", "Suppress informational logs").action(async (opts) => {
+  setQuiet(!!opts.quiet);
+  if (!opts.upstream) {
+    console.error("error: --upstream is required");
+    process.exit(1);
+  }
+  const port = validatePort(opts.port);
+  if (!port.ok) {
+    console.error(port.message);
+    process.exit(1);
+  }
+  await startProxy({
+    upstreamCommand: opts.upstream,
+    port: port.value,
+    transport: opts.transport,
+    openBrowser: opts.open !== false
+  });
+});
+cli.command("record", "Record an MCP session to disk").option("--upstream <cmd>", "Command that launches the upstream MCP server").option("--out <path>", "Output file", { default: "session.mcptrace" }).option("--quiet", "Suppress informational logs").action(async (opts) => {
+  setQuiet(!!opts.quiet);
+  if (!opts.upstream) {
+    console.error("error: --upstream is required");
+    process.exit(1);
+  }
+  await startRecorder({ upstreamCommand: opts.upstream, outPath: opts.out });
+});
+cli.command("open <file>", "Open a recorded .mcptrace file in the UI").option("--port <port>", "Port for the UI", { default: 7456 }).option("--quiet", "Suppress informational logs").action(async (file, opts) => {
+  setQuiet(!!opts.quiet);
+  const port = validatePort(opts.port);
+  if (!port.ok) {
+    console.error(port.message);
+    process.exit(1);
+  }
+  await openTrace({ tracePath: file, port: port.value });
+});
+cli.help();
+cli.version(VERSION);
+cli.parse();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts","../src/proxy.ts","../src/jsonrpc.ts","../src/trace-store.ts","../src/ui-server.ts","../src/util/log.ts","../src/util/open.ts","../src/recorder.ts","../src/util/validate-port.ts","../src/viewer.ts"],"sourcesContent":["/**\n * mcp-devtools CLI entry point.\n *\n * Subcommands:\n *   proxy     spin up a transparent MCP proxy + browser UI\n *   record    record a session to a .mcptrace file\n *   open      open a previously recorded .mcptrace file in the UI\n *   version   print version\n *\n * Global flags:\n *   --quiet   suppress informational logs (warnings and errors still print)\n */\nimport { cac } from \"cac\";\nimport { startProxy } from \"./proxy.js\";\nimport { startRecorder } from \"./recorder.js\";\nimport { setQuiet } from \"./util/log.js\";\nimport { validatePort } from \"./util/validate-port.js\";\nimport { openTrace } from \"./viewer.js\";\n\n// Version is replaced at build time. Avoid `import ... with { type: \"json\" }`\n// so we don't depend on Node ≥20.10 JSON import attributes inside the bundle.\nconst VERSION = \"0.1.0\";\n\nconst cli = cac(\"mcp-devtools\");\n\ncli\n  .command(\"proxy\", \"Start a transparent MCP proxy with a live inspector UI\")\n  .option(\"--upstream <cmd>\", \"Command that launches the upstream MCP server\")\n  .option(\"--port <port>\", \"Port for the UI and proxy endpoint\", { default: 7456 })\n  .option(\"--transport <type>\", \"stdio | http\", { default: \"stdio\" })\n  .option(\"--no-open\", \"Don't auto-open the browser\")\n  .option(\"--quiet\", \"Suppress informational logs\")\n  .action(async (opts) => {\n    setQuiet(!!opts.quiet);\n    if (!opts.upstream) {\n      console.error(\"error: --upstream is required\");\n      process.exit(1);\n    }\n    const port = validatePort(opts.port);\n    if (!port.ok) {\n      console.error(port.message);\n      process.exit(1);\n    }\n    await startProxy({\n      upstreamCommand: opts.upstream,\n      port: port.value,\n      transport: opts.transport,\n      openBrowser: opts.open !== false,\n    });\n  });\n\ncli\n  .command(\"record\", \"Record an MCP session to disk\")\n  .option(\"--upstream <cmd>\", \"Command that launches the upstream MCP server\")\n  .option(\"--out <path>\", \"Output file\", { default: \"session.mcptrace\" })\n  .option(\"--quiet\", \"Suppress informational logs\")\n  .action(async (opts) => {\n    setQuiet(!!opts.quiet);\n    if (!opts.upstream) {\n      console.error(\"error: --upstream is required\");\n      process.exit(1);\n    }\n    await startRecorder({ upstreamCommand: opts.upstream, outPath: opts.out });\n  });\n\ncli\n  .command(\"open <file>\", \"Open a recorded .mcptrace file in the UI\")\n  .option(\"--port <port>\", \"Port for the UI\", { default: 7456 })\n  .option(\"--quiet\", \"Suppress informational logs\")\n  .action(async (file: string, opts) => {\n    setQuiet(!!opts.quiet);\n    const port = validatePort(opts.port);\n    if (!port.ok) {\n      console.error(port.message);\n      process.exit(1);\n    }\n    await openTrace({ tracePath: file, port: port.value });\n  });\n\ncli.help();\ncli.version(VERSION);\ncli.parse();\n","/**\n * Transparent MCP proxy.\n *\n * Spawns the upstream MCP server as a child process and pipes JSON-RPC frames\n * in both directions while persisting them to the in-memory ring buffer that\n * the inspector UI subscribes to.\n *\n * The proxy is intentionally protocol-agnostic — it does NOT parse semantic\n * tool calls; it parses JSON-RPC envelopes and tags each frame with direction,\n * timestamp, and a monotonically-increasing sequence number. Semantic\n * interpretation (e.g. \"this is a tools/call\") happens in the UI layer.\n */\nimport { type ChildProcessWithoutNullStreams, spawn } from \"node:child_process\";\nimport { EventEmitter } from \"node:events\";\nimport { parseFrames } from \"./jsonrpc.js\";\nimport { TraceStore } from \"./trace-store.js\";\nimport { startUiServer } from \"./ui-server.js\";\nimport { log } from \"./util/log.js\";\nimport { openBrowserAt } from \"./util/open.js\";\n\nexport interface ProxyOptions {\n  upstreamCommand: string;\n  port: number;\n  transport: \"stdio\" | \"http\";\n  openBrowser: boolean;\n}\n\nexport async function startProxy(opts: ProxyOptions): Promise<void> {\n  if (opts.transport === \"http\") {\n    throw new Error(\"HTTP transport is on the v0.2 roadmap. Use stdio for now.\");\n  }\n\n  const store = new TraceStore();\n  const events = new EventEmitter();\n\n  // Spawn the upstream server.\n  const parts = splitCommand(opts.upstreamCommand);\n  const cmd = parts[0];\n  if (!cmd) throw new Error(\"empty --upstream command\");\n  const args = parts.slice(1);\n\n  const child: ChildProcessWithoutNullStreams = spawn(cmd, args, {\n    stdio: [\"pipe\", \"pipe\", \"pipe\"],\n    env: { ...process.env, MCP_DEVTOOLS_PROXIED: \"1\" },\n  });\n  log.info(`upstream → ${opts.upstreamCommand} (pid ${child.pid})`);\n\n  // Stream stdin → upstream, tagging frames going \"out\" (client → server).\n  process.stdin.on(\"data\", (chunk) => {\n    child.stdin.write(chunk);\n    for (const frame of parseFrames(chunk)) {\n      const id = store.record({ direction: \"out\", frame });\n      events.emit(\"frame\", id);\n    }\n  });\n  // Propagate stdin EOF so the upstream can shut down cleanly.\n  process.stdin.on(\"end\", () => child.stdin.end());\n\n  // Stream upstream stdout → stdin, tagging frames going \"in\" (server → client).\n  child.stdout.on(\"data\", (chunk) => {\n    process.stdout.write(chunk);\n    for (const frame of parseFrames(chunk)) {\n      const id = store.record({ direction: \"in\", frame });\n      events.emit(\"frame\", id);\n    }\n  });\n\n  // Surface upstream stderr — never swallow it.\n  child.stderr.on(\"data\", (chunk) => process.stderr.write(chunk));\n\n  child.on(\"exit\", (code) => {\n    log.info(`upstream exited with code ${code}`);\n    process.exit(code ?? 0);\n  });\n\n  // Spin up the UI server.\n  await startUiServer({ port: opts.port, store, events });\n  log.info(`inspector ready → http://localhost:${opts.port}/inspect`);\n\n  if (opts.openBrowser) {\n    await openBrowserAt(`http://localhost:${opts.port}/inspect`);\n  }\n}\n\nfunction splitCommand(s: string): string[] {\n  // Naive shell split — good enough for the common case `node ./server.js`.\n  // Real users can pass `--upstream \"/bin/sh -c '...'\"` for anything fancier.\n  return s.match(/(?:[^\\s\"']+|\"[^\"]*\"|'[^']*')+/g) ?? [];\n}\n","/**\n * Minimal JSON-RPC 2.0 frame parser for MCP's newline-delimited stdio transport.\n *\n * MCP servers speak newline-delimited JSON over stdio (the official spec). We\n * read incoming bytes into a buffer and emit one parsed frame per line. We\n * deliberately do NOT validate the JSON-RPC structure — the upstream server\n * already does that, and we don't want the proxy to choke on a server bug.\n */\n\nexport type JsonRpcFrame =\n  | JsonRpcRequest\n  | JsonRpcResponse\n  | JsonRpcNotification\n  | { _raw: string; _parseError: string };\n\nexport interface JsonRpcRequest {\n  jsonrpc: \"2.0\";\n  id: number | string;\n  method: string;\n  params?: unknown;\n}\n\nexport interface JsonRpcResponse {\n  jsonrpc: \"2.0\";\n  id: number | string;\n  result?: unknown;\n  error?: { code: number; message: string; data?: unknown };\n}\n\nexport interface JsonRpcNotification {\n  jsonrpc: \"2.0\";\n  method: string;\n  params?: unknown;\n}\n\nlet pending = \"\";\n\nexport function parseFrames(chunk: Buffer): JsonRpcFrame[] {\n  pending += chunk.toString(\"utf8\");\n  const frames: JsonRpcFrame[] = [];\n  let nl = pending.indexOf(\"\\n\");\n  while (nl !== -1) {\n    const line = pending.slice(0, nl).trim();\n    pending = pending.slice(nl + 1);\n    if (line) {\n      try {\n        frames.push(JSON.parse(line));\n      } catch (err) {\n        frames.push({ _raw: line, _parseError: (err as Error).message });\n      }\n    }\n    nl = pending.indexOf(\"\\n\");\n  }\n  return frames;\n}\n\n/** Helper used by the UI to classify a frame for display. */\nexport function classify(\n  f: JsonRpcFrame,\n):\n  | { kind: \"request\"; method: string; id: number | string }\n  | { kind: \"response\"; id: number | string; isError: boolean }\n  | { kind: \"notification\"; method: string }\n  | { kind: \"malformed\" } {\n  if (\"_parseError\" in f) return { kind: \"malformed\" };\n  if (\"id\" in f && \"method\" in f) {\n    return { kind: \"request\", method: f.method, id: f.id };\n  }\n  if (\"id\" in f) {\n    return { kind: \"response\", id: f.id, isError: \"error\" in f };\n  }\n  if (\"method\" in f) return { kind: \"notification\", method: f.method };\n  return { kind: \"malformed\" };\n}\n","/**\n * In-memory ring buffer for MCP frames. The store keeps the last N frames\n * (default: 10,000) so a long-running session doesn't blow up RAM. Frames are\n * also written incrementally to an on-disk JSONL file under `~/.mcp-devtools/`\n * so that opening a stale tab still shows the full history.\n */\nimport { appendFile, mkdir } from \"node:fs/promises\";\nimport { homedir } from \"node:os\";\nimport { join } from \"node:path\";\nimport type { JsonRpcFrame } from \"./jsonrpc.js\";\n\nexport interface StoredFrame {\n  id: number;\n  direction: \"in\" | \"out\";\n  ts: number;\n  frame: JsonRpcFrame;\n}\n\nexport interface RecordInput {\n  direction: \"in\" | \"out\";\n  frame: JsonRpcFrame;\n}\n\nconst MAX_FRAMES = 10_000;\n\nexport class TraceStore {\n  private buf: StoredFrame[] = [];\n  private nextId = 1;\n  private logPath: string;\n  private initialized = false;\n\n  constructor(opts?: { logDir?: string }) {\n    const dir = opts?.logDir ?? join(homedir(), \".mcp-devtools\");\n    this.logPath = join(dir, `session-${Date.now()}.jsonl`);\n  }\n\n  record(input: RecordInput): number {\n    const entry: StoredFrame = {\n      id: this.nextId++,\n      direction: input.direction,\n      ts: Date.now(),\n      frame: input.frame,\n    };\n    this.buf.push(entry);\n    if (this.buf.length > MAX_FRAMES) this.buf.shift();\n    void this.persist(entry);\n    return entry.id;\n  }\n\n  /** All frames in chronological order. */\n  all(): StoredFrame[] {\n    return this.buf.slice();\n  }\n\n  /** Frames since (exclusive) the given id. Used by the UI's live stream. */\n  since(id: number): StoredFrame[] {\n    return this.buf.filter((f) => f.id > id);\n  }\n\n  private async persist(entry: StoredFrame): Promise<void> {\n    if (!this.initialized) {\n      await mkdir(join(homedir(), \".mcp-devtools\"), { recursive: true });\n      this.initialized = true;\n    }\n    await appendFile(this.logPath, `${JSON.stringify(entry)}\\n`).catch(() => {\n      /* never throw from the recorder — the proxy must keep running */\n    });\n  }\n}\n","import type { EventEmitter } from \"node:events\";\nimport { dirname, join } from \"node:path\";\n/**\n * Local UI server. Serves the static browser bundle from `ui/` and exposes a\n * WebSocket at `/ws` that streams new frames to the inspector in real time.\n */\nimport { fileURLToPath } from \"node:url\";\nimport fastifyStatic from \"@fastify/static\";\nimport websocketPlugin from \"@fastify/websocket\";\nimport fastify from \"fastify\";\nimport type { TraceStore } from \"./trace-store.js\";\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\n\nexport interface UiServerOptions {\n  port: number;\n  store: TraceStore;\n  events: EventEmitter;\n}\n\nexport async function startUiServer({ port, store, events }: UiServerOptions) {\n  const app = fastify({ logger: false });\n\n  await app.register(websocketPlugin);\n  // After the build, this file lives in `dist/ui-server.js` and `ui/` lives\n  // beside `dist/` at the package root, so `../ui` resolves correctly.\n  await app.register(fastifyStatic, {\n    root: join(__dirname, \"..\", \"ui\"),\n    prefix: \"/inspect/\",\n  });\n\n  app.get(\"/api/frames\", async (req) => {\n    const since = Number((req.query as { since?: string }).since ?? 0);\n    return store.since(since);\n  });\n\n  // @fastify/websocket v11: handler receives the WebSocket directly.\n  app.get(\"/ws\", { websocket: true }, (socket /* WebSocket */) => {\n    const send = (id: number) => {\n      const payload = JSON.stringify({ type: \"frame\", frames: store.since(id - 1) });\n      socket.send(payload);\n    };\n    const onFrame = (id: number) => send(id);\n    events.on(\"frame\", onFrame);\n    socket.on(\"close\", () => events.off(\"frame\", onFrame));\n  });\n\n  await app.listen({ port, host: \"127.0.0.1\" });\n  return app;\n}\n","/**\n * Tiny stderr logger — never write progress to stdout (that's the MCP wire).\n *\n * `setQuiet(true)` suppresses `log.info()`. Warnings and errors are never\n * silenced — those carry information the user cannot live without.\n */\nimport kleur from \"kleur\";\n\nlet quiet = false;\n\n/** Toggle the info-channel silence. Idempotent. */\nexport const setQuiet = (q: boolean): void => {\n  quiet = q;\n};\n\n/** For tests + introspection. Not for hot paths. */\nexport const isQuiet = (): boolean => quiet;\n\nexport const log = {\n  info: (msg: string): void => {\n    if (quiet) return;\n    process.stderr.write(`${kleur.dim(\"mcp-devtools\")} ${msg}\\n`);\n  },\n  warn: (msg: string): void => {\n    process.stderr.write(`${kleur.yellow(\"warn\")} ${msg}\\n`);\n  },\n  err: (msg: string): void => {\n    process.stderr.write(`${kleur.red(\"error\")} ${msg}\\n`);\n  },\n};\n","/** Cross-platform \"open a URL in the user's default browser\". */\nimport { spawn } from \"node:child_process\";\n\nexport async function openBrowserAt(url: string): Promise<void> {\n  const cmd =\n    process.platform === \"darwin\" ? \"open\" : process.platform === \"win32\" ? \"start\" : \"xdg-open\";\n  spawn(cmd, [url], { detached: true, stdio: \"ignore\" }).unref();\n}\n","import { spawn } from \"node:child_process\";\n/**\n * Recorder mode — same proxy plumbing but skips the UI and writes a\n * `.mcptrace` (gzipped JSONL) artifact instead. Designed to be replayable\n * deterministically; useful in CI to catch protocol regressions.\n */\nimport { createWriteStream } from \"node:fs\";\nimport { createGzip } from \"node:zlib\";\nimport { parseFrames } from \"./jsonrpc.js\";\nimport { log } from \"./util/log.js\";\n\nexport interface RecorderOptions {\n  upstreamCommand: string;\n  outPath: string;\n}\n\nexport async function startRecorder(opts: RecorderOptions): Promise<void> {\n  const gz = createGzip();\n  const out = createWriteStream(opts.outPath);\n  gz.pipe(out);\n\n  const parts = opts.upstreamCommand.match(/(?:[^\\s\"']+|\"[^\"]*\"|'[^']*')+/g) ?? [];\n  const cmd = parts[0];\n  if (!cmd) throw new Error(\"empty --upstream command\");\n  const args = parts.slice(1);\n\n  const child = spawn(cmd, args, { stdio: [\"pipe\", \"pipe\", \"pipe\"] });\n  log.info(`recording → ${opts.outPath}`);\n\n  let seq = 0;\n  const write = (direction: \"in\" | \"out\", chunk: Buffer) => {\n    for (const frame of parseFrames(chunk)) {\n      gz.write(`${JSON.stringify({ id: ++seq, ts: Date.now(), direction, frame })}\\n`);\n    }\n  };\n\n  process.stdin.on(\"data\", (c) => {\n    child.stdin.write(c);\n    write(\"out\", c);\n  });\n  // Propagate stdin EOF to the child so it can shut down cleanly.\n  process.stdin.on(\"end\", () => child.stdin.end());\n  child.stdout.on(\"data\", (c) => {\n    process.stdout.write(c);\n    write(\"in\", c);\n  });\n  child.stderr.on(\"data\", (c) => process.stderr.write(c));\n\n  child.on(\"exit\", (code) => {\n    // End the gzip transform; wait for the file stream to drain *and* close\n    // before exiting, otherwise the trailing bytes never reach disk.\n    gz.end();\n    out.on(\"finish\", () => process.exit(code ?? 0));\n  });\n}\n","export type PortCheck = { ok: true; value: number } | { ok: false; message: string };\n\nfunction basePortError(got: unknown): string {\n  return `error: --port must be between 1024 and 65535 (got ${String(got)})`;\n}\n\nexport function validatePort(raw: unknown): PortCheck {\n  const port = Number(raw);\n\n  if (!Number.isInteger(port) || port < 0 || port > 65535) {\n    return { ok: false, message: basePortError(raw) };\n  }\n\n  if (port < 1024) {\n    return {\n      ok: false,\n      message: `${basePortError(raw)}; ports below 1024 usually require root, pick a higher port`,\n    };\n  }\n\n  return { ok: true, value: port };\n}\n","import { EventEmitter } from \"node:events\";\n/**\n * Open a previously recorded `.mcptrace` file in the inspector UI.\n * Replays frames into a fresh TraceStore in chronological order and serves\n * the UI in read-only mode.\n */\nimport { createReadStream } from \"node:fs\";\nimport { createInterface } from \"node:readline\";\nimport { createGunzip } from \"node:zlib\";\nimport { TraceStore } from \"./trace-store.js\";\nimport { startUiServer } from \"./ui-server.js\";\nimport { log } from \"./util/log.js\";\nimport { openBrowserAt } from \"./util/open.js\";\n\nexport interface TraceViewerOptions {\n  tracePath: string;\n  port: number;\n}\n\nexport async function openTrace({ tracePath, port }: TraceViewerOptions) {\n  const store = new TraceStore();\n  const events = new EventEmitter();\n\n  const rl = createInterface({\n    input: createReadStream(tracePath).pipe(createGunzip()),\n    crlfDelay: Number.POSITIVE_INFINITY,\n  });\n\n  for await (const line of rl) {\n    if (!line.trim()) continue;\n    const row = JSON.parse(line);\n    store.record({ direction: row.direction, frame: row.frame });\n  }\n\n  await startUiServer({ port, store, events });\n  log.info(`viewing ${tracePath} → http://localhost:${port}/inspect`);\n  await openBrowserAt(`http://localhost:${port}/inspect`);\n}\n"],"mappings":"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","names":["spawn","join","spawn","spawn","spawn","EventEmitter","EventEmitter"]}

package/dist/embed.d.ts

@@ -0,0 +1,16 @@
+interface EmbedOptions {
+    port?: number;
+    openBrowser?: boolean;
+}
+/** Structural interface — works with the official SDK's `Server` or any custom one. */
+interface AttachableServer {
+    _transport?: {
+        onMessage: (m: unknown) => void;
+        send: (m: unknown) => void;
+    };
+}
+declare const devtools: {
+    attach(server: AttachableServer, opts?: EmbedOptions): Promise<void>;
+};
+
+export { type AttachableServer, type EmbedOptions, devtools };

package/dist/embed.js

@@ -0,0 +1,38 @@
+import {
+  TraceStore,
+  log,
+  startUiServer
+} from "./chunk-3V7Q2E62.js";
+
+// src/embed.ts
+import { EventEmitter } from "events";
+var devtools = {
+  async attach(server, opts = {}) {
+    const port = opts.port ?? 7456;
+    const store = new TraceStore();
+    const events = new EventEmitter();
+    const transport = server._transport;
+    if (transport) {
+      const realOnMessage = transport.onMessage.bind(transport);
+      transport.onMessage = (msg) => {
+        const id = store.record({ direction: "out", frame: msg });
+        events.emit("frame", id);
+        return realOnMessage(msg);
+      };
+      const realSend = transport.send.bind(transport);
+      transport.send = (msg) => {
+        const id = store.record({ direction: "in", frame: msg });
+        events.emit("frame", id);
+        return realSend(msg);
+      };
+    } else {
+      log.warn("embed: server has no `_transport`; recording is disabled");
+    }
+    await startUiServer({ port, store, events });
+    log.info(`mcp-devtools embed \u2192 http://localhost:${port}/inspect`);
+  }
+};
+export {
+  devtools
+};
+//# sourceMappingURL=embed.js.map

package/dist/embed.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/embed.ts"],"sourcesContent":["/**\n * Embed mode: attach the inspector UI to an MCP server you already have.\n *\n *   import { devtools } from \"mcp-devtools/embed\";\n *   devtools.attach(server, { port: 7456 });\n *\n * Works by wrapping the server's transport so that every send/receive is also\n * recorded in the local TraceStore that backs the UI.\n *\n * Note: we intentionally use a structural type for the server parameter so we\n * don't take a hard runtime dependency on the @modelcontextprotocol/sdk\n * package — the inspector works with any object that exposes a transport with\n * `onMessage` and `send` hooks.\n */\nimport { EventEmitter } from \"node:events\";\nimport { TraceStore } from \"./trace-store.js\";\nimport { startUiServer } from \"./ui-server.js\";\nimport { log } from \"./util/log.js\";\n\nexport interface EmbedOptions {\n  port?: number;\n  openBrowser?: boolean;\n}\n\n/** Structural interface — works with the official SDK's `Server` or any custom one. */\nexport interface AttachableServer {\n  // The SDK exposes the transport on a (currently private) `_transport` field.\n  // We probe for it gracefully and degrade to no-op if it isn't there.\n  _transport?: {\n    onMessage: (m: unknown) => void;\n    send: (m: unknown) => void;\n  };\n}\n\nexport const devtools = {\n  async attach(server: AttachableServer, opts: EmbedOptions = {}): Promise<void> {\n    const port = opts.port ?? 7456;\n    const store = new TraceStore();\n    const events = new EventEmitter();\n\n    const transport = server._transport;\n    if (transport) {\n      const realOnMessage = transport.onMessage.bind(transport);\n      transport.onMessage = (msg: unknown) => {\n        const id = store.record({ direction: \"out\", frame: msg as never });\n        events.emit(\"frame\", id);\n        return realOnMessage(msg);\n      };\n      const realSend = transport.send.bind(transport);\n      transport.send = (msg: unknown) => {\n        const id = store.record({ direction: \"in\", frame: msg as never });\n        events.emit(\"frame\", id);\n        return realSend(msg);\n      };\n    } else {\n      log.warn(\"embed: server has no `_transport`; recording is disabled\");\n    }\n\n    await startUiServer({ port, store, events });\n    log.info(`mcp-devtools embed → http://localhost:${port}/inspect`);\n  },\n};\n"],"mappings":";;;;;;;AAcA,SAAS,oBAAoB;AAoBtB,IAAM,WAAW;AAAA,EACtB,MAAM,OAAO,QAA0B,OAAqB,CAAC,GAAkB;AAC7E,UAAM,OAAO,KAAK,QAAQ;AAC1B,UAAM,QAAQ,IAAI,WAAW;AAC7B,UAAM,SAAS,IAAI,aAAa;AAEhC,UAAM,YAAY,OAAO;AACzB,QAAI,WAAW;AACb,YAAM,gBAAgB,UAAU,UAAU,KAAK,SAAS;AACxD,gBAAU,YAAY,CAAC,QAAiB;AACtC,cAAM,KAAK,MAAM,OAAO,EAAE,WAAW,OAAO,OAAO,IAAa,CAAC;AACjE,eAAO,KAAK,SAAS,EAAE;AACvB,eAAO,cAAc,GAAG;AAAA,MAC1B;AACA,YAAM,WAAW,UAAU,KAAK,KAAK,SAAS;AAC9C,gBAAU,OAAO,CAAC,QAAiB;AACjC,cAAM,KAAK,MAAM,OAAO,EAAE,WAAW,MAAM,OAAO,IAAa,CAAC;AAChE,eAAO,KAAK,SAAS,EAAE;AACvB,eAAO,SAAS,GAAG;AAAA,MACrB;AAAA,IACF,OAAO;AACL,UAAI,KAAK,0DAA0D;AAAA,IACrE;AAEA,UAAM,cAAc,EAAE,MAAM,OAAO,OAAO,CAAC;AAC3C,QAAI,KAAK,8CAAyC,IAAI,UAAU;AAAA,EAClE;AACF;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+interface ProxyOptions {
+    upstreamCommand: string;
+    port: number;
+    transport: "stdio" | "http";
+    openBrowser: boolean;
+}
+declare function startProxy(opts: ProxyOptions): Promise<void>;
+
+interface RecorderOptions {
+    upstreamCommand: string;
+    outPath: string;
+}
+declare function startRecorder(opts: RecorderOptions): Promise<void>;
+
+interface TraceViewerOptions {
+    tracePath: string;
+    port: number;
+}
+declare function openTrace({ tracePath, port }: TraceViewerOptions): Promise<void>;
+
+/**
+ * Minimal JSON-RPC 2.0 frame parser for MCP's newline-delimited stdio transport.
+ *
+ * MCP servers speak newline-delimited JSON over stdio (the official spec). We
+ * read incoming bytes into a buffer and emit one parsed frame per line. We
+ * deliberately do NOT validate the JSON-RPC structure — the upstream server
+ * already does that, and we don't want the proxy to choke on a server bug.
+ */
+type JsonRpcFrame = JsonRpcRequest | JsonRpcResponse | JsonRpcNotification | {
+    _raw: string;
+    _parseError: string;
+};
+interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id: number | string;
+    method: string;
+    params?: unknown;
+}
+interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    id: number | string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+interface JsonRpcNotification {
+    jsonrpc: "2.0";
+    method: string;
+    params?: unknown;
+}
+declare function parseFrames(chunk: Buffer): JsonRpcFrame[];
+/** Helper used by the UI to classify a frame for display. */
+declare function classify(f: JsonRpcFrame): {
+    kind: "request";
+    method: string;
+    id: number | string;
+} | {
+    kind: "response";
+    id: number | string;
+    isError: boolean;
+} | {
+    kind: "notification";
+    method: string;
+} | {
+    kind: "malformed";
+};
+
+interface StoredFrame {
+    id: number;
+    direction: "in" | "out";
+    ts: number;
+    frame: JsonRpcFrame;
+}
+interface RecordInput {
+    direction: "in" | "out";
+    frame: JsonRpcFrame;
+}
+declare class TraceStore {
+    private buf;
+    private nextId;
+    private logPath;
+    private initialized;
+    constructor(opts?: {
+        logDir?: string;
+    });
+    record(input: RecordInput): number;
+    /** All frames in chronological order. */
+    all(): StoredFrame[];
+    /** Frames since (exclusive) the given id. Used by the UI's live stream. */
+    since(id: number): StoredFrame[];
+    private persist;
+}
+
+export { type JsonRpcFrame, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcResponse, type ProxyOptions, type RecorderOptions, type StoredFrame, TraceStore, type TraceViewerOptions, classify, openTrace, parseFrames, startProxy, startRecorder };

package/dist/index.js

@@ -0,0 +1,162 @@
+import {
+  TraceStore,
+  log,
+  startUiServer
+} from "./chunk-3V7Q2E62.js";
+
+// src/proxy.ts
+import { spawn as spawn2 } from "child_process";
+import { EventEmitter } from "events";
+
+// src/jsonrpc.ts
+var pending = "";
+function parseFrames(chunk) {
+  pending += chunk.toString("utf8");
+  const frames = [];
+  let nl = pending.indexOf("\n");
+  while (nl !== -1) {
+    const line = pending.slice(0, nl).trim();
+    pending = pending.slice(nl + 1);
+    if (line) {
+      try {
+        frames.push(JSON.parse(line));
+      } catch (err) {
+        frames.push({ _raw: line, _parseError: err.message });
+      }
+    }
+    nl = pending.indexOf("\n");
+  }
+  return frames;
+}
+function classify(f) {
+  if ("_parseError" in f) return { kind: "malformed" };
+  if ("id" in f && "method" in f) {
+    return { kind: "request", method: f.method, id: f.id };
+  }
+  if ("id" in f) {
+    return { kind: "response", id: f.id, isError: "error" in f };
+  }
+  if ("method" in f) return { kind: "notification", method: f.method };
+  return { kind: "malformed" };
+}
+
+// src/util/open.ts
+import { spawn } from "child_process";
+async function openBrowserAt(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
+}
+
+// src/proxy.ts
+async function startProxy(opts) {
+  if (opts.transport === "http") {
+    throw new Error("HTTP transport is on the v0.2 roadmap. Use stdio for now.");
+  }
+  const store = new TraceStore();
+  const events = new EventEmitter();
+  const parts = splitCommand(opts.upstreamCommand);
+  const cmd = parts[0];
+  if (!cmd) throw new Error("empty --upstream command");
+  const args = parts.slice(1);
+  const child = spawn2(cmd, args, {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: { ...process.env, MCP_DEVTOOLS_PROXIED: "1" }
+  });
+  log.info(`upstream \u2192 ${opts.upstreamCommand} (pid ${child.pid})`);
+  process.stdin.on("data", (chunk) => {
+    child.stdin.write(chunk);
+    for (const frame of parseFrames(chunk)) {
+      const id = store.record({ direction: "out", frame });
+      events.emit("frame", id);
+    }
+  });
+  process.stdin.on("end", () => child.stdin.end());
+  child.stdout.on("data", (chunk) => {
+    process.stdout.write(chunk);
+    for (const frame of parseFrames(chunk)) {
+      const id = store.record({ direction: "in", frame });
+      events.emit("frame", id);
+    }
+  });
+  child.stderr.on("data", (chunk) => process.stderr.write(chunk));
+  child.on("exit", (code) => {
+    log.info(`upstream exited with code ${code}`);
+    process.exit(code ?? 0);
+  });
+  await startUiServer({ port: opts.port, store, events });
+  log.info(`inspector ready \u2192 http://localhost:${opts.port}/inspect`);
+  if (opts.openBrowser) {
+    await openBrowserAt(`http://localhost:${opts.port}/inspect`);
+  }
+}
+function splitCommand(s) {
+  return s.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+}
+
+// src/recorder.ts
+import { spawn as spawn3 } from "child_process";
+import { createWriteStream } from "fs";
+import { createGzip } from "zlib";
+async function startRecorder(opts) {
+  const gz = createGzip();
+  const out = createWriteStream(opts.outPath);
+  gz.pipe(out);
+  const parts = opts.upstreamCommand.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+  const cmd = parts[0];
+  if (!cmd) throw new Error("empty --upstream command");
+  const args = parts.slice(1);
+  const child = spawn3(cmd, args, { stdio: ["pipe", "pipe", "pipe"] });
+  log.info(`recording \u2192 ${opts.outPath}`);
+  let seq = 0;
+  const write = (direction, chunk) => {
+    for (const frame of parseFrames(chunk)) {
+      gz.write(`${JSON.stringify({ id: ++seq, ts: Date.now(), direction, frame })}
+`);
+    }
+  };
+  process.stdin.on("data", (c) => {
+    child.stdin.write(c);
+    write("out", c);
+  });
+  process.stdin.on("end", () => child.stdin.end());
+  child.stdout.on("data", (c) => {
+    process.stdout.write(c);
+    write("in", c);
+  });
+  child.stderr.on("data", (c) => process.stderr.write(c));
+  child.on("exit", (code) => {
+    gz.end();
+    out.on("finish", () => process.exit(code ?? 0));
+  });
+}
+
+// src/viewer.ts
+import { EventEmitter as EventEmitter2 } from "events";
+import { createReadStream } from "fs";
+import { createInterface } from "readline";
+import { createGunzip } from "zlib";
+async function openTrace({ tracePath, port }) {
+  const store = new TraceStore();
+  const events = new EventEmitter2();
+  const rl = createInterface({
+    input: createReadStream(tracePath).pipe(createGunzip()),
+    crlfDelay: Number.POSITIVE_INFINITY
+  });
+  for await (const line of rl) {
+    if (!line.trim()) continue;
+    const row = JSON.parse(line);
+    store.record({ direction: row.direction, frame: row.frame });
+  }
+  await startUiServer({ port, store, events });
+  log.info(`viewing ${tracePath} \u2192 http://localhost:${port}/inspect`);
+  await openBrowserAt(`http://localhost:${port}/inspect`);
+}
+export {
+  TraceStore,
+  classify,
+  openTrace,
+  parseFrames,
+  startProxy,
+  startRecorder
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/proxy.ts","../src/jsonrpc.ts","../src/util/open.ts","../src/recorder.ts","../src/viewer.ts"],"sourcesContent":["/**\n * Transparent MCP proxy.\n *\n * Spawns the upstream MCP server as a child process and pipes JSON-RPC frames\n * in both directions while persisting them to the in-memory ring buffer that\n * the inspector UI subscribes to.\n *\n * The proxy is intentionally protocol-agnostic — it does NOT parse semantic\n * tool calls; it parses JSON-RPC envelopes and tags each frame with direction,\n * timestamp, and a monotonically-increasing sequence number. Semantic\n * interpretation (e.g. \"this is a tools/call\") happens in the UI layer.\n */\nimport { type ChildProcessWithoutNullStreams, spawn } from \"node:child_process\";\nimport { EventEmitter } from \"node:events\";\nimport { parseFrames } from \"./jsonrpc.js\";\nimport { TraceStore } from \"./trace-store.js\";\nimport { startUiServer } from \"./ui-server.js\";\nimport { log } from \"./util/log.js\";\nimport { openBrowserAt } from \"./util/open.js\";\n\nexport interface ProxyOptions {\n  upstreamCommand: string;\n  port: number;\n  transport: \"stdio\" | \"http\";\n  openBrowser: boolean;\n}\n\nexport async function startProxy(opts: ProxyOptions): Promise<void> {\n  if (opts.transport === \"http\") {\n    throw new Error(\"HTTP transport is on the v0.2 roadmap. Use stdio for now.\");\n  }\n\n  const store = new TraceStore();\n  const events = new EventEmitter();\n\n  // Spawn the upstream server.\n  const parts = splitCommand(opts.upstreamCommand);\n  const cmd = parts[0];\n  if (!cmd) throw new Error(\"empty --upstream command\");\n  const args = parts.slice(1);\n\n  const child: ChildProcessWithoutNullStreams = spawn(cmd, args, {\n    stdio: [\"pipe\", \"pipe\", \"pipe\"],\n    env: { ...process.env, MCP_DEVTOOLS_PROXIED: \"1\" },\n  });\n  log.info(`upstream → ${opts.upstreamCommand} (pid ${child.pid})`);\n\n  // Stream stdin → upstream, tagging frames going \"out\" (client → server).\n  process.stdin.on(\"data\", (chunk) => {\n    child.stdin.write(chunk);\n    for (const frame of parseFrames(chunk)) {\n      const id = store.record({ direction: \"out\", frame });\n      events.emit(\"frame\", id);\n    }\n  });\n  // Propagate stdin EOF so the upstream can shut down cleanly.\n  process.stdin.on(\"end\", () => child.stdin.end());\n\n  // Stream upstream stdout → stdin, tagging frames going \"in\" (server → client).\n  child.stdout.on(\"data\", (chunk) => {\n    process.stdout.write(chunk);\n    for (const frame of parseFrames(chunk)) {\n      const id = store.record({ direction: \"in\", frame });\n      events.emit(\"frame\", id);\n    }\n  });\n\n  // Surface upstream stderr — never swallow it.\n  child.stderr.on(\"data\", (chunk) => process.stderr.write(chunk));\n\n  child.on(\"exit\", (code) => {\n    log.info(`upstream exited with code ${code}`);\n    process.exit(code ?? 0);\n  });\n\n  // Spin up the UI server.\n  await startUiServer({ port: opts.port, store, events });\n  log.info(`inspector ready → http://localhost:${opts.port}/inspect`);\n\n  if (opts.openBrowser) {\n    await openBrowserAt(`http://localhost:${opts.port}/inspect`);\n  }\n}\n\nfunction splitCommand(s: string): string[] {\n  // Naive shell split — good enough for the common case `node ./server.js`.\n  // Real users can pass `--upstream \"/bin/sh -c '...'\"` for anything fancier.\n  return s.match(/(?:[^\\s\"']+|\"[^\"]*\"|'[^']*')+/g) ?? [];\n}\n","/**\n * Minimal JSON-RPC 2.0 frame parser for MCP's newline-delimited stdio transport.\n *\n * MCP servers speak newline-delimited JSON over stdio (the official spec). We\n * read incoming bytes into a buffer and emit one parsed frame per line. We\n * deliberately do NOT validate the JSON-RPC structure — the upstream server\n * already does that, and we don't want the proxy to choke on a server bug.\n */\n\nexport type JsonRpcFrame =\n  | JsonRpcRequest\n  | JsonRpcResponse\n  | JsonRpcNotification\n  | { _raw: string; _parseError: string };\n\nexport interface JsonRpcRequest {\n  jsonrpc: \"2.0\";\n  id: number | string;\n  method: string;\n  params?: unknown;\n}\n\nexport interface JsonRpcResponse {\n  jsonrpc: \"2.0\";\n  id: number | string;\n  result?: unknown;\n  error?: { code: number; message: string; data?: unknown };\n}\n\nexport interface JsonRpcNotification {\n  jsonrpc: \"2.0\";\n  method: string;\n  params?: unknown;\n}\n\nlet pending = \"\";\n\nexport function parseFrames(chunk: Buffer): JsonRpcFrame[] {\n  pending += chunk.toString(\"utf8\");\n  const frames: JsonRpcFrame[] = [];\n  let nl = pending.indexOf(\"\\n\");\n  while (nl !== -1) {\n    const line = pending.slice(0, nl).trim();\n    pending = pending.slice(nl + 1);\n    if (line) {\n      try {\n        frames.push(JSON.parse(line));\n      } catch (err) {\n        frames.push({ _raw: line, _parseError: (err as Error).message });\n      }\n    }\n    nl = pending.indexOf(\"\\n\");\n  }\n  return frames;\n}\n\n/** Helper used by the UI to classify a frame for display. */\nexport function classify(\n  f: JsonRpcFrame,\n):\n  | { kind: \"request\"; method: string; id: number | string }\n  | { kind: \"response\"; id: number | string; isError: boolean }\n  | { kind: \"notification\"; method: string }\n  | { kind: \"malformed\" } {\n  if (\"_parseError\" in f) return { kind: \"malformed\" };\n  if (\"id\" in f && \"method\" in f) {\n    return { kind: \"request\", method: f.method, id: f.id };\n  }\n  if (\"id\" in f) {\n    return { kind: \"response\", id: f.id, isError: \"error\" in f };\n  }\n  if (\"method\" in f) return { kind: \"notification\", method: f.method };\n  return { kind: \"malformed\" };\n}\n","/** Cross-platform \"open a URL in the user's default browser\". */\nimport { spawn } from \"node:child_process\";\n\nexport async function openBrowserAt(url: string): Promise<void> {\n  const cmd =\n    process.platform === \"darwin\" ? \"open\" : process.platform === \"win32\" ? \"start\" : \"xdg-open\";\n  spawn(cmd, [url], { detached: true, stdio: \"ignore\" }).unref();\n}\n","import { spawn } from \"node:child_process\";\n/**\n * Recorder mode — same proxy plumbing but skips the UI and writes a\n * `.mcptrace` (gzipped JSONL) artifact instead. Designed to be replayable\n * deterministically; useful in CI to catch protocol regressions.\n */\nimport { createWriteStream } from \"node:fs\";\nimport { createGzip } from \"node:zlib\";\nimport { parseFrames } from \"./jsonrpc.js\";\nimport { log } from \"./util/log.js\";\n\nexport interface RecorderOptions {\n  upstreamCommand: string;\n  outPath: string;\n}\n\nexport async function startRecorder(opts: RecorderOptions): Promise<void> {\n  const gz = createGzip();\n  const out = createWriteStream(opts.outPath);\n  gz.pipe(out);\n\n  const parts = opts.upstreamCommand.match(/(?:[^\\s\"']+|\"[^\"]*\"|'[^']*')+/g) ?? [];\n  const cmd = parts[0];\n  if (!cmd) throw new Error(\"empty --upstream command\");\n  const args = parts.slice(1);\n\n  const child = spawn(cmd, args, { stdio: [\"pipe\", \"pipe\", \"pipe\"] });\n  log.info(`recording → ${opts.outPath}`);\n\n  let seq = 0;\n  const write = (direction: \"in\" | \"out\", chunk: Buffer) => {\n    for (const frame of parseFrames(chunk)) {\n      gz.write(`${JSON.stringify({ id: ++seq, ts: Date.now(), direction, frame })}\\n`);\n    }\n  };\n\n  process.stdin.on(\"data\", (c) => {\n    child.stdin.write(c);\n    write(\"out\", c);\n  });\n  // Propagate stdin EOF to the child so it can shut down cleanly.\n  process.stdin.on(\"end\", () => child.stdin.end());\n  child.stdout.on(\"data\", (c) => {\n    process.stdout.write(c);\n    write(\"in\", c);\n  });\n  child.stderr.on(\"data\", (c) => process.stderr.write(c));\n\n  child.on(\"exit\", (code) => {\n    // End the gzip transform; wait for the file stream to drain *and* close\n    // before exiting, otherwise the trailing bytes never reach disk.\n    gz.end();\n    out.on(\"finish\", () => process.exit(code ?? 0));\n  });\n}\n","import { EventEmitter } from \"node:events\";\n/**\n * Open a previously recorded `.mcptrace` file in the inspector UI.\n * Replays frames into a fresh TraceStore in chronological order and serves\n * the UI in read-only mode.\n */\nimport { createReadStream } from \"node:fs\";\nimport { createInterface } from \"node:readline\";\nimport { createGunzip } from \"node:zlib\";\nimport { TraceStore } from \"./trace-store.js\";\nimport { startUiServer } from \"./ui-server.js\";\nimport { log } from \"./util/log.js\";\nimport { openBrowserAt } from \"./util/open.js\";\n\nexport interface TraceViewerOptions {\n  tracePath: string;\n  port: number;\n}\n\nexport async function openTrace({ tracePath, port }: TraceViewerOptions) {\n  const store = new TraceStore();\n  const events = new EventEmitter();\n\n  const rl = createInterface({\n    input: createReadStream(tracePath).pipe(createGunzip()),\n    crlfDelay: Number.POSITIVE_INFINITY,\n  });\n\n  for await (const line of rl) {\n    if (!line.trim()) continue;\n    const row = JSON.parse(line);\n    store.record({ direction: row.direction, frame: row.frame });\n  }\n\n  await startUiServer({ port, store, events });\n  log.info(`viewing ${tracePath} → http://localhost:${port}/inspect`);\n  await openBrowserAt(`http://localhost:${port}/inspect`);\n}\n"],"mappings":";;;;;;;AAYA,SAA8C,SAAAA,cAAa;AAC3D,SAAS,oBAAoB;;;ACsB7B,IAAI,UAAU;AAEP,SAAS,YAAY,OAA+B;AACzD,aAAW,MAAM,SAAS,MAAM;AAChC,QAAM,SAAyB,CAAC;AAChC,MAAI,KAAK,QAAQ,QAAQ,IAAI;AAC7B,SAAO,OAAO,IAAI;AAChB,UAAM,OAAO,QAAQ,MAAM,GAAG,EAAE,EAAE,KAAK;AACvC,cAAU,QAAQ,MAAM,KAAK,CAAC;AAC9B,QAAI,MAAM;AACR,UAAI;AACF,eAAO,KAAK,KAAK,MAAM,IAAI,CAAC;AAAA,MAC9B,SAAS,KAAK;AACZ,eAAO,KAAK,EAAE,MAAM,MAAM,aAAc,IAAc,QAAQ,CAAC;AAAA,MACjE;AAAA,IACF;AACA,SAAK,QAAQ,QAAQ,IAAI;AAAA,EAC3B;AACA,SAAO;AACT;AAGO,SAAS,SACd,GAKwB;AACxB,MAAI,iBAAiB,EAAG,QAAO,EAAE,MAAM,YAAY;AACnD,MAAI,QAAQ,KAAK,YAAY,GAAG;AAC9B,WAAO,EAAE,MAAM,WAAW,QAAQ,EAAE,QAAQ,IAAI,EAAE,GAAG;AAAA,EACvD;AACA,MAAI,QAAQ,GAAG;AACb,WAAO,EAAE,MAAM,YAAY,IAAI,EAAE,IAAI,SAAS,WAAW,EAAE;AAAA,EAC7D;AACA,MAAI,YAAY,EAAG,QAAO,EAAE,MAAM,gBAAgB,QAAQ,EAAE,OAAO;AACnE,SAAO,EAAE,MAAM,YAAY;AAC7B;;;ACxEA,SAAS,aAAa;AAEtB,eAAsB,cAAc,KAA4B;AAC9D,QAAM,MACJ,QAAQ,aAAa,WAAW,SAAS,QAAQ,aAAa,UAAU,UAAU;AACpF,QAAM,KAAK,CAAC,GAAG,GAAG,EAAE,UAAU,MAAM,OAAO,SAAS,CAAC,EAAE,MAAM;AAC/D;;;AFoBA,eAAsB,WAAW,MAAmC;AAClE,MAAI,KAAK,cAAc,QAAQ;AAC7B,UAAM,IAAI,MAAM,2DAA2D;AAAA,EAC7E;AAEA,QAAM,QAAQ,IAAI,WAAW;AAC7B,QAAM,SAAS,IAAI,aAAa;AAGhC,QAAM,QAAQ,aAAa,KAAK,eAAe;AAC/C,QAAM,MAAM,MAAM,CAAC;AACnB,MAAI,CAAC,IAAK,OAAM,IAAI,MAAM,0BAA0B;AACpD,QAAM,OAAO,MAAM,MAAM,CAAC;AAE1B,QAAM,QAAwCC,OAAM,KAAK,MAAM;AAAA,IAC7D,OAAO,CAAC,QAAQ,QAAQ,MAAM;AAAA,IAC9B,KAAK,EAAE,GAAG,QAAQ,KAAK,sBAAsB,IAAI;AAAA,EACnD,CAAC;AACD,MAAI,KAAK,mBAAc,KAAK,eAAe,SAAS,MAAM,GAAG,GAAG;AAGhE,UAAQ,MAAM,GAAG,QAAQ,CAAC,UAAU;AAClC,UAAM,MAAM,MAAM,KAAK;AACvB,eAAW,SAAS,YAAY,KAAK,GAAG;AACtC,YAAM,KAAK,MAAM,OAAO,EAAE,WAAW,OAAO,MAAM,CAAC;AACnD,aAAO,KAAK,SAAS,EAAE;AAAA,IACzB;AAAA,EACF,CAAC;AAED,UAAQ,MAAM,GAAG,OAAO,MAAM,MAAM,MAAM,IAAI,CAAC;AAG/C,QAAM,OAAO,GAAG,QAAQ,CAAC,UAAU;AACjC,YAAQ,OAAO,MAAM,KAAK;AAC1B,eAAW,SAAS,YAAY,KAAK,GAAG;AACtC,YAAM,KAAK,MAAM,OAAO,EAAE,WAAW,MAAM,MAAM,CAAC;AAClD,aAAO,KAAK,SAAS,EAAE;AAAA,IACzB;AAAA,EACF,CAAC;AAGD,QAAM,OAAO,GAAG,QAAQ,CAAC,UAAU,QAAQ,OAAO,MAAM,KAAK,CAAC;AAE9D,QAAM,GAAG,QAAQ,CAAC,SAAS;AACzB,QAAI,KAAK,6BAA6B,IAAI,EAAE;AAC5C,YAAQ,KAAK,QAAQ,CAAC;AAAA,EACxB,CAAC;AAGD,QAAM,cAAc,EAAE,MAAM,KAAK,MAAM,OAAO,OAAO,CAAC;AACtD,MAAI,KAAK,2CAAsC,KAAK,IAAI,UAAU;AAElE,MAAI,KAAK,aAAa;AACpB,UAAM,cAAc,oBAAoB,KAAK,IAAI,UAAU;AAAA,EAC7D;AACF;AAEA,SAAS,aAAa,GAAqB;AAGzC,SAAO,EAAE,MAAM,gCAAgC,KAAK,CAAC;AACvD;;;AGxFA,SAAS,SAAAC,cAAa;AAMtB,SAAS,yBAAyB;AAClC,SAAS,kBAAkB;AAS3B,eAAsB,cAAc,MAAsC;AACxE,QAAM,KAAK,WAAW;AACtB,QAAM,MAAM,kBAAkB,KAAK,OAAO;AAC1C,KAAG,KAAK,GAAG;AAEX,QAAM,QAAQ,KAAK,gBAAgB,MAAM,gCAAgC,KAAK,CAAC;AAC/E,QAAM,MAAM,MAAM,CAAC;AACnB,MAAI,CAAC,IAAK,OAAM,IAAI,MAAM,0BAA0B;AACpD,QAAM,OAAO,MAAM,MAAM,CAAC;AAE1B,QAAM,QAAQC,OAAM,KAAK,MAAM,EAAE,OAAO,CAAC,QAAQ,QAAQ,MAAM,EAAE,CAAC;AAClE,MAAI,KAAK,oBAAe,KAAK,OAAO,EAAE;AAEtC,MAAI,MAAM;AACV,QAAM,QAAQ,CAAC,WAAyB,UAAkB;AACxD,eAAW,SAAS,YAAY,KAAK,GAAG;AACtC,SAAG,MAAM,GAAG,KAAK,UAAU,EAAE,IAAI,EAAE,KAAK,IAAI,KAAK,IAAI,GAAG,WAAW,MAAM,CAAC,CAAC;AAAA,CAAI;AAAA,IACjF;AAAA,EACF;AAEA,UAAQ,MAAM,GAAG,QAAQ,CAAC,MAAM;AAC9B,UAAM,MAAM,MAAM,CAAC;AACnB,UAAM,OAAO,CAAC;AAAA,EAChB,CAAC;AAED,UAAQ,MAAM,GAAG,OAAO,MAAM,MAAM,MAAM,IAAI,CAAC;AAC/C,QAAM,OAAO,GAAG,QAAQ,CAAC,MAAM;AAC7B,YAAQ,OAAO,MAAM,CAAC;AACtB,UAAM,MAAM,CAAC;AAAA,EACf,CAAC;AACD,QAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,QAAQ,OAAO,MAAM,CAAC,CAAC;AAEtD,QAAM,GAAG,QAAQ,CAAC,SAAS;AAGzB,OAAG,IAAI;AACP,QAAI,GAAG,UAAU,MAAM,QAAQ,KAAK,QAAQ,CAAC,CAAC;AAAA,EAChD,CAAC;AACH;;;ACtDA,SAAS,gBAAAC,qBAAoB;AAM7B,SAAS,wBAAwB;AACjC,SAAS,uBAAuB;AAChC,SAAS,oBAAoB;AAW7B,eAAsB,UAAU,EAAE,WAAW,KAAK,GAAuB;AACvE,QAAM,QAAQ,IAAI,WAAW;AAC7B,QAAM,SAAS,IAAIC,cAAa;AAEhC,QAAM,KAAK,gBAAgB;AAAA,IACzB,OAAO,iBAAiB,SAAS,EAAE,KAAK,aAAa,CAAC;AAAA,IACtD,WAAW,OAAO;AAAA,EACpB,CAAC;AAED,mBAAiB,QAAQ,IAAI;AAC3B,QAAI,CAAC,KAAK,KAAK,EAAG;AAClB,UAAM,MAAM,KAAK,MAAM,IAAI;AAC3B,UAAM,OAAO,EAAE,WAAW,IAAI,WAAW,OAAO,IAAI,MAAM,CAAC;AAAA,EAC7D;AAEA,QAAM,cAAc,EAAE,MAAM,OAAO,OAAO,CAAC;AAC3C,MAAI,KAAK,WAAW,SAAS,4BAAuB,IAAI,UAAU;AAClE,QAAM,cAAc,oBAAoB,IAAI,UAAU;AACxD;","names":["spawn","spawn","spawn","spawn","EventEmitter","EventEmitter"]}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@adityachilka/mcp-devtools",
+  "version": "0.1.0",
+  "description": "Chrome DevTools for the Model Context Protocol. Inspect, profile, replay, and diff every MCP call your agent makes.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "devtools",
+    "inspector",
+    "profiler",
+    "llm",
+    "agents",
+    "anthropic",
+    "claude",
+    "observability"
+  ],
+  "license": "MIT",
+  "author": "Aditya Chilka <https://github.com/adityachilka1>",
+  "homepage": "https://github.com/adityachilka1/mcp-devtools#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adityachilka1/mcp-devtools.git"
+  },
+  "bugs": "https://github.com/adityachilka1/mcp-devtools/issues",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "mcp-devtools": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./embed": {
+      "types": "./dist/embed.d.ts",
+      "import": "./dist/embed.js"
+    }
+  },
+  "files": [
+    "dist",
+    "ui",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20",
+    "npm": ">=10"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check src",
+    "format": "biome format --write .",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@fastify/static": "^8.0.0",
+    "@fastify/websocket": "^11.0.0",
+    "cac": "^7.0.0",
+    "fastify": "^5.0.0",
+    "kleur": "^4.1.5",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

package/ui/index.html

@@ -0,0 +1,242 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>mcp-devtools · inspector</title>
+    <style>
+      :root {
+        color-scheme: dark;
+        --bg: #0a0a0a;
+        --panel: #111;
+        --border: #1f1f1f;
+        --fg: #e6e6e6;
+        --muted: #8a8a8a;
+        --accent: #6ee7b7;
+        --warn: #fbbf24;
+        --error: #f87171;
+        font-family: ui-monospace, "JetBrains Mono", SFMono-Regular, Menlo, monospace;
+      }
+      * { box-sizing: border-box; }
+      body { margin: 0; background: var(--bg); color: var(--fg); height: 100vh; display: grid; grid-template-rows: 48px 1fr; }
+      header {
+        display: flex; align-items: center; gap: 12px;
+        padding: 0 16px; border-bottom: 1px solid var(--border);
+        font-size: 13px; letter-spacing: 0.04em; text-transform: uppercase;
+      }
+      header .dot { width: 8px; height: 8px; border-radius: 50%; background: var(--accent); box-shadow: 0 0 10px var(--accent); }
+      header .spacer { flex: 1; }
+      header .stat { color: var(--muted); font-size: 11px; }
+      main { display: grid; grid-template-columns: 360px 1fr; min-height: 0; }
+      .timeline { border-right: 1px solid var(--border); background: var(--panel); display: flex; flex-direction: column; min-height: 0; }
+      .filter-bar {
+        display: flex; align-items: center; gap: 8px;
+        padding: 8px 12px; border-bottom: 1px solid var(--border);
+        background: #0e0e0e;
+      }
+      .filter-bar input {
+        flex: 1; background: #060606; color: var(--fg);
+        border: 1px solid var(--border); border-radius: 4px;
+        padding: 6px 10px; font-family: inherit; font-size: 12px;
+      }
+      .filter-bar input:focus { outline: none; border-color: var(--accent); }
+      .filter-bar .count { color: var(--muted); font-size: 11px; white-space: nowrap; }
+      .rows { flex: 1; overflow-y: auto; }
+      .row {
+        padding: 10px 14px; border-bottom: 1px solid var(--border);
+        cursor: pointer; font-size: 12px; position: relative;
+        border-left: 3px solid transparent;
+      }
+      .row:hover { background: #161616; }
+      .row.selected { background: #1c1c1c; }
+      /* Classification tints — subtle left border + tiny bg tint */
+      .row.req      { border-left-color: var(--warn);   background-color: rgba(251, 191, 36, 0.04); }
+      .row.resp-ok  { border-left-color: var(--accent); background-color: rgba(110, 231, 183, 0.04); }
+      .row.resp-err { border-left-color: var(--error);  background-color: rgba(248, 113, 113, 0.08); }
+      .row.notif    { border-left-color: var(--muted);  background-color: rgba(138, 138, 138, 0.03); }
+      .row.selected.req      { background: #261d10; }
+      .row.selected.resp-ok  { background: #102621; }
+      .row.selected.resp-err { background: #2a1414; }
+      .row.selected.notif    { background: #1c1c1c; }
+      .row .dir { display: inline-block; width: 24px; color: var(--muted); }
+      .row.out .dir { color: var(--warn); }
+      .row.in  .dir { color: var(--accent); }
+      .row.in.resp-err .dir { color: var(--error); }
+      .row .method { font-weight: 600; }
+      .row .lat { float: right; color: var(--muted); }
+      .row.hidden { display: none; }
+      .detail { padding: 0; overflow: auto; display: flex; flex-direction: column; min-height: 0; }
+      .detail-bar {
+        display: flex; align-items: center; gap: 8px;
+        padding: 10px 22px; border-bottom: 1px solid var(--border);
+        background: #0e0e0e;
+      }
+      .detail-bar .label { color: var(--muted); font-size: 11px; letter-spacing: 0.06em; text-transform: uppercase; flex: 1; }
+      .detail-bar button {
+        background: #1a1a1a; color: var(--fg); border: 1px solid var(--border);
+        border-radius: 4px; padding: 6px 12px; font: inherit; font-size: 11px; cursor: pointer;
+      }
+      .detail-bar button:hover { background: #222; border-color: var(--accent); }
+      .detail-bar button.flash { background: var(--accent); color: #000; border-color: var(--accent); }
+      .detail-body { padding: 18px 22px; overflow: auto; flex: 1; }
+      pre { background: #060606; border: 1px solid var(--border); padding: 14px; border-radius: 6px; overflow-x: auto; font-size: 12px; margin: 0; }
+      .empty { color: var(--muted); padding: 24px; text-align: center; }
+    </style>
+  </head>
+  <body>
+    <header>
+      <span class="dot"></span>
+      <span>mcp-devtools · inspector</span>
+      <span class="spacer"></span>
+      <span class="stat" id="stat-frames">0 frames</span>
+    </header>
+    <main>
+      <div class="timeline">
+        <div class="filter-bar">
+          <input id="filter" type="search" placeholder="Filter by method or body — Esc to clear" autocomplete="off" spellcheck="false" />
+          <span class="count" id="filter-count"></span>
+        </div>
+        <div class="rows" id="rows"></div>
+      </div>
+      <div class="detail" id="detail">
+        <div class="empty">Select a frame to inspect.</div>
+      </div>
+    </main>
+    <script>
+      // Minimal inspector — v0.1.x. The React UI replaces this once the
+      // schema explorer and replay views are ready (v0.2).
+      const rowsEl   = document.getElementById("rows");
+      const detail   = document.getElementById("detail");
+      const stat     = document.getElementById("stat-frames");
+      const filter   = document.getElementById("filter");
+      const fcount   = document.getElementById("filter-count");
+
+      const frames = [];
+      let selected = null;
+      let filterStr = "";
+
+      function classify(f) {
+        if (f.frame._parseError) return { kind: "malformed" };
+        const fr = f.frame;
+        if (fr.id != null && fr.method) return { kind: "request", method: fr.method, id: fr.id };
+        if (fr.id != null) return { kind: "response", id: fr.id, isError: !!fr.error };
+        if (fr.method) return { kind: "notification", method: fr.method };
+        return { kind: "malformed" };
+      }
+
+      function rowClass(f) {
+        const c = classify(f);
+        const cls = ["row", f.direction];
+        if (c.kind === "request")       cls.push("req");
+        else if (c.kind === "response") cls.push(c.isError ? "resp-err" : "resp-ok");
+        else if (c.kind === "notification") cls.push("notif");
+        return cls;
+      }
+
+      function rowLabel(f) {
+        const c = classify(f);
+        if (c.kind === "request") return c.method;
+        if (c.kind === "response") return c.isError ? `← #${c.id} · error` : `← #${c.id}`;
+        if (c.kind === "notification") return c.method;
+        return "(malformed)";
+      }
+
+      function matchesFilter(f) {
+        if (!filterStr) return true;
+        const c = classify(f);
+        const hay = [
+          c.method ?? "",
+          String(c.id ?? ""),
+          JSON.stringify(f.frame),
+        ].join(" ").toLowerCase();
+        return hay.includes(filterStr);
+      }
+
+      function render() {
+        let shown = 0;
+        rowsEl.innerHTML = frames.map((f, i) => {
+          const visible = matchesFilter(f);
+          if (visible) shown++;
+          const cls = rowClass(f);
+          if (i === selected) cls.push("selected");
+          if (!visible) cls.push("hidden");
+          return `<div class="${cls.join(" ")}" data-i="${i}">
+            <span class="dir">${f.direction === "in" ? "←" : "→"}</span>
+            <span class="method">${escapeHtml(rowLabel(f))}</span>
+          </div>`;
+        }).join("");
+        stat.textContent = `${frames.length} frame${frames.length === 1 ? "" : "s"}`;
+        fcount.textContent = filterStr ? `${shown}/${frames.length}` : "";
+        for (const el of rowsEl.children) {
+          el.addEventListener("click", () => {
+            selected = Number(el.dataset.i);
+            render();
+            showDetail(frames[selected]);
+          });
+        }
+      }
+
+      function showDetail(f) {
+        const json = JSON.stringify(f.frame, null, 2);
+        detail.innerHTML = `
+          <div class="detail-bar">
+            <span class="label">${escapeHtml(f.direction === "in" ? "server → client" : "client → server")}</span>
+            <button id="copy-btn" title="Copy this frame as JSON">Copy as JSON</button>
+          </div>
+          <div class="detail-body"><pre>${escapeHtml(json)}</pre></div>
+        `;
+        const btn = document.getElementById("copy-btn");
+        btn.addEventListener("click", async () => {
+          try {
+            await navigator.clipboard.writeText(json);
+            const original = btn.textContent;
+            btn.textContent = "Copied ✓";
+            btn.classList.add("flash");
+            setTimeout(() => {
+              btn.textContent = original;
+              btn.classList.remove("flash");
+            }, 1200);
+          } catch (err) {
+            btn.textContent = "Clipboard blocked";
+            setTimeout(() => (btn.textContent = "Copy as JSON"), 1500);
+          }
+        });
+      }
+
+      function escapeHtml(s) {
+        return String(s).replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[c]);
+      }
+
+      // Filter input — debounced lightly so typing isn't laggy on big sessions.
+      let filterTimer;
+      filter.addEventListener("input", (e) => {
+        clearTimeout(filterTimer);
+        filterTimer = setTimeout(() => {
+          filterStr = e.target.value.trim().toLowerCase();
+          render();
+        }, 80);
+      });
+      filter.addEventListener("keydown", (e) => {
+        if (e.key === "Escape") {
+          filter.value = "";
+          filterStr = "";
+          render();
+        }
+      });
+
+      const ws = new WebSocket(`ws://${location.host}/ws`);
+      ws.onmessage = (ev) => {
+        const msg = JSON.parse(ev.data);
+        if (msg.type === "frame") {
+          frames.push(...msg.frames);
+          render();
+        }
+      };
+
+      fetch("/api/frames?since=0").then(r => r.json()).then(initial => {
+        frames.push(...initial);
+        render();
+      });
+    </script>
+  </body>
+</html>