@webmcpui/webmcp 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gary Pfaff (Pfaff Digital)
+
+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,56 @@
+# @webmcpui/webmcp
+
+The imperative [WebMCP](https://webmcpui.com/docs/webmcp) exposure layer, on its
+own — zero dependencies, Lit-free, ~2 kB. Register tools with a page's
+`document.modelContext` host without taking a dependency on the
+[`@webmcpui/core`](https://www.npmjs.com/package/@webmcpui/core) component
+library (which builds on this package).
+
+Everything is additive and feature-detected: WebMCP ships only behind a Chrome
+origin trial today, so on pages with no agent host every call is a safe no-op.
+The package prefers the canonical `document.modelContext` and falls back to the
+deprecated `navigator.modelContext`.
+
+## Install
+
+```bash
+pnpm add @webmcpui/webmcp
+```
+
+## Use
+
+```ts
+import { exposeTool, isWebMCPAvailable } from '@webmcpui/webmcp';
+
+const dispose = exposeTool({
+  name: 'book_appointment',
+  description: 'Book the currently selected appointment slot.',
+  inputSchema: {
+    type: 'object',
+    properties: { slot: { type: 'string' } },
+    required: ['slot'],
+  },
+  async execute(args) {
+    const slot = String(args.slot);
+    const ok = await book(slot);
+    return {
+      content: [{ type: 'text', text: ok ? `Booked ${slot}.` : 'Slot taken.' }],
+      isError: !ok,
+    };
+  },
+});
+
+// Later — unregister the tool:
+dispose();
+```
+
+## API
+
+- **`exposeTool(definition): ToolDisposer`** — registers a tool with the page's
+  WebMCP host (no-op returning a no-op disposer when none is present). Warns in
+  dev on duplicate tool names.
+- **`isWebMCPAvailable(): boolean`** — whether a WebMCP host exists on this page.
+- **Types** — `WebMCPToolDefinition`, `WebMCPToolResult`,
+  `WebMCPToolResultContent`, `JSONSchema`, `ToolDisposer`.
+
+Part of [webmcpui](https://webmcpui.com). MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The imperative WebMCP exposure layer.
+ *
+ * WebMCP is an imperative API: `document.modelContext.registerTool(...)`. The
+ * surface is still churning — `document.modelContext` is canonical as of the
+ * Chrome 149+ origin trial, and `navigator.modelContext` is the original
+ * location, deprecated in Chrome 150 — so we feature-detect both and prefer
+ * `document`. As of mid-2026 it ships only behind the origin trial and is
+ * undefined for almost everyone, with no mainstream agent consuming it yet. So
+ * everything here is additive and feature-detected: a component must be a
+ * perfectly good form control with zero agent present.
+ *
+ * The API is `[SecureContext]`, so it only exists on HTTPS pages (localhost
+ * counts as secure); on plain-HTTP origins detection is a no-op by design.
+ */
+/** A JSON-Schema-ish description of a tool's parameters. */
+type JSONSchema = Record<string, unknown>;
+/** A single piece of a tool result. Today only `text` content is supported. */
+interface WebMCPToolResultContent {
+    type: 'text';
+    text: string;
+}
+/** The value a tool's `execute` returns to the agent. */
+interface WebMCPToolResult {
+    content: WebMCPToolResultContent[];
+    isError?: boolean;
+}
+/** Describes a WebMCP tool to register via {@link exposeTool}. */
+interface WebMCPToolDefinition {
+    /** Stable, unique tool name (snake_case by convention). */
+    name: string;
+    /** Natural-language description the agent reads to decide when to call it. */
+    description: string;
+    /** JSON Schema for the tool's arguments. */
+    inputSchema?: JSONSchema;
+    /** Invoked when the agent calls the tool. */
+    execute: (args: Record<string, unknown>) => WebMCPToolResult | Promise<WebMCPToolResult>;
+}
+/** Disposer returned by {@link exposeTool}; safe to call when nothing was registered. */
+type ToolDisposer = () => void;
+/** True when a WebMCP host is present in this environment. */
+declare function isWebMCPAvailable(): boolean;
+declare const isDevEnv: boolean;
+/**
+ * Register a tool with the page's WebMCP host. Returns a disposer that
+ * unregisters it. If no host is present (the common case today), this is a
+ * no-op and the returned disposer does nothing — callers never need to branch.
+ */
+declare function exposeTool(definition: WebMCPToolDefinition): ToolDisposer;
+
+export { type JSONSchema, type ToolDisposer, type WebMCPToolDefinition, type WebMCPToolResult, type WebMCPToolResultContent, exposeTool, isDevEnv, isWebMCPAvailable };

package/dist/index.js

@@ -0,0 +1,54 @@
+// src/index.ts
+function getModelContext() {
+  const fromDocument = typeof document !== "undefined" ? document.modelContext : void 0;
+  const fromNavigator = typeof navigator !== "undefined" ? navigator.modelContext : void 0;
+  const mc = fromDocument ?? fromNavigator;
+  return mc && typeof mc.registerTool === "function" ? mc : void 0;
+}
+function isWebMCPAvailable() {
+  return getModelContext() !== void 0;
+}
+var isDevEnv = globalThis.process?.env?.NODE_ENV !== "production";
+var registeredToolNames = /* @__PURE__ */ new Set();
+function exposeTool(definition) {
+  const mc = getModelContext();
+  if (!mc?.registerTool) return () => {
+  };
+  const descriptor = {
+    name: definition.name,
+    description: definition.description,
+    inputSchema: definition.inputSchema ?? { type: "object", properties: {} },
+    execute: definition.execute
+  };
+  if (isDevEnv && registeredToolNames.has(descriptor.name)) {
+    console.warn(
+      `[webmcpui] A WebMCP tool named "${descriptor.name}" is already registered on this page. Tool names are page-global, so the host rejects the duplicate and this control won't be agent-callable. Give one control a unique \`name\`, or override it with \`tool-name\`.`
+    );
+  }
+  registeredToolNames.add(descriptor.name);
+  const controller = typeof AbortController === "function" ? new AbortController() : void 0;
+  const handle = mc.registerTool(
+    descriptor,
+    controller ? { signal: controller.signal } : void 0
+  );
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    registeredToolNames.delete(descriptor.name);
+    try {
+      controller?.abort();
+      if (handle && typeof handle.unregister === "function") {
+        handle.unregister();
+      } else if (typeof mc.unregisterTool === "function") {
+        mc.unregisterTool(definition.name);
+      }
+    } catch {
+    }
+  };
+}
+export {
+  exposeTool,
+  isDevEnv,
+  isWebMCPAvailable
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@webmcpui/webmcp",
+  "version": "1.0.0-beta.1",
+  "description": "Imperative WebMCP exposure layer — register browser-side tools with the model context host.",
+  "license": "MIT",
+  "author": "Gary Pfaff (Pfaff Digital)",
+  "homepage": "https://webmcpui.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/webmcpui/webmcpui.git",
+    "directory": "packages/webmcp"
+  },
+  "bugs": {
+    "url": "https://github.com/webmcpui/webmcpui/issues"
+  },
+  "keywords": [
+    "webmcp",
+    "modelcontext",
+    "ai-agents"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  }
+}