@anma-labs/mcpgaze 1.0.1

package/dist/index.js

@@ -0,0 +1,2148 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { spawn as spawn3 } from "child_process";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname as dirname3, join } from "path";
+
+// src/logger.ts
+import { createWriteStream, mkdirSync } from "fs";
+import { dirname } from "path";
+
+// src/jsonrpc.ts
+function hasId(msg) {
+  return msg.id !== void 0 && msg.id !== null;
+}
+function classify(msg) {
+  const id = hasId(msg);
+  if (msg.method !== void 0 && id) return "request";
+  if (msg.method !== void 0 && !id) return "notification";
+  if (msg.method === void 0 && id && msg.error !== void 0) return "error";
+  if (msg.method === void 0 && id && msg.result !== void 0) return "response";
+  return "unknown";
+}
+
+// src/colors.ts
+var enabled = !process.env.NO_COLOR && (Boolean(process.stderr.isTTY) || Boolean(process.stdout.isTTY));
+function paint(code) {
+  return (s) => enabled ? `\x1B[${code}m${s}\x1B[0m` : s;
+}
+var color = {
+  red: paint(31),
+  green: paint(32),
+  yellow: paint(33),
+  blue: paint(34),
+  cyan: paint(36),
+  gray: paint(90),
+  dim: paint(2),
+  bold: paint(1)
+};
+
+// src/redact.ts
+var MASK = "***REDACTED***";
+var SECRET_KEY = /(pass(word|wd)?|secret|api[-_]?key|access[-_]?key|token|authorization|auth|bearer|cookie|session|credential|client[-_]?secret|private[-_]?key)/i;
+var VALUE_PATTERNS = [
+  // Provider API keys: sk-... / sk-ant-... / AKIA... / ghp_... / xoxb-...
+  [/\b(sk-[a-z]+-)?[A-Za-z0-9_-]{16,}\b(?=)/g, ""]
+  // placeholder; real patterns below
+];
+VALUE_PATTERNS.length = 0;
+VALUE_PATTERNS.push(
+  // user:pass@host inside a DSN/URL — keep the user + host, drop the password.
+  [/([a-z][a-z0-9+.-]*:\/\/[^\s:@/]+:)[^\s@/]+(@)/gi, `$1${MASK}$2`],
+  // sk-ant-…, sk-…, and similar prefixed provider keys.
+  [/\bsk-[A-Za-z0-9-]{8,}\b/g, MASK],
+  // AWS-style access key ids and their secret siblings.
+  [/\bAKIA[0-9A-Z]{8,}\b/g, MASK],
+  [/\b(?:ASIA|AKIA|AGPA|AIDA|AROA|ANPA|ANVA)[0-9A-Z_-]{8,}\b/g, MASK],
+  // GitHub / Slack / generic prefixed tokens.
+  [/\b(?:gh[pousr]|xox[baprs])[-_][A-Za-z0-9-]{10,}\b/g, MASK],
+  // Bearer <token>.
+  [/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, `Bearer ${MASK}`],
+  // JWT-ish three-segment base64url blobs.
+  [/\beyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\b/g, MASK]
+);
+var MAX_DEPTH = 200;
+function redactText(s) {
+  if (typeof s !== "string" || s.length === 0) return s;
+  try {
+    let out = s;
+    for (const [re, repl] of VALUE_PATTERNS) out = out.replace(re, repl);
+    return out;
+  } catch {
+    return s;
+  }
+}
+function redactValue(value, depth = 0) {
+  if (depth >= MAX_DEPTH) return value;
+  if (value === null) return null;
+  if (typeof value === "string") return redactText(value);
+  if (typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((v) => redactValue(v, depth + 1));
+  const obj = value;
+  const out = {};
+  for (const k of Object.keys(obj)) {
+    out[k] = SECRET_KEY.test(k) ? MASK : redactValue(obj[k], depth + 1);
+  }
+  return out;
+}
+function redactRawJson(raw) {
+  if (typeof raw !== "string" || raw.length === 0) return raw;
+  try {
+    const parsed = JSON.parse(raw);
+    return JSON.stringify(redactValue(parsed));
+  } catch {
+    return redactText(raw);
+  }
+}
+
+// src/logger.ts
+var Logger = class {
+  file;
+  pretty;
+  out;
+  onEvent;
+  redact;
+  constructor(opts) {
+    this.pretty = Boolean(opts.pretty);
+    this.out = opts.prettyStream ?? process.stderr;
+    this.onEvent = opts.onEvent;
+    this.redact = Boolean(opts.redact);
+    if (opts.jsonlPath) {
+      mkdirSync(dirname(opts.jsonlPath), { recursive: true });
+      this.file = createWriteStream(opts.jsonlPath, { flags: "a", mode: 384 });
+      this.file.on("error", () => {
+      });
+    }
+  }
+  write(ev) {
+    this.file?.write(JSON.stringify(ev) + "\n");
+    this.onEvent?.(ev);
+  }
+  message(f, latencyMs) {
+    const kind2 = f.msg ? classify(f.msg) : "unparsed";
+    const ev = {
+      t: (/* @__PURE__ */ new Date()).toISOString(),
+      type: "message",
+      dir: f.direction,
+      kind: kind2,
+      id: f.msg?.id ?? null,
+      method: f.msg?.method ?? null,
+      latencyMs: latencyMs ?? null,
+      parseError: f.parseError ?? null,
+      // redact masks credential-shaped params at rest; the wire already carried
+      // f.raw byte-exact, so this only touches the on-disk observation.
+      raw: this.redact ? redactRawJson(f.raw) : f.raw
+    };
+    this.write(ev);
+    if (this.pretty) this.renderMessage(ev, kind2);
+  }
+  serverStderr(text) {
+    const t = this.redact ? redactText(text) : text;
+    this.write({ t: (/* @__PURE__ */ new Date()).toISOString(), type: "server_stderr", text: t });
+  }
+  note(code, detail) {
+    this.write({ t: (/* @__PURE__ */ new Date()).toISOString(), type: "note", code, detail });
+    if (this.pretty) this.out.write(color.dim(`\u2022 ${code}: ${detail}
+`));
+  }
+  renderMessage(ev, kind2) {
+    const arrow = ev.dir === "c2s" ? color.cyan("\u2192 to server  ") : color.green("\u2190 to client  ");
+    const tag = kind2 === "error" ? color.red("ERROR") : kind2 === "request" ? color.bold("req") : kind2 === "response" ? "res" : kind2 === "notification" ? color.gray("notif") : color.yellow(kind2);
+    const id = ev.id !== null ? color.dim(`#${String(ev.id)} `) : "";
+    const method = ev.method ? String(ev.method) : "";
+    const lat = typeof ev.latencyMs === "number" ? color.dim(` (${ev.latencyMs.toFixed(1)}ms)`) : "";
+    const pe = ev.parseError ? color.red(`  !parse: ${String(ev.parseError)}`) : "";
+    this.out.write(`${arrow}${tag} ${id}${method}${lat}${pe}
+`);
+  }
+  close() {
+    this.file?.end();
+  }
+};
+
+// src/proxy.ts
+import { spawn } from "child_process";
+import { performance } from "perf_hooks";
+
+// src/framer.ts
+import { StringDecoder } from "string_decoder";
+var MAX_LINE = 64 * 1024 * 1024;
+var LineFramer = class {
+  constructor(onMessage, direction) {
+    this.onMessage = onMessage;
+    this.direction = direction;
+  }
+  onMessage;
+  direction;
+  buf = "";
+  overflow = false;
+  // discarding an over-long, newline-free line until the next "\n"
+  decoder = new StringDecoder("utf8");
+  push(chunk) {
+    const text = typeof chunk === "string" ? chunk : this.decoder.write(chunk);
+    if (this.overflow) {
+      const nl2 = text.indexOf("\n");
+      if (nl2 < 0) return;
+      this.overflow = false;
+      this.buf = text.slice(nl2 + 1);
+    } else {
+      this.buf += text;
+    }
+    let nl;
+    while ((nl = this.buf.indexOf("\n")) >= 0) {
+      const line = this.buf.slice(0, nl);
+      this.buf = this.buf.slice(nl + 1);
+      const trimmed = line.trim();
+      if (trimmed === "") continue;
+      this.emit(trimmed);
+    }
+    if (this.buf.length > MAX_LINE) {
+      this.overflow = true;
+      this.buf = "";
+    }
+  }
+  emit(raw) {
+    let msg = null;
+    let parseError;
+    try {
+      msg = JSON.parse(raw);
+    } catch (e) {
+      parseError = e.message;
+    }
+    this.onMessage({ direction: this.direction, raw, msg, parseError });
+  }
+};
+
+// src/proxy.ts
+var Correlator = class {
+  constructor(logger, onPair) {
+    this.logger = logger;
+    this.onPair = onPair;
+  }
+  logger;
+  onPair;
+  pending = /* @__PURE__ */ new Map();
+  onClientToServer(f) {
+    this.logger.message(f);
+    if (f.msg && classify(f.msg) === "request" && hasId(f.msg)) {
+      this.pending.set(String(f.msg.id), {
+        method: f.msg.method ?? "",
+        params: f.msg.params,
+        at: performance.now()
+      });
+    }
+  }
+  onServerToClient(f) {
+    let latency;
+    if (f.msg && hasId(f.msg) && f.msg.method === void 0) {
+      const key = String(f.msg.id);
+      const p = this.pending.get(key);
+      if (p) {
+        latency = performance.now() - p.at;
+        this.pending.delete(key);
+        this.onPair?.(
+          { method: p.method, params: p.params },
+          { result: f.msg.result, error: f.msg.error }
+        );
+      }
+    }
+    this.logger.message(f, latency);
+  }
+  reportOrphans() {
+    for (const [id, p] of this.pending) {
+      this.logger.note(
+        "orphan-request",
+        `id=${id} method=${p.method} never received a response`
+      );
+    }
+  }
+};
+function runProxy(opts) {
+  return new Promise((resolve) => {
+    const child = spawn(opts.command, opts.args, {
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    const correlator = new Correlator(
+      opts.logger,
+      opts.onInteraction ? (request, response) => opts.onInteraction({ request, response }) : void 0
+    );
+    child.stdin.on("error", () => {
+    });
+    process.stdout.on("error", () => {
+    });
+    process.stderr.on("error", () => {
+    });
+    process.stdin.pipe(child.stdin);
+    const c2s = new LineFramer((m) => correlator.onClientToServer(m), "c2s");
+    process.stdin.on("data", (chunk) => {
+      try {
+        c2s.push(chunk);
+      } catch (e) {
+        opts.logger.note("observer-error", `c2s ${e.message}`);
+      }
+    });
+    child.stdout.pipe(process.stdout, { end: false });
+    const s2c = new LineFramer((m) => correlator.onServerToClient(m), "s2c");
+    child.stdout.on("data", (chunk) => {
+      try {
+        s2c.push(chunk);
+      } catch (e) {
+        opts.logger.note("observer-error", `s2c ${e.message}`);
+      }
+    });
+    child.stderr.on("data", (chunk) => {
+      if (opts.mirrorStderr !== false) {
+        try {
+          process.stderr.write(chunk);
+        } catch (e) {
+          opts.logger.note("observer-error", `stderr-mirror ${e.message}`);
+        }
+      }
+      opts.logger.serverStderr(chunk.toString("utf8"));
+    });
+    process.stdin.on("end", () => child.stdin.end());
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+      process.on(sig, () => child.kill(sig));
+    }
+    child.on("error", (err) => {
+      opts.logger.note("spawn-error", err.message);
+      opts.logger.close();
+      resolve(127);
+    });
+    child.on("exit", (code, signal) => {
+      correlator.reportOrphans();
+      opts.logger.note("server-exit", `code=${String(code)} signal=${String(signal)}`);
+      opts.logger.close();
+      resolve(code ?? (signal ? 1 : 0));
+    });
+  });
+}
+
+// src/http-proxy.ts
+import { createServer } from "http";
+
+// src/sse.ts
+import { StringDecoder as StringDecoder2 } from "string_decoder";
+var SseParser = class {
+  constructor(onEvent) {
+    this.onEvent = onEvent;
+  }
+  onEvent;
+  buf = "";
+  dataLines = [];
+  sawCr = false;
+  // last line ended on a CR that was the final byte of a chunk
+  decoder = new StringDecoder2("utf8");
+  push(chunk) {
+    this.buf += typeof chunk === "string" ? chunk : this.decoder.write(chunk);
+    if (this.sawCr) {
+      this.sawCr = false;
+      if (this.buf.startsWith("\n")) this.buf = this.buf.slice(1);
+    }
+    for (; ; ) {
+      const lf = this.buf.indexOf("\n");
+      const cr = this.buf.indexOf("\r");
+      if (lf === -1 && cr === -1) break;
+      if (cr !== -1 && (lf === -1 || cr < lf)) {
+        if (cr === this.buf.length - 1) {
+          const line2 = this.buf.slice(0, cr);
+          this.buf = "";
+          this.sawCr = true;
+          this.handleLine(line2);
+          break;
+        }
+        const line = this.buf.slice(0, cr);
+        const skip = this.buf[cr + 1] === "\n" ? 2 : 1;
+        this.buf = this.buf.slice(cr + skip);
+        this.handleLine(line);
+      } else {
+        const line = this.buf.slice(0, lf);
+        this.buf = this.buf.slice(lf + 1);
+        this.handleLine(line);
+      }
+    }
+  }
+  handleLine(line) {
+    if (line === "") {
+      this.dispatch();
+      return;
+    }
+    if (line.startsWith(":")) return;
+    const colon = line.indexOf(":");
+    const field = colon === -1 ? line : line.slice(0, colon);
+    let value = colon === -1 ? "" : line.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "data") this.dataLines.push(value);
+  }
+  dispatch() {
+    if (this.dataLines.length === 0) return;
+    const data = this.dataLines.join("\n");
+    this.dataLines = [];
+    if (data.trim() !== "") this.onEvent(data);
+  }
+};
+
+// src/http-proxy.ts
+var LOCAL_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+function isAllowedOrigin(origin, allowed) {
+  if (!origin) return true;
+  if (allowed) return allowed.includes(origin);
+  try {
+    return LOCAL_HOSTS.has(new URL(origin).hostname);
+  } catch {
+    return false;
+  }
+}
+function matchRemainder(prefix, pathname) {
+  if (prefix === "/") return pathname === "/" ? "" : pathname;
+  if (pathname === prefix) return "";
+  if (pathname.startsWith(prefix + "/")) return pathname.slice(prefix.length);
+  return null;
+}
+function resolveRoute(routes, pathname) {
+  let best = null;
+  for (const r of routes) {
+    const remainder = matchRemainder(r.prefix, pathname);
+    if (remainder === null) continue;
+    if (!best || r.prefix.length > best.prefix.length) {
+      best = { upstream: r.upstream, remainder, prefix: r.prefix, forwardCredentials: Boolean(r.forwardCredentials) };
+    }
+  }
+  return best;
+}
+function buildTarget(upstream, remainder, search) {
+  const u = new URL(upstream);
+  if (remainder) u.pathname = u.pathname.replace(/\/+$/, "") + remainder;
+  if (search) u.search = search;
+  return u.toString();
+}
+function routeFromUpstream(upstream, forwardCredentials = true) {
+  const p = new URL(upstream).pathname;
+  return { prefix: p && p !== "" ? p : "/", upstream, forwardCredentials };
+}
+function buildRoutes(upstream, routeSpecs, opts = {}) {
+  const credsPrefixes = new Set(opts.credsPrefixes ?? []);
+  const routes = [];
+  for (const spec of routeSpecs) {
+    const eq = spec.indexOf("=");
+    if (eq < 0) throw new Error(`bad --route "${spec}" (expected prefix=url)`);
+    const prefix = spec.slice(0, eq);
+    const url = spec.slice(eq + 1);
+    if (!prefix.startsWith("/")) throw new Error(`route prefix must start with "/": "${prefix}"`);
+    new URL(url);
+    routes.push({ prefix, upstream: url, forwardCredentials: false });
+  }
+  if (upstream) {
+    new URL(upstream);
+    routes.push(routeFromUpstream(upstream, true));
+  }
+  if (routes.length === 0) throw new Error("no upstream configured (use --upstream or --route)");
+  if (opts.noForwardCredentials) {
+    for (const r of routes) r.forwardCredentials = false;
+  } else if (routes.length === 1) {
+    routes[0].forwardCredentials = true;
+  } else {
+    for (const r of routes) {
+      r.forwardCredentials = Boolean(opts.forwardCredentials) || credsPrefixes.has(r.prefix);
+    }
+  }
+  return routes;
+}
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}
+var HOP_BY_HOP = ["host", "connection", "content-length", "accept-encoding"];
+var CREDENTIAL_HEADERS = ["authorization", "cookie"];
+function forwardHeaders(req, forwardCredentials) {
+  const h = new Headers();
+  for (const [k, v] of Object.entries(req.headers)) {
+    const lk = k.toLowerCase();
+    if (HOP_BY_HOP.includes(lk)) continue;
+    if (!forwardCredentials && CREDENTIAL_HEADERS.includes(lk)) continue;
+    if (typeof v === "string") h.set(k, v);
+    else if (Array.isArray(v)) h.set(k, v.join(", "));
+  }
+  h.set("accept-encoding", "identity");
+  return h;
+}
+function observe(raw, dir, correlator) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    const f = { direction: dir, raw, msg: null, parseError: e.message };
+    dir === "c2s" ? correlator.onClientToServer(f) : correlator.onServerToClient(f);
+    return;
+  }
+  const list = Array.isArray(parsed) ? parsed : [parsed];
+  for (const m of list) {
+    const f = { direction: dir, raw, msg: m };
+    dir === "c2s" ? correlator.onClientToServer(f) : correlator.onServerToClient(f);
+  }
+}
+function runHttpProxy(opts) {
+  const correlator = new Correlator(opts.logger);
+  const seenSessions = /* @__PURE__ */ new Set();
+  const seenTargets = /* @__PURE__ */ new Set();
+  const server = createServer((req, res) => {
+    res.on("error", () => {
+    });
+    void handle(req, res).catch((e) => {
+      opts.logger.note("proxy-error", e.message);
+      if (res.writableEnded) return;
+      if (res.headersSent) {
+        res.end();
+        return;
+      }
+      res.writeHead(502, { "content-type": "text/plain" });
+      res.end("mcpgaze: upstream error");
+    });
+  });
+  async function handle(req, res) {
+    if (!isAllowedOrigin(req.headers.origin, opts.allowedOrigins)) {
+      opts.logger.note("origin-rejected", String(req.headers.origin));
+      res.writeHead(403, { "content-type": "text/plain" });
+      res.end("forbidden origin");
+      return;
+    }
+    const reqUrl = new URL(req.url ?? "/", "http://localhost");
+    const match = resolveRoute(opts.routes, reqUrl.pathname);
+    if (!match) {
+      opts.logger.note("no-route", reqUrl.pathname);
+      res.writeHead(404, { "content-type": "text/plain" });
+      res.end(`mcpgaze: no route for ${reqUrl.pathname}`);
+      return;
+    }
+    const target = buildTarget(match.upstream, match.remainder, reqUrl.search);
+    if (!seenTargets.has(target)) {
+      seenTargets.add(target);
+      opts.logger.note("route", `${match.prefix} \u2192 ${target}`);
+    }
+    const method = req.method ?? "GET";
+    const body = method === "POST" || method === "DELETE" ? await readBody(req) : void 0;
+    if (body && body.length) observe(body.toString("utf8"), "c2s", correlator);
+    const upstream = await fetch(target, {
+      method,
+      headers: forwardHeaders(req, match.forwardCredentials),
+      body: body && body.length ? body : void 0,
+      redirect: "manual"
+    });
+    const sid = upstream.headers.get("mcp-session-id");
+    if (sid && !seenSessions.has(sid)) {
+      seenSessions.add(sid);
+      opts.logger.note("session", `Mcp-Session-Id=${sid}`);
+    }
+    const headers = {};
+    upstream.headers.forEach((v, k) => {
+      if (["transfer-encoding", "content-encoding", "connection", "content-length"].includes(k)) return;
+      if (!match.forwardCredentials && ["set-cookie", "mcp-session-id"].includes(k)) return;
+      headers[k] = v;
+    });
+    const ct = upstream.headers.get("content-type") ?? "";
+    if (ct.includes("text/event-stream") && upstream.body) {
+      res.writeHead(upstream.status, headers);
+      const sse = new SseParser((data) => observe(data, "s2c", correlator));
+      const reader = upstream.body.getReader();
+      try {
+        for (; ; ) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          const buf = Buffer.from(value);
+          res.write(buf);
+          try {
+            sse.push(buf);
+          } catch (e) {
+            opts.logger.note("observer-error", `sse ${e.message}`);
+          }
+        }
+      } catch (e) {
+        opts.logger.note("sse-upstream-error", e.message);
+      } finally {
+        await reader.cancel().catch(() => {
+        });
+      }
+      res.end();
+    } else {
+      const buf = Buffer.from(await upstream.arrayBuffer());
+      res.writeHead(upstream.status, headers);
+      res.end(buf);
+      if (buf.length) observe(buf.toString("utf8"), "s2c", correlator);
+    }
+  }
+  return new Promise((resolve) => {
+    server.listen(opts.port, opts.host, () => {
+      const addr = server.address();
+      const port = typeof addr === "object" && addr ? addr.port : opts.port;
+      resolve({
+        port,
+        close: () => new Promise((r) => {
+          opts.logger.close();
+          server.close(() => r());
+        })
+      });
+    });
+  });
+}
+
+// src/snapshot.ts
+import { writeFileSync } from "fs";
+
+// src/mcp-connection.ts
+import { spawn as spawn2 } from "child_process";
+var McpConnection = class _McpConnection {
+  child;
+  pending = /* @__PURE__ */ new Map();
+  framer;
+  nextId = 1;
+  stderrBuf = "";
+  closed = false;
+  constructor(command, args, env) {
+    this.child = spawn2(command, args, { stdio: ["pipe", "pipe", "pipe"], env: env ?? process.env });
+    this.child.stdin.on("error", () => {
+    });
+    this.child.on("error", (err) => {
+      this.closed = true;
+      for (const w of this.pending.values()) w.reject(err instanceof Error ? err : new Error(String(err)));
+      this.pending.clear();
+    });
+    this.child.stderr.on("data", (c) => {
+      this.stderrBuf += c.toString("utf8");
+    });
+    this.framer = new LineFramer((f) => {
+      if (!f.msg || f.msg.method !== void 0) return;
+      const id = f.msg.id;
+      if (typeof id !== "number" || !Number.isInteger(id)) return;
+      const w = this.pending.get(id);
+      if (!w) return;
+      this.pending.delete(id);
+      w.resolve({ result: f.msg.result, error: f.msg.error });
+    }, "s2c");
+    this.child.stdout.on("data", (c) => this.framer.push(c));
+    this.child.on("exit", () => {
+      this.closed = true;
+      for (const w of this.pending.values()) w.reject(new Error("server exited"));
+      this.pending.clear();
+    });
+  }
+  static spawn(command, args, env) {
+    return new _McpConnection(command, args, env);
+  }
+  get stderr() {
+    return this.stderrBuf;
+  }
+  request(method, params, timeoutMs = 15e3) {
+    if (this.closed) return Promise.reject(new Error("connection closed"));
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        const tail = this.stderrBuf.trim();
+        reject(
+          new Error(
+            `timed out after ${timeoutMs}ms on "${method}"` + (tail ? `
+--- server stderr ---
+${tail}` : "")
+          )
+        );
+      }, timeoutMs);
+      this.pending.set(id, {
+        resolve: (v) => {
+          clearTimeout(timer);
+          resolve(v);
+        },
+        reject: (e) => {
+          clearTimeout(timer);
+          reject(e);
+        }
+      });
+      this.child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
+    });
+  }
+  notify(method, params) {
+    if (this.closed) return;
+    this.child.stdin.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n");
+  }
+  close() {
+    this.closed = true;
+    this.child.kill();
+  }
+};
+
+// src/version.ts
+var VERSION = "1.0.0";
+
+// src/client.ts
+var PROTOCOL_VERSION = "2025-11-25";
+var PROBE_TIMEOUT_MS = 15e3;
+async function probeServer(command, args, timeoutMs = PROBE_TIMEOUT_MS, env) {
+  const conn = McpConnection.spawn(command, args, env);
+  try {
+    const init = await conn.request(
+      "initialize",
+      {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: "mcpgaze", version: VERSION }
+      },
+      timeoutMs
+    );
+    if (init.error) throw new Error(`initialize failed: ${init.error.message}`);
+    const initResult = init.result ?? {};
+    conn.notify("notifications/initialized");
+    const tools = [];
+    let cursor;
+    do {
+      const page = await conn.request("tools/list", cursor ? { cursor } : {}, timeoutMs);
+      if (page.error) throw new Error(`tools/list failed: ${page.error.message}`);
+      const r = page.result ?? {};
+      for (const t of r.tools ?? []) {
+        tools.push({ name: t.name, description: t.description, inputSchema: t.inputSchema });
+      }
+      cursor = r.nextCursor;
+    } while (cursor);
+    return {
+      protocolVersion: initResult.protocolVersion ?? PROTOCOL_VERSION,
+      server: initResult.serverInfo ?? {},
+      tools
+    };
+  } finally {
+    conn.close();
+  }
+}
+
+// src/snapshot.ts
+async function buildBaseline(command, args) {
+  const probe = await probeServer(command, args);
+  const tools = {};
+  for (const t of probe.tools) {
+    tools[t.name] = { description: t.description ?? "", inputSchema: t.inputSchema ?? {} };
+  }
+  return {
+    mcpgazeVersion: VERSION,
+    capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    protocolVersion: probe.protocolVersion,
+    server: probe.server,
+    tools
+  };
+}
+async function snapshot(command, args, outPath) {
+  const baseline = await buildBaseline(command, args);
+  writeFileSync(outPath, JSON.stringify(baseline, null, 2) + "\n");
+  return baseline;
+}
+
+// src/diff.ts
+import { readFileSync } from "fs";
+
+// src/schema-diff.ts
+function fmtType(t) {
+  return t === void 0 ? "(none)" : JSON.stringify(t);
+}
+function diffInputSchema(toolName, oldSchemaRaw, newSchemaRaw) {
+  const changes = [];
+  const oldS = oldSchemaRaw ?? {};
+  const newS = newSchemaRaw ?? {};
+  const oldProps = oldS.properties ?? {};
+  const newProps = newS.properties ?? {};
+  const oldReq = new Set(oldS.required ?? []);
+  const newReq = new Set(newS.required ?? []);
+  for (const k of Object.keys(oldProps)) {
+    if (!(k in newProps)) {
+      changes.push({ severity: "breaking", path: `${toolName}.${k}`, message: "property removed" });
+    }
+  }
+  for (const k of Object.keys(newProps)) {
+    if (!(k in oldProps)) {
+      const req = newReq.has(k);
+      changes.push({
+        severity: req ? "breaking" : "info",
+        path: `${toolName}.${k}`,
+        message: req ? "new required property added" : "new optional property added"
+      });
+    }
+  }
+  for (const k of Object.keys(oldProps)) {
+    if (!(k in newProps)) continue;
+    const o = oldProps[k] ?? {};
+    const n = newProps[k] ?? {};
+    if (JSON.stringify(o.type) !== JSON.stringify(n.type)) {
+      changes.push({
+        severity: "breaking",
+        path: `${toolName}.${k}`,
+        message: `type changed from ${fmtType(o.type)} to ${fmtType(n.type)}`
+      });
+    }
+    if (o.enum || n.enum) {
+      const oset = new Set((o.enum ?? []).map((v) => JSON.stringify(v)));
+      const nset = new Set((n.enum ?? []).map((v) => JSON.stringify(v)));
+      for (const v of oset) {
+        if (!nset.has(v)) {
+          changes.push({ severity: "breaking", path: `${toolName}.${k}`, message: `enum value removed: ${v}` });
+        }
+      }
+      for (const v of nset) {
+        if (!oset.has(v)) {
+          changes.push({ severity: "info", path: `${toolName}.${k}`, message: `enum value added: ${v}` });
+        }
+      }
+    }
+    const wasReq = oldReq.has(k);
+    const isReq = newReq.has(k);
+    if (!wasReq && isReq) {
+      changes.push({ severity: "breaking", path: `${toolName}.${k}`, message: "became required" });
+    } else if (wasReq && !isReq) {
+      changes.push({ severity: "warning", path: `${toolName}.${k}`, message: "no longer required" });
+    }
+  }
+  return changes;
+}
+var RANK = { info: 0, warning: 1, breaking: 2 };
+function worstSeverity(changes) {
+  let worst = null;
+  for (const c of changes) {
+    if (worst === null || RANK[c.severity] > RANK[worst]) worst = c.severity;
+  }
+  return worst;
+}
+
+// src/diff.ts
+async function diff(command, args, baselinePath) {
+  const baseline = JSON.parse(readFileSync(baselinePath, "utf8"));
+  const probe = await probeServer(command, args);
+  const current = {};
+  for (const t of probe.tools) {
+    current[t.name] = { description: t.description ?? "", inputSchema: t.inputSchema ?? {} };
+  }
+  const baseTools = baseline.tools ?? {};
+  const toolsRemoved = Object.keys(baseTools).filter((n) => !(n in current));
+  const toolsAdded = Object.keys(current).filter((n) => !(n in baseTools));
+  const changes = [];
+  for (const n of toolsRemoved) changes.push({ severity: "breaking", path: n, message: "tool removed" });
+  for (const n of toolsAdded) changes.push({ severity: "info", path: n, message: "tool added" });
+  for (const n of Object.keys(baseTools)) {
+    if (!(n in current)) continue;
+    changes.push(...diffInputSchema(n, baseTools[n].inputSchema, current[n].inputSchema));
+    if ((baseTools[n].description ?? "") !== (current[n].description ?? "")) {
+      changes.push({ severity: "info", path: n, message: "description changed" });
+    }
+  }
+  return { changes, toolsAdded, toolsRemoved };
+}
+
+// src/cassette.ts
+import { writeFileSync as writeFileSync2, readFileSync as readFileSync2 } from "fs";
+var MAX_DEPTH2 = 200;
+function stableStringify(value, depth = 0) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (depth >= MAX_DEPTH2) return '"__mcpgaze_max_depth__"';
+  if (Array.isArray(value)) return "[" + value.map((v) => stableStringify(v, depth + 1)).join(",") + "]";
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k], depth + 1)).join(",") + "}";
+}
+var CassetteRecorder = class {
+  /** When true, mask credential-shaped params/results before they are persisted. */
+  constructor(redact = false) {
+    this.redact = redact;
+  }
+  redact;
+  interactions = [];
+  seen = /* @__PURE__ */ new Set();
+  add(request, response) {
+    const params = this.redact ? redactValue(request.params) : request.params;
+    const interaction = {
+      request: { method: request.method, params },
+      response: response.error ? { error: this.redact ? redactValue(response.error) : response.error } : { result: this.redact ? redactValue(response.result) : response.result }
+    };
+    const key = stableStringify(interaction);
+    if (this.seen.has(key)) return;
+    this.seen.add(key);
+    this.interactions.push(interaction);
+  }
+  toCassette() {
+    return {
+      mcpgazeVersion: VERSION,
+      recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      interactions: this.interactions
+    };
+  }
+  write(path) {
+    writeFileSync2(path, JSON.stringify(this.toCassette(), null, 2) + "\n", { mode: 384 });
+    return this.interactions.length;
+  }
+};
+function buildIndex(cassette) {
+  const byKey = /* @__PURE__ */ new Map();
+  const byMethod = /* @__PURE__ */ new Map();
+  for (const it of cassette.interactions) {
+    byKey.set(it.request.method + "|" + stableStringify(it.request.params ?? null), it);
+    const list = byMethod.get(it.request.method) ?? [];
+    list.push(it);
+    byMethod.set(it.request.method, list);
+  }
+  return { byKey, byMethod };
+}
+function matchRequest(index, method, params) {
+  const exact = index.byKey.get(method + "|" + stableStringify(params ?? null));
+  const chosen = exact ?? pickMethodOnly(index, method);
+  if (!chosen) {
+    return { kind: "error", error: { code: -32601, message: `no recorded interaction for "${method}"` } };
+  }
+  if (chosen.response.error) return { kind: "error", error: chosen.response.error };
+  return { kind: "result", result: chosen.response.result };
+}
+function pickMethodOnly(index, method) {
+  const list = index.byMethod.get(method);
+  return list && list.length === 1 ? list[0] : void 0;
+}
+function runReplayServer(cassettePath) {
+  return new Promise((resolve, reject) => {
+    let index;
+    try {
+      const cassette = parseCassette(readFileSync2(cassettePath, "utf8"));
+      index = buildIndex(cassette);
+    } catch (e) {
+      reject(new Error(`invalid cassette: ${e.message}`));
+      return;
+    }
+    const framer = new LineFramer((f) => {
+      if (!f.msg) return;
+      const isRequest = f.msg.method !== void 0 && f.msg.id !== void 0 && f.msg.id !== null;
+      if (!isRequest) return;
+      const outcome = matchRequest(index, f.msg.method, f.msg.params);
+      const envelope = outcome.kind === "result" ? { jsonrpc: "2.0", id: f.msg.id, result: outcome.result } : { jsonrpc: "2.0", id: f.msg.id, error: outcome.error };
+      process.stdout.write(JSON.stringify(envelope) + "\n");
+    }, "c2s");
+    process.stdin.on("data", (chunk) => {
+      try {
+        framer.push(chunk);
+      } catch {
+      }
+    });
+    process.stdin.on("end", () => resolve(0));
+    for (const sig of ["SIGINT", "SIGTERM"]) {
+      process.on(sig, () => resolve(0));
+    }
+  });
+}
+function parseCassette(text) {
+  const parsed = JSON.parse(text);
+  if (!parsed || typeof parsed !== "object") throw new Error("not a JSON object");
+  const c = parsed;
+  if (!Array.isArray(c.interactions)) throw new Error("missing 'interactions' array");
+  for (const it of c.interactions) {
+    if (!it || typeof it !== "object") throw new Error("interaction is not an object");
+    const req = it.request;
+    if (!req || typeof req !== "object" || typeof req.method !== "string") {
+      throw new Error("interaction.request.method must be a string");
+    }
+  }
+  return parsed;
+}
+
+// src/preflight.ts
+import { readFileSync as readFileSync3 } from "fs";
+var GUI_INHERITED_DEFAULT = process.platform === "win32" ? ["PATH", "USERPROFILE", "APPDATA", "LOCALAPPDATA", "TEMP", "TMP", "SystemRoot", "ProgramFiles", "ProgramData", "ComSpec", "NUMBER_OF_PROCESSORS", "OS"] : ["HOME", "PATH", "USER", "SHELL", "LANG", "LOGNAME", "TERM", "TMPDIR", "LC_ALL", "LC_CTYPE"];
+var SUSPECT = /KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|_API|API_|AUTH|DSN|ENDPOINT|_URL|_URI|_HOST|_PORT|ACCOUNT|REGION|BUCKET|PROJECT|DATABASE|CONN/i;
+function restrict(env, allow) {
+  const out = {};
+  for (const k of allow) if (env[k] !== void 0) out[k] = env[k];
+  return out;
+}
+async function preflight(command, args, options = {}) {
+  const env = options.baseEnv ?? process.env;
+  const allow = options.allowlist ?? GUI_INHERITED_DEFAULT;
+  const timeout = options.timeoutMs ?? PROBE_TIMEOUT_MS;
+  let fullEnvOk = true;
+  let fullError;
+  try {
+    await probeServer(command, args, timeout, env);
+  } catch (e) {
+    fullEnvOk = false;
+    fullError = e.message;
+  }
+  let restrictedEnvOk = true;
+  let restrictedError;
+  try {
+    await probeServer(command, args, timeout, restrict(env, allow));
+  } catch (e) {
+    restrictedEnvOk = false;
+    restrictedError = e.message;
+  }
+  const allowSet = new Set(allow);
+  const missingVars = Object.keys(env).filter((k) => !allowSet.has(k)).sort();
+  const suspectVars = missingVars.filter((k) => SUSPECT.test(k));
+  return { fullEnvOk, restrictedEnvOk, fullError, restrictedError, missingVars, suspectVars };
+}
+function checkConfigEnv(configPath, serverName) {
+  const raw = JSON.parse(readFileSync3(configPath, "utf8"));
+  const servers = raw.mcpServers ?? {};
+  const names = serverName ? [serverName] : Object.keys(servers);
+  const findings = [];
+  for (const name of names) {
+    const env = servers[name]?.env ?? {};
+    for (const [key, value] of Object.entries(env)) {
+      if (typeof value !== "string") continue;
+      if (/\$\{?[A-Z_]/i.test(value)) {
+        findings.push({ level: "error", key, message: `value contains "${value}" \u2014 GUI clients do NOT expand shell variables; pass the literal value` });
+      }
+      if (value.trim() === "") {
+        findings.push({ level: "warning", key, message: "empty value" });
+      }
+    }
+  }
+  return findings;
+}
+
+// src/conform.ts
+var KNOWN_SPEC_VERSIONS = ["2025-06-18", "2025-11-25", "2026-07-28"];
+var ok = (detail) => ({ status: "pass", detail });
+var fail = (detail) => ({ status: "fail", detail });
+var warn = (detail) => ({ status: "warn", detail });
+var CHECKS = [
+  {
+    id: "init.result",
+    title: "initialize returns a valid result",
+    level: "required",
+    run: async (c) => c.initError ? fail(c.initError) : c.initResult ? ok("initialize responded") : fail("no initialize result")
+  },
+  {
+    id: "init.protocolVersion",
+    title: "initialize result advertises a protocolVersion",
+    level: "required",
+    run: async (c) => c.initResult?.protocolVersion ? ok(`server reports ${c.initResult.protocolVersion}`) : fail("missing protocolVersion in initialize result")
+  },
+  {
+    id: "init.serverInfo",
+    title: "initialize result includes serverInfo.name",
+    level: "required",
+    run: async (c) => c.initResult?.serverInfo?.name ? ok(`serverInfo.name = ${c.initResult.serverInfo.name}`) : fail("missing serverInfo.name")
+  },
+  {
+    id: "init.capabilities",
+    title: "initialize result includes a capabilities object",
+    level: "recommended",
+    run: async (c) => c.initResult && typeof c.initResult.capabilities === "object" && c.initResult.capabilities !== null ? ok("capabilities present") : warn("no capabilities object advertised")
+  },
+  {
+    id: "tools.list",
+    title: "tools/list returns an array of tools",
+    level: "required",
+    run: async (c) => Array.isArray(c.tools) ? ok(`${c.tools.length} tool(s)`) : fail("tools/list did not return an array")
+  },
+  {
+    id: "tools.names",
+    title: "every tool has a non-empty name",
+    level: "required",
+    run: async (c) => {
+      const list = Array.isArray(c.tools) ? c.tools : [];
+      const bad = list.filter((t) => !t.name || typeof t.name !== "string");
+      return bad.length === 0 ? ok("all tools named") : fail(`${bad.length} tool(s) missing a name`);
+    }
+  },
+  {
+    id: "tools.inputSchema",
+    title: 'every tool inputSchema is an object schema (type: "object")',
+    level: "recommended",
+    run: async (c) => {
+      const list = Array.isArray(c.tools) ? c.tools : [];
+      const bad = list.filter((t) => {
+        const s = t.inputSchema;
+        return !s || typeof s !== "object" || s.type !== "object";
+      });
+      return bad.length === 0 ? ok("all input schemas are object schemas") : warn(`${bad.length} tool(s) without an object inputSchema`);
+    }
+  },
+  {
+    id: "tools.requiredRefs",
+    title: "tool required[] only names declared properties",
+    level: "recommended",
+    run: async (c) => {
+      const offenders = [];
+      for (const t of Array.isArray(c.tools) ? c.tools : []) {
+        const s = t.inputSchema;
+        if (!Array.isArray(s?.required)) continue;
+        const props = new Set(Object.keys(s.properties ?? {}));
+        for (const r of s.required) if (!props.has(r)) offenders.push(`${t.name}.${r}`);
+      }
+      return offenders.length === 0 ? ok("required[] is consistent") : warn(`undeclared required fields: ${offenders.join(", ")}`);
+    }
+  },
+  {
+    id: "error.unknownMethod",
+    title: "an unknown method returns a JSON-RPC error (not a hang/crash)",
+    level: "required",
+    run: async (c) => {
+      try {
+        const res = await c.conn.request("mcpgaze/definitely-not-a-method", {}, Math.min(c.timeoutMs, 4e3));
+        if (res.error) {
+          return res.error.code === -32601 ? ok("returns -32601 method not found") : warn(`returns an error, but code ${res.error.code} (expected -32601)`);
+        }
+        return fail("unknown method returned a result instead of an error");
+      } catch (e) {
+        return fail(`no error response (${e.message.split("\n")[0]})`);
+      }
+    }
+  }
+];
+async function conform(command, args, protocolVersion, timeoutMs = 8e3) {
+  const conn = McpConnection.spawn(command, args);
+  const ctx = { conn, initResult: null, tools: [], timeoutMs };
+  try {
+    const init = await conn.request(
+      "initialize",
+      { protocolVersion, capabilities: {}, clientInfo: { name: "mcpgaze", version: VERSION } },
+      timeoutMs
+    );
+    if (init.error) ctx.initError = `initialize error: ${init.error.message}`;
+    else ctx.initResult = init.result ?? {};
+    conn.notify("notifications/initialized");
+    if (ctx.initResult) {
+      try {
+        const list = await conn.request("tools/list", {}, timeoutMs);
+        const r = list.result ?? {};
+        ctx.tools = r.tools ?? [];
+      } catch {
+        ctx.tools = [];
+      }
+    }
+    const results = [];
+    for (const chk of CHECKS) {
+      let r;
+      try {
+        r = await chk.run(ctx);
+      } catch (e) {
+        r = { status: "fail", detail: `check errored: ${e.message}` };
+      }
+      results.push({ id: chk.id, title: chk.title, level: chk.level, ...r });
+    }
+    const passed = !results.some((r) => r.level === "required" && r.status === "fail");
+    return {
+      protocolVersion,
+      serverProtocolVersion: ctx.initResult?.protocolVersion ?? null,
+      results,
+      passed
+    };
+  } finally {
+    conn.close();
+  }
+}
+
+// src/verify.ts
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+
+// src/shape.ts
+var MAX_DEPTH3 = 500;
+function shapeOf(value, depth = 0) {
+  if (value === null || value === void 0) return "null";
+  if (depth >= MAX_DEPTH3) return "null";
+  if (Array.isArray(value)) return { array: value.length ? shapeOf(value[0], depth + 1) : null };
+  const t = typeof value;
+  if (t === "string") return "string";
+  if (t === "number") return "number";
+  if (t === "boolean") return "boolean";
+  if (t === "object") {
+    const obj = value;
+    const out = {};
+    for (const k of Object.keys(obj).sort()) out[k] = shapeOf(obj[k], depth + 1);
+    return { object: out };
+  }
+  return "null";
+}
+function kind(s) {
+  if (typeof s === "object") return "object" in s ? "object" : "array";
+  return "primitive";
+}
+function diffShape(path, oldS, newS, depth = 0) {
+  const changes = [];
+  if (depth >= MAX_DEPTH3) return changes;
+  const ok2 = kind(oldS);
+  const nk = kind(newS);
+  if (ok2 !== nk) {
+    changes.push({ severity: "breaking", path, message: `type changed from ${ok2} to ${nk}` });
+    return changes;
+  }
+  if (ok2 === "primitive") {
+    if (oldS !== newS) {
+      changes.push({ severity: "breaking", path, message: `type changed from ${String(oldS)} to ${String(newS)}` });
+    }
+    return changes;
+  }
+  if (ok2 === "object") {
+    const o = oldS.object;
+    const n = newS.object;
+    for (const k of Object.keys(o)) {
+      if (!(k in n)) changes.push({ severity: "breaking", path: `${path}.${k}`, message: "field removed from response" });
+      else changes.push(...diffShape(`${path}.${k}`, o[k], n[k], depth + 1));
+    }
+    for (const k of Object.keys(n)) {
+      if (!(k in o)) changes.push({ severity: "info", path: `${path}.${k}`, message: "field added to response" });
+    }
+    return changes;
+  }
+  const oe = oldS.array;
+  const ne = newS.array;
+  if (oe !== null && ne === null) {
+    changes.push({ severity: "warning", path: `${path}[]`, message: "array is now empty (was populated)" });
+  } else if (oe === null && ne !== null) {
+    changes.push({ severity: "info", path: `${path}[]`, message: "array is now populated (was empty)" });
+  } else if (oe !== null && ne !== null) {
+    changes.push(...diffShape(`${path}[]`, oe, ne, depth + 1));
+  }
+  return changes;
+}
+
+// src/verify.ts
+var READ_ONLY_METHODS = /* @__PURE__ */ new Set([
+  "tools/list",
+  "resources/list",
+  "resources/templates/list",
+  "prompts/list",
+  "ping",
+  "completion/complete"
+]);
+function isVerifiable(method) {
+  return method !== "initialize" && !method.startsWith("notifications/");
+}
+function shouldReissue(method, allowToolCalls) {
+  if (!isVerifiable(method)) return false;
+  return allowToolCalls || READ_ONLY_METHODS.has(method);
+}
+async function verify(command, args, cassettePath, timeoutMs = 15e3, opts = {}) {
+  const allowToolCalls = Boolean(opts.allowToolCalls);
+  const cassette = parseCassette(readFileSync4(cassettePath, "utf8"));
+  const conn = McpConnection.spawn(command, args);
+  const result = { checked: 0, changes: [], errors: [], skipped: [] };
+  try {
+    const init = await conn.request(
+      "initialize",
+      { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: "mcpgaze", version: VERSION } },
+      timeoutMs
+    );
+    if (init.error) throw new Error(`initialize failed: ${init.error.message}`);
+    conn.notify("notifications/initialized");
+    for (const it of cassette.interactions) {
+      const method = it.request.method;
+      if (!isVerifiable(method)) continue;
+      if (!shouldReissue(method, allowToolCalls)) {
+        result.skipped.push(method);
+        continue;
+      }
+      result.checked++;
+      let live;
+      try {
+        live = await conn.request(method, it.request.params, timeoutMs);
+      } catch (e) {
+        result.errors.push({ method, message: e.message.split("\n")[0] });
+        continue;
+      }
+      const recordedIsError = it.response.error !== void 0;
+      const liveIsError = live.error !== void 0;
+      if (recordedIsError !== liveIsError) {
+        result.changes.push({
+          method,
+          severity: "breaking",
+          path: method,
+          message: recordedIsError ? "recorded an error but the live server now returns a result" : "recorded a result but the live server now returns an error"
+        });
+        continue;
+      }
+      if (recordedIsError) continue;
+      const recordedShape = shapeOf(it.response.result);
+      const liveShape = shapeOf(live.result);
+      for (const c of diffShape(method, recordedShape, liveShape)) {
+        result.changes.push({ method, ...c });
+      }
+    }
+    return result;
+  } finally {
+    conn.close();
+  }
+}
+async function updateCassette(command, args, cassettePath, timeoutMs = 15e3, opts = {}) {
+  const allowToolCalls = Boolean(opts.allowToolCalls);
+  const cassette = parseCassette(readFileSync4(cassettePath, "utf8"));
+  const conn = McpConnection.spawn(command, args);
+  let updated = 0;
+  try {
+    const init = await conn.request(
+      "initialize",
+      { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: "mcpgaze", version: VERSION } },
+      timeoutMs
+    );
+    if (init.error) throw new Error(`initialize failed: ${init.error.message}`);
+    conn.notify("notifications/initialized");
+    for (const it of cassette.interactions) {
+      if (!shouldReissue(it.request.method, allowToolCalls)) continue;
+      const live = await conn.request(it.request.method, it.request.params, timeoutMs);
+      it.response = live.error ? { error: live.error } : { result: live.result };
+      updated++;
+    }
+    cassette.recordedAt = (/* @__PURE__ */ new Date()).toISOString();
+    let serialized;
+    try {
+      serialized = JSON.stringify(cassette, null, 2) + "\n";
+    } catch (e) {
+      throw new Error(
+        `failed to serialize updated cassette (a live response is too deeply nested): ${e.message}`
+      );
+    }
+    writeFileSync3(cassettePath, serialized, { mode: 384 });
+    return updated;
+  } finally {
+    conn.close();
+  }
+}
+
+// src/triage.ts
+import { readFileSync as readFileSync5 } from "fs";
+var STDERR_SIGNAL = /(error|fatal|exception|traceback|panic|unhandled|econnrefused|eaddrinuse)/i;
+var NOTE_FAILURES = /* @__PURE__ */ new Set(["orphan-request", "spawn-error", "proxy-error", "observer-error", "origin-rejected"]);
+function truncate(s, n = 400) {
+  return s.length > n ? s.slice(0, n) + "\u2026" : s;
+}
+function extractFailures(events) {
+  const failures = [];
+  for (const e of events) {
+    if (e.type === "message" && e.kind === "error") {
+      failures.push({ kind: "rpc-error", summary: `error response to ${e.method ?? "request"} (id ${String(e.id)})`, detail: e.raw ? truncate(e.raw) : void 0 });
+    } else if (e.type === "message" && e.parseError) {
+      failures.push({ kind: "parse-error", summary: `malformed JSON-RPC on ${e.dir ?? "?"}`, detail: e.parseError });
+    } else if (e.type === "note" && e.code && NOTE_FAILURES.has(e.code)) {
+      failures.push({ kind: e.code, summary: e.code.replace(/-/g, " "), detail: e.detail });
+    } else if (e.type === "server_stderr" && e.text && STDERR_SIGNAL.test(e.text)) {
+      failures.push({ kind: "server-stderr", summary: "server logged an error", detail: truncate(e.text.trim()) });
+    }
+  }
+  return failures;
+}
+function parseSessionLog(path) {
+  const text = readFileSync5(path, "utf8");
+  const out = [];
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (!t) continue;
+    try {
+      out.push(JSON.parse(t));
+    } catch {
+    }
+  }
+  return out;
+}
+function buildTriagePrompt(failures) {
+  const lines = failures.map(
+    (f, i) => `${i + 1}. [${f.kind}] ${f.summary}${f.detail ? `
+   ${redactText(f.detail)}` : ""}`
+  );
+  return [
+    "You are debugging a Model Context Protocol (MCP) server. Below are failure",
+    "signals captured by a transparent proxy during a live session. For each",
+    "distinct problem, give the most likely root cause and a concrete fix.",
+    "Be specific and concise (a few bullets). Common MCP gotchas: writing logs to",
+    "stdout corrupts the JSON-RPC wire; GUI clients don't inherit shell env vars;",
+    "tool schema/signature drift breaks agents silently; default ~30s client",
+    "timeouts; transport mismatches (stdio vs Streamable HTTP).",
+    "",
+    "Failure signals:",
+    ...lines
+  ].join("\n");
+}
+var DEFAULT_TRIAGE_MODEL = "claude-sonnet-4-6";
+async function callClaude(prompt, apiKey, model = DEFAULT_TRIAGE_MODEL) {
+  const res = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01"
+    },
+    body: JSON.stringify({ model, max_tokens: 1024, messages: [{ role: "user", content: prompt }] })
+  });
+  if (!res.ok) throw new Error(`Anthropic API ${res.status}: ${truncate(await res.text(), 200)}`);
+  const data = await res.json();
+  return (data.content ?? []).filter((b) => b.type === "text").map((b) => b.text ?? "").join("").trim();
+}
+async function triage(logPath, opts = {}) {
+  const failures = extractFailures(parseSessionLog(logPath));
+  const report = { failures };
+  if (failures.length === 0) return report;
+  if (!opts.useAi) {
+    report.aiSkippedReason = "AI triage not requested (pass --ai)";
+    return report;
+  }
+  if (!opts.apiKey) {
+    report.aiSkippedReason = "no ANTHROPIC_API_KEY set";
+    return report;
+  }
+  const prompt = buildTriagePrompt(failures);
+  const consented = opts.confirmEgress ? await opts.confirmEgress(prompt) : false;
+  if (!consented) {
+    report.aiSkippedReason = "egress to api.anthropic.com not confirmed (pass --yes to consent)";
+    return report;
+  }
+  try {
+    report.aiDiagnosis = await callClaude(prompt, opts.apiKey, opts.model);
+  } catch (e) {
+    report.aiSkippedReason = e.message;
+  }
+  return report;
+}
+
+// src/health.ts
+import { writeFileSync as writeFileSync4, mkdirSync as mkdirSync2 } from "fs";
+import { dirname as dirname2 } from "path";
+import { performance as performance2 } from "perf_hooks";
+async function healthCheckOnce(command, args, timeoutMs = 8e3) {
+  const at = (/* @__PURE__ */ new Date()).toISOString();
+  const conn = McpConnection.spawn(command, args);
+  const t0 = performance2.now();
+  try {
+    const init = await conn.request(
+      "initialize",
+      { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: "mcpgaze", version: VERSION } },
+      timeoutMs
+    );
+    if (init.error) return { at, ok: false, error: `initialize: ${init.error.message}` };
+    conn.notify("notifications/initialized");
+    const list = await conn.request("tools/list", {}, timeoutMs);
+    if (list.error) return { at, ok: false, error: `tools/list: ${list.error.message}` };
+    const tools = (list.result ?? {}).tools ?? [];
+    return {
+      at,
+      ok: true,
+      latencyMs: Math.round(performance2.now() - t0),
+      toolCount: tools.length,
+      toolsHash: stableStringify(tools.map((t) => ({ n: t.name, s: t.inputSchema })))
+    };
+  } catch (e) {
+    return { at, ok: false, error: e.message.split("\n")[0] };
+  } finally {
+    conn.close();
+  }
+}
+function summarize(history) {
+  const checks = history.length;
+  const upCount = history.filter((h) => h.ok).length;
+  let consecutiveFailures = 0;
+  for (let i = history.length - 1; i >= 0; i--) {
+    if (history[i].ok) break;
+    consecutiveFailures++;
+  }
+  const lats = history.filter((h) => h.ok && typeof h.latencyMs === "number").map((h) => h.latencyMs).sort((a, b) => a - b);
+  const p50 = lats.length ? lats[Math.floor(lats.length / 2)] : null;
+  return {
+    checks,
+    upCount,
+    uptimePct: checks ? Math.round(upCount / checks * 1e3) / 10 : 0,
+    consecutiveFailures,
+    p50LatencyMs: p50
+  };
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function runHealthDaemon(command, args, opts = {}) {
+  const intervalMs = opts.intervalMs ?? 6e4;
+  const statusPath = opts.statusPath ?? ".mcpgaze/health.json";
+  const maxHistory = opts.maxHistory ?? 500;
+  const history = [];
+  let prevOk = null;
+  let prevHash;
+  let last = { at: (/* @__PURE__ */ new Date()).toISOString(), ok: false };
+  const persist = () => {
+    try {
+      mkdirSync2(dirname2(statusPath), { recursive: true });
+      writeFileSync4(
+        statusPath,
+        JSON.stringify(
+          { server: [command, ...args].join(" "), updatedAt: (/* @__PURE__ */ new Date()).toISOString(), current: last, summary: summarize(history), history },
+          null,
+          2
+        )
+      );
+    } catch {
+    }
+  };
+  for (; ; ) {
+    const c = await healthCheckOnce(command, args);
+    last = c;
+    history.push(c);
+    if (history.length > maxHistory) history.shift();
+    opts.onCheck?.(c);
+    if (prevOk !== null && prevOk !== c.ok) {
+      opts.onTransition?.(c.ok ? "recovered: server is responding again" : `DOWN: ${c.error ?? "unresponsive"}`);
+    }
+    if (c.ok && prevHash !== void 0 && c.toolsHash !== prevHash) {
+      opts.onTransition?.("schema drift: the server's tool surface changed");
+    }
+    prevOk = c.ok;
+    if (c.ok && c.toolsHash) prevHash = c.toolsHash;
+    persist();
+    if (opts.once) return c;
+    await sleep(intervalMs);
+  }
+}
+
+// src/tui.ts
+var TuiState = class {
+  serverCmd;
+  startedAt = Date.now();
+  requests = 0;
+  responses = 0;
+  errors = 0;
+  notifications = 0;
+  orphans = 0;
+  parseErrors = 0;
+  latencies = [];
+  recent = [];
+  lastStderr = "";
+  constructor(serverCmd) {
+    this.serverCmd = serverCmd;
+  }
+  ingest(e) {
+    if (e.type === "message") {
+      if (e.parseError) this.parseErrors++;
+      switch (e.kind) {
+        case "request":
+          this.requests++;
+          break;
+        case "response":
+          this.responses++;
+          break;
+        case "error":
+          this.errors++;
+          break;
+        case "notification":
+          this.notifications++;
+          break;
+      }
+      if (typeof e.latencyMs === "number") this.latencies.push(e.latencyMs);
+      this.recent.push({
+        dir: e.dir ?? "?",
+        kind: e.kind ?? "?",
+        method: e.method ?? "",
+        id: e.id != null ? String(e.id) : "",
+        latencyMs: typeof e.latencyMs === "number" ? e.latencyMs : null,
+        error: e.kind === "error"
+      });
+      if (this.recent.length > 200) this.recent.shift();
+    } else if (e.type === "server_stderr" && e.text) {
+      this.lastStderr = e.text.trim().split("\n").pop() ?? "";
+    } else if (e.type === "note" && e.code === "orphan-request") {
+      this.orphans++;
+    }
+  }
+};
+function percentile(samples, p) {
+  if (samples.length === 0) return null;
+  const sorted = [...samples].sort((a, b) => a - b);
+  const idx = Math.min(sorted.length - 1, Math.floor(p / 100 * sorted.length));
+  return sorted[idx];
+}
+function fmtMs(n) {
+  return n == null ? "\u2014" : `${n.toFixed(0)}ms`;
+}
+function fmtDuration(ms) {
+  const s = Math.floor(ms / 1e3);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  return `${m}m${String(s % 60).padStart(2, "0")}s`;
+}
+function renderFrame(state, cols, rows) {
+  const width = Math.max(40, Math.min(1e3, Number.isFinite(cols) ? Math.floor(cols) : 80));
+  const safeRows = Math.max(8, Math.min(1e3, Number.isFinite(rows) ? Math.floor(rows) : 24));
+  const bar = "\u2500".repeat(width);
+  const lines = [];
+  lines.push(color.bold("mcpgaze") + color.dim(`  \u27F3 ${fmtDuration(Date.now() - state.startedAt)}  \xB7  ${state.serverCmd}`));
+  lines.push(color.dim(bar));
+  const listHeight = Math.max(3, safeRows - 8);
+  const slice = state.recent.slice(-listHeight);
+  for (const r of slice) {
+    const arrow = r.dir === "c2s" ? color.cyan("\u2192") : color.green("\u2190");
+    const tag = r.error ? color.red("ERR ") : r.kind === "request" ? color.bold("req ") : r.kind === "response" ? "res " : r.kind === "notification" ? color.gray("note") : "?   ";
+    const id = r.id ? color.dim(`#${r.id}`) : "   ";
+    const lat = r.latencyMs != null ? color.dim(` ${r.latencyMs.toFixed(1)}ms`) : "";
+    lines.push(`${arrow} ${tag} ${id} ${r.method}${lat}`);
+  }
+  for (let i = slice.length; i < listHeight; i++) lines.push("");
+  lines.push(color.dim(bar));
+  if (state.lastStderr) lines.push(color.yellow("stderr ") + color.dim(state.lastStderr.slice(0, width - 8)));
+  else lines.push(color.dim("stderr \u2014"));
+  const p50 = fmtMs(percentile(state.latencies, 50));
+  const p95 = fmtMs(percentile(state.latencies, 95));
+  const errPart = state.errors > 0 ? color.red(`${state.errors} err`) : color.green("0 err");
+  const orphanPart = state.orphans > 0 ? color.red(`${state.orphans} orphan`) : "0 orphan";
+  lines.push(
+    color.dim(
+      `req ${state.requests}  res ${state.responses}  notif ${state.notifications}  `
+    ) + `${errPart}  ${orphanPart}  ` + color.dim(`p50 ${p50}  p95 ${p95}`)
+  );
+  lines.push(color.dim("Ctrl-C to stop"));
+  return lines.join("\n");
+}
+var ALT_ON = "\x1B[?1049h\x1B[?25l";
+var ALT_OFF = "\x1B[?25h\x1B[?1049l";
+var HOME = "\x1B[H";
+var CLEAR_DOWN = "\x1B[0J";
+var Tui = class {
+  state;
+  out;
+  timer = null;
+  active = false;
+  constructor(serverCmd, out = process.stderr) {
+    this.state = new TuiState(serverCmd);
+    this.out = out;
+  }
+  static isSupported(out = process.stderr) {
+    return Boolean(out.isTTY) && !process.env.NO_TUI;
+  }
+  start() {
+    this.active = true;
+    this.out.write(ALT_ON);
+    this.paint();
+    this.timer = setInterval(() => this.paint(), 100);
+  }
+  update(e) {
+    this.state.ingest(e);
+  }
+  paint() {
+    if (!this.active) return;
+    const cols = this.out.columns ?? 80;
+    const rows = this.out.rows ?? 24;
+    this.out.write(HOME + renderFrame(this.state, cols, rows) + CLEAR_DOWN);
+  }
+  stop() {
+    if (!this.active) return;
+    this.active = false;
+    if (this.timer) clearInterval(this.timer);
+    this.out.write(ALT_OFF);
+  }
+};
+
+// src/index.ts
+function splitOnDoubleDash(args) {
+  const i = args.indexOf("--");
+  if (i === -1) return { opts: args, cmd: [] };
+  return { opts: args.slice(0, i), cmd: args.slice(i + 1) };
+}
+function getOpt(opts, name) {
+  const i = opts.indexOf(name);
+  return i >= 0 && i + 1 < opts.length ? opts[i + 1] : void 0;
+}
+function getOpts(opts, name) {
+  const out = [];
+  for (let i = 0; i < opts.length - 1; i++) if (opts[i] === name) out.push(opts[i + 1]);
+  return out;
+}
+function hasFlag(opts, name) {
+  return opts.includes(name);
+}
+function parseTimeoutOpt(raw, name) {
+  if (raw === void 0) return void 0;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) die(`${name} must be a positive number of milliseconds (got "${raw}")`);
+  return n;
+}
+function die(msg) {
+  process.stderr.write(color.red(msg) + "\n");
+  process.exit(2);
+}
+function timestamp() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+}
+function promptYesNo(question) {
+  return new Promise((resolve) => {
+    process.stderr.write(question);
+    const onData = (chunk) => {
+      process.stdin.pause();
+      process.stdin.off("data", onData);
+      resolve(/^y(es)?$/i.test(chunk.toString("utf8").trim()));
+    };
+    process.stdin.resume();
+    process.stdin.once("data", onData);
+  });
+}
+var HELP = `mcpgaze v${VERSION} \u2014 a transparent wiretap for MCP servers
+
+USAGE
+  mcpgaze wrap [--log <path>] [--print] [--redact] [--tui] [--native] -- <server command...>
+  mcpgaze wrap-http (--upstream <url> | --route <prefix>=<url> ...) [--port <n>] [--host 127.0.0.1]
+                    [--forward-credentials | --creds-route <prefix> ... | --no-forward-credentials] [--redact]
+  mcpgaze record [--cassette mcpgaze.cassette.json] [--log <path>] [--no-redact] -- <server command...>
+  mcpgaze replay --cassette <file>
+  mcpgaze snapshot [--out mcpgaze.baseline.json] -- <server command...>
+  mcpgaze diff [--baseline <f>] [--fail-on <breaking|warning|any>] [--update] -- <server command...>
+  mcpgaze conform [--spec <ver>|--all] [--json] -- <server command...>
+  mcpgaze verify --cassette <file> [--fail-on <sev>] [--update] [--allow-tool-calls] -- <server command...>
+  mcpgaze health [--interval <sec>] [--once] [--status <path>] -- <server command...>
+  mcpgaze triage [--log <session.jsonl>] [--ai] [--yes] [--model <name>]
+  mcpgaze preflight [--config <file> [--server <name>]] [--timeout <ms>] [-- <server command...>]
+
+COMMANDS
+  wrap        Transparent stdio proxy; logs every JSON-RPC message to a side
+              channel without touching the wire. --tui shows a live dashboard;
+              --native uses the zero-overhead Rust single-binary proxy.
+  wrap-http   Same idea for Streamable HTTP: localhost-bound, Origin-checked.
+              Routes by path prefix, so one proxy can front several upstreams
+              (--route /a=URL --route /b=URL); --upstream is the single-route form.
+              A single --upstream/--route forwards the client's Authorization/
+              Cookie to that one upstream (one destination, nothing to misroute);
+              add --no-forward-credentials to strip them. With MULTIPLE routes a
+              token could reach the wrong upstream, so credentials are stripped
+              unless a route opts in (--creds-route /a, or --forward-credentials).
+  record      Wrap a server and write a replayable cassette of req/res pairs.
+              Secrets are redacted by default (it is a shareable artifact);
+              pass --no-redact to capture params/results/stderr verbatim.
+  replay      Deterministic mock MCP server (stdio) from a cassette.
+  snapshot    Probe the server, write a tool-schema baseline you commit to git.
+  diff        Diff the live tool surface vs the baseline. --update accepts it.
+  conform     Spec-conformance suite across protocol versions.
+  verify      Re-issue recorded requests and diff RESPONSE SHAPES. --update
+              re-baselines the cassette (accept intentional behavioral changes).
+              Only read-only methods are re-issued unless --allow-tool-calls.
+  health      Continuously health-check a server (uptime, latency, drift), or
+              --once as a cron/CI liveness probe (exit 0 up / 1 down).
+  triage      Read a session log, surface failures, and (with --ai) get a
+              plain-English root-cause + fix from Claude.
+  preflight   Diagnose env vars a GUI client won't inherit; check config env.
+
+EXAMPLES
+  mcpgaze wrap --tui -- node server.js
+  mcpgaze wrap --native -- node server.js
+  mcpgaze health --interval 30 -- node server.js
+  mcpgaze conform --all -- node server.js
+  mcpgaze diff --update -- node server.js          # accept the new tool surface
+  mcpgaze verify --cassette s.json --update -- node server.js
+`;
+function findNativeProxy() {
+  const fromEnv = process.env.MCPGAZE_PROXY_BIN;
+  if (fromEnv && existsSync(fromEnv)) return fromEnv;
+  const here = dirname3(fileURLToPath(import.meta.url));
+  const candidates = [
+    join(here, "..", "native", "mcpgaze-proxy", "target", "release", "mcpgaze-proxy"),
+    join(here, "..", "..", "native", "mcpgaze-proxy", "target", "release", "mcpgaze-proxy")
+  ];
+  return candidates.find((p) => existsSync(p)) ?? null;
+}
+async function cmdWrap(args) {
+  const { opts, cmd } = splitOnDoubleDash(args);
+  if (cmd.length === 0) die("usage: mcpgaze wrap [--log <path>] [--print] [--tui] [--native] -- <server command...>");
+  const logPath = getOpt(opts, "--log") ?? `.mcpgaze/session-${timestamp()}.jsonl`;
+  if (hasFlag(opts, "--native")) {
+    const bin = findNativeProxy();
+    if (!bin) {
+      process.stderr.write(color.yellow("[mcpgaze] native proxy not found; build it with `cargo build --release` in native/mcpgaze-proxy, or set MCPGAZE_PROXY_BIN. Falling back to the Node proxy.\n"));
+    } else {
+      const child = spawn3(bin, ["--log", logPath, "--", ...cmd], { stdio: "inherit" });
+      child.on("exit", (code2) => process.exit(code2 ?? 0));
+      return;
+    }
+  }
+  const useTui = hasFlag(opts, "--tui");
+  if (useTui && !Tui.isSupported()) {
+    process.stderr.write(color.yellow("[mcpgaze] --tui needs a TTY; falling back to plain logging.\n"));
+  }
+  const tui = useTui && Tui.isSupported() ? new Tui(cmd.join(" ")) : null;
+  const logger = new Logger({
+    jsonlPath: logPath,
+    pretty: !tui && hasFlag(opts, "--print"),
+    onEvent: tui ? (ev) => tui.update(ev) : void 0,
+    redact: hasFlag(opts, "--redact")
+  });
+  if (tui) {
+    tui.start();
+    const stop = () => {
+      tui.stop();
+      process.exit(0);
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+  } else {
+    process.stderr.write(color.dim(`[mcpgaze] logging session to ${logPath}
+`));
+  }
+  const code = await runProxy({ command: cmd[0], args: cmd.slice(1), logger, mirrorStderr: !tui });
+  if (tui) tui.stop();
+  process.exit(code);
+}
+async function cmdWrapHttp(args) {
+  const { opts } = splitOnDoubleDash(args);
+  const upstream = getOpt(opts, "--upstream");
+  const routeSpecs = getOpts(opts, "--route");
+  if (!upstream && routeSpecs.length === 0) {
+    die("usage: mcpgaze wrap-http (--upstream <url> | --route <prefix>=<url> ...) [--port <n>] [--host 127.0.0.1]");
+  }
+  const noForwardCredentials = hasFlag(opts, "--no-forward-credentials");
+  if (noForwardCredentials && (hasFlag(opts, "--forward-credentials") || getOpts(opts, "--creds-route").length > 0)) {
+    die("--no-forward-credentials cannot be combined with --forward-credentials or --creds-route");
+  }
+  let routes;
+  try {
+    routes = buildRoutes(upstream, routeSpecs, {
+      forwardCredentials: hasFlag(opts, "--forward-credentials"),
+      credsPrefixes: getOpts(opts, "--creds-route"),
+      noForwardCredentials
+    });
+  } catch (e) {
+    die(e.message);
+  }
+  const host = getOpt(opts, "--host") ?? "127.0.0.1";
+  const port = Number(getOpt(opts, "--port") ?? "0");
+  const logPath = getOpt(opts, "--log") ?? `.mcpgaze/session-${timestamp()}.jsonl`;
+  const allow = getOpt(opts, "--allow-origin");
+  const logger = new Logger({ jsonlPath: logPath, pretty: hasFlag(opts, "--print"), redact: hasFlag(opts, "--redact") });
+  const handle = await runHttpProxy({
+    routes,
+    host,
+    port,
+    logger,
+    allowedOrigins: allow ? allow.split(",") : void 0
+  });
+  process.stderr.write(color.green(`[mcpgaze] proxy listening on http://${host}:${handle.port}`) + "\n");
+  for (const r of routes) {
+    process.stderr.write(color.dim(`  ${r.prefix.padEnd(12)} \u2192 ${r.upstream}
+`));
+  }
+  process.stderr.write(color.dim(`[mcpgaze] logging to ${logPath}
+`));
+  if (host !== "127.0.0.1" && host !== "localhost") {
+    process.stderr.write(color.yellow(`[mcpgaze] warning: binding to ${host} exposes the proxy beyond localhost
+`));
+  }
+  const shutdown = () => void handle.close().then(() => process.exit(0));
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+async function cmdRecord(args) {
+  const { opts, cmd } = splitOnDoubleDash(args);
+  if (cmd.length === 0) die("usage: mcpgaze record [--cassette <path>] -- <server command...>");
+  const cassettePath = getOpt(opts, "--cassette") ?? "mcpgaze.cassette.json";
+  const logPath = getOpt(opts, "--log") ?? `.mcpgaze/session-${timestamp()}.jsonl`;
+  const redact = !hasFlag(opts, "--no-redact");
+  const logger = new Logger({ jsonlPath: logPath, pretty: hasFlag(opts, "--print"), redact });
+  const recorder = new CassetteRecorder(redact);
+  process.stderr.write(color.dim(`[mcpgaze] recording cassette to ${cassettePath}
+`));
+  process.stderr.write(
+    redact ? color.dim("[mcpgaze] secret redaction ON (cassette + log); pass --no-redact to capture verbatim\n") : color.yellow("[mcpgaze] --no-redact: secrets in params/results/stderr will be stored verbatim\n")
+  );
+  const code = await runProxy({
+    command: cmd[0],
+    args: cmd.slice(1),
+    logger,
+    onInteraction: ({ request, response }) => recorder.add(request, response)
+  });
+  const n = recorder.write(cassettePath);
+  process.stderr.write(color.green(`[mcpgaze] wrote ${cassettePath} \u2014 ${n} interaction(s)
+`));
+  process.exit(code);
+}
+async function cmdReplay(args) {
+  const { opts } = splitOnDoubleDash(args);
+  const cassettePath = getOpt(opts, "--cassette");
+  if (!cassettePath) die("usage: mcpgaze replay --cassette <file>");
+  const code = await runReplayServer(cassettePath);
+  process.exit(code);
+}
+async function cmdPreflight(args) {
+  const { opts, cmd } = splitOnDoubleDash(args);
+  const configPath = getOpt(opts, "--config");
+  if (configPath) {
+    const findings = checkConfigEnv(configPath, getOpt(opts, "--server"));
+    if (findings.length === 0) {
+      process.stdout.write(color.green("\u2713 config env block looks clean\n"));
+    } else {
+      for (const f of findings) {
+        const badge = f.level === "error" ? color.red("ERROR  ") : color.yellow("WARNING");
+        process.stdout.write(`  ${badge}  ${color.bold(f.key)} \u2014 ${f.message}
+`);
+      }
+    }
+    if (cmd.length === 0) return;
+  }
+  if (cmd.length === 0) die("usage: mcpgaze preflight [--config <file>] [--timeout <ms>] [-- <server command...>]");
+  const timeoutMs = parseTimeoutOpt(getOpt(opts, "--timeout") ?? process.env.MCPGAZE_PREFLIGHT_TIMEOUT, "--timeout");
+  process.stderr.write(color.dim("[mcpgaze] probing with full env, then with the GUI-inherited subset\u2026\n"));
+  const r = await preflight(cmd[0], cmd.slice(1), timeoutMs !== void 0 ? { timeoutMs } : {});
+  if (!r.fullEnvOk) {
+    process.stdout.write(color.red("\u2717 the server failed to start even with your full environment.\n"));
+    if (r.fullError) process.stdout.write(color.dim(`  ${r.fullError.split("\n")[0]}
+`));
+    process.exit(1);
+  }
+  if (r.restrictedEnvOk) {
+    process.stdout.write(color.green("\u2713 starts cleanly with only the env a GUI client inherits \u2014 no env surprises.\n"));
+    return;
+  }
+  process.stdout.write(
+    color.yellow("\u26A0 starts with your full shell env but FAILS with only what a GUI client inherits.\n") + "  Your server likely depends on env vars Claude Desktop (and similar) won't pass.\n"
+  );
+  if (r.suspectVars.length) {
+    process.stdout.write(color.bold("\n  Likely culprits (set in your shell, not inherited by GUI clients):\n"));
+    for (const v of r.suspectVars.slice(0, 15)) process.stdout.write(`    \u2022 ${v}
+`);
+    process.stdout.write(
+      color.dim(`
+  Fix: pass them explicitly in your client config's "env" block (literal values, not $VARS).
+`)
+    );
+  }
+  process.exit(1);
+}
+async function cmdSnapshot(args) {
+  const { opts, cmd } = splitOnDoubleDash(args);
+  if (cmd.length === 0) die("usage: mcpgaze snapshot [--out <path>] -- <server command...>");
+  const outPath = getOpt(opts, "--out") ?? "mcpgaze.baseline.json";
+  const baseline = await snapshot(cmd[0], cmd.slice(1), outPath);
+  const n = Object.keys(baseline.tools).length;
+  process.stdout.write(
+    color.green(`\u2713 wrote ${outPath}`) + ` \u2014 ${n} tool${n === 1 ? "" : "s"} from ${baseline.server.name ?? "server"} ` + color.dim(`(protocol ${baseline.protocolVersion})`) + "\n"
+  );
+}
+function thresholdMet(worst, failOn) {
+  if (!failOn) return false;
+  if (worst === null) return false;
+  const rank = { info: 0, warning: 1, breaking: 2 };
+  const want = failOn === "any" ? 0 : failOn === "warning" ? 1 : 2;
+  return rank[worst] >= want;
+}
+async function cmdDiff(args) {
+  const { opts, cmd } = splitOnDoubleDash(args);
+  if (cmd.length === 0) die("usage: mcpgaze diff [--baseline <path>] [--fail-on <sev>] [--update] -- <server command...>");
+  const baselinePath = getOpt(opts, "--baseline") ?? "mcpgaze.baseline.json";
+  const failOn = hasFlag(opts, "--fail-on-drift") ? "breaking" : getOpt(opts, "--fail-on");
+  if (hasFlag(opts, "--update")) {
+    const baseline = await snapshot(cmd[0], cmd.slice(1), baselinePath);
+    const n = Object.keys(baseline.tools).length;
+    process.stdout.write(color.green(`\u2713 baseline updated`) + ` \u2014 ${n} tool(s) accepted into ${baselinePath}
+`);
+    return;
+  }
+  const result = await diff(cmd[0], cmd.slice(1), baselinePath);
+  if (result.changes.length === 0) {
+    process.stdout.write(color.green("\u2713 no drift \u2014 tool surface matches the baseline\n"));
+    return;
+  }
+  const badge = {
+    breaking: color.red("BREAKING"),
+    warning: color.yellow("WARNING "),
+    info: color.blue("INFO    ")
+  };
+  process.stdout.write(color.bold(`Found ${result.changes.length} change(s):
+`));
+  for (const c of result.changes) {
+    process.stdout.write(`  ${badge[c.severity]}  ${color.bold(c.path)} \u2014 ${c.message}
+`);
+  }
+  const worst = worstSeverity(result.changes);
+  if (thresholdMet(worst, failOn)) {
+    process.stderr.write(color.red(`
+\u2717 drift at/above '${failOn}' \u2014 failing.
+`));
+    process.exit(1);
+  }
+}
+var SEV_BADGE = {
+  breaking: color.red("BREAKING"),
+  warning: color.yellow("WARNING "),
+  info: color.blue("INFO    ")
+};
+async function cmdConform(args) {
+  const { opts, cmd } = splitOnDoubleDash(args);
+  if (cmd.length === 0) die("usage: mcpgaze conform [--spec <ver>|--all] [--json] -- <server command...>");
+  const specs = hasFlag(opts, "--all") ? [...KNOWN_SPEC_VERSIONS] : [getOpt(opts, "--spec") ?? KNOWN_SPEC_VERSIONS[0]];
+  const reports = [];
+  for (const spec of specs) reports.push(await conform(cmd[0], cmd.slice(1), spec));
+  if (hasFlag(opts, "--json")) {
+    process.stdout.write(JSON.stringify(reports, null, 2) + "\n");
+  } else {
+    const mark = {
+      pass: color.green("\u2713"),
+      fail: color.red("\u2717"),
+      warn: color.yellow("\u26A0"),
+      skip: color.dim("\u2218")
+    };
+    for (const r of reports) {
+      process.stdout.write(
+        color.bold(`
+Protocol ${r.protocolVersion}`) + color.dim(` (server reports ${r.serverProtocolVersion ?? "?"})
+`)
+      );
+      for (const c of r.results) {
+        const lvl = c.level === "required" ? "" : color.dim(" (recommended)");
+        process.stdout.write(`  ${mark[c.status]} ${c.title}${lvl} \u2014 ${color.dim(c.detail)}
+`);
+      }
+      process.stdout.write(r.passed ? color.green("  PASS\n") : color.red("  FAIL\n"));
+    }
+  }
+  if (reports.some((r) => !r.passed)) process.exit(1);
+}
+async function cmdVerify(args) {
+  const { opts, cmd } = splitOnDoubleDash(args);
+  const cassette = getOpt(opts, "--cassette");
+  if (!cassette || cmd.length === 0) die("usage: mcpgaze verify --cassette <file> [--update] [--allow-tool-calls] -- <server command...>");
+  const allowToolCalls = hasFlag(opts, "--allow-tool-calls");
+  if (hasFlag(opts, "--update")) {
+    const n = await updateCassette(cmd[0], cmd.slice(1), cassette, void 0, { allowToolCalls });
+    process.stdout.write(color.green(`\u2713 cassette re-baselined`) + ` \u2014 ${n} response(s) accepted into ${cassette}
+`);
+    return;
+  }
+  const failOn = getOpt(opts, "--fail-on");
+  const r = await verify(cmd[0], cmd.slice(1), cassette, void 0, { allowToolCalls });
+  process.stdout.write(color.dim(`re-issued ${r.checked} recorded request(s)
+`));
+  if (r.skipped.length > 0) {
+    const uniq = [...new Set(r.skipped)];
+    process.stdout.write(
+      color.dim(`skipped ${r.skipped.length} state-changing request(s) [${uniq.join(", ")}] \u2014 pass --allow-tool-calls to re-issue
+`)
+    );
+  }
+  for (const e of r.errors) process.stdout.write(`  ${color.red("ERROR   ")}  ${color.bold(e.method)} \u2014 ${e.message}
+`);
+  if (r.changes.length === 0 && r.errors.length === 0) {
+    process.stdout.write(color.green("\u2713 no behavioral drift \u2014 response shapes match the cassette\n"));
+    return;
+  }
+  for (const c of r.changes) {
+    process.stdout.write(`  ${SEV_BADGE[c.severity]}  ${color.bold(c.path)} \u2014 ${c.message}
+`);
+  }
+  const worst = worstSeverity(r.changes);
+  if (thresholdMet(worst, failOn) || failOn && r.errors.length > 0) {
+    process.stderr.write(color.red(`
+\u2717 behavioral drift at/above '${failOn}' \u2014 failing.
+`));
+    process.exit(1);
+  }
+}
+async function cmdHealth(args) {
+  const { opts, cmd } = splitOnDoubleDash(args);
+  if (cmd.length === 0) die("usage: mcpgaze health [--interval <sec>] [--once] [--status <path>] -- <server command...>");
+  const once = hasFlag(opts, "--once");
+  const intervalMs = Number(getOpt(opts, "--interval") ?? "60") * 1e3;
+  const statusPath = getOpt(opts, "--status") ?? ".mcpgaze/health.json";
+  if (!once) {
+    process.stderr.write(
+      color.dim(`[mcpgaze] health-checking every ${intervalMs / 1e3}s \xB7 status \u2192 ${statusPath} \xB7 Ctrl-C to stop
+`)
+    );
+  }
+  const last = await runHealthDaemon(cmd[0], cmd.slice(1), {
+    once,
+    intervalMs,
+    statusPath,
+    onCheck: (c) => {
+      if (!once) {
+        const stamp = color.dim(new Date(c.at).toLocaleTimeString());
+        process.stderr.write(
+          c.ok ? `${stamp} ${color.green("UP")}   ${c.toolCount} tools \xB7 ${c.latencyMs}ms
+` : `${stamp} ${color.red("DOWN")} ${c.error ?? ""}
+`
+        );
+      }
+    },
+    onTransition: (msg) => process.stderr.write(color.bold(`  \u27EB ${msg}
+`))
+  });
+  if (once) {
+    process.stdout.write(
+      last.ok ? color.green(`\u2713 UP`) + ` \u2014 ${last.toolCount} tools, ${last.latencyMs}ms
+` : color.red(`\u2717 DOWN`) + ` \u2014 ${last.error ?? "unresponsive"}
+`
+    );
+    process.exit(last.ok ? 0 : 1);
+  }
+}
+async function cmdTriage(args) {
+  const { opts } = splitOnDoubleDash(args);
+  const logPath = getOpt(opts, "--log");
+  if (!logPath) die("usage: mcpgaze triage --log <session.jsonl> [--ai] [--yes] [--model <name>]");
+  const preConsented = hasFlag(opts, "--yes");
+  const report = await triage(logPath, {
+    useAi: hasFlag(opts, "--ai"),
+    apiKey: process.env.ANTHROPIC_API_KEY,
+    model: getOpt(opts, "--model") ?? process.env.MCPGAZE_TRIAGE_MODEL,
+    // --ai egresses (redacted) failure details to api.anthropic.com. Require an
+    // explicit acknowledgement: --yes, or a "y" at the interactive preview.
+    confirmEgress: async (prompt) => {
+      if (preConsented) return true;
+      if (!process.stdin.isTTY) return false;
+      process.stderr.write(
+        color.yellow("\n[mcpgaze] triage --ai will POST these (redacted) failure details to api.anthropic.com:\n") + color.dim(prompt.split("\n").map((l) => "  " + l).join("\n") + "\n")
+      );
+      return await promptYesNo("Send to Anthropic? [y/N] ");
+    }
+  });
+  if (report.failures.length === 0) {
+    process.stdout.write(color.green("\u2713 no failure signals in this session\n"));
+    return;
+  }
+  process.stdout.write(color.bold(`Found ${report.failures.length} failure signal(s):
+`));
+  for (const f of report.failures) {
+    process.stdout.write(`  ${color.red("\u2022")} ${color.bold(f.kind)} \u2014 ${f.summary}
+`);
+    if (f.detail) process.stdout.write(color.dim(`      ${f.detail}
+`));
+  }
+  if (report.aiDiagnosis) {
+    process.stdout.write(color.bold("\n\u2500\u2500 Claude's triage \u2500\u2500\n") + report.aiDiagnosis + "\n");
+  } else if (report.aiSkippedReason) {
+    process.stdout.write(color.dim(`
+(AI triage skipped: ${report.aiSkippedReason})
+`));
+  }
+}
+async function main() {
+  const [, , command, ...rest] = process.argv;
+  switch (command) {
+    case "wrap":
+      return cmdWrap(rest);
+    case "wrap-http":
+      return cmdWrapHttp(rest);
+    case "record":
+      return cmdRecord(rest);
+    case "replay":
+      return cmdReplay(rest);
+    case "snapshot":
+      return cmdSnapshot(rest);
+    case "diff":
+      return cmdDiff(rest);
+    case "conform":
+      return cmdConform(rest);
+    case "verify":
+      return cmdVerify(rest);
+    case "triage":
+      return cmdTriage(rest);
+    case "health":
+      return cmdHealth(rest);
+    case "preflight":
+      return cmdPreflight(rest);
+    case "-v":
+    case "--version":
+      process.stdout.write(VERSION + "\n");
+      return;
+    case void 0:
+    case "-h":
+    case "--help":
+    case "help":
+      process.stdout.write(HELP);
+      return;
+    default:
+      die(`unknown command: ${command}
+
+${HELP}`);
+  }
+}
+main().catch((e) => {
+  process.stderr.write(color.red(`error: ${e.message}`) + "\n");
+  process.exit(1);
+});