@zap-studio/webmcp-react 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0]
+
+### Added
+
+- First release. `useWebMCPTool(tool, deps?)` registers `tool` with `@zap-studio/webmcp`'s `registerTool` on mount, and unregisters it on unmount or when `deps` changes. `deps` defaults to `[]` and follows `useEffect`'s dependency-array semantics.
+- Registration failures (most commonly an unsupported browser) are caught and surfaced through the hook's returned `error`, instead of being thrown.
+- Guards against unmount-before-registration-resolves races: a tool that finishes registering after the component has already unmounted is unregistered immediately instead of leaking.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandre Trotel
+
+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,101 @@
+# @zap-studio/webmcp-react
+
+React bindings for [`@zap-studio/webmcp`](https://www.npmjs.com/package/@zap-studio/webmcp): a `useWebMCPTool` hook that registers a tool with the native WebMCP API for the lifetime of a component.
+
+Full documentation: [zapstudio.dev/webmcp/react](https://www.zapstudio.dev/webmcp/react)
+
+## Installation
+
+```bash
+npm install @zap-studio/webmcp-react @zap-studio/webmcp
+```
+
+## Import
+
+```ts
+import { useWebMCPTool } from "@zap-studio/webmcp-react";
+```
+
+## Basic Usage
+
+```tsx
+import { useWebMCPTool } from "@zap-studio/webmcp-react";
+
+function LikeButton({ postId }: { postId: string }) {
+  useWebMCPTool(
+    {
+      name: "posts_like",
+      description: "Like a post by ID",
+      execute: async ({ id }: { id: string }) => ({ liked: await likePost(id) }),
+    },
+    [postId],
+  );
+
+  return <button onClick={() => likePost(postId)}>Like</button>;
+}
+```
+
+Registration runs in `useEffect`, so it happens after mount, in the browser only — safe under Next.js and TanStack Start server rendering, where the hook simply registers nothing.
+
+## Changing Tools
+
+Pass `deps` to control when the tool re-registers — this works exactly like `useEffect`'s dependency array. With the default `[]`, the tool registers once, on mount, using the first render's `tool`:
+
+```tsx
+useWebMCPTool(
+  {
+    name: "posts_like",
+    description: "Like a post by ID",
+    execute: async ({ id }: { id: string }) => ({ liked: await likePost(id) }),
+  },
+  [],
+);
+```
+
+Pass the values `tool` depends on to re-register when they change — for example, when a tool's `execute` closes over a prop:
+
+```tsx
+useWebMCPTool(
+  {
+    name: "posts_like",
+    description: "Like a post by ID",
+    execute: async () => ({ liked: await likePost(postId) }),
+  },
+  [postId],
+);
+```
+
+## Unmount / Cleanup
+
+The tool unregisters automatically when the component unmounts, or right before it re-registers on a `deps` change — no manual cleanup needed. If registration is still pending when the component unmounts, `useWebMCPTool` unregisters it as soon as it resolves instead of leaking a dangling tool.
+
+## Handling Errors
+
+Registration failures — most commonly an unsupported browser — are caught internally and surfaced through the returned `error`, not thrown, so a missing agent-callable tool never crashes the component tree:
+
+```tsx
+function LikeButton({ postId }: { postId: string }) {
+  const { error } = useWebMCPTool(
+    {
+      name: "posts_like",
+      description: "Like a post by ID",
+      execute: async ({ id }: { id: string }) => ({ liked: await likePost(id) }),
+    },
+    [postId],
+  );
+
+  return (
+    <button onClick={() => likePost(postId)}>Like{error ? " (agent tool unavailable)" : ""}</button>
+  );
+}
+```
+
+## See Also
+
+- [`@zap-studio/webmcp`](https://www.npmjs.com/package/@zap-studio/webmcp) — the framework-agnostic core this hook wraps
+- [Getting Started](/webmcp/getting-started) — `defineTool`, `registerTool`, and SSR safety
+- [Tool Registry](/webmcp/registry) — batch-register a route's tools outside of React
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { UseWebMCPToolResult, useWebMCPTool } from "./use-web-mcp-tool.js";
+export { type UseWebMCPToolResult, useWebMCPTool };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { useWebMCPTool } from "./use-web-mcp-tool.js";
+export { useWebMCPTool };

package/dist/use-web-mcp-tool.d.ts

@@ -0,0 +1,52 @@
+import { ModelContextTool } from "@zap-studio/webmcp";
+import { DependencyList } from "react";
+//#region src/use-web-mcp-tool.d.ts
+/** The shape returned by `useWebMCPTool`. */
+interface UseWebMCPToolResult {
+  /**
+   * Set when registration fails — most commonly because the browser doesn't
+   * support WebMCP, or `tool` failed validation. `null` while pending or
+   * once registration succeeds.
+   */
+  error: Error | null;
+}
+/**
+ * Registers `tool` with the native WebMCP API on mount, and unregisters it
+ * on unmount. Re-registers whenever `deps` changes — this works just like
+ * `useEffect`'s dependency array, so `tool` only needs a stable reference if
+ * `deps` does not change between renders.
+ *
+ * Registration failures (most commonly an unsupported browser) are caught
+ * and surfaced through the returned `error`, not thrown — a missing
+ * agent-callable tool shouldn't crash the component tree.
+ *
+ * @param tool - The tool to register.
+ * @param deps - Re-registers `tool` when these change. Defaults to `[]`
+ *   (register once, on mount).
+ *
+ * @example
+ * ```tsx
+ * import { useWebMCPTool } from "@zap-studio/webmcp-react";
+ *
+ * function LikeButton({ postId }: { postId: string }) {
+ *   const { error } = useWebMCPTool(
+ *     {
+ *       name: "posts_like",
+ *       description: "Like a post by ID",
+ *       execute: async ({ id }: { id: string }) => ({ liked: await likePost(id) }),
+ *     },
+ *     [postId],
+ *   );
+ *
+ *   return (
+ *     <button onClick={() => likePost(postId)}>
+ *       Like{error ? " (agent tool unavailable)" : ""}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare const useWebMCPTool: <TInput = unknown>(tool: ModelContextTool<TInput>, deps?: DependencyList) => UseWebMCPToolResult;
+//#endregion
+export { UseWebMCPToolResult, useWebMCPTool };
+//# sourceMappingURL=use-web-mcp-tool.d.ts.map

package/dist/use-web-mcp-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-web-mcp-tool.d.ts","names":[],"sources":["../src/use-web-mcp-tool.ts"],"mappings":";;;;UAciB;;;;;;EAMf,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAuCI,gBAAiB,kBAC5B,MAAM,iBAAiB,SACvB,OAAM,mBACL"}

package/dist/use-web-mcp-tool.js

@@ -0,0 +1,69 @@
+import { registerTool } from "@zap-studio/webmcp";
+import { useEffect, useState } from "react";
+//#region src/use-web-mcp-tool.ts
+/**
+* Registers `tool` with the native WebMCP API on mount, and unregisters it
+* on unmount. Re-registers whenever `deps` changes — this works just like
+* `useEffect`'s dependency array, so `tool` only needs a stable reference if
+* `deps` does not change between renders.
+*
+* Registration failures (most commonly an unsupported browser) are caught
+* and surfaced through the returned `error`, not thrown — a missing
+* agent-callable tool shouldn't crash the component tree.
+*
+* @param tool - The tool to register.
+* @param deps - Re-registers `tool` when these change. Defaults to `[]`
+*   (register once, on mount).
+*
+* @example
+* ```tsx
+* import { useWebMCPTool } from "@zap-studio/webmcp-react";
+*
+* function LikeButton({ postId }: { postId: string }) {
+*   const { error } = useWebMCPTool(
+*     {
+*       name: "posts_like",
+*       description: "Like a post by ID",
+*       execute: async ({ id }: { id: string }) => ({ liked: await likePost(id) }),
+*     },
+*     [postId],
+*   );
+*
+*   return (
+*     <button onClick={() => likePost(postId)}>
+*       Like{error ? " (agent tool unavailable)" : ""}
+*     </button>
+*   );
+* }
+* ```
+*/
+const useWebMCPTool = (tool, deps = []) => {
+	const [error, setError] = useState(null);
+	useEffect(() => {
+		let cancelled = false;
+		let cleanup = () => {};
+		setError(null);
+		const run = async () => {
+			try {
+				const unregisterTool = await registerTool(tool);
+				if (cancelled) {
+					unregisterTool();
+					return;
+				}
+				cleanup = unregisterTool;
+			} catch (caught) {
+				if (!cancelled) setError(caught instanceof Error ? caught : new Error(String(caught)));
+			}
+		};
+		run();
+		return () => {
+			cancelled = true;
+			cleanup();
+		};
+	}, deps);
+	return { error };
+};
+//#endregion
+export { useWebMCPTool };
+
+//# sourceMappingURL=use-web-mcp-tool.js.map

package/dist/use-web-mcp-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-web-mcp-tool.js","names":[],"sources":["../src/use-web-mcp-tool.ts"],"sourcesContent":["/**\n * `useWebMCPTool`: registers a tool with the native WebMCP API for as long\n * as the calling component is mounted.\n *\n * @module @zap-studio/webmcp-react/use-web-mcp-tool\n */\n\nimport type { ModelContextTool } from \"@zap-studio/webmcp\";\nimport type { DependencyList } from \"react\";\n\nimport { registerTool } from \"@zap-studio/webmcp\";\nimport { useEffect, useState } from \"react\";\n\n/** The shape returned by `useWebMCPTool`. */\nexport interface UseWebMCPToolResult {\n  /**\n   * Set when registration fails — most commonly because the browser doesn't\n   * support WebMCP, or `tool` failed validation. `null` while pending or\n   * once registration succeeds.\n   */\n  error: Error | null;\n}\n\n/**\n * Registers `tool` with the native WebMCP API on mount, and unregisters it\n * on unmount. Re-registers whenever `deps` changes — this works just like\n * `useEffect`'s dependency array, so `tool` only needs a stable reference if\n * `deps` does not change between renders.\n *\n * Registration failures (most commonly an unsupported browser) are caught\n * and surfaced through the returned `error`, not thrown — a missing\n * agent-callable tool shouldn't crash the component tree.\n *\n * @param tool - The tool to register.\n * @param deps - Re-registers `tool` when these change. Defaults to `[]`\n *   (register once, on mount).\n *\n * @example\n * ```tsx\n * import { useWebMCPTool } from \"@zap-studio/webmcp-react\";\n *\n * function LikeButton({ postId }: { postId: string }) {\n *   const { error } = useWebMCPTool(\n *     {\n *       name: \"posts_like\",\n *       description: \"Like a post by ID\",\n *       execute: async ({ id }: { id: string }) => ({ liked: await likePost(id) }),\n *     },\n *     [postId],\n *   );\n *\n *   return (\n *     <button onClick={() => likePost(postId)}>\n *       Like{error ? \" (agent tool unavailable)\" : \"\"}\n *     </button>\n *   );\n * }\n * ```\n */\nexport const useWebMCPTool = <TInput = unknown>(\n  tool: ModelContextTool<TInput>,\n  deps: DependencyList = [],\n): UseWebMCPToolResult => {\n  const [error, setError] = useState<Error | null>(null);\n\n  // oxlint-disable-next-line react-hooks/exhaustive-deps -- `deps` comes from the caller, like the dependency array of useEffect. This hook cannot know what is inside it.\n  useEffect(() => {\n    let cancelled = false;\n    let cleanup = (): void => {};\n    setError(null);\n\n    const run = async () => {\n      try {\n        const unregisterTool = await registerTool(tool);\n        if (cancelled) {\n          unregisterTool();\n          return;\n        }\n        cleanup = unregisterTool;\n      } catch (caught) {\n        if (!cancelled) {\n          setError(caught instanceof Error ? caught : new Error(String(caught)));\n        }\n      }\n    };\n\n    void run();\n\n    return () => {\n      cancelled = true;\n      cleanup();\n    };\n    // oxlint-disable-next-line react-hooks/exhaustive-deps -- same pass-through `deps` as above; the rule cannot verify a non-literal dependency list.\n  }, deps);\n\n  return { error };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,MAAa,iBACX,MACA,OAAuB,CAAC,MACA;CACxB,MAAM,CAAC,OAAO,YAAY,SAAuB,IAAI;CAGrD,gBAAgB;EACd,IAAI,YAAY;EAChB,IAAI,gBAAsB,CAAC;EAC3B,SAAS,IAAI;EAEb,MAAM,MAAM,YAAY;GACtB,IAAI;IACF,MAAM,iBAAiB,MAAM,aAAa,IAAI;IAC9C,IAAI,WAAW;KACb,eAAe;KACf;IACF;IACA,UAAU;GACZ,SAAS,QAAQ;IACf,IAAI,CAAC,WACH,SAAS,kBAAkB,QAAQ,SAAS,IAAI,MAAM,OAAO,MAAM,CAAC,CAAC;GAEzE;EACF;EAEA,IAAS;EAET,aAAa;GACX,YAAY;GACZ,QAAQ;EACV;CAEF,GAAG,IAAI;CAEP,OAAO,EAAE,MAAM;AACjB"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@zap-studio/webmcp-react",
+  "version": "1.0.0",
+  "private": false,
+  "description": "React bindings for @zap-studio/webmcp: a useWebMCPTool hook that registers a tool with the native WebMCP API for the lifetime of a component.",
+  "keywords": [
+    "ai",
+    "ai-agent",
+    "mcp",
+    "model-context-protocol",
+    "react",
+    "react-hooks",
+    "tools",
+    "typescript",
+    "webmcp"
+  ],
+  "homepage": "https://www.zapstudio.dev/webmcp/react",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zap-studio/monorepo.git",
+    "directory": "packages/webmcp-react"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./use-web-mcp-tool": "./dist/use-web-mcp-tool.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.5",
+    "@zap-studio/typescript": "0.0.0",
+    "@zap-studio/webmcp": "1.0.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "peerDependencies": {
+    "@zap-studio/webmcp": "^1.0.0",
+    "react": ">=18.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {}
+}