@sonordev/site-kit 4.2.4 → 4.3.0

package/dist/mcp/WebMcpTools.d.ts

@@ -0,0 +1,60 @@
+import type { JsonSchemaObject } from './types';
+/** True when the visiting browser exposes WebMCP at all. */
+export declare function isWebMcpAvailable(): boolean;
+/** A tool as it crosses the server→client boundary: JSON, no functions. */
+export interface WebMcpToolDescriptor {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema: JsonSchemaObject;
+}
+export interface WebMcpLocalTool extends WebMcpToolDescriptor {
+    /** Runs in the browser. Use for DOM-aware tools only. */
+    execute: (args: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+export interface WebMcpToolsProps {
+    /**
+     * Proxied tools — executed server-side via the MCP endpoint.
+     *
+     * Usually omit this. Passing descriptors from a server component sends the
+     * whole tool catalog through the RSC payload of EVERY page, costing every
+     * human visitor several KB for a capability only an agent uses. Leave it
+     * empty and the component fetches `tools/list` instead — but only after
+     * confirming the browser actually exposes WebMCP, so the fetch never
+     * happens for ordinary visitors. Pass descriptors only to pin a subset.
+     */
+    tools?: WebMcpToolDescriptor[];
+    /** Tools whose handler runs in the browser. */
+    localTools?: WebMcpLocalTool[];
+    /** MCP endpoint on this origin (default `/api/mcp`). */
+    endpoint?: string;
+    /**
+     * Wait for the page to go quiet before registering (default true).
+     *
+     * Registration is not user-visible and must never compete with hydration.
+     * An agent arriving at the page polls or listens for `toolchange`, so a
+     * couple of hundred milliseconds costs nothing; a blocked LCP costs a lot.
+     */
+    defer?: boolean;
+    /**
+     * Fetch the catalog from the endpoint's `tools/list` when no `tools` are
+     * passed (default true). The fetch is gated on WebMCP being present.
+     */
+    discover?: boolean;
+}
+/**
+ * Register this site's MCP tools with the visiting browser's agent.
+ *
+ * Renders nothing. Mount it as a CHILDLESS sibling in the layout — never as a
+ * wrapper around `{children}`, which would de-opt the whole route to client
+ * rendering (the cardinal rule in the root CLAUDE.md).
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * <SiteKitLayout analytics={false}>{children}</SiteKitLayout>
+ * <WebMcpTools tools={MCP_TOOL_DESCRIPTORS} />
+ * ```
+ */
+export declare function WebMcpTools({ tools, localTools, endpoint, defer, discover, }: WebMcpToolsProps): null;
+//# sourceMappingURL=WebMcpTools.d.ts.map

package/dist/mcp/WebMcpTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebMcpTools.d.ts","sourceRoot":"","sources":["../../src/mcp/WebMcpTools.tsx"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,gBAAgB,EAAiB,MAAM,SAAS,CAAA;AA6B9D,4DAA4D;AAC5D,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAMD,2EAA2E;AAC3E,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,gBAAgB,CAAA;CAC9B;AAED,MAAM,WAAW,eAAgB,SAAQ,oBAAoB;IAC3D,yDAAyD;IACzD,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;CACvE;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,oBAAoB,EAAE,CAAA;IAC9B,+CAA+C;IAC/C,UAAU,CAAC,EAAE,eAAe,EAAE,CAAA;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAU,EACV,UAAe,EACf,QAAqB,EACrB,KAAY,EACZ,QAAe,GAChB,EAAE,gBAAgB,QAqIlB"}

package/dist/mcp/client.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @sonordev/site-kit/mcp/client — browser-side WebMCP
+ *
+ * Split from `@sonordev/site-kit/mcp` so a route handler importing the server
+ * pieces never drags a `'use client'` component into its graph.
+ */
+export { WebMcpTools, isWebMcpAvailable } from './WebMcpTools';
+export type { WebMcpToolsProps, WebMcpToolDescriptor, WebMcpLocalTool, } from './WebMcpTools';
+//# sourceMappingURL=client.d.ts.map

package/dist/mcp/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/mcp/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAC9D,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,GAChB,MAAM,eAAe,CAAA"}

package/dist/mcp/client.js

@@ -0,0 +1,132 @@
+'use client';
+'use strict';
+
+var chunkHGNSJXWT_js = require('../chunk-HGNSJXWT.js');
+require('../chunk-SNAQBZPT.js');
+var react = require('react');
+
+function getModelContext() {
+  if (typeof window === "undefined") return null;
+  const doc = document;
+  if (doc.modelContext) return doc.modelContext;
+  const nav = navigator;
+  return nav.modelContext ?? null;
+}
+function isWebMcpAvailable() {
+  return getModelContext() !== null;
+}
+function WebMcpTools({
+  tools = [],
+  localTools = [],
+  endpoint = "/api/mcp",
+  defer = true,
+  discover = true
+}) {
+  const ready = chunkHGNSJXWT_js.useDeferredActivation(defer);
+  react.useEffect(() => {
+    if (!ready) return;
+    const modelContext = getModelContext();
+    if (!modelContext) return;
+    const controller = new AbortController();
+    const callRemote = async (name, args) => {
+      try {
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+            "Mcp-Method": "tools/call",
+            "Mcp-Name": name
+          },
+          body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: `webmcp-${name}`,
+            method: "tools/call",
+            params: { name, arguments: args }
+          }),
+          signal: controller.signal
+        });
+        const payload = await response.json();
+        if (payload.error) {
+          return {
+            content: [{ type: "text", text: payload.error.message ?? "Tool call failed." }],
+            isError: true
+          };
+        }
+        return payload.result ?? { content: [{ type: "text", text: "(no result)" }] };
+      } catch (error) {
+        if (controller.signal.aborted) throw error;
+        const detail = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: "text", text: `Tool call failed: ${detail}` }], isError: true };
+      }
+    };
+    const normalize = (value) => {
+      if (value && typeof value === "object" && Array.isArray(value.content)) {
+        return value;
+      }
+      return {
+        content: [
+          { type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }
+        ],
+        structuredContent: value
+      };
+    };
+    const proxied = (list) => list.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      execute: (args) => callRemote(tool.name, args ?? {})
+    }));
+    const local = localTools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      execute: async (args) => normalize(await tool.execute(args ?? {}))
+    }));
+    const listRemoteTools = async () => {
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json, text/event-stream",
+          "Mcp-Method": "tools/list"
+        },
+        body: JSON.stringify({ jsonrpc: "2.0", id: "webmcp-list", method: "tools/list" }),
+        signal: controller.signal
+      });
+      const payload = await response.json();
+      return payload.result?.tools ?? [];
+    };
+    let cancelled = false;
+    void (async () => {
+      try {
+        const discovered = tools.length === 0 && discover ? await listRemoteTools() : tools;
+        if (cancelled) return;
+        const definitions = [...proxied(discovered), ...local];
+        if (definitions.length === 0) return;
+        if (typeof modelContext.registerTool === "function") {
+          for (const definition of definitions) {
+            if (cancelled) return;
+            await modelContext.registerTool(definition, { signal: controller.signal });
+          }
+        } else if (typeof modelContext.provideContext === "function") {
+          await modelContext.provideContext({ tools: definitions });
+        }
+      } catch (error) {
+        if (process.env.NODE_ENV !== "production") {
+          console.warn("[site-kit/mcp] WebMCP registration failed:", error);
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+      controller.abort();
+    };
+  }, [ready, tools, localTools, endpoint, discover]);
+  return null;
+}
+
+exports.WebMcpTools = WebMcpTools;
+exports.isWebMcpAvailable = isWebMcpAvailable;
+//# sourceMappingURL=client.js.map
+//# sourceMappingURL=client.js.map

