webmcpx 0.1.0 → 0.2.1

package/agent/page.js

@@ -0,0 +1,304 @@
+// One tab in the agent's browser. Before any page script runs, it installs the W3C WebMCP polyfill
+// (https://github.com/w3c-oss/webmcp-polyfill), so a site's own registerTool() calls work in any
+// Chromium, with no flag. Nothing else is injected, and the page's CSP stays on. Tools are listed and
+// called only through the spec's consumer methods, document.modelContext.getTools() and executeTool(),
+// on the very descriptors getTools() returned (they keep the owning frame).
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { READ_PAGE } from "./standard.js";
+
+const POLYFILL = readFileSync(fileURLToPath(new URL("polyfill.js", import.meta.resolve("@w3c/webmcp-polyfill"))), "utf8");
+const CHANGED = "__webmcpxToolsChanged";
+// Runs in every new document, before the page's scripts. An iframe's initial about:blank is special:
+// when it navigates to a same-origin page, Chrome keeps its Window and does not run this again, and a
+// polyfill installed in the blank document would talk to frames through state tied to that discarded
+// document (no discovery across frames). So there it installs on first use, from the real document.
+const BOOT = `(() => {
+  const install = () => {
+${POLYFILL}
+  };
+  if (window !== window.top && document.URL === "about:blank") {
+    const proto = Document.prototype;
+    Object.defineProperty(proto, "modelContext", {
+      configurable: true,
+      enumerable: true,
+      get() {
+        delete proto.modelContext;
+        install();
+        return this.modelContext;
+      },
+    });
+    return;
+  }
+  install();
+  const mc = document.modelContext;
+  if (window === window.top && typeof mc?.addEventListener === "function" && typeof ${CHANGED} === "function") {
+    mc.addEventListener("toolchange", () => ${CHANGED}(""));
+  }
+})();`;
+
+const GET_TOOLS = `(async () => {
+  const mc = document.modelContext;
+  return typeof mc?.getTools === "function" ? await mc.getTools() : null;
+})()`;
+
+// Called on the array getTools() returned: plain summaries, by index.
+function summarize() {
+  const parse = (s) => {
+    try {
+      return typeof s === "string" ? JSON.parse(s) : s;
+    } catch {
+      return undefined;
+    }
+  };
+  // The frame that owns each tool (the spec's RegisteredTool.window), as a number that stays the same
+  // while the page is open: same-named tools in two frames are two tools.
+  // Frame ids are scoped to this document: after a navigation, a frame is never mistaken for an older
+  // one. The page itself is 0, so a site's own tools keep their names from visit to visit.
+  const owners = (globalThis.__webmcpxOwners ??= { ids: new WeakMap(), next: 1, doc: Math.random().toString(36).slice(2) });
+  const owner = (w) => {
+    if (!w || w === window) return "0";
+    try {
+      if (!owners.ids.has(w)) owners.ids.set(w, `${owners.doc}.${owners.next++}`);
+      return owners.ids.get(w);
+    } catch {
+      return "?";
+    }
+  };
+  return this.map((t, index) => ({
+    index,
+    name: t.name,
+    description: t.description ?? "",
+    inputSchema: parse(t.inputSchema),
+    annotations: { ...(t.annotations ?? {}) },
+    origin: t.origin,
+    owner: owner(t.window),
+  }));
+}
+
+// Called on the same array: runs one descriptor, cancellable through `cancel` below. executeTool() returns
+// the result JSON-serialized; a tool that returned a string (like the webmcpx envelope) comes back as a
+// JSON string literal: unwrap it once.
+async function execute(index, input, call) {
+  const controller = new AbortController();
+  (this.__webmcpxCalls ??= new Map()).set(call, controller);
+  let out;
+  try {
+    out = await document.modelContext.executeTool(this[index], input, { signal: controller.signal });
+  } finally {
+    this.__webmcpxCalls.delete(call);
+  }
+  let value = out;
+  try {
+    value = typeof out === "string" ? JSON.parse(out) : out;
+  } catch {
+    // not JSON: keep the text
+  }
+  return typeof value === "string" ? value : JSON.stringify(value ?? null);
+}
+
+function cancel(call) {
+  this.__webmcpxCalls?.get(call)?.abort();
+}
+
+const GROUP = "webmcpx-tools";
+const LOAD_TIMEOUT = 30_000;
+const CALL_TIMEOUT = 60_000;
+/** How long a cancellation may take before the tab counts as frozen. */
+const CANCEL_WAIT = 2_000;
+const SETTLE = { min: 400, max: 3_000, every: 200 };
+// Unref'd: a pending timeout must never keep the CLI alive after its work is done.
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms).unref());
+const timeout = (ms, what) =>
+  new Promise((_, reject) => {
+    setTimeout(() => reject(new Error(`${what} took longer than ${ms / 1000} s`)), ms).unref();
+  });
+
+/** The tool's list is gone (the page navigated since it was read): the call never started. */
+export const stale = (e) => /Could not find object|Cannot find context/i.test(e?.message);
+/** The page navigated while the tool ran: it may have done its work. */
+const interrupted = (e) => /context was destroyed|Inspected target navigated|Execution context/i.test(e?.message);
+
+export class Page {
+  #cdp;
+  #session;
+  #target;
+  #unsubscribe;
+  #onChange;
+  #calls = 0;
+  /** Set when the page stopped answering: the session must not use this tab again. */
+  broken = false;
+  #callTimeout = CALL_TIMEOUT;
+  #loads = new Set();
+  #handles = [];
+  #debounce;
+
+  /** Opens a new tab. `onChange()` fires when the page's tools may have changed on their own. */
+  /** `callTimeout` (ms) bounds one tool call; tests shorten it. */
+  static async create(cdp, { onChange = () => {}, callTimeout = CALL_TIMEOUT } = {}) {
+    const { targetId } = await cdp.send("Target.createTarget", { url: "about:blank" });
+    const { sessionId } = await cdp.send("Target.attachToTarget", { targetId, flatten: true });
+    const page = new Page(cdp, sessionId, targetId, onChange);
+    page.#callTimeout = callTimeout;
+    await page.#init();
+    return page;
+  }
+
+  constructor(cdp, session, target, onChange) {
+    this.#cdp = cdp;
+    this.#session = session;
+    this.#target = target;
+    this.#onChange = onChange;
+    this.#unsubscribe = cdp.on((msg) => msg.sessionId === session && this.#event(msg));
+  }
+
+  /** Closes this tab (in a browser we attached to, it is the only thing we opened there). */
+  async close() {
+    clearTimeout(this.#debounce);
+    this.#unsubscribe();
+    await this.#cdp.send("Target.closeTarget", { targetId: this.#target }).catch(() => {});
+  }
+
+  #send(method, params) {
+    return this.#cdp.send(method, params, this.#session);
+  }
+
+  async #init() {
+    await Promise.all([this.#send("Page.enable"), this.#send("Runtime.enable")]);
+    await this.#send("Runtime.addBinding", { name: CHANGED });
+    await this.#send("Page.addScriptToEvaluateOnNewDocument", { source: BOOT });
+  }
+
+  #event({ method, params }) {
+    if (method === "Page.javascriptDialogOpening") {
+      // An alert() would block every later call: dismiss it, like a user closing it.
+      this.#send("Page.handleJavaScriptDialog", { accept: false }).catch(() => {});
+    } else if (method === "Page.loadEventFired") {
+      for (const resolve of this.#loads) resolve();
+      this.#loads.clear();
+      this.#changed(); // a new document: a new tool list
+    } else if (method === "Runtime.bindingCalled" && params.name === CHANGED) {
+      this.#changed();
+    }
+  }
+
+  #changed() {
+    clearTimeout(this.#debounce);
+    this.#debounce = setTimeout(() => this.#onChange(), 150);
+  }
+
+  async #evaluate(expression, ms = CALL_TIMEOUT) {
+    const run = this.#send("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true });
+    const { result, exceptionDetails } = await Promise.race([run, timeout(ms, "the page")]);
+    if (exceptionDetails) throw new Error(describeException(exceptionDetails));
+    return result.value;
+  }
+
+  /**
+   * Navigates and waits for the tool list to settle.
+   * @returns {Promise<{url: string, title: string, tools: PageTool[] | null}>} `tools` is null without WebMCP
+   * (outside a secure context).
+   */
+  async open(url) {
+    // The old document's tool lists die with it.
+    await this.#send("Runtime.releaseObjectGroup", { objectGroup: GROUP }).catch(() => {});
+    this.#handles = [];
+    const loaded = new Promise((resolve) => this.#loads.add(resolve));
+    const nav = await this.#send("Page.navigate", { url });
+    if (nav.errorText) throw new Error(`could not open ${url}: ${nav.errorText}`);
+    if (nav.loaderId) await Promise.race([loaded, wait(LOAD_TIMEOUT)]);
+    const tools = await this.#settle();
+    const { url: at, title } = await this.#evaluate("({ url: location.href, title: document.title })");
+    return { url: at, title, tools };
+  }
+
+  /** Polls until the tool list has been stable for a moment (sites often register after load). */
+  async #settle() {
+    const start = Date.now();
+    const names = (list) => JSON.stringify(list?.map((t) => t.name));
+    let last = await this.tools();
+    while (Date.now() - start < SETTLE.max) {
+      await wait(SETTLE.every);
+      const now = await this.tools();
+      const same = names(now) === names(last);
+      last = now;
+      if (same && Date.now() - start >= SETTLE.min) break;
+    }
+    return last;
+  }
+
+  /**
+   * Reads the page's tools. Each keeps the `index` of its descriptor in this list, which `call` runs:
+   * same-named tools in different frames stay distinct. Null without `document.modelContext`.
+   * @returns {Promise<PageTool[] | null>}
+   */
+  async tools() {
+    const run = this.#send("Runtime.evaluate", { expression: GET_TOOLS, awaitPromise: true, objectGroup: GROUP });
+    const { result, exceptionDetails } = await Promise.race([run, timeout(CALL_TIMEOUT, "the page")]);
+    if (exceptionDetails) throw new Error(describeException(exceptionDetails));
+    if (!result.objectId) return null;
+    const { result: list } = await this.#send("Runtime.callFunctionOn", {
+      objectId: result.objectId,
+      functionDeclaration: summarize.toString(),
+      returnByValue: true,
+    });
+    // Each tool keeps the very list it came from: a call runs on that descriptor, so it reaches the
+    // owning frame or fails if that owner unregistered it; it never shifts to another tool.
+    this.#handles.push(result.objectId);
+    if (this.#handles.length > 50) {
+      this.#send("Runtime.releaseObject", { objectId: this.#handles.shift() }).catch(() => {});
+    }
+    return list.value.map((tool) => ({ ...tool, list: result.objectId }));
+  }
+
+  /**
+   * Runs a tool on the list it came from; resolves with its result text. A tool past the time limit is
+   * cancelled (its AbortSignal fires); a page that navigates mid-call reports that the tool may have run.
+   */
+  async call(tool, input) {
+    const call = ++this.#calls;
+    const run = this.#send("Runtime.callFunctionOn", {
+      objectId: tool.list,
+      functionDeclaration: execute.toString(),
+      arguments: [{ value: tool.index }, { value: input ?? {} }, { value: call }],
+      awaitPromise: true,
+      returnByValue: true,
+      userGesture: true,
+    });
+    let reply;
+    try {
+      reply = await Promise.race([run, timeout(this.#callTimeout, "the tool")]);
+    } catch (e) {
+      if (stale(e)) throw e;
+      if (interrupted(e)) {
+        throw new Error(`the page navigated while "${tool.name}" ran: it may have done its work, so check before calling it again`);
+      }
+      if (!/took longer than/.test(e?.message)) throw e;
+      // Ask the tool to stop. A page whose script is stuck can't even take that: then the tab is broken,
+      // and the session replaces it (see Session.call).
+      const cancelled = this.#send("Runtime.callFunctionOn", {
+        objectId: tool.list,
+        functionDeclaration: cancel.toString(),
+        arguments: [{ value: call }],
+      });
+      const answered = await Promise.race([cancelled.then(() => true, () => true), wait(CANCEL_WAIT).then(() => false)]);
+      if (!answered) {
+        this.broken = true;
+        throw new Error(`"${tool.name}" took longer than ${this.#callTimeout / 1000} s and froze the page; it may have partly run`);
+      }
+      throw new Error(`"${tool.name}" took longer than ${this.#callTimeout / 1000} s and was cancelled; it may have partly run`);
+    }
+    const { result, exceptionDetails } = reply;
+    if (exceptionDetails) throw new Error(describeException(exceptionDetails));
+    return result.value;
+  }
+
+  /** The loader's `readPage(what)`, evaluated in the page (for the standard tools). */
+  read(what) {
+    return this.#evaluate(`${READ_PAGE}(${JSON.stringify(what)})`);
+  }
+}
+
+const describeException = (d) => d.exception?.description?.split("\n")[0] ?? d.text;
+
+/** @typedef {{index: number, list: string, name: string, description: string, inputSchema?: object, annotations: Record<string, boolean>, origin?: string, owner?: string}} PageTool */

