webmcpx 0.1.0 → 0.2.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "webmcpx",
-  "version": "0.1.0",
-  "description": "Standard WebMCP tools for any website: one script tag, zero config.",
+  "version": "0.2.1",
+  "description": "Standard WebMCP tools for any website, and an MCP server that gives any agent the WebMCP tools of the pages it opens.",
   "type": "module",
   "license": "MIT",
   "homepage": "https://webmcpx.dev",
@@ -11,22 +11,45 @@
     "directory": "packages/webmcpx"
   },
   "keywords": [
-    "webmcp",
-    "mcp",
+    "agent",
     "ai-agents",
+    "mcp",
+    "mcp-server",
     "model-context",
-    "wasm"
+    "polyfill",
+    "react",
+    "svelte",
+    "vue",
+    "wasm",
+    "webmcp"
   ],
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
       "default": "./src/index.js"
     },
-    "./auto": "./src/auto.js"
+    "./auto": "./src/auto.js",
+    "./react": {
+      "types": "./src/react.d.ts",
+      "default": "./src/react.js"
+    },
+    "./vue": {
+      "types": "./src/vue.d.ts",
+      "default": "./src/vue.js"
+    },
+    "./svelte": {
+      "types": "./src/svelte.d.ts",
+      "default": "./src/svelte.js"
+    }
   },
   "types": "./src/index.d.ts",
+  "bin": {
+    "webmcpx": "bin/webmcpx.js"
+  },
   "files": [
     "src",
+    "agent",
+    "bin",
     "wasm/webmcpx_wasm.js",
     "wasm/webmcpx_wasm_bg.wasm",
     "README.md",
@@ -36,12 +59,37 @@
     "./src/auto.js"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test --experimental-test-module-mocks"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@w3c/webmcp-polyfill": "0.1.0"
   },
   "devDependencies": {
-    "linkedom": "0.18.15"
+    "linkedom": "0.18.15",
+    "react": "19.3.1",
+    "svelte": "5.57.3",
+    "vue": "3.5.45"
   },
   "bugs": {
     "url": "https://github.com/webmcpx/webmcpx/issues"
+  },
+  "peerDependencies": {
+    "react": ">=16.8",
+    "vue": ">=2.7",
+    "svelte": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    }
   }
 }

package/src/auto.js

@@ -1,4 +1,12 @@
-// Drop-in: <script type="module" src="https://cdn.jsdelivr.net/npm/webmcpx/src/auto.js"></script>
-import { register } from "./index.js";
+// Drop-in: <script type="module" src="https://cdn.jsdelivr.net/npm/webmcpx@0.2/src/auto.js"></script>
+// Standard tools, plus <form toolname> as tools (that code loads only where such a form exists).
+import { register } from "./loader.js";
 
 register();
+const doc = globalThis.document;
+const forms = () => import("./tool.js").then((m) => m.forms());
+if (doc?.querySelector("form[toolname]")) forms();
+else if (doc) {
+  const watch = new MutationObserver(() => doc.querySelector("form[toolname]") && (watch.disconnect(), forms()));
+  watch.observe(doc.documentElement, { subtree: true, childList: true, attributes: true, attributeFilter: ["toolname"] });
+}

package/src/generated.js

@@ -17,3 +17,11 @@ export const CODES = {
   REQUIRES_USER: false,
   UNAVAILABLE: true,
 };
+
+/** Authoring limits, in chars (webmcpx-core `limits`). */
+export const LIMITS = {
+  NAME_WARN: 30,
+  DESCRIPTION_WARN: 500,
+  TOOLS_WARN: 20,
+  OUTPUT_MAX: 20000,
+};

package/src/index.d.ts