package/dist/mcp/client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/mcp/WebMcpTools.tsx"],"names":["useDeferredActivation","useEffect"],"mappings":";;;;;;AAsDA,SAAS,eAAA,GAA2C;AAClD,EAAA,IAAI,OAAO,MAAA,KAAW,WAAA,EAAa,OAAO,IAAA;AAC1C,EAAA,MAAM,GAAA,GAAM,QAAA;AACZ,EAAA,IAAI,GAAA,CAAI,YAAA,EAAc,OAAO,GAAA,CAAI,YAAA;AACjC,EAAA,MAAM,GAAA,GAAM,SAAA;AACZ,EAAA,OAAO,IAAI,YAAA,IAAgB,IAAA;AAC7B;AAGO,SAAS,iBAAA,GAA6B;AAC3C,EAAA,OAAO,iBAAgB,KAAM,IAAA;AAC/B;AAoEO,SAAS,WAAA,CAAY;AAAA,EAC1B,QAAQ,EAAC;AAAA,EACT,aAAa,EAAC;AAAA,EACd,QAAA,GAAW,UAAA;AAAA,EACX,KAAA,GAAQ,IAAA;AAAA,EACR,QAAA,GAAW;AACb,CAAA,EAAqB;AACnB,EAAA,MAAM,KAAA,GAAQA,uCAAsB,KAAK,CAAA;AAEzC,EAAAC,eAAA,CAAU,MAAM;AACd,IAAA,IAAI,CAAC,KAAA,EAAO;AAGZ,IAAA,MAAM,eAAe,eAAA,EAAgB;AACrC,IAAA,IAAI,CAAC,YAAA,EAAc;AAEnB,IAAA,MAAM,UAAA,GAAa,IAAI,eAAA,EAAgB;AAEvC,IAAA,MAAM,UAAA,GAAa,OACjB,IAAA,EACA,IAAA,KAC2B;AAC3B,MAAA,IAAI;AACF,QAAA,MAAM,QAAA,GAAW,MAAM,KAAA,CAAM,QAAA,EAAU;AAAA,UACrC,MAAA,EAAQ,MAAA;AAAA,UACR,OAAA,EAAS;AAAA,YACP,cAAA,EAAgB,kBAAA;AAAA,YAChB,MAAA,EAAQ,qCAAA;AAAA,YACR,YAAA,EAAc,YAAA;AAAA,YACd,UAAA,EAAY;AAAA,WACd;AAAA,UACA,IAAA,EAAM,KAAK,SAAA,CAAU;AAAA,YACnB,OAAA,EAAS,KAAA;AAAA,YACT,EAAA,EAAI,UAAU,IAAI,CAAA,CAAA;AAAA,YAClB,MAAA,EAAQ,YAAA;AAAA,YACR,MAAA,EAAQ,EAAE,IAAA,EAAM,SAAA,EAAW,IAAA;AAAK,WACjC,CAAA;AAAA,UACD,QAAQ,UAAA,CAAW;AAAA,SACpB,CAAA;AACD,QAAA,MAAM,OAAA,GAAW,MAAM,QAAA,CAAS,IAAA,EAAK;AAIrC,QAAA,IAAI,QAAQ,KAAA,EAAO;AACjB,UAAA,OAAO;AAAA,YACL,OAAA,EAAS,CAAC,EAAE,IAAA,EAAM,MAAA,EAAQ,MAAM,OAAA,CAAQ,KAAA,CAAM,OAAA,IAAW,mBAAA,EAAqB,CAAA;AAAA,YAC9E,OAAA,EAAS;AAAA,WACX;AAAA,QACF;AACA,QAAA,OAAO,OAAA,CAAQ,MAAA,IAAU,EAAE,OAAA,EAAS,CAAC,EAAE,IAAA,EAAM,MAAA,EAAQ,IAAA,EAAM,aAAA,EAAe,CAAA,EAAE;AAAA,MAC9E,SAAS,KAAA,EAAO;AACd,QAAA,IAAI,UAAA,CAAW,MAAA,CAAO,OAAA,EAAS,MAAM,KAAA;AACrC,QAAA,MAAM,SAAS,KAAA,YAAiB,KAAA,GAAQ,KAAA,CAAM,OAAA,GAAU,OAAO,KAAK,CAAA;AACpE,QAAA,OAAO,EAAE,OAAA,EAAS,CAAC,EAAE,IAAA,EAAM,MAAA,EAAQ,IAAA,EAAM,CAAA,kBAAA,EAAqB,MAAM,CAAA,CAAA,EAAI,CAAA,EAAG,SAAS,IAAA,EAAK;AAAA,MAC3F;AAAA,IACF,CAAA;AAEA,IAAA,MAAM,SAAA,GAAY,CAAC,KAAA,KAAkC;AACnD,MAAA,IAAI,KAAA,IAAS,OAAO,KAAA,KAAU,QAAA,IAAY,MAAM,OAAA,CAAS,KAAA,CAAwB,OAAO,CAAA,EAAG;AACzF,QAAA,OAAO,KAAA;AAAA,MACT;AACA,MAAA,OAAO;AAAA,QACL,OAAA,EAAS;AAAA,UACP,EAAE,IAAA,EAAM,MAAA,EAAQ,IAAA,EAAM,OAAO,KAAA,KAAU,QAAA,GAAW,KAAA,GAAQ,IAAA,CAAK,SAAA,CAAU,KAAA,EAAO,IAAA,EAAM,CAAC,CAAA;AAAE,SAC3F;AAAA,QACA,iBAAA,EAAmB;AAAA,OACrB;AAAA,IACF,CAAA;AAEA,IAAA,MAAM,UAAU,CAAC,IAAA,KACf,IAAA,CAAK,GAAA,CAAI,CAAC,IAAA,MAAU;AAAA,MAClB,MAAM,IAAA,CAAK,IAAA;AAAA,MACX,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB,OAAA,EAAS,CAAC,IAAA,KAAkC,UAAA,CAAW,KAAK,IAAA,EAAM,IAAA,IAAQ,EAAE;AAAA,KAC9E,CAAE,CAAA;AAEJ,IAAA,MAAM,KAAA,GAAQ,UAAA,CAAW,GAAA,CAAI,CAAC,IAAA,MAAU;AAAA,MACtC,MAAM,IAAA,CAAK,IAAA;AAAA,MACX,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB,aAAa,IAAA,CAAK,WAAA;AAAA,MAClB,OAAA,EAAS,OAAO,IAAA,KAAkC,SAAA,CAAU,MAAM,KAAK,OAAA,CAAQ,IAAA,IAAQ,EAAE,CAAC;AAAA,KAC5F,CAAE,CAAA;AAGF,IAAA,MAAM,kBAAkB,YAA6C;AACnE,MAAA,MAAM,QAAA,GAAW,MAAM,KAAA,CAAM,QAAA,EAAU;AAAA,QACrC,MAAA,EAAQ,MAAA;AAAA,QACR,OAAA,EAAS;AAAA,UACP,cAAA,EAAgB,kBAAA;AAAA,UAChB,MAAA,EAAQ,qCAAA;AAAA,UACR,YAAA,EAAc;AAAA,SAChB;AAAA,QACA,IAAA,EAAM,IAAA,CAAK,SAAA,CAAU,EAAE,OAAA,EAAS,OAAO,EAAA,EAAI,aAAA,EAAe,MAAA,EAAQ,YAAA,EAAc,CAAA;AAAA,QAChF,QAAQ,UAAA,CAAW;AAAA,OACpB,CAAA;AACD,MAAA,MAAM,OAAA,GAAW,MAAM,QAAA,CAAS,IAAA,EAAK;AAGrC,MAAA,OAAO,OAAA,CAAQ,MAAA,EAAQ,KAAA,IAAS,EAAC;AAAA,IACnC,CAAA;AAEA,IAAA,IAAI,SAAA,GAAY,KAAA;AAChB,IAAA,KAAA,CAAM,YAAY;AAChB,MAAA,IAAI;AACF,QAAA,MAAM,aACJ,KAAA,CAAM,MAAA,KAAW,KAAK,QAAA,GAAW,MAAM,iBAAgB,GAAI,KAAA;AAC7D,QAAA,IAAI,SAAA,EAAW;AAEf,QAAA,MAAM,cAAc,CAAC,GAAG,QAAQ,UAAU,CAAA,EAAG,GAAG,KAAK,CAAA;AACrD,QAAA,IAAI,WAAA,CAAY,WAAW,CAAA,EAAG;AAE9B,QAAA,IAAI,OAAO,YAAA,CAAa,YAAA,KAAiB,UAAA,EAAY;AACnD,UAAA,KAAA,MAAW,cAAc,WAAA,EAAa;AACpC,YAAA,IAAI,SAAA,EAAW;AACf,YAAA,MAAM,aAAa,YAAA,CAAa,UAAA,EAAY,EAAE,MAAA,EAAQ,UAAA,CAAW,QAAQ,CAAA;AAAA,UAC3E;AAAA,QACF,CAAA,MAAA,IAAW,OAAO,YAAA,CAAa,cAAA,KAAmB,UAAA,EAAY;AAC5D,UAAA,MAAM,YAAA,CAAa,cAAA,CAAe,EAAE,KAAA,EAAO,aAAa,CAAA;AAAA,QAC1D;AAAA,MACF,SAAS,KAAA,EAAO;AAId,QAAA,IAAI,OAAA,CAAQ,GAAA,CAAI,QAAA,KAAa,YAAA,EAAc;AACzC,UAAA,OAAA,CAAQ,IAAA,CAAK,8CAA8C,KAAK,CAAA;AAAA,QAClE;AAAA,MACF;AAAA,IACF,CAAA,GAAG;AAEH,IAAA,OAAO,MAAM;AACX,MAAA,SAAA,GAAY,IAAA;AAGZ,MAAA,UAAA,CAAW,KAAA,EAAM;AAAA,IACnB,CAAA;AAAA,EACF,GAAG,CAAC,KAAA,EAAO,OAAO,UAAA,EAAY,QAAA,EAAU,QAAQ,CAAC,CAAA;AAEjD,EAAA,OAAO,IAAA;AACT","file":"client.js","sourcesContent":["'use client'\n\n/**\n * @sonordev/site-kit/mcp — WebMCP in-page tool registration\n *\n * The browser half of WebMCP (W3C Web Machine Learning CG). When an agent is\n * driving the page — a browser-integrated assistant, an extension, a\n * headless-Chrome operator — it does not fetch our `.well-known` card and open\n * a network connection. It looks for tools registered on the *document*.\n *\n * `document.modelContext.registerTool()` is the current shape in the explainer;\n * earlier drafts and some flagged builds put the same object on `navigator`,\n * and an even earlier one took a whole tool array via `provideContext()`. All\n * three are probed, because the spec is a live draft and a site that only\n * knows one shape silently exposes nothing in the others.\n *\n * ── Why the handlers are proxied ──────────────────────────────────────────\n * Tools are registered here as thin wrappers that POST `tools/call` to this\n * site's own MCP endpoint. That is deliberate:\n *\n *   - one implementation. The tool an agent calls in-page and the tool it\n *     calls over HTTP run the SAME server-side handler, so they cannot drift.\n *   - no secrets in the bundle. Handlers reach Sonor with `SONOR_API_KEY`.\n *     Registering real handlers client-side would drag that key into a\n *     `'use client'` graph, which is exactly how a raw `sonor_` key once ended\n *     up in a public chunk of an upforge build (see build-entries.ts).\n *\n * Tools that genuinely need live DOM state (reading what's on screen, filling\n * a form the user is looking at) are passed as `localTools` and run in-page.\n */\n\nimport { useEffect } from 'react'\nimport { useDeferredActivation } from '../shared/defer'\nimport type { JsonSchemaObject, McpToolResult } from './types'\n\n// ============================================\n// The WebMCP surface, as far as we rely on it\n// ============================================\n\ninterface WebMcpToolDefinition {\n  name: string\n  description: string\n  inputSchema: JsonSchemaObject\n  execute: (args: Record<string, unknown>) => Promise<McpToolResult>\n}\n\ninterface ModelContextLike {\n  registerTool?: (\n    tool: WebMcpToolDefinition,\n    options?: { signal?: AbortSignal },\n  ) => Promise<unknown> | unknown\n  provideContext?: (context: { tools: WebMcpToolDefinition[] }) => Promise<unknown> | unknown\n}\n\nfunction getModelContext(): ModelContextLike | null {\n  if (typeof window === 'undefined') return null\n  const doc = document as unknown as { modelContext?: ModelContextLike }\n  if (doc.modelContext) return doc.modelContext\n  const nav = navigator as unknown as { modelContext?: ModelContextLike }\n  return nav.modelContext ?? null\n}\n\n/** True when the visiting browser exposes WebMCP at all. */\nexport function isWebMcpAvailable(): boolean {\n  return getModelContext() !== null\n}\n\n// ============================================\n// Props\n// ============================================\n\n/** A tool as it crosses the server→client boundary: JSON, no functions. */\nexport interface WebMcpToolDescriptor {\n  name: string\n  title?: string\n  description: string\n  inputSchema: JsonSchemaObject\n}\n\nexport interface WebMcpLocalTool extends WebMcpToolDescriptor {\n  /** Runs in the browser. Use for DOM-aware tools only. */\n  execute: (args: Record<string, unknown>) => Promise<unknown> | unknown\n}\n\nexport interface WebMcpToolsProps {\n  /**\n   * Proxied tools — executed server-side via the MCP endpoint.\n   *\n   * Usually omit this. Passing descriptors from a server component sends the\n   * whole tool catalog through the RSC payload of EVERY page, costing every\n   * human visitor several KB for a capability only an agent uses. Leave it\n   * empty and the component fetches `tools/list` instead — but only after\n   * confirming the browser actually exposes WebMCP, so the fetch never\n   * happens for ordinary visitors. Pass descriptors only to pin a subset.\n   */\n  tools?: WebMcpToolDescriptor[]\n  /** Tools whose handler runs in the browser. */\n  localTools?: WebMcpLocalTool[]\n  /** MCP endpoint on this origin (default `/api/mcp`). */\n  endpoint?: string\n  /**\n   * Wait for the page to go quiet before registering (default true).\n   *\n   * Registration is not user-visible and must never compete with hydration.\n   * An agent arriving at the page polls or listens for `toolchange`, so a\n   * couple of hundred milliseconds costs nothing; a blocked LCP costs a lot.\n   */\n  defer?: boolean\n  /**\n   * Fetch the catalog from the endpoint's `tools/list` when no `tools` are\n   * passed (default true). The fetch is gated on WebMCP being present.\n   */\n  discover?: boolean\n}\n\n// ============================================\n// Component\n// ============================================\n\n/**\n * Register this site's MCP tools with the visiting browser's agent.\n *\n * Renders nothing. Mount it as a CHILDLESS sibling in the layout — never as a\n * wrapper around `{children}`, which would de-opt the whole route to client\n * rendering (the cardinal rule in the root CLAUDE.md).\n *\n * @example\n * ```tsx\n * // app/layout.tsx\n * <SiteKitLayout analytics={false}>{children}</SiteKitLayout>\n * <WebMcpTools tools={MCP_TOOL_DESCRIPTORS} />\n * ```\n */\nexport function WebMcpTools({\n  tools = [],\n  localTools = [],\n  endpoint = '/api/mcp',\n  defer = true,\n  discover = true,\n}: WebMcpToolsProps) {\n  const ready = useDeferredActivation(defer)\n\n  useEffect(() => {\n    if (!ready) return\n    // Gate EVERYTHING on WebMCP being present. A browser without it does no\n    // work and issues no request — which is every human visitor today.\n    const modelContext = getModelContext()\n    if (!modelContext) return\n\n    const controller = new AbortController()\n\n    const callRemote = async (\n      name: string,\n      args: Record<string, unknown>,\n    ): Promise<McpToolResult> => {\n      try {\n        const response = await fetch(endpoint, {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            Accept: 'application/json, text/event-stream',\n            'Mcp-Method': 'tools/call',\n            'Mcp-Name': name,\n          },\n          body: JSON.stringify({\n            jsonrpc: '2.0',\n            id: `webmcp-${name}`,\n            method: 'tools/call',\n            params: { name, arguments: args },\n          }),\n          signal: controller.signal,\n        })\n        const payload = (await response.json()) as {\n          result?: McpToolResult\n          error?: { message?: string }\n        }\n        if (payload.error) {\n          return {\n            content: [{ type: 'text', text: payload.error.message ?? 'Tool call failed.' }],\n            isError: true,\n          }\n        }\n        return payload.result ?? { content: [{ type: 'text', text: '(no result)' }] }\n      } catch (error) {\n        if (controller.signal.aborted) throw error\n        const detail = error instanceof Error ? error.message : String(error)\n        return { content: [{ type: 'text', text: `Tool call failed: ${detail}` }], isError: true }\n      }\n    }\n\n    const normalize = (value: unknown): McpToolResult => {\n      if (value && typeof value === 'object' && Array.isArray((value as McpToolResult).content)) {\n        return value as McpToolResult\n      }\n      return {\n        content: [\n          { type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) },\n        ],\n        structuredContent: value,\n      }\n    }\n\n    const proxied = (list: WebMcpToolDescriptor[]): WebMcpToolDefinition[] =>\n      list.map((tool) => ({\n        name: tool.name,\n        description: tool.description,\n        inputSchema: tool.inputSchema,\n        execute: (args: Record<string, unknown>) => callRemote(tool.name, args ?? {}),\n      }))\n\n    const local = localTools.map((tool) => ({\n      name: tool.name,\n      description: tool.description,\n      inputSchema: tool.inputSchema,\n      execute: async (args: Record<string, unknown>) => normalize(await tool.execute(args ?? {})),\n    }))\n\n    /** Ask our own endpoint what it serves, so the two can't disagree. */\n    const listRemoteTools = async (): Promise<WebMcpToolDescriptor[]> => {\n      const response = await fetch(endpoint, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n          Accept: 'application/json, text/event-stream',\n          'Mcp-Method': 'tools/list',\n        },\n        body: JSON.stringify({ jsonrpc: '2.0', id: 'webmcp-list', method: 'tools/list' }),\n        signal: controller.signal,\n      })\n      const payload = (await response.json()) as {\n        result?: { tools?: WebMcpToolDescriptor[] }\n      }\n      return payload.result?.tools ?? []\n    }\n\n    let cancelled = false\n    void (async () => {\n      try {\n        const discovered =\n          tools.length === 0 && discover ? await listRemoteTools() : tools\n        if (cancelled) return\n\n        const definitions = [...proxied(discovered), ...local]\n        if (definitions.length === 0) return\n\n        if (typeof modelContext.registerTool === 'function') {\n          for (const definition of definitions) {\n            if (cancelled) return\n            await modelContext.registerTool(definition, { signal: controller.signal })\n          }\n        } else if (typeof modelContext.provideContext === 'function') {\n          await modelContext.provideContext({ tools: definitions })\n        }\n      } catch (error) {\n        // A draft API that rejects is not a site error. Stay silent in\n        // production so a spec change never shows up as console noise on a\n        // marketing page.\n        if (process.env.NODE_ENV !== 'production') {\n          console.warn('[site-kit/mcp] WebMCP registration failed:', error)\n        }\n      }\n    })()\n\n    return () => {\n      cancelled = true\n      // Aborting the signal is how WebMCP unregisters — important on client\n      // navigation, or the previous page's tools linger on the document.\n      controller.abort()\n    }\n  }, [ready, tools, localTools, endpoint, discover])\n\n  return null\n}\n"]}