package/agent/session.js

@@ -0,0 +1,137 @@
+// What the CLI and the MCP server share: one browser (started on first use), one tab, and the tool list
+// the agent sees: the page's own tools plus the standard ones the page does not already have.
+import { attach, launch } from "./browser.js";
+import { Page, stale } from "./page.js";
+import { runStandard, standardTools } from "./standard.js";
+
+export class Session {
+  #options;
+  #browser;
+  #page;
+  #ready;
+  #closed = false;
+  #queue = Promise.resolve();
+
+  /** @param {{headed?: boolean, browser?: string, cdp?: string, onChange?: () => void, callTimeout?: number}} options */
+  constructor(options = {}) {
+    this.#options = options;
+  }
+
+  #start() {
+    if (this.#closed) return Promise.reject(new Error("the session is closed"));
+    this.#ready ??= (async () => {
+      const { cdp, headed, browser, onChange, callTimeout } = this.#options;
+      const opened = cdp ? await attach(cdp) : await launch({ headed, executable: browser });
+      // Closed while the browser was starting: shut it instead of leaving it running.
+      if (this.#closed) {
+        opened.close();
+        throw new Error("the session is closed");
+      }
+      this.#browser = opened;
+      // A browser that quits or crashes is started again on the next page.
+      opened.cdp.onClose(() => {
+        if (this.#browser === opened) [this.#browser, this.#ready, this.#page] = [];
+      });
+      return Page.create(opened.cdp, { onChange, callTimeout });
+    })().catch((e) => {
+      this.#ready = undefined;
+      throw e;
+    });
+    return this.#ready;
+  }
+
+  /** Runs page work one at a time: there is one tab, so a navigation must not interleave with a call. */
+  #serial(work) {
+    const run = this.#queue.then(work);
+    this.#queue = run.catch(() => {});
+    return run;
+  }
+
+  /** @returns {Promise<{url: string, title: string, tools: Tool[] | null}>} */
+  goto(url) {
+    return this.#serial(async () => {
+      this.#page = await this.#start();
+      const page = await this.#page.open(normalize(url));
+      return { ...page, tools: page.tools && withStandard(page.tools) };
+    });
+  }
+
+  /** The current tool list (empty before a page is open, or without WebMCP). */
+  tools() {
+    return this.#serial(async () => (this.#page ? withStandard((await this.#page.tools()) ?? []) : []));
+  }
+
+  /** Calls a tool from a list the page gave; one from a page that has since navigated is refused. */
+  call(tool, input) {
+    return this.#serial(async () => {
+      if (!this.#page) throw new Error("no page is open yet: call open_page first");
+      const page = this.#page;
+      if (tool.standard) return runStandard(tool.name, input, (what) => page.read(what));
+      try {
+        return await page.call(tool, input);
+      } catch (e) {
+        // A frozen page can't be used again: drop the browser (or, attached, our tab); the next page
+        // starts fresh instead of waiting on it forever.
+        if (page.broken) await this.#reset();
+        // The tool's list is gone only when the page navigated: never guess which new tool is "the same".
+        if (stale(e)) throw new Error(`the page changed since "${tool.name}" was listed: open it again or use the new tools`);
+        throw e;
+      }
+    });
+  }
+
+  async #reset() {
+    const [browser, ready] = [this.#browser, this.#ready];
+    [this.#browser, this.#ready, this.#page] = [];
+    const page = await ready?.catch(() => undefined);
+    await Promise.race([page?.close(), new Promise((resolve) => setTimeout(resolve, 2_000).unref())]);
+    browser?.close();
+  }
+
+  /** Closes our tab and the browser (or only our tab's connection, in a browser we attached to). */
+  async close() {
+    this.#closed = true;
+    const page = await this.#ready?.catch(() => undefined);
+    await page?.close();
+    this.#browser?.close();
+  }
+}
+
+/** The page's tools, then each standard tool the page does not already register. */
+function withStandard(tools) {
+  const names = new Set(tools.map((t) => t.name));
+  return [...tools, ...standardTools().filter((t) => !names.has(t.name))];
+}
+
+/** `example.com` → `https://example.com`; `localhost:3000` → `http://localhost:3000`. */
+export function normalize(url) {
+  const raw = String(url ?? "").trim();
+  if (!raw) throw new Error("give a URL, e.g. https://example.com or http://localhost:3000");
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw) || raw.startsWith("about:") || raw.startsWith("file:")) return raw;
+  const local = /^(localhost|127\.|\[::1\]|0\.0\.0\.0)/.test(raw);
+  return `${local ? "http" : "https"}://${raw}`;
+}
+
+/** Whether a tool result reports failure: a webmcpx envelope (`"ok": false`) or an MCP result (`"isError": true`). */
+export function failed(text) {
+  try {
+    const value = JSON.parse(text);
+    return value?.ok === false || value?.isError === true;
+  } catch {
+    return false;
+  }
+}
+
+/** A result some sites already shape like MCP (`{content: [...]}`, e.g. Shopify), or undefined. */
+export function mcpResult(text) {
+  try {
+    const value = JSON.parse(text);
+    if (!Array.isArray(value?.content)) return undefined;
+    const { content, structuredContent, isError } = value;
+    return { content, ...(structuredContent && { structuredContent }), ...(isError === true && { isError }) };
+  } catch {
+    return undefined;
+  }
+}
+
+/** @typedef {import("./page.js").PageTool & {standard?: boolean}} Tool */

