@agent-surface/webmcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wiseair S.r.l.
+
+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

@@ -0,0 +1,30 @@
+# @agent-surface/webmcp
+
+> **Experimental.** The WebMCP (`navigator.modelContext`) surface area, permission model, and lifecycle are unstable; this adapter tracks them and absorbs the drift so nothing WebMCP-shaped leaks into `@agent-surface/core`. The application model stays in agent-surface — WebMCP is strictly transport/discovery.
+
+WebMCP transport adapter for [agent-surface](https://github.com/Wiseair-srl/agent-surface): one wire-named tool per **available** capability, re-provided on every `surface-changed`. Unavailable capabilities are not registered (WebMCP has no disabled state today — the availability reason is lost on this transport; accepted limitation). The user agent is treated as the least-trusted consumer: scope the adapter and keep two-phase confirmations.
+
+Docs: https://agent-surface-docs.vercel.app
+
+## Install
+
+```bash
+pnpm add @agent-surface/core @agent-surface/webmcp
+```
+
+## Use
+
+```ts
+import { createWebMcpAdapter } from "@agent-surface/webmcp";
+
+const adapter = createWebMcpAdapter({
+  snapshotContext: { scope: ["devices"] }, // least-trusted peer: scope it
+});
+adapter.start({ registry, consumer: { id: "browser-agent", kind: "webmcp" } });
+```
+
+If `navigator.modelContext` is absent, `start()` resolves and does nothing (feature-detect, never polyfill). Capability errors ride in tool content with `code`/`retry`/`details` preserved — never protocol-level errors.
+
+Full specification: [docs/09](https://github.com/Wiseair-srl/agent-surface/blob/main/docs/09-adapters.md).
+
+MIT © Wiseair S.r.l.

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import { AgentSurfaceRegistry, AgentConsumer, SnapshotContext, AgentCapabilityDescriptorUnion, JsonSchema, JsonValue } from '@agent-surface/core';
+
+interface AdapterHost {
+    registry: AgentSurfaceRegistry;
+    consumer: AgentConsumer;
+    /** Adapter-scoped snapshot defaults (scope, budget). */
+    snapshotContext?: Omit<SnapshotContext, "consumer">;
+}
+interface AgentSurfaceAdapter {
+    readonly name: string;
+    start(host: AdapterHost): void | Promise<void>;
+    stop(): void | Promise<void>;
+}
+interface WebMcpToolInit {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    execute(input: JsonValue): Promise<WebMcpToolResult>;
+}
+interface WebMcpToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+interface WebMcpModelContext {
+    provideContext(context: {
+        tools: WebMcpToolInit[];
+    }): void;
+}
+interface CreateWebMcpAdapterOptions {
+    snapshotContext?: Omit<SnapshotContext, "consumer">;
+    /**
+     * Map/curate before exposing; return null to skip a capability, undefined
+     * to keep the default mapping.
+     */
+    exposeCapability?: (descriptor: AgentCapabilityDescriptorUnion) => WebMcpToolInit | null | undefined;
+    /** Test seam: defaults to (navigator as any).modelContext. */
+    modelContext?: WebMcpModelContext;
+}
+/**
+ * Maps the registry onto `navigator.modelContext`, treating WebMCP strictly
+ * as transport/discovery: one wire-named tool per AVAILABLE capability,
+ * re-provided on every surface-changed; unavailable capabilities are not
+ * registered (WebMCP has no disabled state today — accepted limitation);
+ * confirmations stay two-phase; absent modelContext ⇒ start() does nothing.
+ */
+declare function createWebMcpAdapter(options?: CreateWebMcpAdapterOptions): AgentSurfaceAdapter;
+
+export { type AdapterHost, type AgentSurfaceAdapter, type CreateWebMcpAdapterOptions, type WebMcpModelContext, type WebMcpToolInit, type WebMcpToolResult, createWebMcpAdapter };

package/dist/index.js

@@ -0,0 +1,108 @@
+// src/core-facade.ts
+import { encodeWireName, encodeWireNameForInstance } from "@agent-surface/core";
+function randomInvocationId() {
+  return `inv_${Math.random().toString(36).slice(2, 14)}`;
+}
+
+// src/index.ts
+function createWebMcpAdapter(options) {
+  let unsubscribe;
+  return {
+    name: "webmcp",
+    start(host) {
+      const modelContext = options?.modelContext ?? globalThis.navigator?.modelContext;
+      if (!modelContext) return;
+      const provide = () => {
+        const snapshot = host.registry.snapshot({
+          consumer: host.consumer,
+          ...options?.snapshotContext ?? host.snapshotContext ?? {},
+          includeUnavailable: false
+        });
+        const tools = [];
+        const toTool = (descriptor, capabilityId, registrationId, inputSchema, description) => ({
+          name: encodeWireName(capabilityId),
+          description,
+          inputSchema,
+          execute: async (input) => {
+            const result = await host.registry.invoke(
+              {
+                invocationId: randomInvocationId(),
+                capabilityId,
+                registrationId,
+                surfaceVersion: snapshot.surfaceVersion,
+                ...input !== void 0 && Object.keys(input).length > 0 ? { input } : {}
+              },
+              { consumer: host.consumer }
+            );
+            if (result.status === "ok") {
+              return {
+                content: [{ type: "text", text: JSON.stringify(result.output ?? null) }]
+              };
+            }
+            return {
+              content: [{ type: "text", text: JSON.stringify(result.error) }],
+              isError: true
+            };
+          }
+        });
+        for (const component of snapshot.components) {
+          for (const obs of component.observations) {
+            if (!obs.available) continue;
+            const curated = options?.exposeCapability?.(obs);
+            if (options?.exposeCapability && curated === null) continue;
+            tools.push(
+              curated ?? toTool(
+                obs,
+                obs.capabilityId,
+                component.registrationId,
+                { type: "object", properties: {}, additionalProperties: false },
+                `[view \xB7 read] ${obs.description}`
+              )
+            );
+          }
+          for (const act of component.actions) {
+            if (!act.available) continue;
+            const curated = options?.exposeCapability?.(act);
+            if (options?.exposeCapability && curated === null) continue;
+            tools.push(
+              curated ?? toTool(
+                act,
+                act.capabilityId,
+                component.registrationId,
+                act.inputSchema,
+                `[view \xB7 ${act.effect}] ${act.description}`
+              )
+            );
+          }
+        }
+        for (const proc of snapshot.procedures) {
+          if (!proc.available) continue;
+          const curated = options?.exposeCapability?.(proc);
+          if (options?.exposeCapability && curated === null) continue;
+          tools.push(
+            curated ?? toTool(
+              proc,
+              proc.procedureId,
+              proc.registrationId,
+              proc.inputSchema,
+              `[domain \xB7 ${proc.effect}${proc.confirmation === "required" ? " \xB7 requires confirmation" : ""}] ${proc.description}`
+            )
+          );
+        }
+        modelContext.provideContext({ tools });
+      };
+      provide();
+      unsubscribe = host.registry.subscribe((event) => {
+        if (event.type === "surface-changed") provide();
+      });
+    },
+    stop() {
+      unsubscribe?.();
+      unsubscribe = void 0;
+    }
+  };
+}
+export {
+  createWebMcpAdapter
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core-facade.ts","../src/index.ts"],"sourcesContent":["export { encodeWireName, encodeWireNameForInstance } from \"@agent-surface/core\";\nexport type {\n  AgentCapabilityDescriptorUnion,\n  AgentConsumer,\n  AgentSurfaceRegistry,\n  JsonSchema,\n  JsonValue,\n  SnapshotContext,\n} from \"@agent-surface/core\";\n\nexport function randomInvocationId(): string {\n  return `inv_${Math.random().toString(36).slice(2, 14)}`;\n}\n","import {\n  encodeWireName,\n  randomInvocationId,\n  type AgentCapabilityDescriptorUnion,\n  type AgentConsumer,\n  type AgentSurfaceRegistry,\n  type JsonSchema,\n  type JsonValue,\n  type SnapshotContext,\n} from \"./core-facade.js\";\n\n/* ───────────────────────── adapter contract (docs/09) ───────────────────────── */\n\nexport interface AdapterHost {\n  registry: AgentSurfaceRegistry;\n  consumer: AgentConsumer; // identity this adapter acts as\n  /** Adapter-scoped snapshot defaults (scope, budget). */\n  snapshotContext?: Omit<SnapshotContext, \"consumer\">;\n}\n\nexport interface AgentSurfaceAdapter {\n  readonly name: string;\n  start(host: AdapterHost): void | Promise<void>;\n  stop(): void | Promise<void>;\n}\n\n/* ───────────── assumed navigator.modelContext shape (Experimental) ─────────────\n * The WebMCP surface area is unstable (OQ-2); this module encodes the current\n * assumption and absorbs drift so nothing WebMCP-shaped leaks into core.\n */\n\nexport interface WebMcpToolInit {\n  name: string;\n  description: string;\n  inputSchema: JsonSchema;\n  execute(input: JsonValue): Promise<WebMcpToolResult>;\n}\n\nexport interface WebMcpToolResult {\n  content: Array<{ type: \"text\"; text: string }>;\n  isError?: boolean;\n}\n\nexport interface WebMcpModelContext {\n  provideContext(context: { tools: WebMcpToolInit[] }): void;\n}\n\nexport interface CreateWebMcpAdapterOptions {\n  snapshotContext?: Omit<SnapshotContext, \"consumer\">;\n  /**\n   * Map/curate before exposing; return null to skip a capability, undefined\n   * to keep the default mapping.\n   */\n  exposeCapability?: (\n    descriptor: AgentCapabilityDescriptorUnion,\n  ) => WebMcpToolInit | null | undefined;\n  /** Test seam: defaults to (navigator as any).modelContext. */\n  modelContext?: WebMcpModelContext;\n}\n\n/**\n * Maps the registry onto `navigator.modelContext`, treating WebMCP strictly\n * as transport/discovery: one wire-named tool per AVAILABLE capability,\n * re-provided on every surface-changed; unavailable capabilities are not\n * registered (WebMCP has no disabled state today — accepted limitation);\n * confirmations stay two-phase; absent modelContext ⇒ start() does nothing.\n */\nexport function createWebMcpAdapter(options?: CreateWebMcpAdapterOptions): AgentSurfaceAdapter {\n  let unsubscribe: (() => void) | undefined;\n\n  return {\n    name: \"webmcp\",\n\n    start(host: AdapterHost): void {\n      const modelContext =\n        options?.modelContext ??\n        (globalThis as { navigator?: { modelContext?: WebMcpModelContext } }).navigator\n          ?.modelContext;\n      if (!modelContext) return; // feature-detect, never polyfill\n\n      const provide = (): void => {\n        const snapshot = host.registry.snapshot({\n          consumer: host.consumer,\n          ...(options?.snapshotContext ?? host.snapshotContext ?? {}),\n          includeUnavailable: false,\n        });\n\n        const tools: WebMcpToolInit[] = [];\n\n        const toTool = (\n          descriptor: AgentCapabilityDescriptorUnion,\n          capabilityId: string,\n          registrationId: string,\n          inputSchema: JsonSchema,\n          description: string,\n        ): WebMcpToolInit => ({\n          name: encodeWireName(capabilityId),\n          description,\n          inputSchema,\n          execute: async (input: JsonValue): Promise<WebMcpToolResult> => {\n            const result = await host.registry.invoke(\n              {\n                invocationId: randomInvocationId(),\n                capabilityId,\n                registrationId,\n                surfaceVersion: snapshot.surfaceVersion,\n                ...(input !== undefined && Object.keys(input as object).length > 0\n                  ? { input }\n                  : {}),\n              },\n              { consumer: host.consumer },\n            );\n            // Capability errors ride in tool CONTENT, never protocol errors\n            // (docs/07 adapter mapping): code/retry/details preserved.\n            if (result.status === \"ok\") {\n              return {\n                content: [{ type: \"text\", text: JSON.stringify(result.output ?? null) }],\n              };\n            }\n            return {\n              content: [{ type: \"text\", text: JSON.stringify(result.error) }],\n              isError: true,\n            };\n          },\n        });\n\n        for (const component of snapshot.components) {\n          for (const obs of component.observations) {\n            if (!obs.available) continue;\n            const curated = options?.exposeCapability?.(obs);\n            if (options?.exposeCapability && curated === null) continue;\n            tools.push(\n              curated ??\n                toTool(\n                  obs,\n                  obs.capabilityId,\n                  component.registrationId,\n                  { type: \"object\", properties: {}, additionalProperties: false },\n                  `[view · read] ${obs.description}`,\n                ),\n            );\n          }\n          for (const act of component.actions) {\n            if (!act.available) continue;\n            const curated = options?.exposeCapability?.(act);\n            if (options?.exposeCapability && curated === null) continue;\n            tools.push(\n              curated ??\n                toTool(\n                  act,\n                  act.capabilityId,\n                  component.registrationId,\n                  act.inputSchema,\n                  `[view · ${act.effect}] ${act.description}`,\n                ),\n            );\n          }\n        }\n        for (const proc of snapshot.procedures) {\n          if (!proc.available) continue;\n          const curated = options?.exposeCapability?.(proc);\n          if (options?.exposeCapability && curated === null) continue;\n          tools.push(\n            curated ??\n              toTool(\n                proc,\n                proc.procedureId,\n                proc.registrationId,\n                proc.inputSchema,\n                `[domain · ${proc.effect}${proc.confirmation === \"required\" ? \" · requires confirmation\" : \"\"}] ${proc.description}`,\n              ),\n          );\n        }\n\n        modelContext.provideContext({ tools });\n      };\n\n      provide();\n      unsubscribe = host.registry.subscribe((event) => {\n        if (event.type === \"surface-changed\") provide();\n      });\n    },\n\n    stop(): void {\n      unsubscribe?.();\n      unsubscribe = undefined;\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@agent-surface/webmcp",
+  "version": "0.1.0",
+  "description": "[Experimental] WebMCP (navigator.modelContext) transport adapter for agent-surface",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@agent-surface/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "zod": "^4.1.5",
+    "@agent-surface/testing": "0.1.0"
+  },
+  "author": "Paolo Barbato",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Wiseair-srl/agent-surface.git",
+    "directory": "packages/webmcp"
+  },
+  "homepage": "https://agent-surface-docs.vercel.app",
+  "bugs": {
+    "url": "https://github.com/Wiseair-srl/agent-surface/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "agent-surface",
+    "agent",
+    "ai",
+    "llm",
+    "frontend",
+    "capabilities",
+    "typescript",
+    "webmcp",
+    "mcp",
+    "modelcontext"
+  ],
+  "size-limit": [
+    {
+      "path": "dist/index.js",
+      "limit": "4 kB",
+      "ignore": [
+        "@agent-surface/core"
+      ]
+    }
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "size": "size-limit"
+  }
+}