@agentnext/webmcp 0.1.2 → 0.1.3

package/README.md

@@ -1,30 +1,94 @@
-# AgentNext WebMCP
-
-Bridge AgentNext actions into browser-exposed WebMCP tool interfaces.
-
-## Overview
-Expose AgentNext actions as browser tools that AI clients can discover and invoke.
-
-## Features
-- Tool registration with document.modelContext
-- JSON schema generation from Zod
-- Safe execution wrapper for browser runtimes
-
-## Installation
-```bash
-npm install @agentnext/webmcp @agentnext/core
-```
-
-## Usage
-```ts
-import { action } from "@agentnext/core";
-import { registerActionWithWebMCP } from "@agentnext/webmcp";
-
-const ping = action({
-  name: "ping",
-  input: z.object({ text: z.string() }),
-  execute: async ({ text }) => ({ text }),
-});
-
-registerActionWithWebMCP(ping);
-```
+# @agentnext/webmcp
+
+Expose AgentNext actions as WebMCP browser tools — register actions with `document.modelContext` so AI clients can discover and invoke them directly from the browser.
+
+## Features
+
+- Converts `ActionDefinition` to a WebMCP-compatible tool registration
+- Zod → JSON Schema conversion via `zod-to-json-schema`
+- Safe async execution wrapper (catches errors, returns structured output)
+- Gracefully no-ops in non-browser environments or when WebMCP is unavailable
+
+## Installation
+
+```bash
+npm install @agentnext/webmcp @agentnext/core zod
+```
+
+## Usage
+
+### Register a single action with WebMCP
+
+```ts
+import { z } from "zod";
+import { action } from "@agentnext/core";
+import { registerActionWithWebMCP } from "@agentnext/webmcp";
+
+const addToCart = action({
+  name: "add_to_cart",
+  description: "Adds a product to the shopping cart by product ID and quantity.",
+  input: z.object({
+    productId: z.string(),
+    quantity: z.number().int().min(1).default(1),
+  }),
+  execute: async ({ productId, quantity }) => {
+    const result = await cart.add(productId, quantity);
+    return result;
+  },
+});
+
+// Registers the action with document.modelContext if WebMCP is available
+await registerActionWithWebMCP(addToCart);
+```
+
+### Checking if WebMCP is supported
+
+`registerActionWithWebMCP` returns `{ supported: false }` when `document.modelContext` is not present (e.g. server-side rendering, or a browser without WebMCP). You can use this to branch logic:
+
+```ts
+const result = await registerActionWithWebMCP(addToCart);
+
+if (!result?.supported) {
+  console.log("WebMCP is not available in this environment.");
+}
+```
+
+### Registering multiple actions at startup
+
+```ts
+import { registerActionWithWebMCP } from "@agentnext/webmcp";
+import { addToCart, removeFromCart, checkout } from "./actions";
+
+// Register all actions when the app initialises
+await Promise.all([
+  registerActionWithWebMCP(addToCart),
+  registerActionWithWebMCP(removeFromCart),
+  registerActionWithWebMCP(checkout),
+]);
+```
+
+### Using with `@agentnext/react`
+
+The `useAgentAction` hook from `@agentnext/react` calls `registerActionWithWebMCP` automatically — you don't need to call it manually in React apps:
+
+```tsx
+import { useAgentAction } from "@agentnext/react";
+import { addToCart } from "./actions";
+
+export function CartPage() {
+  useAgentAction(addToCart); // registered with WebMCP automatically
+  return <div>Cart</div>;
+}
+```
+
+### How it works
+
+1. Your `ActionDefinition.input` (a Zod schema) is converted to JSON Schema using `zod-to-json-schema`.
+2. The resulting tool descriptor is passed to `document.modelContext.registerTool()`.
+3. When an AI client invokes the tool, the `execute` wrapper validates input, runs your handler, and returns a JSON string (or error object) safe for LLM consumption.
+
+## API Reference
+
+| Export                             | Description                                                                 |
+| ---------------------------------- | --------------------------------------------------------------------------- |
+| `registerActionWithWebMCP(action)` | Registers an `ActionDefinition` as a WebMCP tool. Returns a promise resolving to the registration result, or `{ supported: false }` if WebMCP is unavailable. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentnext/webmcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "WebMCP adapter for AgentNext — registers actions with document.modelContext",
   "license": "MIT",
   "author": "AgentNext",
@@ -34,7 +34,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@agentnext/core": "^0.1.2",
+    "@agentnext/core": "^0.1.3",
     "zod-to-json-schema": "^3.23.0"
   },
   "devDependencies": {