package/agent/standard.js

@@ -0,0 +1,57 @@
+// The webmcpx standard tools, run by the agent bridge itself: the page is only read (through the
+// loader's own `readPage`, evaluated by DevTools, which the page's CSP does not apply to) and the text
+// engine runs here in Node. Nothing is injected into the page besides the W3C polyfill.
+import { readFileSync } from "node:fs";
+import { CODES, TOOLS } from "../src/generated.js";
+import { readPage } from "../src/loader.js";
+
+export const STANDARD = ["get_page_context", "search_page", "fetch_as_markdown"];
+
+/** Source of a page expression: `${READ_PAGE}("blocks")`. */
+export const READ_PAGE = `(${readPage})`;
+
+let engine;
+const load = () =>
+  (engine ??= import("../wasm/webmcpx_wasm.js")
+    .then(async (m) => {
+      await m.default({ module_or_path: readFileSync(new URL("../wasm/webmcpx_wasm_bg.wasm", import.meta.url)) });
+      return m;
+    })
+    .catch((e) => {
+      engine = undefined;
+      throw e;
+    }));
+
+const envelope = (body) => JSON.stringify(body);
+const err = (code, message) => envelope({ ok: false, error: { code, message, retryable: CODES[code] } });
+
+/** The standard tools as page-tool descriptors (`standard: true`), for listing next to the site's. */
+export const standardTools = () =>
+  STANDARD.map((name) => {
+    const { description, inputSchema, annotations } = TOOLS[name];
+    return { name, description, inputSchema, annotations: { ...annotations }, standard: true };
+  });
+
+/**
+ * Runs a standard tool. `read(what)` returns `readPage(what)` evaluated in the page.
+ * Like the in-page tools, it never rejects: any input and any failure yield an envelope.
+ */
+export async function runStandard(name, input, read) {
+  const args = input && typeof input === "object" && !Array.isArray(input) ? input : {};
+  try {
+    if (name === "get_page_context") return envelope({ ok: true, data: await read("context") });
+    if (name === "search_page" && typeof args.query !== "string") return err("INVALID_INPUT", "`query` must be a string");
+    const page = await read("blocks");
+    let m;
+    try {
+      m = await load();
+    } catch (e) {
+      return err("UNAVAILABLE", `the text engine could not load: ${e?.message ?? e}`);
+    }
+    if (name === "search_page") return m.search(page, args.query, args.limit ?? 0);
+    if (name === "fetch_as_markdown") return m.markdown(page, String(args.cursor ?? ""), args.max_chars ?? 0);
+    return err("NOT_FOUND", `no standard tool named ${name}`);
+  } catch (e) {
+    return err("UNAVAILABLE", String(e?.message ?? e));
+  }
+}