package/dist/mcp/client.mjs

@@ -0,0 +1,129 @@
+'use client';
+import { useDeferredActivation } from '../chunk-ZVBLXXNJ.mjs';
+import '../chunk-BEXTDHO4.mjs';
+import { useEffect } from 'react';
+
+function getModelContext() {
+  if (typeof window === "undefined") return null;
+  const doc = document;
+  if (doc.modelContext) return doc.modelContext;
+  const nav = navigator;
+  return nav.modelContext ?? null;
+}
+function isWebMcpAvailable() {
+  return getModelContext() !== null;
+}
+function WebMcpTools({
+  tools = [],
+  localTools = [],
+  endpoint = "/api/mcp",
+  defer = true,
+  discover = true
+}) {
+  const ready = useDeferredActivation(defer);
+  useEffect(() => {
+    if (!ready) return;
+    const modelContext = getModelContext();
+    if (!modelContext) return;
+    const controller = new AbortController();
+    const callRemote = async (name, args) => {
+      try {
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+            "Mcp-Method": "tools/call",
+            "Mcp-Name": name
+          },
+          body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: `webmcp-${name}`,
+            method: "tools/call",
+            params: { name, arguments: args }
+          }),
+          signal: controller.signal
+        });
+        const payload = await response.json();
+        if (payload.error) {
+          return {
+            content: [{ type: "text", text: payload.error.message ?? "Tool call failed." }],
+            isError: true
+          };
+        }
+        return payload.result ?? { content: [{ type: "text", text: "(no result)" }] };
+      } catch (error) {
+        if (controller.signal.aborted) throw error;
+        const detail = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: "text", text: `Tool call failed: ${detail}` }], isError: true };
+      }
+    };
+    const normalize = (value) => {
+      if (value && typeof value === "object" && Array.isArray(value.content)) {
+        return value;
+      }
+      return {
+        content: [
+          { type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }
+        ],
+        structuredContent: value
+      };
+    };
+    const proxied = (list) => list.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      execute: (args) => callRemote(tool.name, args ?? {})
+    }));
+    const local = localTools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      execute: async (args) => normalize(await tool.execute(args ?? {}))
+    }));
+    const listRemoteTools = async () => {
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json, text/event-stream",
+          "Mcp-Method": "tools/list"
+        },
+        body: JSON.stringify({ jsonrpc: "2.0", id: "webmcp-list", method: "tools/list" }),
+        signal: controller.signal
+      });
+      const payload = await response.json();
+      return payload.result?.tools ?? [];
+    };
+    let cancelled = false;
+    void (async () => {
+      try {
+        const discovered = tools.length === 0 && discover ? await listRemoteTools() : tools;
+        if (cancelled) return;
+        const definitions = [...proxied(discovered), ...local];
+        if (definitions.length === 0) return;
+        if (typeof modelContext.registerTool === "function") {
+          for (const definition of definitions) {
+            if (cancelled) return;
+            await modelContext.registerTool(definition, { signal: controller.signal });
+          }
+        } else if (typeof modelContext.provideContext === "function") {
+          await modelContext.provideContext({ tools: definitions });
+        }
+      } catch (error) {
+        if (process.env.NODE_ENV !== "production") {
+          console.warn("[site-kit/mcp] WebMCP registration failed:", error);
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+      controller.abort();
+    };
+  }, [ready, tools, localTools, endpoint, discover]);
+  return null;
+}
+
+export { WebMcpTools, isWebMcpAvailable };
+//# sourceMappingURL=client.mjs.map
+//# sourceMappingURL=client.mjs.map