@@ -40,3 +40,43 @@ export const TOOLS: Record<ToolName, {
 export type Envelope<T = unknown> =
   | { ok: true; data: T; truncated?: true; next_cursor?: string; hint?: string }
   | { ok: false; error: { code: string; message: string; retryable: boolean }; hint?: string };
+
+/** An input field: a JSON type ("string", "number?" for optional), a list of choices, or a property schema. */
+export type InputField = string | readonly (string | number)[] | Record<string, unknown>;
+
+export interface ToolDefinition<I = any, O = unknown> {
+  /** 1–128 of A-Z a-z 0-9 _ . - (keep it under 30). */
+  name: string;
+  /** What it does and when to use it (under 500 chars). */
+  description: string;
+  /** Shorthand: `{ sku: "string", "qty?": "number", size: ["S", "M"] }`. */
+  input?: Record<string, InputField>;
+  /** A full JSON Schema instead of `input` (checked: type, enum, required, properties, bounds, pattern...). */
+  inputSchema?: { type: "object"; [key: string]: unknown };
+  /** Returns the data for `{ ok: true, data }`. Throw for errors; an error with a webmcpx `code` keeps it. */
+  run(input: I, client?: unknown): O | Promise<O>;
+  /** Only reads (readOnlyHint). */
+  readOnly?: boolean;
+  /** Changes something for the user: cart, booking, message (consequentialHint). */
+  acts?: boolean;
+  /** Returns third-party content, like reviews or comments (untrustedContentHint). */
+  untrusted?: boolean;
+  /** Abort to unregister. */
+  signal?: AbortSignal;
+}
+
+export interface ToolHandle {
+  /** Resolves true once registered, false where WebMCP is missing or the host refused it. */
+  ready: Promise<boolean>;
+  /** Unregisters the tool. */
+  dispose(): void;
+}
+
+/** Registers one of your own tools with the webmcpx contract. A no-op where WebMCP is missing. */
+export function tool<I = any, O = unknown>(definition: ToolDefinition<I, O>): ToolHandle;
+
+/** Exposes every `<form toolname>` as a tool (WebMCP declarative API), following DOM changes. */
+export function forms(): { dispose(): void };
+
+/** The JSON Schema an input shorthand stands for. */
+export function schema(input?: Record<string, InputField>): object;

package/src/index.js

@@ -1,139 +1,3 @@
-// webmcpx loader: registers the standard WebMCP tools. Owns the DOM and registerTool();
-// all text processing runs in a WebAssembly module loaded on the first tool call.
-import { CODES, TOOLS } from "./generated.js";
-
-const RECORD = "\x1e";
-const FIELD = "\x1f";
-const KINDS = {
-  H1: "h1", H2: "h2", H3: "h3", H4: "h4", H5: "h5", H6: "h6",
-  P: "p", LI: "li", PRE: "pre", BLOCKQUOTE: "quote",
-  DT: "p", DD: "p", FIGCAPTION: "p", SUMMARY: "p",
-};
-const SKIP = new Set(["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE", "SVG", "NAV", "FOOTER", "ASIDE"]);
-const DEFAULT_TOOLS = ["get_page_context", "search_page", "fetch_as_markdown"];
-
-const envelope = (body) => JSON.stringify(body);
-const ok = (data) => envelope({ ok: true, data });
-const err = (code, message, hint) =>
-  envelope({ ok: false, error: { code, message, retryable: CODES[code] }, ...(hint && { hint }) });
-
-let wasm;
-const engine = (source) =>
-  (wasm ??= import("../wasm/webmcpx_wasm.js")
-    .then(async (m) => (await m.default(source ? { module_or_path: source } : undefined), m))
-    .catch((e) => {
-      wasm = undefined;
-      throw e;
-    }));
-
-const pageUrl = () => location.href.split("#")[0];
-const text = (s) => (s ?? "").replace(/\s+/g, " ").trim();
-
-const skipped = (el) => SKIP.has(el.tagName) || el.hasAttribute("hidden") || el.getAttribute("aria-hidden") === "true";
-
-/** Serializes readable content of `root` as a block stream (see webmcpx-std `blocks`). */
-function blocks(root) {
-  let out = "";
-  let anchor = "";
-  const base = pageUrl();
-  const visit = (el) => {
-    for (const child of el.children) {
-      if (skipped(child)) continue;
-      if (child.id) anchor = `${base}#${child.id}`;
-      // A table row is one block ("Monday | Closed"), so search keeps a value next to its label.
-      const row = child.tagName === "TR" && [...child.children].filter((c) => !skipped(c)).map((c) => text(c.textContent)).join(" | ");
-      const kind = row ? "p" : KINDS[child.tagName] ?? (child.children.length === 0 && "p");
-      if (kind) out += kind + FIELD + (row || child.textContent) + FIELD + anchor + RECORD;
-      else visit(child);
-    }
-  };
-  visit(root);
-  return out;
-}
-
-function contentRoot(root) {
-  if (typeof root === "string") return document.querySelector(root) ?? document.body;
-  return root ?? document.querySelector("main, [role=main], article") ?? document.body;
-}
-
-function pageContext() {
-  const base = pageUrl();
-  return ok({
-    title: document.title,
-    url: location.href,
-    lang: document.documentElement.lang || undefined,
-    description: document.querySelector('meta[name="description"]')?.getAttribute("content") || undefined,
-    headings: [...document.querySelectorAll("h1, h2, h3")].slice(0, 30).map((h) => ({
-      level: Number(h.tagName[1]),
-      text: text(h.textContent).slice(0, 120),
-      url: h.id ? `${base}#${h.id}` : undefined,
-    })),
-    selection: text(globalThis.getSelection?.()?.toString()).slice(0, 1000) || undefined,
-  });
-}
-
-function executors(options) {
-  const withEngine = (run) => async (input) => {
-    let m;
-    try {
-      m = await engine(options.wasm);
-    } catch (e) {
-      return err("UNAVAILABLE", `WebAssembly could not load: ${e?.message ?? e}`,
-        "If the page sets a Content-Security-Policy, add 'wasm-unsafe-eval' to script-src.");
-    }
-    return run(m, blocks(contentRoot(options.root)), input);
-  };
-  return {
-    get_page_context: async () => pageContext(),
-    search_page: withEngine((m, page, { query, limit }) =>
-      typeof query === "string" ? m.search(page, query, limit ?? 0) : err("INVALID_INPUT", "`query` must be a string")),
-    fetch_as_markdown: withEngine((m, page, { cursor, max_chars }) => m.markdown(page, String(cursor ?? ""), max_chars ?? 0)),
-    search_site: async ({ query, limit = 5 }, { signal } = {}) => {
-      if (typeof query !== "string" || !query.trim()) return err("INVALID_INPUT", "`query` must be a non-empty string");
-      const found = await options.searchSite(query, { limit, signal });
-      if (!found?.length) return err("NOT_FOUND", "no page matches the query", "Try fewer or different words.");
-      return ok({ results: found.slice(0, limit).map(({ title, url, snippet }) => ({ title, url, snippet })) });
-    },
-  };
-}
-
-/** Tools resolve with an envelope and never reject: hosts drop rejection reasons (webmcp#282). */
-const guard = (run) => async (input, client) => {
-  try {
-    return await run(typeof input === "string" ? JSON.parse(input || "{}") : input ?? {}, client);
-  } catch (e) {
-    return err("UNAVAILABLE", String(e?.message ?? e));
-  }
-};
-
-/**
- * Registers webmcpx standard tools on the current document.
- * @param {import("./index").Options} [options]
- * @returns {Promise<import("./index").Registration>}
- */
-export async function register(options = {}) {
-  const mc = globalThis.document?.modelContext ?? globalThis.navigator?.modelContext;
-  const controller = new AbortController();
-  const result = { registered: [], failed: [], dispose: () => controller.abort() };
-  if (typeof mc?.registerTool !== "function") return result;
-
-  const run = executors(options);
-  const names = options.tools ?? [...DEFAULT_TOOLS, ...(options.searchSite ? ["search_site"] : [])];
-  await Promise.all(names.map(async (name) => {
-    if (!TOOLS[name]) return result.failed.push({ name, error: "unknown tool" });
-    if (name === "search_site" && !options.searchSite) {
-      return result.failed.push({ name, error: "search_site needs options.searchSite" });
-    }
-    try {
-      // Never assign onto `mc`: some agent browsers expose a frozen object (webmcp#293).
-      await mc.registerTool({ ...TOOLS[name], execute: guard(run[name]) }, { signal: controller.signal });
-      result.registered.push(name);
-    } catch (e) {
-      result.failed.push({ name, error: String(e?.message ?? e) });
-    }
-  }));
-  result.registered.sort();
-  return result;
-}
-
-export { TOOLS };
+// webmcpx: the standard WebMCP tools, your own tools and <form toolname>, in one package.
+export { readPage, register, TOOLS } from "./loader.js";
+export { forms, schema, tool } from "./tool.js";

package/src/loader.js

@@ -0,0 +1,133 @@
+// The standard tools: DOM and registerTool() here, text work in WebAssembly (loaded on first call).
+import { CODES, TOOLS } from "./generated.js";
+
+const DEFAULT_TOOLS = ["get_page_context", "search_page", "fetch_as_markdown"];
+
+const envelope = (body) => JSON.stringify(body);
+const ok = (data) => envelope({ ok: true, data });
+const err = (code, message, hint) =>
+  envelope({ ok: false, error: { code, message, retryable: CODES[code] }, ...(hint && { hint }) });
+
+let wasm;
+const engine = (source) =>
+  (wasm ??= import("../wasm/webmcpx_wasm.js")
+    .then(async (m) => (await m.default(source ? { module_or_path: source } : undefined), m))
+    .catch((e) => {
+      wasm = undefined;
+      throw e;
+    }));
+
+// "blocks": main content as a webmcpx-std block stream; "context": the page. Self-contained:
+// agent/ runs its source in pages. Internal, not public API.
+export function readPage(what, root) {
+  const RECORD = "\x1e";
+  const FIELD = "\x1f";
+  const KINDS = {
+    H1: "h1", H2: "h2", H3: "h3", H4: "h4", H5: "h5", H6: "h6",
+    P: "p", LI: "li", PRE: "pre", BLOCKQUOTE: "quote",
+    DT: "p", DD: "p", FIGCAPTION: "p", SUMMARY: "p",
+  };
+  const SKIP = new Set(["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE", "SVG", "NAV", "FOOTER", "ASIDE"]);
+  const base = location.href.split("#")[0];
+  const text = (s) => (s ?? "").replace(/\s+/g, " ").trim();
+  if (what === "context") {
+    return {
+      title: document.title,
+      url: location.href,
+      lang: document.documentElement.lang || undefined,
+      description: document.querySelector('meta[name="description"]')?.getAttribute("content") || undefined,
+      headings: [...document.querySelectorAll("h1, h2, h3")].slice(0, 30).map((h) => ({
+        level: Number(h.tagName[1]),
+        text: text(h.textContent).slice(0, 120),
+        url: h.id ? `${base}#${h.id}` : undefined,
+      })),
+      selection: text(globalThis.getSelection?.()?.toString()).slice(0, 1000) || undefined,
+    };
+  }
+  const skipped = (el) => SKIP.has(el.tagName) || el.hasAttribute("hidden") || el.getAttribute("aria-hidden") === "true";
+  // Text without hidden parts; an element with no block inside is one block ("Free <b>delivery</b>").
+  const textOf = (el) =>
+    [...el.childNodes].map((n) => (n.nodeType === 3 ? n.data : n.nodeType === 1 && !skipped(n) ? textOf(n) : "")).join("");
+  const BLOCKS = Object.keys(KINDS) + ",div,section,article,main,ul,ol,dl,table,tr,form,header,figure,details";
+  let out = "";
+  let anchor = "";
+  const add = (kind, s) => text(s) && (out += kind + FIELD + s + FIELD + anchor + RECORD);
+  const visit = (el) => {
+    for (const child of el.childNodes) {
+      if (child.nodeType === 3) add("p", child.data);
+      if (child.nodeType !== 1 || skipped(child)) continue;
+      if (child.id) anchor = `${base}#${child.id}`;
+      // A table row is one block ("Monday | Closed"), so search keeps a value next to its label.
+      const row = child.tagName === "TR" && [...child.children].filter((c) => !skipped(c)).map((c) => text(textOf(c))).join(" | ");
+      const kind = row ? "p" : KINDS[child.tagName] ?? (!child.querySelector(BLOCKS) && "p");
+      if (kind) add(kind, row || textOf(child));
+      else visit(child);
+    }
+  };
+  visit(root ?? document.querySelector("main, [role=main], article") ?? document.body);
+  return out;
+}
+
+const contentRoot = (root) => (typeof root === "string" ? document.querySelector(root) ?? document.body : root);
+
+function executors(options) {
+  const withEngine = (run) => async (input) => {
+    let m;
+    try {
+      m = await engine(options.wasm);
+    } catch (e) {
+      return err("UNAVAILABLE", `WebAssembly could not load: ${e?.message ?? e}`,
+        "If the page sets a Content-Security-Policy, add 'wasm-unsafe-eval' to script-src.");
+    }
+    return run(m, readPage("blocks", contentRoot(options.root)), input);
+  };
+  return {
+    get_page_context: async () => ok(readPage("context")),
+    search_page: withEngine((m, page, { query, limit }) =>
+      typeof query === "string" ? m.search(page, query, limit ?? 0) : err("INVALID_INPUT", "`query` must be a string")),
+    fetch_as_markdown: withEngine((m, page, { cursor, max_chars }) => m.markdown(page, String(cursor ?? ""), max_chars ?? 0)),
+    search_site: async ({ query, limit = 5 }, { signal } = {}) => {
+      if (typeof query !== "string" || !query.trim()) return err("INVALID_INPUT", "`query` must be a non-empty string");
+      const found = await options.searchSite(query, { limit, signal });
+      if (!found?.length) return err("NOT_FOUND", "no page matches the query", "Try fewer or different words.");
+      return ok({ results: found.slice(0, limit).map(({ title, url, snippet }) => ({ title, url, snippet })) });
+    },
+  };
+}
+
+/** Tools resolve with an envelope and never reject: hosts drop rejection reasons (webmcp#282). */
+const guard = (run) => async (input, client) => {
+  try {
+    return await run(typeof input === "string" ? JSON.parse(input || "{}") : input ?? {}, client);
+  } catch (e) {
+    return err("UNAVAILABLE", String(e?.message ?? e));
+  }
+};
+
+/** Registers the standard tools (types: index.d.ts). */
+export async function register(options = {}) {
+  const mc = globalThis.document?.modelContext ?? globalThis.navigator?.modelContext;
+  const controller = new AbortController();
+  const result = { registered: [], failed: [], dispose: () => controller.abort() };
+  if (typeof mc?.registerTool !== "function") return result;
+
+  const run = executors(options);
+  const names = options.tools ?? [...DEFAULT_TOOLS, ...(options.searchSite ? ["search_site"] : [])];
+  await Promise.all(names.map(async (name) => {
+    if (!TOOLS[name]) return result.failed.push({ name, error: "unknown tool" });
+    if (name === "search_site" && !options.searchSite) {
+      return result.failed.push({ name, error: "search_site needs options.searchSite" });
+    }
+    try {
+      // Never assign onto `mc`: some agent browsers expose a frozen object (webmcp#293).
+      await mc.registerTool({ ...TOOLS[name], execute: guard(run[name]) }, { signal: controller.signal });
+      result.registered.push(name);
+    } catch (e) {
+      result.failed.push({ name, error: String(e?.message ?? e) });
+    }
+  }));
+  result.registered.sort();
+  return result;
+}
+
+export { TOOLS };

package/src/react.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "./index.js";
+
+/** Registers the tool while the component is mounted. */
+export function useTool(definition: ToolDefinition): void;

package/src/react.js

@@ -0,0 +1,17 @@
+// React 16.8+ (and Preact via preact/compat): `useTool({ name, description, input, run })` registers the tool while the component is
+// mounted. `run` always sees the latest props and state; the tool re-registers when what the agent
+// sees changes: name, description, input or annotations.
+import { useEffect, useRef } from "react";
+import { tool } from "./tool.js";
+
+export function useTool(definition) {
+  const latest = useRef(definition);
+  latest.current = definition;
+  const { name, description, input, inputSchema, readOnly, acts, untrusted, signal } = definition;
+  // What the agent sees (and is told about safety) re-registers the tool; `run` is always the latest.
+  const shape = JSON.stringify([input ?? {}, inputSchema ?? null]);
+  useEffect(
+    () => tool({ ...latest.current, run: (args, client) => latest.current.run(args, client) }).dispose,
+    [name, description, shape, Boolean(readOnly), Boolean(acts), Boolean(untrusted), signal],
+  );
+}

package/src/svelte.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDefinition } from "./index.js";
+
+/** Registers the tool while the component is mounted. */
+export function useTool(definition: ToolDefinition): void;

package/src/svelte.js

@@ -0,0 +1,8 @@
+// Svelte 3, 4 and 5: `useTool(definition)` in a component's script registers the tool while it is
+// mounted. (In Svelte 5 you can also write `$effect(() => tool(definition).dispose)`.)
+import { onMount } from "svelte";
+import { tool } from "./tool.js";
+
+export function useTool(definition) {
+  onMount(() => tool(definition).dispose);
+}