package/bin/webmcpx.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// npx webmcpx: WebMCP for any agent, in any Chromium, today.
+//   webmcpx mcp                      MCP server: your agent calls the tools of any page it opens
+//   webmcpx tools <url>              list a page's WebMCP tools (great on localhost)
+//   webmcpx call <url> <tool> [json] call one and print the result
+import { parseArgs } from "node:util";
+import { describe, named, serve } from "../agent/mcp.js";
+import { Session, failed, mcpResult } from "../agent/session.js";
+
+const tty = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (s) => (tty ? `\x1b[${code}m${s}\x1b[0m` : s);
+const bold = paint(1);
+const dim = paint(2);
+const green = paint(32);
+const yellow = paint(33);
+
+const HELP = `${bold("webmcpx")}: WebMCP for any agent, in any Chromium, today.
+
+${bold("Give your agent the tools of every page it opens")}
+  Claude Code   claude mcp add webmcpx -- npx -y webmcpx mcp
+  Codex         codex mcp add webmcpx -- npx -y webmcpx mcp
+  Cursor, VS Code, Windsurf (mcp.json):
+                { "mcpServers": { "webmcpx": { "command": "npx", "args": ["-y", "webmcpx", "mcp"] } } }
+
+${bold("Check your own site's tools")} ${dim("(no Chrome flags)")}
+  npx webmcpx tools localhost:3000
+  npx webmcpx call localhost:3000 search_page '{"query": "pricing"}'
+
+${bold("Commands")}
+  mcp                         MCP server over stdio
+  tools <url>                 list the page's WebMCP tools
+  call <url> <tool> [json]    call one tool and print its result
+
+${bold("Options")}
+  --headed                    show the browser window
+  --browser <path>            Chrome, Chromium, Edge or Brave to use (or WEBMCPX_CHROME)
+  --cdp <url>                 use a browser you started with --remote-debugging-port
+
+Every page gets search_page, fetch_as_markdown and get_page_context, plus the site's own tools.
+The linter is the Rust CLI: cargo install webmcpx. Docs: https://webmcpx.dev`;
+
+const usage = (message) => {
+  console.error(`${message}\n\nRun "npx webmcpx --help" for usage.`);
+  process.exit(2);
+};
+
+function parse(argv) {
+  try {
+    return parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        headed: { type: "boolean" },
+        browser: { type: "string" },
+        cdp: { type: "string" },
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
+      },
+    });
+  } catch (e) {
+    return usage(e.message);
+  }
+}
+
+const firstLine = (s, max = 72) => {
+  const line = String(s ?? "").split("\n")[0];
+  return line.length > max ? `${line.slice(0, max - 1)}…` : line;
+};
+
+function printTools(page) {
+  if (page.tools === null) return console.log(describe(page));
+  const own = page.tools.filter((t) => !t.standard);
+  const standard = page.tools.filter((t) => t.standard);
+  const width = Math.max(0, ...page.tools.map((t) => t.name.length)) + 2;
+  const row = (t) => {
+    const a = t.annotations ?? {};
+    const tag = a.readOnlyHint ? dim("read-only ") : a.consequentialHint ? yellow("acts      ") : "          ";
+    return `  ${bold(t.name.padEnd(width))}${tag}${dim(firstLine(t.description))}`;
+  };
+  console.log(`${bold(page.title || page.url)} ${dim(page.url)}\n`);
+  if (own.length) {
+    console.log(green(`✓ ${own.length} WebMCP tool${own.length === 1 ? "" : "s"} registered by the site`));
+    for (const t of own) console.log(row(t));
+  } else {
+    console.log(yellow("○ The site registers no WebMCP tools of its own.") + dim(" Add them: https://webmcpx.dev/#fix"));
+  }
+  if (standard.length) {
+    console.log(`\n${dim("+ standard tools webmcpx adds to every page")}`);
+    for (const t of standard) console.log(row(t));
+  }
+  console.log(dim(`\nTry one: npx webmcpx call ${page.url} search_page '{"query": "..."}'`));
+}
+
+// An MCP client stops its server with a signal: exit through process.exit, so the browser we started
+// is killed by its exit hook instead of being orphaned.
+for (const [signal, code] of [["SIGINT", 130], ["SIGTERM", 143], ["SIGHUP", 129]]) {
+  process.once(signal, () => process.exit(code));
+}
+
+async function main() {
+  const { values, positionals } = parse(process.argv.slice(2));
+  const [command, ...rest] = positionals;
+  if (values.version) {
+    const { readFileSync } = await import("node:fs");
+    return console.log(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version);
+  }
+  if (values.help || !command || command === "help") return console.log(HELP);
+  const options = { headed: values.headed, browser: values.browser, cdp: values.cdp };
+
+  if (command === "mcp") return serve(options);
+  if (command === "lint") usage("The linter is the Rust CLI: cargo install webmcpx, then webmcpx lint <dir>.");
+  if (command !== "tools" && command !== "call") usage(`Unknown command "${command}".`);
+
+  const [url, name, json] = rest;
+  if (!url) usage(`Give a URL: npx webmcpx ${command} localhost:3000`);
+  if (command === "call" && !name) usage("Give a tool name: npx webmcpx call <url> <tool> [json]");
+  let input = {};
+  if (json) {
+    try {
+      input = JSON.parse(json);
+    } catch {
+      usage(`The input is not JSON: ${json}`);
+    }
+    if (!input || typeof input !== "object" || Array.isArray(input)) usage(`The input must be a JSON object, like '{"query": "pricing"}'.`);
+  }
+
+  const session = new Session(options);
+  try {
+    const page = await session.goto(url);
+    if (command === "tools") return printTools(page);
+    const entries = named(page.tools ?? []);
+    const tool = (entries.find((e) => e.tool.name === name) ?? entries.find((e) => e.name === name))?.tool;
+    if (!tool) {
+      console.error(`webmcpx: ${page.url} has no tool named "${name}". Run: npx webmcpx tools ${url}`);
+      process.exitCode = 2;
+      return;
+    }
+    const out = await session.call(tool, input);
+    const mcp = mcpResult(out);
+    let pretty = out;
+    try {
+      pretty = mcp
+        ? mcp.content.map((c) => (c.type === "text" ? c.text : JSON.stringify(c))).join("\n")
+        : JSON.stringify(JSON.parse(out), null, 2);
+    } catch {
+      // not JSON: print as is
+    }
+    console.log(pretty);
+    if (failed(out)) process.exitCode = 1;
+  } finally {
+    await session.close();
+  }
+}
+
+main().catch((e) => {
+  console.error(`webmcpx: ${e.message}`);
+  process.exit(1);
+});