package/dist/mcp/client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/mcp/WebMcpTools.tsx"],"names":[],"mappings":"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","file":"client.mjs","sourcesContent":["'use client'\n\n/**\n * @sonordev/site-kit/mcp — WebMCP in-page tool registration\n *\n * The browser half of WebMCP (W3C Web Machine Learning CG). When an agent is\n * driving the page — a browser-integrated assistant, an extension, a\n * headless-Chrome operator — it does not fetch our `.well-known` card and open\n * a network connection. It looks for tools registered on the *document*.\n *\n * `document.modelContext.registerTool()` is the current shape in the explainer;\n * earlier drafts and some flagged builds put the same object on `navigator`,\n * and an even earlier one took a whole tool array via `provideContext()`. All\n * three are probed, because the spec is a live draft and a site that only\n * knows one shape silently exposes nothing in the others.\n *\n * ── Why the handlers are proxied ──────────────────────────────────────────\n * Tools are registered here as thin wrappers that POST `tools/call` to this\n * site's own MCP endpoint. That is deliberate:\n *\n *   - one implementation. The tool an agent calls in-page and the tool it\n *     calls over HTTP run the SAME server-side handler, so they cannot drift.\n *   - no secrets in the bundle. Handlers reach Sonor with `SONOR_API_KEY`.\n *     Registering real handlers client-side would drag that key into a\n *     `'use client'` graph, which is exactly how a raw `sonor_` key once ended\n *     up in a public chunk of an upforge build (see build-entries.ts).\n *\n * Tools that genuinely need live DOM state (reading what's on screen, filling\n * a form the user is looking at) are passed as `localTools` and run in-page.\n */\n\nimport { useEffect } from 'react'\nimport { useDeferredActivation } from '../shared/defer'\nimport type { JsonSchemaObject, McpToolResult } from './types'\n\n// ============================================\n// The WebMCP surface, as far as we rely on it\n// ============================================\n\ninterface WebMcpToolDefinition {\n  name: string\n  description: string\n  inputSchema: JsonSchemaObject\n  execute: (args: Record<string, unknown>) => Promise<McpToolResult>\n}\n\ninterface ModelContextLike {\n  registerTool?: (\n    tool: WebMcpToolDefinition,\n    options?: { signal?: AbortSignal },\n  ) => Promise<unknown> | unknown\n  provideContext?: (context: { tools: WebMcpToolDefinition[] }) => Promise<unknown> | unknown\n}\n\nfunction getModelContext(): ModelContextLike | null {\n  if (typeof window === 'undefined') return null\n  const doc = document as unknown as { modelContext?: ModelContextLike }\n  if (doc.modelContext) return doc.modelContext\n  const nav = navigator as unknown as { modelContext?: ModelContextLike }\n  return nav.modelContext ?? null\n}\n\n/** True when the visiting browser exposes WebMCP at all. */\nexport function isWebMcpAvailable(): boolean {\n  return getModelContext() !== null\n}\n\n// ============================================\n// Props\n// ============================================\n\n/** A tool as it crosses the server→client boundary: JSON, no functions. */\nexport interface WebMcpToolDescriptor {\n  name: string\n  title?: string\n  description: string\n  inputSchema: JsonSchemaObject\n}\n\nexport interface WebMcpLocalTool extends WebMcpToolDescriptor {\n  /** Runs in the browser. Use for DOM-aware tools only. */\n  execute: (args: Record<string, unknown>) => Promise<unknown> | unknown\n}\n\nexport interface WebMcpToolsProps {\n  /**\n   * Proxied tools — executed server-side via the MCP endpoint.\n   *\n   * Usually omit this. Passing descriptors from a server component sends the\n   * whole tool catalog through the RSC payload of EVERY page, costing every\n   * human visitor several KB for a capability only an agent uses. Leave it\n   * empty and the component fetches `tools/list` instead — but only after\n   * confirming the browser actually exposes WebMCP, so the fetch never\n   * happens for ordinary visitors. Pass descriptors only to pin a subset.\n   */\n  tools?: WebMcpToolDescriptor[]\n  /** Tools whose handler runs in the browser. */\n  localTools?: WebMcpLocalTool[]\n  /** MCP endpoint on this origin (default `/api/mcp`). */\n  endpoint?: string\n  /**\n   * Wait for the page to go quiet before registering (default true).\n   *\n   * Registration is not user-visible and must never compete with hydration.\n   * An agent arriving at the page polls or listens for `toolchange`, so a\n   * couple of hundred milliseconds costs nothing; a blocked LCP costs a lot.\n   */\n  defer?: boolean\n  /**\n   * Fetch the catalog from the endpoint's `tools/list` when no `tools` are\n   * passed (default true). The fetch is gated on WebMCP being present.\n   */\n  discover?: boolean\n}\n\n// ============================================\n// Component\n// ============================================\n\n/**\n * Register this site's MCP tools with the visiting browser's agent.\n *\n * Renders nothing. Mount it as a CHILDLESS sibling in the layout — never as a\n * wrapper around `{children}`, which would de-opt the whole route to client\n * rendering (the cardinal rule in the root CLAUDE.md).\n *\n * @example\n * ```tsx\n * // app/layout.tsx\n * <SiteKitLayout analytics={false}>{children}</SiteKitLayout>\n * <WebMcpTools tools={MCP_TOOL_DESCRIPTORS} />\n * ```\n */\nexport function WebMcpTools({\n  tools = [],\n  localTools = [],\n  endpoint = '/api/mcp',\n  defer = true,\n  discover = true,\n}: WebMcpToolsProps) {\n  const ready = useDeferredActivation(defer)\n\n  useEffect(() => {\n    if (!ready) return\n    // Gate EVERYTHING on WebMCP being present. A browser without it does no\n    // work and issues no request — which is every human visitor today.\n    const modelContext = getModelContext()\n    if (!modelContext) return\n\n    const controller = new AbortController()\n\n    const callRemote = async (\n      name: string,\n      args: Record<string, unknown>,\n    ): Promise<McpToolResult> => {\n      try {\n        const response = await fetch(endpoint, {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            Accept: 'application/json, text/event-stream',\n            'Mcp-Method': 'tools/call',\n            'Mcp-Name': name,\n          },\n          body: JSON.stringify({\n            jsonrpc: '2.0',\n            id: `webmcp-${name}`,\n            method: 'tools/call',\n            params: { name, arguments: args },\n          }),\n          signal: controller.signal,\n        })\n        const payload = (await response.json()) as {\n          result?: McpToolResult\n          error?: { message?: string }\n        }\n        if (payload.error) {\n          return {\n            content: [{ type: 'text', text: payload.error.message ?? 'Tool call failed.' }],\n            isError: true,\n          }\n        }\n        return payload.result ?? { content: [{ type: 'text', text: '(no result)' }] }\n      } catch (error) {\n        if (controller.signal.aborted) throw error\n        const detail = error instanceof Error ? error.message : String(error)\n        return { content: [{ type: 'text', text: `Tool call failed: ${detail}` }], isError: true }\n      }\n    }\n\n    const normalize = (value: unknown): McpToolResult => {\n      if (value && typeof value === 'object' && Array.isArray((value as McpToolResult).content)) {\n        return value as McpToolResult\n      }\n      return {\n        content: [\n          { type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) },\n        ],\n        structuredContent: value,\n      }\n    }\n\n    const proxied = (list: WebMcpToolDescriptor[]): WebMcpToolDefinition[] =>\n      list.map((tool) => ({\n        name: tool.name,\n        description: tool.description,\n        inputSchema: tool.inputSchema,\n        execute: (args: Record<string, unknown>) => callRemote(tool.name, args ?? {}),\n      }))\n\n    const local = localTools.map((tool) => ({\n      name: tool.name,\n      description: tool.description,\n      inputSchema: tool.inputSchema,\n      execute: async (args: Record<string, unknown>) => normalize(await tool.execute(args ?? {})),\n    }))\n\n    /** Ask our own endpoint what it serves, so the two can't disagree. */\n    const listRemoteTools = async (): Promise<WebMcpToolDescriptor[]> => {\n      const response = await fetch(endpoint, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n          Accept: 'application/json, text/event-stream',\n          'Mcp-Method': 'tools/list',\n        },\n        body: JSON.stringify({ jsonrpc: '2.0', id: 'webmcp-list', method: 'tools/list' }),\n        signal: controller.signal,\n      })\n      const payload = (await response.json()) as {\n        result?: { tools?: WebMcpToolDescriptor[] }\n      }\n      return payload.result?.tools ?? []\n    }\n\n    let cancelled = false\n    void (async () => {\n      try {\n        const discovered =\n          tools.length === 0 && discover ? await listRemoteTools() : tools\n        if (cancelled) return\n\n        const definitions = [...proxied(discovered), ...local]\n        if (definitions.length === 0) return\n\n        if (typeof modelContext.registerTool === 'function') {\n          for (const definition of definitions) {\n            if (cancelled) return\n            await modelContext.registerTool(definition, { signal: controller.signal })\n          }\n        } else if (typeof modelContext.provideContext === 'function') {\n          await modelContext.provideContext({ tools: definitions })\n        }\n      } catch (error) {\n        // A draft API that rejects is not a site error. Stay silent in\n        // production so a spec change never shows up as console noise on a\n        // marketing page.\n        if (process.env.NODE_ENV !== 'production') {\n          console.warn('[site-kit/mcp] WebMCP registration failed:', error)\n        }\n      }\n    })()\n\n    return () => {\n      cancelled = true\n      // Aborting the signal is how WebMCP unregisters — important on client\n      // navigation, or the previous page's tools linger on the document.\n      controller.abort()\n    }\n  }, [ready, tools, localTools, endpoint, discover])\n\n  return null\n}\n"]}

