@terramind/webmcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Terramind
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @terramind/webmcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Registers [WebMCP](https://webmachinelearning.github.io/webmcp/) page tools from React, so agent browsers can call a site's own functions instead of driving its UI.
+
+```sh
+bun add @terramind/webmcp
+```
+
+```tsx
+"use client"
+import { defineTool, useWebMcpTools } from "@terramind/webmcp"
+
+const getPricing = defineTool({
+  name: "get_pricing",
+  description: "Returns the current plans and their monthly prices.",
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  annotations: { readOnlyHint: true },
+  execute: () => ({ plans: [{ name: "Pro", usdPerMonth: 20 }] }),
+})
+
+export function PricingTools() {
+  useWebMcpTools([getPricing])
+  return null
+}
+```
+
+Tools are registered with `document.modelContext.registerTool` (falling back to the older `navigator.modelContext`) and unregistered when the component unmounts. Where the browser has no WebMCP API, every call does nothing, so the page behaves as it did without tools. Nothing is polyfilled.
+
+## API
+
+| Export | What it does |
+| --- | --- |
+| `defineTool(tool)` | Types a tool. `execute` returns a JSON-serialisable value. |
+| `useWebMcpTools(tools, deps?)` | Registers `tools` while the component is mounted. Re-registers when `deps` change. |
+| `WebMcpTools` | The hook as a component, for layouts that can't call hooks. |
+| `registerTools(tools, options?)` | Registers outside React. Returns an unregister function. Errors go to `options.onError` and are never thrown. |
+| `getModelContext()` | The browser's model context, or `null`. |
+| `validateTools(tools)` | Lists every convention a set breaks; use it in a test. |
+
+## Conventions `validateTools` checks
+
+- Names are snake_case, start with a letter, at most 64 characters, unique in a set.
+- A description is set and at most 500 characters.
+- `annotations.readOnlyHint` is always set, and a read-only tool is never `consequentialHint`.
+- `inputSchema` is a JSON object schema with `additionalProperties: false` at every object level.
+- A tool that takes an email address sets `consequentialHint`.
+
+## Browser support
+
+WebMCP is behind an origin trial in Chrome 149 to 156. A site needs a trial token for its own origin.
+
+## License
+
+MIT

package/dist/webmcp.d.ts

@@ -0,0 +1,69 @@
+export type JsonSchema = {
+    [key: string]: unknown;
+};
+export interface ToolAnnotations {
+    /** True when the tool only reads. Required so every tool states it. */
+    readOnlyHint: boolean;
+    /** True when the tool submits personal data or commits to something. */
+    consequentialHint?: boolean;
+    /** True when the result may contain text the site does not control. */
+    untrustedContentHint?: boolean;
+}
+export interface WebMcpTool<Input = Record<string, unknown>> {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema: JsonSchema;
+    annotations: ToolAnnotations;
+    /** Returns a JSON-serialisable value; the browser hands it to the agent as JSON. */
+    execute: (input: Input, options: {
+        signal?: AbortSignal;
+    }) => unknown;
+}
+export type AnyWebMcpTool = WebMcpTool<any>;
+export declare function defineTool<Input = Record<string, unknown>>(tool: WebMcpTool<Input>): WebMcpTool<Input>;
+/** The object handed to `registerTool`, as the spec's ModelContextTool. */
+export interface RegisteredTool {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema: JsonSchema;
+    annotations: ToolAnnotations;
+    execute: (input: unknown, options?: {
+        signal?: AbortSignal;
+    }) => unknown;
+}
+/** The subset of the browser API this module touches. */
+export interface ModelContextLike {
+    registerTool: (tool: RegisteredTool, options?: {
+        signal?: AbortSignal;
+    }) => unknown;
+    /** Only on the pre-July-2026 `navigator.modelContext` builds. */
+    unregisterTool?: (name: string) => unknown;
+}
+/** `document.modelContext`, else the deprecated `navigator.modelContext`, else null. */
+export declare function getModelContext(): ModelContextLike | null;
+/**
+ * Registers `tools` and returns a function that unregisters them.
+ * Registration failures (an older browser rejecting a field, a name another
+ * component already holds) are reported to `onError` and never thrown: a
+ * missing tool must not break the page.
+ */
+export declare function registerTools(tools: readonly AnyWebMcpTool[], options?: {
+    context?: ModelContextLike | null;
+    onError?: (error: unknown, name: string) => void;
+}): () => void;
+/**
+ * Registers `tools` while the calling component is mounted. Pass `deps` for
+ * anything the tools close over; the set is re-registered when they change.
+ * Strict-mode double mounts are safe: the first mount's tools are aborted
+ * before the second registers.
+ */
+export declare function useWebMcpTools(tools: readonly AnyWebMcpTool[], deps?: readonly unknown[]): void;
+/** `useWebMcpTools` as a component, for server layouts that cannot call hooks. */
+export declare function WebMcpTools({ tools }: {
+    tools: readonly AnyWebMcpTool[];
+}): null;
+/** Returns every convention a set of tools breaks; an empty list means it passes. */
+export declare function validateTools(tools: readonly AnyWebMcpTool[]): string[];
+//# sourceMappingURL=webmcp.d.ts.map

package/dist/webmcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webmcp.d.ts","sourceRoot":"","sources":["../src/webmcp.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,UAAU,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAA;AAEnD,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,YAAY,EAAE,OAAO,CAAA;IACrB,wEAAwE;IACxE,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,uEAAuE;IACvE,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAC/B;AAED,MAAM,WAAW,UAAU,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzD,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,UAAU,CAAA;IACvB,WAAW,EAAE,eAAe,CAAA;IAC5B,oFAAoF;IACpF,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAA;CACtE;AAGD,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;AAE3C,wBAAgB,UAAU,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAEtG;AAED,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,UAAU,CAAA;IACvB,WAAW,EAAE,eAAe,CAAA;IAC5B,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAA;CACzE;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAA;IACnF,iEAAiE;IACjE,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAA;CAC3C;AAQD,wFAAwF;AACxF,wBAAgB,eAAe,IAAI,gBAAgB,GAAG,IAAI,CASzD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO,GACpG,MAAM,IAAI,CAqCZ;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,EAAE,IAAI,GAAE,SAAS,OAAO,EAAO,GAAG,IAAI,CAGnG;AAED,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,EAAE,KAAK,EAAE,EAAE;IAAE,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;CAAE,GAAG,IAAI,CAGhF;AAQD,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,EAAE,CAsBvE"}

package/dist/webmcp.js

@@ -0,0 +1,186 @@
+"use client";
+/**
+ * WebMCP page tools for Terramind sites.
+ *
+ * A page lists its tools with `defineTool` and mounts them with
+ * `useWebMcpTools`. The hook registers each tool through the browser's
+ * `document.modelContext.registerTool` (spec:
+ * https://webmachinelearning.github.io/webmcp/) and unregisters them by
+ * aborting one signal when the component unmounts.
+ *
+ * Nothing here polyfills the API. Where it is missing every call is a no-op,
+ * so a page behaves exactly as it did without tools. A polyfill would also
+ * shadow the native object that agent browsers (Nucleus, Chrome) read.
+ */
+import { useEffect } from "react";
+export function defineTool(tool) {
+    return tool;
+}
+function asModelContext(value) {
+    return value && typeof value.registerTool === "function"
+        ? value
+        : null;
+}
+/** `document.modelContext`, else the deprecated `navigator.modelContext`, else null. */
+export function getModelContext() {
+    if (typeof document !== "undefined") {
+        const current = asModelContext(document.modelContext);
+        if (current)
+            return current;
+    }
+    if (typeof navigator !== "undefined") {
+        return asModelContext(navigator.modelContext);
+    }
+    return null;
+}
+/**
+ * Registers `tools` and returns a function that unregisters them.
+ * Registration failures (an older browser rejecting a field, a name another
+ * component already holds) are reported to `onError` and never thrown: a
+ * missing tool must not break the page.
+ */
+export function registerTools(tools, options = {}) {
+    const context = options.context === undefined ? getModelContext() : options.context;
+    if (!context || tools.length === 0)
+        return () => { };
+    const onError = options.onError ?? defaultOnError;
+    const controller = new AbortController();
+    for (const tool of tools) {
+        const registration = {
+            name: tool.name,
+            ...(tool.title ? { title: tool.title } : {}),
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: tool.annotations,
+            execute: (input, executeOptions) => tool.execute((input ?? {}), { signal: executeOptions?.signal }),
+        };
+        try {
+            const result = context.registerTool(registration, { signal: controller.signal });
+            if (result && typeof result.then === "function") {
+                ;
+                result.then(undefined, (error) => onError(error, tool.name));
+            }
+        }
+        catch (error) {
+            onError(error, tool.name);
+        }
+    }
+    return () => {
+        controller.abort();
+        // Builds that predate signal-based unregistration ignore the abort.
+        if (typeof context.unregisterTool === "function") {
+            for (const tool of tools) {
+                try {
+                    context.unregisterTool(tool.name);
+                }
+                catch {
+                    // Already gone.
+                }
+            }
+        }
+    };
+}
+function defaultOnError(error, name) {
+    if (typeof console !== "undefined")
+        console.warn(`[webmcp] could not register ${name}`, error);
+}
+/**
+ * Registers `tools` while the calling component is mounted. Pass `deps` for
+ * anything the tools close over; the set is re-registered when they change.
+ * Strict-mode double mounts are safe: the first mount's tools are aborted
+ * before the second registers.
+ */
+export function useWebMcpTools(tools, deps = []) {
+    // biome-ignore lint/correctness/useExhaustiveDependencies: callers name what the tools close over
+    useEffect(() => registerTools(tools), deps);
+}
+/** `useWebMcpTools` as a component, for server layouts that cannot call hooks. */
+export function WebMcpTools({ tools }) {
+    useWebMcpTools(tools, [tools]);
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Conventions, checked by each site's test through `validateTools`.
+const NAME = /^[a-z][a-z0-9_]{0,63}$/;
+const MAX_DESCRIPTION = 500;
+/** Returns every convention a set of tools breaks; an empty list means it passes. */
+export function validateTools(tools) {
+    const problems = [];
+    const seen = new Set();
+    for (const tool of tools) {
+        const at = `tool ${JSON.stringify(tool.name)}`;
+        if (!NAME.test(tool.name))
+            problems.push(`${at}: name must be snake_case, start with a letter, at most 64 chars`);
+        if (seen.has(tool.name))
+            problems.push(`${at}: name is used twice in one set`);
+        seen.add(tool.name);
+        const description = tool.description?.trim() ?? "";
+        if (!description)
+            problems.push(`${at}: description is empty`);
+        if (description.length > MAX_DESCRIPTION)
+            problems.push(`${at}: description is over ${MAX_DESCRIPTION} chars`);
+        if (typeof tool.annotations?.readOnlyHint !== "boolean")
+            problems.push(`${at}: annotations.readOnlyHint must be set`);
+        if (tool.annotations?.readOnlyHint && tool.annotations.consequentialHint) {
+            problems.push(`${at}: a read-only tool cannot be consequential`);
+        }
+        if (typeof tool.execute !== "function")
+            problems.push(`${at}: execute is not a function`);
+        problems.push(...schemaProblems(tool.inputSchema, `${at}: inputSchema`, true));
+        if (schemaMentions(tool.inputSchema, "email") && !tool.annotations?.consequentialHint) {
+            problems.push(`${at}: takes an email, so it must set consequentialHint`);
+        }
+    }
+    return problems;
+}
+function schemaProblems(schema, at, root) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return [`${at} must be an object`];
+    const node = schema;
+    const problems = [];
+    try {
+        JSON.stringify(node);
+    }
+    catch {
+        return [`${at} is not JSON-serialisable`];
+    }
+    if (root && node.type !== "object")
+        problems.push(`${at} must have type "object"`);
+    if (node.type === "object") {
+        if (node.additionalProperties !== false)
+            problems.push(`${at} must set additionalProperties: false`);
+        const properties = (node.properties ?? {});
+        if (typeof properties !== "object" || Array.isArray(properties))
+            problems.push(`${at}.properties must be an object`);
+        for (const [key, value] of Object.entries(properties)) {
+            problems.push(...schemaProblems(value, `${at}.properties.${key}`, false));
+        }
+        const required = node.required;
+        if (required !== undefined) {
+            if (!Array.isArray(required))
+                problems.push(`${at}.required must be an array`);
+            else
+                for (const key of required)
+                    if (!(key in properties))
+                        problems.push(`${at}.required names unknown "${key}"`);
+        }
+    }
+    if (node.type === "string" && !Array.isArray(node.enum) && typeof node.maxLength !== "number") {
+        problems.push(`${at} is a free string, so it needs maxLength`);
+    }
+    if (node.type === "array" && node.items)
+        problems.push(...schemaProblems(node.items, `${at}.items`, false));
+    if (!root && typeof node.description !== "string")
+        problems.push(`${at} needs a description`);
+    return problems;
+}
+function schemaMentions(schema, needle) {
+    if (!schema || typeof schema !== "object")
+        return false;
+    const node = schema;
+    if (node.format === needle)
+        return true;
+    const properties = (node.properties ?? {});
+    return Object.entries(properties).some(([key, value]) => key === needle || schemaMentions(value, needle));
+}
+//# sourceMappingURL=webmcp.js.map

package/dist/webmcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webmcp.js","sourceRoot":"","sources":["../src/webmcp.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@terramind/webmcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "WebMCP page tools for Terramind sites: register, unregister and check tools on document.modelContext.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/webmcp.js",
+  "types": "dist/webmcp.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/webmcp.d.ts",
+      "import": "./dist/webmcp.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun test && bun run ts:check && bun run build",
+    "test": "bun test",
+    "ts:check": "tsc --noEmit",
+    "vendor": "bun scripts/vendor.ts"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.2.0",
+    "react": "^19.2.0",
+    "typescript": "^5.9.0"
+  }
+}