package/dist/mcp/declarative.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @sonordev/site-kit/mcp — declarative WebMCP (forms as tools)
+ *
+ * The half of WebMCP that needs no JavaScript. A `<form>` carrying `toolname`
+ * and `tooldescription` IS an agent tool: the browser synthesizes the input
+ * schema from the form controls, and the agent fills and submits the real
+ * form the human would have used.
+ *
+ * This matters more than the imperative API for one reason — there is exactly
+ * one code path. The agent submits the same form, hits the same validation,
+ * files the same CRM record. Nothing can drift, because there is nothing to
+ * drift from.
+ *
+ * Attributes (per the W3C declarative-api explainer):
+ *   toolname               on <form>     — the tool's machine name
+ *   tooldescription        on <form>     — what it does
+ *   toolautosubmit         on <form>     — submit without waiting for the human
+ *   toolparamdescription   on a control  — describes that field in the schema
+ *
+ * These are plain HTML attributes; React 19 passes unknown lowercase
+ * attributes straight through to the DOM, so the returned objects spread
+ * directly onto JSX.
+ */
+export interface DeclarativeToolFormOptions {
+    /** Machine name, `snake_case`. Match the remote tool it mirrors. */
+    name: string;
+    /** What submitting this form accomplishes, in one sentence. */
+    description: string;
+    /**
+     * Let an agent submit without a human confirming.
+     *
+     * Default false, and leave it false for anything that creates a record,
+     * sends a message, or spends money. A booking request or an audit request
+     * should be something the person watching agrees to — `toolautosubmit` on a
+     * lead form is how an agent files fifty of them by accident.
+     */
+    autoSubmit?: boolean;
+}
+export interface DeclarativeToolFormAttributes {
+    toolname: string;
+    tooldescription: string;
+    toolautosubmit?: string;
+}
+/**
+ * Attributes that turn a `<form>` into an agent-callable tool.
+ *
+ * @example
+ * ```tsx
+ * <form {...declarativeToolForm({
+ *   name: 'request_site_audit',
+ *   description: 'Request a free technical SEO and performance audit of a website.',
+ * })} action="/api/audit" method="post">
+ * ```
+ */
+export declare function declarativeToolForm(options: DeclarativeToolFormOptions): DeclarativeToolFormAttributes;
+export interface DeclarativeToolFieldAttributes {
+    toolparamdescription: string;
+}
+/**
+ * Describe one form control for the synthesized input schema.
+ *
+ * The control's `name` becomes the schema property and `required` marks it
+ * required, so this only supplies the prose — but the prose is what the model
+ * reads to decide what to put in the field.
+ *
+ * @example
+ * ```tsx
+ * <input
+ *   type="url"
+ *   name="url"
+ *   required
+ *   {...declarativeToolField('The full URL of the website to audit, including https://')}
+ * />
+ * ```
+ */
+export declare function declarativeToolField(description: string): DeclarativeToolFieldAttributes;
+//# sourceMappingURL=declarative.d.ts.map

package/dist/mcp/declarative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declarative.d.ts","sourceRoot":"","sources":["../../src/mcp/declarative.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,0BAA0B;IACzC,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,MAAM,CAAA;IAChB,eAAe,EAAE,MAAM,CAAA;IACvB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,6BAA6B,CAS/B;AAED,MAAM,WAAW,8BAA8B;IAC7C,oBAAoB,EAAE,MAAM,CAAA;CAC7B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,8BAA8B,CAExF"}

package/dist/mcp/handlers.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @sonordev/site-kit/mcp — Next.js route handlers (Streamable HTTP + card)
+ *
+ * Two things get mounted on a site:
+ *
+ *   app/api/mcp/route.ts                  → createMcpHandler({ server })
+ *   app/.well-known/mcp-server-card/...   → createMcpServerCardHandler({ ... })
+ *   app/.well-known/mcp.json/route.ts     → the same handler (legacy path)
+ *
+ * The endpoint is stateless. Every request is self-describing, nothing is
+ * cached between calls, and no session is minted — which is exactly what the
+ * 2026-07-28 revision asks for and also the only thing that works on a
+ * serverless host where consecutive requests hit different instances.
+ */
+import { MCP_SUPPORTED_PROTOCOL_VERSIONS, type McpServerDefinition } from './protocol';
+import { type BuildMcpServerCardOptions } from './serverCard';
+/**
+ * Undo the spec's Base64 sentinel wrapper: `=?base64?{b64}?=`.
+ * Values that aren't wrapped come back untouched.
+ */
+export declare function decodeHeaderValue(value: string | null): string | null;
+export interface McpHandlerOptions {
+    server: McpServerDefinition;
+    /** Absolute site origin, passed to every tool handler as context. */
+    baseUrl?: string;
+    /**
+     * Origins allowed to call the endpoint from a browser. Defaults to `*`.
+     *
+     * A public marketing MCP server is meant to be called by anyone's agent and
+     * serves only data that is already on the public site, so the wildcard is
+     * the correct setting, not a lapse. The DNS-rebinding attack the spec's
+     * Origin rule defends against is about *localhost* servers, where the
+     * browser can reach a private origin the attacker otherwise couldn't.
+     * Set this explicitly for any endpoint that gains auth or writes.
+     */
+    allowedOrigins?: string[] | '*';
+    /** Reject modern requests missing the mirror headers. See DispatchOptions. */
+    strictHeaders?: boolean;
+}
+export interface McpRouteHandlers {
+    POST: (request: Request) => Promise<Response>;
+    GET: (request: Request) => Promise<Response>;
+    DELETE: (request: Request) => Promise<Response>;
+    OPTIONS: (request: Request) => Promise<Response>;
+}
+/**
+ * Create the Streamable HTTP MCP endpoint.
+ *
+ * @example
+ * ```ts
+ * // app/api/mcp/route.ts
+ * import { createMcpHandler } from '@sonordev/site-kit/mcp'
+ * import { mcpServer } from '@/lib/mcp/server'
+ *
+ * export const { POST, GET, DELETE, OPTIONS } = createMcpHandler({ server: mcpServer })
+ * export const dynamic = 'force-dynamic'
+ * ```
+ */
+export declare function createMcpHandler(options: McpHandlerOptions): McpRouteHandlers;
+export interface McpServerCardHandlerOptions extends BuildMcpServerCardOptions {
+    /** Seconds for `Cache-Control: public, max-age=…` (default 3600). */
+    maxAge?: number;
+}
+export interface McpServerCardRouteHandlers {
+    GET: () => Promise<Response>;
+    OPTIONS: () => Promise<Response>;
+}
+/**
+ * Serve the SEP-2127 server card. Mount at BOTH well-known paths.
+ *
+ * The handler never reads the incoming Request, so the route stays statically
+ * prerenderable — the same constraint the llms.txt handlers document, and for
+ * the same reason: touching `request.headers` opts the route into dynamic
+ * rendering and it stops being served from the CDN.
+ *
+ * @example
+ * ```ts
+ * // app/.well-known/mcp-server-card/route.ts
+ * import { createMcpServerCardHandler } from '@sonordev/site-kit/mcp'
+ * import { mcpServer, SITE_URL } from '@/lib/mcp/server'
+ *
+ * export const { GET, OPTIONS } = createMcpServerCardHandler({
+ *   info: mcpServer.info,
+ *   tools: mcpServer.tools,
+ *   baseUrl: SITE_URL,
+ * })
+ * export const revalidate = 3600
+ * ```
+ */
+export declare function createMcpServerCardHandler(options: McpServerCardHandlerOptions): McpServerCardRouteHandlers;
+export { MCP_SUPPORTED_PROTOCOL_VERSIONS };
+//# sourceMappingURL=handlers.d.ts.map