package/src/webmcp.ts

@@ -0,0 +1,219 @@
+"use client"
+
+/**
+ * WebMCP page tools for Terramind sites.
+ *
+ * A page lists its tools with `defineTool` and mounts them with
+ * `useWebMcpTools`. The hook registers each tool through the browser's
+ * `document.modelContext.registerTool` (spec:
+ * https://webmachinelearning.github.io/webmcp/) and unregisters them by
+ * aborting one signal when the component unmounts.
+ *
+ * Nothing here polyfills the API. Where it is missing every call is a no-op,
+ * so a page behaves exactly as it did without tools. A polyfill would also
+ * shadow the native object that agent browsers (Nucleus, Chrome) read.
+ */
+
+import { useEffect } from "react"
+
+export type JsonSchema = { [key: string]: unknown }
+
+export interface ToolAnnotations {
+  /** True when the tool only reads. Required so every tool states it. */
+  readOnlyHint: boolean
+  /** True when the tool submits personal data or commits to something. */
+  consequentialHint?: boolean
+  /** True when the result may contain text the site does not control. */
+  untrustedContentHint?: boolean
+}
+
+export interface WebMcpTool<Input = Record<string, unknown>> {
+  name: string
+  title?: string
+  description: string
+  inputSchema: JsonSchema
+  annotations: ToolAnnotations
+  /** Returns a JSON-serialisable value; the browser hands it to the agent as JSON. */
+  execute: (input: Input, options: { signal?: AbortSignal }) => unknown
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: tools of different input types share one list
+export type AnyWebMcpTool = WebMcpTool<any>
+
+export function defineTool<Input = Record<string, unknown>>(tool: WebMcpTool<Input>): WebMcpTool<Input> {
+  return tool
+}
+
+/** The object handed to `registerTool`, as the spec's ModelContextTool. */
+export interface RegisteredTool {
+  name: string
+  title?: string
+  description: string
+  inputSchema: JsonSchema
+  annotations: ToolAnnotations
+  execute: (input: unknown, options?: { signal?: AbortSignal }) => unknown
+}
+
+/** The subset of the browser API this module touches. */
+export interface ModelContextLike {
+  registerTool: (tool: RegisteredTool, options?: { signal?: AbortSignal }) => unknown
+  /** Only on the pre-July-2026 `navigator.modelContext` builds. */
+  unregisterTool?: (name: string) => unknown
+}
+
+function asModelContext(value: unknown): ModelContextLike | null {
+  return value && typeof (value as ModelContextLike).registerTool === "function"
+    ? (value as ModelContextLike)
+    : null
+}
+
+/** `document.modelContext`, else the deprecated `navigator.modelContext`, else null. */
+export function getModelContext(): ModelContextLike | null {
+  if (typeof document !== "undefined") {
+    const current = asModelContext((document as unknown as { modelContext?: unknown }).modelContext)
+    if (current) return current
+  }
+  if (typeof navigator !== "undefined") {
+    return asModelContext((navigator as unknown as { modelContext?: unknown }).modelContext)
+  }
+  return null
+}
+
+/**
+ * Registers `tools` and returns a function that unregisters them.
+ * Registration failures (an older browser rejecting a field, a name another
+ * component already holds) are reported to `onError` and never thrown: a
+ * missing tool must not break the page.
+ */
+export function registerTools(
+  tools: readonly AnyWebMcpTool[],
+  options: { context?: ModelContextLike | null; onError?: (error: unknown, name: string) => void } = {},
+): () => void {
+  const context = options.context === undefined ? getModelContext() : options.context
+  if (!context || tools.length === 0) return () => {}
+  const onError = options.onError ?? defaultOnError
+  const controller = new AbortController()
+  for (const tool of tools) {
+    const registration: RegisteredTool = {
+      name: tool.name,
+      ...(tool.title ? { title: tool.title } : {}),
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      annotations: tool.annotations,
+      execute: (input: unknown, executeOptions?: { signal?: AbortSignal }) =>
+        tool.execute((input ?? {}) as never, { signal: executeOptions?.signal }),
+    }
+    try {
+      const result = context.registerTool(registration, { signal: controller.signal })
+      if (result && typeof (result as Promise<unknown>).then === "function") {
+        ;(result as Promise<unknown>).then(undefined, (error) => onError(error, tool.name))
+      }
+    } catch (error) {
+      onError(error, tool.name)
+    }
+  }
+  return () => {
+    controller.abort()
+    // Builds that predate signal-based unregistration ignore the abort.
+    if (typeof context.unregisterTool === "function") {
+      for (const tool of tools) {
+        try {
+          context.unregisterTool(tool.name)
+        } catch {
+          // Already gone.
+        }
+      }
+    }
+  }
+}
+
+function defaultOnError(error: unknown, name: string) {
+  if (typeof console !== "undefined") console.warn(`[webmcp] could not register ${name}`, error)
+}
+
+/**
+ * Registers `tools` while the calling component is mounted. Pass `deps` for
+ * anything the tools close over; the set is re-registered when they change.
+ * Strict-mode double mounts are safe: the first mount's tools are aborted
+ * before the second registers.
+ */
+export function useWebMcpTools(tools: readonly AnyWebMcpTool[], deps: readonly unknown[] = []): void {
+  // biome-ignore lint/correctness/useExhaustiveDependencies: callers name what the tools close over
+  useEffect(() => registerTools(tools), deps)
+}
+
+/** `useWebMcpTools` as a component, for server layouts that cannot call hooks. */
+export function WebMcpTools({ tools }: { tools: readonly AnyWebMcpTool[] }): null {
+  useWebMcpTools(tools, [tools])
+  return null
+}
+
+// ---------------------------------------------------------------------------
+// Conventions, checked by each site's test through `validateTools`.
+
+const NAME = /^[a-z][a-z0-9_]{0,63}$/
+const MAX_DESCRIPTION = 500
+
+/** Returns every convention a set of tools breaks; an empty list means it passes. */
+export function validateTools(tools: readonly AnyWebMcpTool[]): string[] {
+  const problems: string[] = []
+  const seen = new Set<string>()
+  for (const tool of tools) {
+    const at = `tool ${JSON.stringify(tool.name)}`
+    if (!NAME.test(tool.name)) problems.push(`${at}: name must be snake_case, start with a letter, at most 64 chars`)
+    if (seen.has(tool.name)) problems.push(`${at}: name is used twice in one set`)
+    seen.add(tool.name)
+    const description = tool.description?.trim() ?? ""
+    if (!description) problems.push(`${at}: description is empty`)
+    if (description.length > MAX_DESCRIPTION) problems.push(`${at}: description is over ${MAX_DESCRIPTION} chars`)
+    if (typeof tool.annotations?.readOnlyHint !== "boolean") problems.push(`${at}: annotations.readOnlyHint must be set`)
+    if (tool.annotations?.readOnlyHint && tool.annotations.consequentialHint) {
+      problems.push(`${at}: a read-only tool cannot be consequential`)
+    }
+    if (typeof tool.execute !== "function") problems.push(`${at}: execute is not a function`)
+    problems.push(...schemaProblems(tool.inputSchema, `${at}: inputSchema`, true))
+    if (schemaMentions(tool.inputSchema, "email") && !tool.annotations?.consequentialHint) {
+      problems.push(`${at}: takes an email, so it must set consequentialHint`)
+    }
+  }
+  return problems
+}
+
+function schemaProblems(schema: unknown, at: string, root: boolean): string[] {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) return [`${at} must be an object`]
+  const node = schema as JsonSchema
+  const problems: string[] = []
+  try {
+    JSON.stringify(node)
+  } catch {
+    return [`${at} is not JSON-serialisable`]
+  }
+  if (root && node.type !== "object") problems.push(`${at} must have type "object"`)
+  if (node.type === "object") {
+    if (node.additionalProperties !== false) problems.push(`${at} must set additionalProperties: false`)
+    const properties = (node.properties ?? {}) as Record<string, unknown>
+    if (typeof properties !== "object" || Array.isArray(properties)) problems.push(`${at}.properties must be an object`)
+    for (const [key, value] of Object.entries(properties)) {
+      problems.push(...schemaProblems(value, `${at}.properties.${key}`, false))
+    }
+    const required = node.required
+    if (required !== undefined) {
+      if (!Array.isArray(required)) problems.push(`${at}.required must be an array`)
+      else for (const key of required) if (!(key in properties)) problems.push(`${at}.required names unknown "${key}"`)
+    }
+  }
+  if (node.type === "string" && !Array.isArray(node.enum) && typeof node.maxLength !== "number") {
+    problems.push(`${at} is a free string, so it needs maxLength`)
+  }
+  if (node.type === "array" && node.items) problems.push(...schemaProblems(node.items, `${at}.items`, false))
+  if (!root && typeof node.description !== "string") problems.push(`${at} needs a description`)
+  return problems
+}
+
+function schemaMentions(schema: unknown, needle: string): boolean {
+  if (!schema || typeof schema !== "object") return false
+  const node = schema as JsonSchema
+  if (node.format === needle) return true
+  const properties = (node.properties ?? {}) as Record<string, unknown>
+  return Object.entries(properties).some(([key, value]) => key === needle || schemaMentions(value, needle))
+}