package/dist/mcp/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/mcp/handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAKL,+BAA+B,EAG/B,KAAK,mBAAmB,EACzB,MAAM,YAAY,CAAA;AACnB,OAAO,EAEL,KAAK,yBAAyB,EAE/B,MAAM,cAAc,CAAA;AAoCrB;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAcrE;AAMD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,mBAAmB,CAAA;IAC3B,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAA;IAC/B,8EAA8E;IAC9E,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC7C,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC5C,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC/C,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CACjD;AAoBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CA8G7E;AAMD,MAAM,WAAW,2BAA4B,SAAQ,yBAAyB;IAC5E,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,0BAA0B;IACzC,GAAG,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC5B,OAAO,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,GACnC,0BAA0B,CAkB5B;AAED,OAAO,EAAE,+BAA+B,EAAE,CAAA"}

package/dist/mcp/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @sonordev/site-kit/mcp — Main entry point
+ *
+ * WebMCP + Model Context Protocol for marketing sites: make a site something
+ * an AI agent can *use*, not just read.
+ *
+ * Three surfaces, one tool definition:
+ *
+ *   1. Remote MCP endpoint — `createMcpHandler`. Streamable HTTP, dual-era
+ *      (2026-07-28 modern + the `initialize` handshake older clients speak).
+ *   2. Discovery — `createMcpServerCardHandler`, the SEP-2127 card served at
+ *      `/.well-known/mcp-server-card` and `/.well-known/mcp.json`.
+ *   3. In-page WebMCP — `<WebMcpTools>` (imperative) and
+ *      `declarativeToolForm` (declarative), for browser-driving agents.
+ *
+ * @see https://modelcontextprotocol.io/specification/2026-07-28
+ * @see https://github.com/webmachinelearning/webmcp
+ */
+export type { JsonSchemaNode, JsonSchemaObject, McpContent, McpTextContent, McpResourceLinkContent, McpToolResult, McpToolHandlerResult, McpToolAnnotations, McpToolContext, McpToolHandler, SiteKitMcpTool, McpServerInfo, McpServerIcon, } from './types';
+export { defineMcpTool } from './types';
+export { MCP_PROTOCOL_VERSION_MODERN, MCP_PROTOCOL_VERSIONS_LEGACY, MCP_SUPPORTED_PROTOCOL_VERSIONS, META_PROTOCOL_VERSION, META_CLIENT_INFO, META_SERVER_INFO, MCP_ERROR_HEADER_MISMATCH, MCP_ERROR_UNSUPPORTED_PROTOCOL_VERSION, JSONRPC_METHOD_NOT_FOUND, dispatch, toToolResult, toolErrorResult, toToolDescriptor, validateArgs, isSupportedVersion, } from './protocol';
+export type { JsonRpcRequest, JsonRpcResponse, JsonRpcError, DispatchOutcome, DispatchOptions, McpServerDefinition, McpToolDescriptor, } from './protocol';
+export { buildMcpServerCard, validateMcpServerCard, MCP_SERVER_CARD_SCHEMA, MCP_SERVER_CARD_PATH, MCP_SERVER_CARD_LEGACY_PATH, SITE_KIT_CARD_META_KEY, } from './serverCard';
+export type { McpServerCard, McpRemote, BuildMcpServerCardOptions, } from './serverCard';
+export { createMcpHandler, createMcpServerCardHandler, decodeHeaderValue, } from './handlers';
+export type { McpHandlerOptions, McpRouteHandlers, McpServerCardHandlerOptions, McpServerCardRouteHandlers, } from './handlers';
+export { declarativeToolForm, declarativeToolField } from './declarative';
+export type { DeclarativeToolFormOptions, DeclarativeToolFormAttributes, DeclarativeToolFieldAttributes, } from './declarative';
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,cAAc,EACd,aAAa,EACb,aAAa,GACd,MAAM,SAAS,CAAA;AAEhB,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAKvC,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC5B,+BAA+B,EAC/B,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,yBAAyB,EACzB,sCAAsC,EACtC,wBAAwB,EACxB,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,GACnB,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,cAAc,EACd,eAAe,EACf,YAAY,EACZ,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,YAAY,CAAA;AAKnB,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,2BAA2B,EAC3B,sBAAsB,GACvB,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,aAAa,EACb,SAAS,EACT,yBAAyB,GAC1B,MAAM,cAAc,CAAA;AAKrB,OAAO,EACL,gBAAgB,EAChB,0BAA0B,EAC1B,iBAAiB,GAClB,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,YAAY,CAAA;AAKnB,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACzE,YAAY,EACV,0BAA0B,EAC1B,6BAA6B,EAC7B,8BAA8B,GAC/B,MAAM,eAAe,CAAA"}