usewebmcp 4.0.0 → 5.0.0

package/README.md

@@ -1,56 +1,21 @@
 # usewebmcp
 
-Standalone React hooks for strict core WebMCP tool registration via `document.modelContext`.
+React hook for registering strict-core WebMCP tools with `document.modelContext`.
 
-`usewebmcp` is intentionally separate from `@mcp-b/react-webmcp`:
-
-- Use `usewebmcp` for strict core WebMCP workflows.
-- Use `@mcp-b/react-webmcp` for full MCP-B runtime features (resources, prompts, client/provider flows, etc.).
-
-## Type Safety First
-
-`usewebmcp` is built for schema-driven types:
-
-- `config.execute`/`config.handler` input is inferred from `inputSchema`
-- Tool result type is inferred from `outputSchema`
-- `state.lastResult` and returned `execute(input)` are typed from that same inferred output
-
-## Package Selection
-
-| Package                  | Use When                                                  |
-| ------------------------ | --------------------------------------------------------- |
-| `usewebmcp`              | React hooks for strict core `document.modelContext` tools |
-| `@mcp-b/react-webmcp`    | React hooks for full MCP-B runtime surface                |
-| `@mcp-b/webmcp-polyfill` | You need a strict core runtime polyfill                   |
-| `@mcp-b/global`          | You need full MCP-B runtime (core + extensions)           |
+Use `usewebmcp` when an app only needs standard tool registration. Use
+`@mcp-b/react-webmcp` for prompts, resources, or MCP client/provider flows.
 
 ## Install
 
 ```bash
 pnpm add usewebmcp react
-# or
-npm install usewebmcp react
 ```
 
-Optional (only if you want Standard Schema authoring like Zod v4 input schemas):
+The hook expects `document.modelContext` to exist before the component mounts. Provide it through
+native browser support, `@mcp-b/webmcp-polyfill`, or `@mcp-b/global`. Older
+`navigator.modelContext` runtimes remain a fallback.
 
-```bash
-pnpm add zod
-```
-
-## Runtime Prerequisite
-
-`usewebmcp` expects `window.document.modelContext` to exist.
-
-You can provide it via:
-
-- Browser-native WebMCP implementation, or
-- `@mcp-b/webmcp-polyfill`, or
-- `@mcp-b/global`
-
-If `document.modelContext` is missing, the hook falls back to older preview `navigator.modelContext` runtimes. If both are missing, the hook logs a warning and skips registration.
-
-## Quick Start
+## Quick start
 
 ```tsx
 import { initializeWebMCPPolyfill } from '@mcp-b/webmcp-polyfill';
@@ -58,221 +23,85 @@ import { useWebMCP } from 'usewebmcp';
 
 initializeWebMCPPolyfill();
 
-const COUNTER_INPUT_SCHEMA = {
-  type: 'object',
-  properties: {},
-} as const;
-
-const COUNTER_OUTPUT_SCHEMA = {
-  type: 'object',
-  properties: {
-    count: { type: 'integer' },
-  },
-  required: ['count'],
-  additionalProperties: false,
-} as const;
-
-export function CounterTool() {
-  const counterTool = useWebMCP({
-    name: 'counter_get',
-    description: 'Get current count',
-    inputSchema: COUNTER_INPUT_SCHEMA,
-    outputSchema: COUNTER_OUTPUT_SCHEMA,
-    execute: async () => ({ count: 42 }),
-  });
-
-  return (
-    <div>
-      <p>Executions: {counterTool.state.executionCount}</p>
-      <p>Last count: {counterTool.state.lastResult?.count ?? 'none'}</p>
-      {counterTool.state.error && <p>Error: {counterTool.state.error.message}</p>}
-      <button
-        onClick={async () => {
-          await counterTool.execute({});
-        }}
-      >
-        Run Tool Locally
-      </button>
-    </div>
-  );
-}
-```
-
-## How `useWebMCP` Works
-
-- Registers a tool on mount with `document.modelContext.registerTool(tool, { signal })` and aborts the controller on unmount.
-- Older Chrome preview builds may not remove tools when the controller aborts. Install `@mcp-b/global` or `@mcp-b/webmcp-polyfill` when you need consistent cleanup across preview versions.
-- Exposes local execution state:
-  - `state.isExecuting`
-  - `state.lastResult`
-  - `state.error`
-  - `state.executionCount`
-- Returns `execute(input)` for manual in-app invocation and `reset()` for state reset.
-
-Your tool implementation (`config.execute` or `config.handler`) can be synchronous or asynchronous.
-
-## `config.execute` vs returned `execute(...)`
-
-- `config.execute`: preferred config field for tool logic.
-- `config.handler`: backward-compatible alias for `config.execute`.
-- returned `execute(input)`: hook return function for local manual invocation from your UI/tests.
-
-If both `config.execute` and `config.handler` are provided, `config.execute` is used.
-
-Both paths run the same underlying tool logic and update the hook state.
-
-## Type Inference
-
-### Input inference
-
-`inputSchema` supports:
-
-- JSON Schema literals (`as const`) via `InferArgsFromInputSchema`
-- Standard Schema v1 input typing (for example Zod v4 / Valibot / ArkType) via `~standard.types.input`
-
-```tsx
 const INPUT_SCHEMA = {
   type: 'object',
-  properties: {
-    query: { type: 'string' },
-    limit: { type: 'integer' },
-  },
+  properties: { query: { type: 'string' } },
   required: ['query'],
-  additionalProperties: false,
 } as const;
 
-useWebMCP({
-  name: 'search',
-  description: 'Search docs',
-  inputSchema: INPUT_SCHEMA,
-  execute(input) {
-    // input is inferred as { query: string; limit?: number }
-    return { total: 1 };
-  },
-});
-```
-
-### Output inference
-
-When `outputSchema` is provided as a literal JSON Schema:
-
-- implementation return type is inferred from `outputSchema`
-- `state.lastResult` is inferred to the same type
-- MCP response includes `structuredContent`
-
-```tsx
 const OUTPUT_SCHEMA = {
   type: 'object',
-  properties: {
-    total: { type: 'integer' },
-  },
+  properties: { total: { type: 'integer' } },
   required: ['total'],
-  additionalProperties: false,
 } as const;
 
-const tool = useWebMCP({
-  name: 'count_items',
-  description: 'Count items',
-  outputSchema: OUTPUT_SCHEMA,
-  execute: () => ({ total: 3 }),
-});
-
-// tool.state.lastResult is inferred as { total: number } | null
-```
-
-## Manual `execute(...)` Calls
-
-You can call the returned `execute(...)` function directly from your component.
-
-```tsx
-function SearchToolPanel() {
-  const searchTool = useWebMCP({
-    name: 'search_local',
-    description: 'Run local search',
-    inputSchema: {
-      type: 'object',
-      properties: { query: { type: 'string' } },
-      required: ['query'],
-      additionalProperties: false,
-    } as const,
-    execute: async ({ query }) => ({ query, total: query.length }),
+export function SearchTool() {
+  const search = useWebMCP({
+    name: 'search',
+    description: 'Search indexed documents',
+    inputSchema: INPUT_SCHEMA,
+    outputSchema: OUTPUT_SCHEMA,
+    execute: async ({ query }) => ({ total: await countMatches(query) }),
   });
 
   return (
-    <button
-      onClick={async () => {
-        await searchTool.execute({ query: 'webmcp' });
-      }}
-    >
-      Run Search
+    <button disabled={search.state.isExecuting} onClick={() => search.execute({ query: 'webmcp' })}>
+      Run search ({search.state.executionCount})
     </button>
   );
 }
 ```
 
-## Output Schema Contract
-
-If `outputSchema` is defined, your tool implementation must return a JSON-serializable value that matches that schema for MCP-B helpers that consume it. Object, array, string, number, boolean, and null schemas are supported for type inference and hook result shaping.
+JSON Schema literals infer the `execute` input, output, returned `execute(input)`, and
+`state.lastResult` types. Standard JSON Schema v1 inputs such as Zod 4.2+ are also supported.
 
-Native Chrome WebMCP does not currently define or enforce `outputSchema`; the browser standard tool dictionary defines `inputSchema`.
-
-## Re-Registration and Performance
-
-The tool re-registers when any of these change:
-
-- `name`
-- `description`
-- `inputSchema` reference
-- `outputSchema` reference
-- `annotations` reference
-- values in `deps`
-
-The hook avoids re-registration when only callback references change:
+## API
 
-- `execute`
-- `handler`
-- `onSuccess`
-- `onError`
-- `formatOutput`
+```ts
+const { state, execute, reset } = useWebMCP(config, deps?);
+```
 
-Latest callback versions are still used at execution time.
+`config` contains:
 
-Recommendation:
+- `name` and `description`
+- optional `inputSchema`, `outputSchema`, and `annotations`
+- `execute(input)`, which may return synchronously or asynchronously
 
-- Define schemas/annotations outside render or memoize them.
-- Keep `deps` primitive when possible.
+`state` contains `isExecuting`, `lastResult`, `error`, and `executionCount`. The returned
+`execute(input)` invokes the same implementation locally. `reset()` clears observed state; it does
+not cancel work already running.
 
-## API
+## Tool responses
 
-### `useWebMCP(config, deps?)`
+Raw return values use the same normalization as the MCP-B runtime:
 
-`config` fields:
+- Existing MCP responses with a `content` array pass through unchanged.
+- Strings become text content.
+- JSON values become text content plus `structuredContent`.
+- Other values receive a safe text representation.
 
-- `name: string`
-- `description: string`
-- `inputSchema?`
-- `outputSchema?`
-- `annotations?`
-- `execute(input)` (preferred)
-- `handler(input)` (backward-compatible alias)
-- `formatOutput?(output)` (deprecated)
-- `onSuccess?(result, input)`
-- `onError?(error, input)`
+When `outputSchema` is present, a non-JSON-serializable result rejects local execution and becomes
+an MCP error response. Native Chrome WebMCP does not advertise `outputSchema`; it is MCP-B metadata
+for output inference and compatible runtimes.
 
-Return value:
+## Re-registration
 
-- `state`
-- `execute(input)`
-- `reset()`
+The tool re-registers when `name`, `description`, or a value in `deps` changes. Implementations,
+schemas, and annotations use their latest committed values without reference-driven churn. Include
+a primitive schema or annotation revision in `deps` when registered metadata must change.
 
-`execute(input)` is a local direct call to your configured tool implementation for in-app control/testing.
-Tool calls coming from MCP clients still go through the page `document.modelContext` surface.
+Registration is aborted on unmount. If the runtime is missing at mount, the hook warns and skips
+registration; initialize the runtime first rather than polling once per hook.
 
-## Important Notes
+## Exports
 
-- This is a client-side hook package (`'use client'`).
-- `formatOutput` is deprecated; prefer `outputSchema` + structured output.
-- When tool output is not a string, default text content is pretty-printed JSON.
+- `useWebMCP`
+- `WebMCPConfig`
+- `WebMCPReturn`
+- `ToolExecutionState`
+- `ToolExecuteFunction`
+- `InferToolInput`
+- `InferOutput`
 
 ## License
 

package/dist/index.d.ts

@@ -3,377 +3,53 @@ import { DependencyList } from "react";
 import { InferArgsFromInputSchema, InferJsonSchema, InputSchema, JsonSchemaForInference, ToolAnnotations } from "@mcp-b/webmcp-types";
 
 //#region src/types.d.ts
-/**
- * Infers tool input type from either a Standard Schema or JSON Schema.
- *
- * - **Standard Schema** (Zod v4, Valibot, ArkType): extracts `~standard.types.input`
- * - **JSON Schema** (`as const`): uses `InferArgsFromInputSchema` for structural inference
- * - **Fallback**: `Record<string, unknown>`
- *
- * @template T - The input schema type
- * @internal
- */
+/** Infers tool input from a JSON Schema literal or Standard JSON Schema. */
 type InferToolInput<T> = T extends {
   readonly '~standard': {
     readonly types?: infer Types;
   };
-} ? Types extends {
-  readonly input: infer I;
-} ? I : Record<string, unknown> : T extends InputSchema ? InferArgsFromInputSchema<T> : Record<string, unknown>;
-/**
- * Utility type to infer the output type from a JSON Schema.
- *
- * When `TOutputSchema` is a literal inferable JSON schema, this resolves to
- * `InferJsonSchema<TOutputSchema>`. When it's `undefined`,
- * it falls back to the provided `TFallback` type.
- *
- * @template TOutputSchema - JSON Schema for output inference
- * @template TFallback - Fallback type when no schema is provided
- * @internal
- */
-type InferOutput<TOutputSchema extends JsonSchemaForInference | undefined = undefined, TFallback = unknown> = TOutputSchema extends undefined ? TFallback : TOutputSchema extends JsonSchemaForInference ? InferJsonSchema<TOutputSchema> : TFallback;
-/**
- * Represents the current execution state of a tool, including loading status,
- * results, errors, and execution history.
- *
- * @template TOutput - The type of data returned by the tool implementation
- * @public
- */
+} ? NonNullable<Types> extends {
+  readonly input: infer Input;
+} ? Input : Record<string, unknown> : T extends InputSchema ? InferArgsFromInputSchema<T> : Record<string, unknown>;
+/** Infers tool output from a JSON Schema literal. */
+type InferOutput<TOutputSchema extends JsonSchemaForInference | undefined = undefined> = TOutputSchema extends undefined ? unknown : TOutputSchema extends JsonSchemaForInference ? InferJsonSchema<TOutputSchema> : unknown;
+/** Current state for local and MCP-triggered tool executions. */
 interface ToolExecutionState<TOutput = unknown> {
-  /**
-   * Indicates whether the tool is currently executing.
-   * Use this to show loading states in your UI.
-   */
+  /** Whether at least one execution is pending. */
   isExecuting: boolean;
-  /**
-   * The result from the most recent successful execution.
-   * Will be `null` if the tool hasn't been executed or last execution failed.
-   */
+  /** Most recent successful result, or `null` before one exists. */
   lastResult: TOutput | null;
-  /**
-   * The error from the most recent failed execution.
-   * Will be `null` if the tool hasn't been executed or last execution succeeded.
-   */
+  /** Most recent execution error. */
   error: Error | null;
-  /**
-   * Total number of times this tool has been executed.
-   * Increments on successful executions only.
-   */
+  /** Number of successful executions since the last reset. */
   executionCount: number;
 }
-/**
- * Tool implementation function used by `useWebMCP`.
- *
- * Supports sync or async implementations.
- *
- * @template TInputSchema - Schema defining input parameters
- * @template TOutputSchema - Optional JSON Schema defining output structure
- *
- * @public
- */
+/** Synchronous or asynchronous tool implementation. */
 type ToolExecuteFunction<TInputSchema extends ToolInputSchema = InputSchema, TOutputSchema extends JsonSchemaForInference | undefined = undefined> = (input: InferToolInput<TInputSchema>) => Promise<InferOutput<TOutputSchema>> | InferOutput<TOutputSchema>;
-/**
- * Shared configuration fields for the `useWebMCP` hook.
- *
- * Defines a tool's metadata, schema, and lifecycle callbacks.
- * Uses JSON Schema for type inference via `as const`.
- *
- * @template TInputSchema - JSON Schema defining input parameters
- * @template TOutputSchema - JSON Schema defining output structure
- *
- * @public
- *
- * @example Basic tool without output schema:
- * ```typescript
- * const config: WebMCPConfig = {
- *   name: 'posts_like',
- *   description: 'Like a post by its ID',
- *   inputSchema: {
- *     type: 'object',
- *     properties: { postId: { type: 'string' } },
- *     required: ['postId'],
- *   } as const,
- *   execute: async ({ postId }) => {
- *     await api.likePost(postId);
- *     return { success: true };
- *   },
- * };
- * ```
- *
- * @example Tool with output schema (enables MCP structuredContent):
- * ```typescript
- * useWebMCP({
- *   name: 'posts_like',
- *   description: 'Like a post and return updated like count',
- *   inputSchema: {
- *     type: 'object',
- *     properties: { postId: { type: 'string' } },
- *     required: ['postId'],
- *   } as const,
- *   outputSchema: {
- *     type: 'object',
- *     properties: {
- *       likes: { type: 'number', description: 'Updated like count' },
- *       likedAt: { type: 'string', description: 'ISO timestamp of the like' },
- *     },
- *   } as const,
- *   execute: async ({ postId }) => {
- *     const result = await api.likePost(postId);
- *     return { likes: result.likes, likedAt: new Date().toISOString() };
- *   },
- * });
- * ```
- */
-interface WebMCPConfigBase<TInputSchema extends ToolInputSchema = InputSchema, TOutputSchema extends JsonSchemaForInference | undefined = undefined> {
-  /**
-   * Unique identifier for the tool (e.g., 'posts_like', 'graph_navigate').
-   * Must follow naming conventions: lowercase with underscores.
-   */
+/** Configuration for a tool registered by `useWebMCP`. */
+interface WebMCPConfig<TInputSchema extends ToolInputSchema = InputSchema, TOutputSchema extends JsonSchemaForInference | undefined = undefined> {
+  /** Unique WebMCP tool name. */
   name: string;
-  /**
-   * Human-readable description explaining what the tool does.
-   * This description is used by AI assistants to understand when to use the tool.
-   */
+  /** Description shown to MCP clients. */
   description: string;
-  /**
-   * Schema defining the input parameters for the tool.
-   * Accepts JSON Schema (with `as const`) or any Standard Schema v1
-   * library (Zod v4, Valibot, ArkType, etc.).
-   *
-   * @example JSON Schema
-   * ```typescript
-   * inputSchema: {
-   *   type: 'object',
-   *   properties: {
-   *     postId: { type: 'string', description: 'The ID of the post to like' },
-   *   },
-   *   required: ['postId'],
-   * } as const
-   * ```
-   *
-   * @example Standard Schema (Zod v4)
-   * ```typescript
-   * inputSchema: z.object({ postId: z.string() })
-   * ```
-   */
+  /** JSON Schema literal or Standard JSON Schema for the tool input. */
   inputSchema?: TInputSchema;
-  /**
-   * **Recommended:** JSON Schema defining the expected output structure.
-   *
-   * When provided, this enables three key features:
-   * 1. **Type Safety**: The implementation return type is inferred from this schema
-   * 2. **MCP structuredContent**: The MCP response includes `structuredContent`
-   *    containing the typed output per the MCP specification
-   * 3. **AI Understanding**: AI models can better understand and use the tool's output
-   *
-   * @see {@link https://spec.modelcontextprotocol.io/specification/server/tools/#output-schemas}
-   *
-   * @example
-   * ```typescript
-   * outputSchema: {
-   *   type: 'object',
-   *   properties: {
-   *     counter: { type: 'number', description: 'The current counter value' },
-   *     timestamp: { type: 'string', description: 'ISO timestamp' },
-   *   },
-   * } as const
-   * ```
-   */
+  /** JSON Schema used for output inference and structured content. */
   outputSchema?: TOutputSchema;
-  /**
-   * Optional metadata annotations providing hints about tool behavior.
-   * See {@link ToolAnnotations} for available options.
-   */
+  /** Optional WebMCP behavior hints. */
   annotations?: ToolAnnotations;
-  /**
-   * Custom formatter for the MCP text response.
-   *
-   * @deprecated Use `outputSchema` instead. The `outputSchema` provides type-safe
-   * structured output via MCP's `structuredContent`, which is the recommended
-   * approach for tool outputs. This property will be removed in a future version.
-   *
-   * @param output - The raw output from the tool implementation
-   * @returns Formatted string for the MCP response content
-   */
-  formatOutput?: (output: InferOutput<TOutputSchema>) => string;
-  /**
-   * Optional callback invoked when the tool execution succeeds.
-   * Useful for triggering side effects like navigation or analytics.
-   *
-   * @param result - The successful result from the tool implementation
-   * @param input - The input that was passed to the tool implementation
-   */
-  onSuccess?: (result: InferOutput<TOutputSchema>, input: unknown) => void;
-  /**
-   * Optional callback invoked when the tool execution fails.
-   * Useful for error handling, logging, or showing user notifications.
-   *
-   * @param error - The error that occurred during execution
-   * @param input - The input that was passed to the tool implementation
-   */
-  onError?: (error: Error, input: unknown) => void;
-}
-type WebMCPConfigImplementation<TInputSchema extends ToolInputSchema = InputSchema, TOutputSchema extends JsonSchemaForInference | undefined = undefined> = {
-  /**
-   * Preferred tool implementation function.
-   */
+  /** Tool implementation. */
   execute: ToolExecuteFunction<TInputSchema, TOutputSchema>;
-  /**
-   * Backward-compatible alias for `execute`.
-   */
-  handler?: ToolExecuteFunction<TInputSchema, TOutputSchema>;
-} | {
-  /**
-   * Backward-compatible alias for `execute`.
-   */
-  handler: ToolExecuteFunction<TInputSchema, TOutputSchema>;
-  /**
-   * Preferred tool implementation function.
-   */
-  execute?: ToolExecuteFunction<TInputSchema, TOutputSchema>;
-};
-/**
- * Configuration options for the `useWebMCP` hook.
- *
- * You can provide tool logic with either:
- * - `execute` (preferred), or
- * - `handler` (backward-compatible alias).
- *
- * If both are provided, `execute` is used.
- *
- * @template TInputSchema - JSON Schema defining input parameters
- * @template TOutputSchema - JSON Schema defining output structure
- *
- * @public
- */
-type WebMCPConfig<TInputSchema extends ToolInputSchema = InputSchema, TOutputSchema extends JsonSchemaForInference | undefined = undefined> = WebMCPConfigBase<TInputSchema, TOutputSchema> & WebMCPConfigImplementation<TInputSchema, TOutputSchema>;
-/**
- * Return value from the `useWebMCP` hook.
- * Provides access to execution state and methods for manual tool control.
- *
- * @template TOutputSchema - JSON Schema defining output structure
- * @public
- */
+}
+/** State and controls returned by `useWebMCP`. */
 interface WebMCPReturn<TOutputSchema extends JsonSchemaForInference | undefined = undefined, TInputSchema extends ToolInputSchema = InputSchema> {
-  /**
-   * Current execution state including loading status, results, and errors.
-   * See {@link ToolExecutionState} for details.
-   */
   state: ToolExecutionState<InferOutput<TOutputSchema>>;
-  /**
-   * Manually execute the tool with the provided input.
-   * Useful for testing, debugging, or triggering execution from your UI.
-   *
-   * @param input - The input parameters to pass to the tool
-   * @returns Promise resolving to the tool's output
-   * @throws Error if validation fails or tool implementation throws
-   */
   execute: (input: InferToolInput<TInputSchema>) => Promise<InferOutput<TOutputSchema>>;
-  /**
-   * Reset the execution state to its initial values.
-   * Clears results, errors, and resets the execution count.
-   */
   reset: () => void;
 }
 //#endregion
 //#region src/useWebMCP.d.ts
-/**
- * React hook for registering and managing Model Context Protocol (MCP) tools.
- *
- * This hook handles the complete lifecycle of an MCP tool:
- * - Registers the tool with `window.document.modelContext`
- * - Manages execution state (loading, results, errors)
- * - Handles tool execution and lifecycle callbacks
- * - Automatically unregisters on component unmount
- * - Returns `structuredContent` when `outputSchema` is defined
- *
- * ## Output Schema (Recommended)
- *
- * Always define an `outputSchema` for your tools. This provides:
- * - **Type Safety**: Handler return type is inferred from the schema
- * - **MCP structuredContent**: AI models receive structured, typed data
- * - **Better AI Understanding**: Models can reason about your tool's output format
- *
- * ```tsx
- * useWebMCP({
- *   name: 'get_user',
- *   description: 'Get user by ID',
- *   inputSchema: {
- *     type: 'object',
- *     properties: { userId: { type: 'string' } },
- *     required: ['userId'],
- *   } as const,
- *   outputSchema: {
- *     type: 'object',
- *     properties: {
- *       id: { type: 'string' },
- *       name: { type: 'string' },
- *       email: { type: 'string' },
- *     },
- *   } as const,
- *   execute: async ({ userId }) => {
- *     const user = await fetchUser(userId);
- *     return { id: user.id, name: user.name, email: user.email };
- *   },
- * });
- * ```
- *
- * ## Re-render Optimization
- *
- * This hook is optimized to minimize unnecessary tool re-registrations:
- *
- * - **Ref-based static descriptors and callbacks**: `inputSchema`, `outputSchema`,
- *   `annotations`, `execute`/`handler`, `onSuccess`, `onError`, and `formatOutput`
- *   are stored in refs, so recreating them during render won't trigger re-registration.
- *
- * If a schema or annotation actually changes and the registered descriptor should change,
- * include the relevant primitive value in the `deps` array.
- *
- * ```tsx
- * useWebMCP({
- *   outputSchema: { type: 'object', properties: { count: { type: 'number' } } } as const,
- * });
- * ```
- *
- * @template TInputSchema - JSON Schema defining input parameter types (use `as const` for inference)
- * @template TOutputSchema - JSON Schema defining output structure
- *
- * @param config - Configuration object for the tool
- * @param deps - Optional dependency array that triggers tool re-registration when values change.
- *
- * @returns Object containing execution state and control methods
- *
- * @public
- *
- * @example
- * Basic tool with outputSchema (recommended):
- * ```tsx
- * function PostActions() {
- *   const likeTool = useWebMCP({
- *     name: 'posts_like',
- *     description: 'Like a post by ID',
- *     inputSchema: {
- *       type: 'object',
- *       properties: { postId: { type: 'string', description: 'The post ID' } },
- *       required: ['postId'],
- *     } as const,
- *     outputSchema: {
- *       type: 'object',
- *       properties: {
- *         success: { type: 'boolean' },
- *         likeCount: { type: 'number' },
- *       },
- *     } as const,
- *     execute: async ({ postId }) => {
- *       const result = await api.posts.like(postId);
- *       return { success: true, likeCount: result.likes };
- *     },
- *   });
- *
- *   return <div>Likes: {likeTool.state.lastResult?.likeCount ?? 0}</div>;
- * }
- * ```
- */
+/** Registers a React-owned tool with the current WebMCP model context. */
 declare function useWebMCP<TInputSchema extends ToolInputSchema = InputSchema, TOutputSchema extends JsonSchemaForInference | undefined = undefined>(config: WebMCPConfig<TInputSchema, TOutputSchema>, deps?: DependencyList): WebMCPReturn<TOutputSchema, TInputSchema>;
 //#endregion
 export { type InferOutput, type InferToolInput, type ToolExecuteFunction, type ToolExecutionState, type WebMCPConfig, type WebMCPReturn, useWebMCP };

package/dist/index.js

@@ -1,2 +1,2 @@
-"use client";import{normalizeInputSchema as e,toJsonValue as t}from"@mcp-b/webmcp-polyfill/schema";import{useCallback as n,useEffect as r,useLayoutEffect as i,useRef as a,useState as o}from"react";function s(){if(typeof window>`u`)return;let e=window.document.modelContext,t=window.navigator.modelContext;return e??t}function c(e){return typeof e==`string`?e:JSON.stringify(e,null,2)}const l=new Map,u=typeof window<`u`?i:r;function d(){let e=typeof process<`u`?`production`:void 0;return e===void 0?!1:e!==`production`}function f(i,f){let{name:p,description:m,inputSchema:h,outputSchema:g,annotations:_,execute:v,handler:y,formatOutput:b=c,onSuccess:x,onError:S}=i,C=v??y;if(!C)throw TypeError(`[useWebMCP] Tool "${p}" must provide an implementation via config.execute or config.handler`);let[w,T]=o({isExecuting:!1,lastResult:null,error:null,executionCount:0}),E=a(C),D=a(x),O=a(S),k=a(b),A=a(h),j=a(g),M=a(_),N=a(!0),P=a(new Set),F=a({description:m,deps:f});u(()=>{E.current=C,D.current=x,O.current=S,k.current=b,A.current=h,j.current=g,M.current=_},[_,h,x,S,g,C,b]),r(()=>(N.current=!0,()=>{N.current=!1}),[]),r(()=>{if(!d()){F.current={description:m,deps:f};return}let e=(e,t)=>{P.current.has(e)||(console.warn(`[useWebMCP] ${t}`),P.current.add(e))};m!==F.current.description&&e(`description`,`Tool "${p}" description changed; this re-registers the tool. Memoize the description if it does not need to update.`),f?.some(e=>typeof e==`object`&&!!e||typeof e==`function`)&&e(`deps`,`Tool "${p}" deps contains non-primitive values; prefer primitives or memoize objects/functions to reduce re-registration.`),F.current={description:m,deps:f}},[f,m,p]);let I=n(async e=>{T(e=>({...e,isExecuting:!0,error:null}));try{let t=await E.current(e);return N.current&&T(e=>({isExecuting:!1,lastResult:t,error:null,executionCount:e.executionCount+1})),D.current&&D.current(t,e),t}catch(t){let n=t instanceof Error?t:Error(String(t));throw N.current&&T(e=>({...e,isExecuting:!1,error:n})),O.current&&O.current(n,e),n}},[]),L=a(I);r(()=>{L.current=I},[I]);let R=n(e=>L.current(e),[]),z=n(()=>{T({isExecuting:!1,lastResult:null,error:null,executionCount:0})},[]);return r(()=>{let n=s();if(!n){console.warn(`[useWebMCP] window.document.modelContext is not available. Tool "${p}" will not be registered.`);return}let r=async e=>{try{let n=await Reflect.apply(L.current,void 0,[e]),r={content:[{type:`text`,text:k.current(n)}]};if(j.current){let e=t(n);if(e===void 0)throw Error(`Tool "${p}" outputSchema requires the tool implementation to return a JSON-serializable result`);r.structuredContent=e}return r}catch(e){return{content:[{type:`text`,text:`Error: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}},i=Symbol(p),a=e(A.current).inputSchema,o=j.current,c=M.current,u={name:p,description:m,inputSchema:a,...o&&{outputSchema:o},...c&&{annotations:c},execute:r},d=new AbortController,f=!1,h=!1;try{let e=n.registerTool(u,{signal:d.signal});Promise.resolve(e).then(()=>{!h&&!d.signal.aborted&&(f=!0,l.set(p,i))},e=>{d.signal.aborted||(d.abort(),console.warn(`[useWebMCP] registerTool("${p}") rejected:`,e))})}catch(e){d.abort(),console.warn(`[useWebMCP] registerTool("${p}") rejected:`,e);return}return()=>{if(h=!0,f&&l.get(p)===i){l.delete(p),d.abort();return}f||d.abort()}},[p,m,...f??[]]),{state:w,execute:R,reset:z}}export{f as useWebMCP};
+"use client";import{normalizeInputSchema as e,normalizeToolResponse as t}from"@mcp-b/webmcp-polyfill/schema";import{useCallback as n,useEffect as r,useLayoutEffect as i,useRef as a,useState as o}from"react";const s={isExecuting:!1,lastResult:null,error:null,executionCount:0},c=typeof window>`u`?r:i;function l(i,l){let{name:u,description:d}=i,[f,p]=o(s),m=a(i),h=a(0);c(()=>{m.current=i});let g=n(async e=>{h.current+=1,p(e=>({...e,isExecuting:!0,error:null}));let n,r=m.current;try{if(n=await r.execute(e),r.outputSchema&&t(n).structuredContent===void 0)throw Error(`Tool "${r.name}" outputSchema requires execute to return a JSON-serializable result`)}catch(e){--h.current;let t=e instanceof Error?e:Error(String(e));throw p(e=>({...e,isExecuting:h.current>0,error:t})),t}return--h.current,p(e=>({isExecuting:h.current>0,lastResult:n,error:null,executionCount:e.executionCount+1})),n},[]),_=n(()=>p({...s,isExecuting:h.current>0}),[]);return r(()=>{let n=typeof document>`u`?void 0:document.modelContext??(typeof navigator>`u`?void 0:navigator.modelContext);if(!n){console.warn(`[useWebMCP] document.modelContext is not available. Tool "${u}" will not be registered.`);return}let r=m.current,i=r.outputSchema,a=new AbortController,o={name:u,description:d,inputSchema:e(r.inputSchema).inputSchema,...i&&{outputSchema:i},...r.annotations&&{annotations:r.annotations},execute:async e=>{try{let n=t(await g(e));if(i&&n.structuredContent===void 0)throw Error(`Tool "${u}" outputSchema requires the tool implementation to return a JSON-serializable result`);return n}catch(e){return{content:[{type:`text`,text:`Error: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}}};try{let e=n.registerTool(o,{signal:a.signal});Promise.resolve(e).catch(e=>{a.signal.aborted||(a.abort(),console.warn(`[useWebMCP] registerTool("${u}") rejected:`,e))})}catch(e){a.abort(),console.warn(`[useWebMCP] registerTool("${u}") rejected:`,e);return}return()=>a.abort()},[u,d,...l??[]]),{state:f,execute:g,reset:_}}export{l as useWebMCP};
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/model-context.ts","../src/useWebMCP.ts"],"sourcesContent":["import type { ModelContext } from '@mcp-b/webmcp-types';\n\nexport type ModelContextSurface = ModelContext;\ntype ModelContextHost = { modelContext?: ModelContext };\n\nexport function getModelContext(): ModelContextSurface | undefined {\n  if (typeof window === 'undefined') {\n    return undefined;\n  }\n\n  const documentContext = (window.document as Document & ModelContextHost).modelContext;\n  const navigatorContext = (window.navigator as Navigator & ModelContextHost).modelContext;\n  return documentContext ?? navigatorContext;\n}\n","import {\n  normalizeInputSchema,\n  toJsonValue,\n  type ToolInputSchema,\n} from '@mcp-b/webmcp-polyfill/schema';\nimport type {\n  CallToolResult,\n  InputSchema,\n  JsonSchemaForInference,\n  ToolDescriptor,\n} from '@mcp-b/webmcp-types';\nimport type { DependencyList } from 'react';\nimport { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';\nimport type {\n  InferOutput,\n  InferToolInput,\n  ToolExecutionState,\n  WebMCPConfig,\n  WebMCPReturn,\n} from './types.js';\nimport { getModelContext } from './model-context.js';\n\n/**\n * Default output formatter that converts values to formatted JSON strings.\n *\n * String values are returned as-is; all other types are serialized to\n * indented JSON for readability.\n *\n * @internal\n */\nfunction defaultFormatOutput(output: unknown): string {\n  if (typeof output === 'string') {\n    return output;\n  }\n  return JSON.stringify(output, null, 2);\n}\n\nconst TOOL_OWNER_BY_NAME = new Map<string, symbol>();\n\nconst useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;\n\nfunction isDev(): boolean {\n  const env = typeof process !== 'undefined' ? process.env?.NODE_ENV : undefined;\n  return env !== undefined ? env !== 'production' : false;\n}\n\n/**\n * React hook for registering and managing Model Context Protocol (MCP) tools.\n *\n * This hook handles the complete lifecycle of an MCP tool:\n * - Registers the tool with `window.document.modelContext`\n * - Manages execution state (loading, results, errors)\n * - Handles tool execution and lifecycle callbacks\n * - Automatically unregisters on component unmount\n * - Returns `structuredContent` when `outputSchema` is defined\n *\n * ## Output Schema (Recommended)\n *\n * Always define an `outputSchema` for your tools. This provides:\n * - **Type Safety**: Handler return type is inferred from the schema\n * - **MCP structuredContent**: AI models receive structured, typed data\n * - **Better AI Understanding**: Models can reason about your tool's output format\n *\n * ```tsx\n * useWebMCP({\n *   name: 'get_user',\n *   description: 'Get user by ID',\n *   inputSchema: {\n *     type: 'object',\n *     properties: { userId: { type: 'string' } },\n *     required: ['userId'],\n *   } as const,\n *   outputSchema: {\n *     type: 'object',\n *     properties: {\n *       id: { type: 'string' },\n *       name: { type: 'string' },\n *       email: { type: 'string' },\n *     },\n *   } as const,\n *   execute: async ({ userId }) => {\n *     const user = await fetchUser(userId);\n *     return { id: user.id, name: user.name, email: user.email };\n *   },\n * });\n * ```\n *\n * ## Re-render Optimization\n *\n * This hook is optimized to minimize unnecessary tool re-registrations:\n *\n * - **Ref-based static descriptors and callbacks**: `inputSchema`, `outputSchema`,\n *   `annotations`, `execute`/`handler`, `onSuccess`, `onError`, and `formatOutput`\n *   are stored in refs, so recreating them during render won't trigger re-registration.\n *\n * If a schema or annotation actually changes and the registered descriptor should change,\n * include the relevant primitive value in the `deps` array.\n *\n * ```tsx\n * useWebMCP({\n *   outputSchema: { type: 'object', properties: { count: { type: 'number' } } } as const,\n * });\n * ```\n *\n * @template TInputSchema - JSON Schema defining input parameter types (use `as const` for inference)\n * @template TOutputSchema - JSON Schema defining output structure\n *\n * @param config - Configuration object for the tool\n * @param deps - Optional dependency array that triggers tool re-registration when values change.\n *\n * @returns Object containing execution state and control methods\n *\n * @public\n *\n * @example\n * Basic tool with outputSchema (recommended):\n * ```tsx\n * function PostActions() {\n *   const likeTool = useWebMCP({\n *     name: 'posts_like',\n *     description: 'Like a post by ID',\n *     inputSchema: {\n *       type: 'object',\n *       properties: { postId: { type: 'string', description: 'The post ID' } },\n *       required: ['postId'],\n *     } as const,\n *     outputSchema: {\n *       type: 'object',\n *       properties: {\n *         success: { type: 'boolean' },\n *         likeCount: { type: 'number' },\n *       },\n *     } as const,\n *     execute: async ({ postId }) => {\n *       const result = await api.posts.like(postId);\n *       return { success: true, likeCount: result.likes };\n *     },\n *   });\n *\n *   return <div>Likes: {likeTool.state.lastResult?.likeCount ?? 0}</div>;\n * }\n * ```\n */\nexport function useWebMCP<\n  TInputSchema extends ToolInputSchema = InputSchema,\n  TOutputSchema extends JsonSchemaForInference | undefined = undefined,\n>(\n  config: WebMCPConfig<TInputSchema, TOutputSchema>,\n  deps?: DependencyList\n): WebMCPReturn<TOutputSchema, TInputSchema> {\n  type TOutput = InferOutput<TOutputSchema>;\n  type TInput = InferToolInput<TInputSchema>;\n  const {\n    name,\n    description,\n    inputSchema,\n    outputSchema,\n    annotations,\n    execute: configExecute,\n    handler: legacyHandler,\n    formatOutput = defaultFormatOutput,\n    onSuccess,\n    onError,\n  } = config;\n  const toolExecute = configExecute ?? legacyHandler;\n\n  if (!toolExecute) {\n    throw new TypeError(\n      `[useWebMCP] Tool \"${name}\" must provide an implementation via config.execute or config.handler`\n    );\n  }\n\n  const [state, setState] = useState<ToolExecutionState<TOutput>>({\n    isExecuting: false,\n    lastResult: null,\n    error: null,\n    executionCount: 0,\n  });\n\n  const toolExecuteRef = useRef(toolExecute);\n  const onSuccessRef = useRef(onSuccess);\n  const onErrorRef = useRef(onError);\n  const formatOutputRef = useRef(formatOutput);\n  const inputSchemaRef = useRef(inputSchema);\n  const outputSchemaRef = useRef(outputSchema);\n  const annotationsRef = useRef(annotations);\n  const isMountedRef = useRef(true);\n  const warnedRef = useRef(new Set<string>());\n  const prevConfigRef = useRef({\n    description,\n    deps,\n  });\n  // Update refs when callbacks or static descriptors are recreated during render.\n  useIsomorphicLayoutEffect(() => {\n    toolExecuteRef.current = toolExecute;\n    onSuccessRef.current = onSuccess;\n    onErrorRef.current = onError;\n    formatOutputRef.current = formatOutput;\n    inputSchemaRef.current = inputSchema;\n    outputSchemaRef.current = outputSchema;\n    annotationsRef.current = annotations;\n  }, [annotations, inputSchema, onSuccess, onError, outputSchema, toolExecute, formatOutput]);\n\n  // Cleanup: mark component as unmounted\n  useEffect(() => {\n    isMountedRef.current = true;\n    return () => {\n      isMountedRef.current = false;\n    };\n  }, []);\n\n  useEffect(() => {\n    if (!isDev()) {\n      prevConfigRef.current = { description, deps };\n      return;\n    }\n\n    const warnOnce = (key: string, message: string) => {\n      if (warnedRef.current.has(key)) {\n        return;\n      }\n      console.warn(`[useWebMCP] ${message}`);\n      warnedRef.current.add(key);\n    };\n\n    const prev = prevConfigRef.current;\n\n    if (description !== prev.description) {\n      warnOnce(\n        'description',\n        `Tool \"${name}\" description changed; this re-registers the tool. Memoize the description if it does not need to update.`\n      );\n    }\n\n    if (\n      deps?.some(\n        (value) => (typeof value === 'object' && value !== null) || typeof value === 'function'\n      )\n    ) {\n      warnOnce(\n        'deps',\n        `Tool \"${name}\" deps contains non-primitive values; prefer primitives or memoize objects/functions to reduce re-registration.`\n      );\n    }\n\n    prevConfigRef.current = { description, deps };\n  }, [deps, description, name]);\n\n  /**\n   * Executes the configured tool implementation with input validation and state management.\n   *\n   * @param input - The input parameters to validate and pass to the tool implementation\n   * @returns Promise resolving to the tool output\n   * @throws Error if validation fails or the tool implementation throws\n   */\n  const execute = useCallback(async (input: TInput): Promise<TOutput> => {\n    setState((prev) => ({\n      ...prev,\n      isExecuting: true,\n      error: null,\n    }));\n\n    try {\n      const result = await toolExecuteRef.current(input);\n\n      // Only update state if component is still mounted\n      if (isMountedRef.current) {\n        setState((prev) => ({\n          isExecuting: false,\n          lastResult: result,\n          error: null,\n          executionCount: prev.executionCount + 1,\n        }));\n      }\n\n      if (onSuccessRef.current) {\n        onSuccessRef.current(result, input);\n      }\n\n      return result;\n    } catch (error) {\n      const err = error instanceof Error ? error : new Error(String(error));\n\n      // Only update state if component is still mounted\n      if (isMountedRef.current) {\n        setState((prev) => ({\n          ...prev,\n          isExecuting: false,\n          error: err,\n        }));\n      }\n\n      if (onErrorRef.current) {\n        onErrorRef.current(err, input);\n      }\n\n      throw err;\n    }\n  }, []);\n  const executeRef = useRef(execute);\n\n  useEffect(() => {\n    executeRef.current = execute;\n  }, [execute]);\n\n  const stableExecute = useCallback(\n    (input: TInput): Promise<TOutput> => executeRef.current(input),\n    []\n  );\n\n  /**\n   * Resets the execution state to initial values.\n   */\n  const reset = useCallback(() => {\n    setState({\n      isExecuting: false,\n      lastResult: null,\n      error: null,\n      executionCount: 0,\n    });\n  }, []);\n\n  useEffect(() => {\n    const modelContext = getModelContext();\n    if (!modelContext) {\n      console.warn(\n        `[useWebMCP] window.document.modelContext is not available. Tool \"${name}\" will not be registered.`\n      );\n      return;\n    }\n\n    /**\n     * Handles MCP tool execution by running the tool implementation and formatting the response.\n     *\n     * @param input - The input parameters from the MCP client\n     * @returns CallToolResult with text content and optional structuredContent\n     */\n    const mcpHandler = async (input: unknown): Promise<CallToolResult> => {\n      try {\n        const result = await Reflect.apply(executeRef.current, undefined, [input]);\n        const formattedOutput = formatOutputRef.current(result);\n\n        const response: CallToolResult = {\n          content: [\n            {\n              type: 'text',\n              text: formattedOutput,\n            },\n          ],\n        };\n\n        if (outputSchemaRef.current) {\n          const structuredContent = toJsonValue(result);\n          if (structuredContent === undefined) {\n            throw new Error(\n              `Tool \"${name}\" outputSchema requires the tool implementation to return a JSON-serializable result`\n            );\n          }\n          response.structuredContent = structuredContent;\n        }\n\n        return response;\n      } catch (error) {\n        const errorMessage = error instanceof Error ? error.message : String(error);\n\n        return {\n          content: [\n            {\n              type: 'text',\n              text: `Error: ${errorMessage}`,\n            },\n          ],\n          isError: true,\n        };\n      }\n    };\n\n    const ownerToken = Symbol(name);\n    const resolvedInputSchema = normalizeInputSchema(inputSchemaRef.current).inputSchema;\n    const resolvedOutputSchema = outputSchemaRef.current;\n    const resolvedAnnotations = annotationsRef.current;\n    const toolDescriptor: ToolDescriptor & { inputSchema: InputSchema } = {\n      name,\n      description,\n      inputSchema: resolvedInputSchema,\n      ...(resolvedOutputSchema && { outputSchema: resolvedOutputSchema }),\n      ...(resolvedAnnotations && { annotations: resolvedAnnotations }),\n      execute: mcpHandler,\n    };\n\n    const controller = new AbortController();\n    let registered = false;\n    let disposed = false;\n\n    try {\n      const registerResult = modelContext.registerTool(toolDescriptor, {\n        signal: controller.signal,\n      });\n\n      void Promise.resolve(registerResult).then(\n        () => {\n          if (!disposed && !controller.signal.aborted) {\n            registered = true;\n            TOOL_OWNER_BY_NAME.set(name, ownerToken);\n          }\n        },\n        (error: unknown) => {\n          if (!controller.signal.aborted) {\n            controller.abort();\n            console.warn(`[useWebMCP] registerTool(\"${name}\") rejected:`, error);\n          }\n        }\n      );\n    } catch (error) {\n      controller.abort();\n      console.warn(`[useWebMCP] registerTool(\"${name}\") rejected:`, error);\n      return;\n    }\n\n    return () => {\n      disposed = true;\n\n      if (registered && TOOL_OWNER_BY_NAME.get(name) === ownerToken) {\n        TOOL_OWNER_BY_NAME.delete(name);\n        controller.abort();\n        return;\n      }\n\n      if (!registered) {\n        controller.abort();\n      }\n    };\n    // Spread operator in dependencies: Allows users to provide additional dependencies\n    // via the `deps` parameter. While unconventional, this pattern is intentional to support\n    // dynamic dependency injection. The spread is safe because deps is validated and warned\n    // about non-primitive values earlier in this hook.\n  }, [name, description, ...(deps ?? [])]);\n\n  return {\n    state,\n    execute: stableExecute,\n    reset,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/useWebMCP.ts"],"sourcesContent":["import {\n  normalizeInputSchema,\n  normalizeToolResponse,\n  type ToolInputSchema,\n} from '@mcp-b/webmcp-polyfill/schema';\nimport type { InputSchema, JsonSchemaForInference } from '@mcp-b/webmcp-types';\nimport type { DependencyList } from 'react';\nimport { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';\nimport type {\n  InferOutput,\n  InferToolInput,\n  ToolExecutionState,\n  WebMCPConfig,\n  WebMCPReturn,\n} from './types.js';\n\nconst INITIAL_STATE = {\n  isExecuting: false,\n  lastResult: null,\n  error: null,\n  executionCount: 0,\n};\n\nconst useIsomorphicLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;\n\n/** Registers a React-owned tool with the current WebMCP model context. */\nexport function useWebMCP<\n  TInputSchema extends ToolInputSchema = InputSchema,\n  TOutputSchema extends JsonSchemaForInference | undefined = undefined,\n>(\n  config: WebMCPConfig<TInputSchema, TOutputSchema>,\n  deps?: DependencyList\n): WebMCPReturn<TOutputSchema, TInputSchema> {\n  type TOutput = InferOutput<TOutputSchema>;\n  type TInput = InferToolInput<TInputSchema>;\n  const { name, description } = config;\n  const [state, setState] = useState<ToolExecutionState<TOutput>>(INITIAL_STATE);\n  const committedConfigRef = useRef(config);\n  const pendingExecutionsRef = useRef(0);\n\n  // MCP calls can arrive after commit but before passive effects. A layout effect\n  // publishes only committed renders; the server fallback avoids the SSR warning.\n  useIsomorphicLayoutEffect(() => {\n    committedConfigRef.current = config;\n  });\n\n  const run = useCallback(async (input: TInput): Promise<TOutput> => {\n    pendingExecutionsRef.current += 1;\n    setState((previous) => ({ ...previous, isExecuting: true, error: null }));\n\n    let result: TOutput;\n    const executionConfig = committedConfigRef.current;\n    try {\n      result = await executionConfig.execute(input);\n      if (\n        executionConfig.outputSchema &&\n        normalizeToolResponse(result).structuredContent === undefined\n      ) {\n        throw new Error(\n          `Tool \"${executionConfig.name}\" outputSchema requires execute to return a JSON-serializable result`\n        );\n      }\n    } catch (error) {\n      pendingExecutionsRef.current -= 1;\n      const normalizedError = error instanceof Error ? error : new Error(String(error));\n      setState((previous) => ({\n        ...previous,\n        isExecuting: pendingExecutionsRef.current > 0,\n        error: normalizedError,\n      }));\n      throw normalizedError;\n    }\n\n    pendingExecutionsRef.current -= 1;\n    setState((previous) => ({\n      isExecuting: pendingExecutionsRef.current > 0,\n      lastResult: result,\n      error: null,\n      executionCount: previous.executionCount + 1,\n    }));\n    return result;\n  }, []);\n\n  const reset = useCallback(\n    () => setState({ ...INITIAL_STATE, isExecuting: pendingExecutionsRef.current > 0 }),\n    []\n  );\n\n  useEffect(() => {\n    const modelContext =\n      typeof document === 'undefined'\n        ? undefined\n        : (document.modelContext ??\n          (typeof navigator === 'undefined' ? undefined : navigator.modelContext));\n    if (!modelContext) {\n      console.warn(\n        `[useWebMCP] document.modelContext is not available. Tool \"${name}\" will not be registered.`\n      );\n      return;\n    }\n\n    const registeredConfig = committedConfigRef.current;\n    const registeredOutputSchema = registeredConfig.outputSchema;\n    const controller = new AbortController();\n    const tool = {\n      name,\n      description,\n      inputSchema: normalizeInputSchema(registeredConfig.inputSchema).inputSchema,\n      ...(registeredOutputSchema && { outputSchema: registeredOutputSchema }),\n      ...(registeredConfig.annotations && { annotations: registeredConfig.annotations }),\n      execute: async (input: TInput) => {\n        try {\n          const response = normalizeToolResponse(await run(input));\n          if (registeredOutputSchema && response.structuredContent === undefined) {\n            throw new Error(\n              `Tool \"${name}\" outputSchema requires the tool implementation to return a JSON-serializable result`\n            );\n          }\n          return response;\n        } catch (error) {\n          const message = error instanceof Error ? error.message : String(error);\n          return {\n            content: [{ type: 'text' as const, text: `Error: ${message}` }],\n            isError: true,\n          };\n        }\n      },\n    };\n\n    try {\n      const registration = modelContext.registerTool(tool, { signal: controller.signal });\n      void Promise.resolve(registration).catch((error: unknown) => {\n        if (!controller.signal.aborted) {\n          controller.abort();\n          console.warn(`[useWebMCP] registerTool(\"${name}\") rejected:`, error);\n        }\n      });\n    } catch (error) {\n      controller.abort();\n      console.warn(`[useWebMCP] registerTool(\"${name}\") rejected:`, error);\n      return;\n    }\n\n    return () => controller.abort();\n    // `deps` lets callers explicitly opt descriptor values into re-registration.\n    // oxlint-disable-next-line react-doctor/exhaustive-deps -- Public API deliberately forwards caller deps.\n  }, [name, description, ...(deps ?? [])]);\n\n  return { state, execute: run, reset };\n}\n"],"mappings":"+MAgBA,MAAM,EAAgB,CACpB,YAAa,GACb,WAAY,KACZ,MAAO,KACP,eAAgB,EACjB,CAEK,EAA4B,OAAO,OAAW,IAAc,EAAY,EAG9E,SAAgB,EAId,EACA,EAC2C,CAG3C,GAAM,CAAE,OAAM,eAAgB,EACxB,CAAC,EAAO,GAAY,EAAsC,EAAc,CACxE,EAAqB,EAAO,EAAO,CACnC,EAAuB,EAAO,EAAE,CAItC,MAAgC,CAC9B,EAAmB,QAAU,GAC7B,CAEF,IAAM,EAAM,EAAY,KAAO,IAAoC,CACjE,EAAqB,SAAW,EAChC,EAAU,IAAc,CAAE,GAAG,EAAU,YAAa,GAAM,MAAO,KAAM,EAAE,CAEzE,IAAI,EACE,EAAkB,EAAmB,QAC3C,GAAI,CAEF,GADA,EAAS,MAAM,EAAgB,QAAQ,EAAM,CAE3C,EAAgB,cAChB,EAAsB,EAAO,CAAC,oBAAsB,IAAA,GAEpD,MAAU,MACR,SAAS,EAAgB,KAAK,sEAC/B,OAEI,EAAO,CACd,IAAqB,QACrB,IAAM,EAAkB,aAAiB,MAAQ,EAAY,MAAM,OAAO,EAAM,CAAC,CAMjF,MALA,EAAU,IAAc,CACtB,GAAG,EACH,YAAa,EAAqB,QAAU,EAC5C,MAAO,EACR,EAAE,CACG,EAUR,MAPA,IAAqB,QACrB,EAAU,IAAc,CACtB,YAAa,EAAqB,QAAU,EAC5C,WAAY,EACZ,MAAO,KACP,eAAgB,EAAS,eAAiB,EAC3C,EAAE,CACI,GACN,EAAE,CAAC,CAEA,EAAQ,MACN,EAAS,CAAE,GAAG,EAAe,YAAa,EAAqB,QAAU,EAAG,CAAC,CACnF,EAAE,CACH,CA8DD,OA5DA,MAAgB,CACd,IAAM,EACJ,OAAO,SAAa,IAChB,IAAA,GACC,SAAS,eACT,OAAO,UAAc,IAAc,IAAA,GAAY,UAAU,cAChE,GAAI,CAAC,EAAc,CACjB,QAAQ,KACN,6DAA6D,EAAK,2BACnE,CACD,OAGF,IAAM,EAAmB,EAAmB,QACtC,EAAyB,EAAiB,aAC1C,EAAa,IAAI,gBACjB,EAAO,CACX,OACA,cACA,YAAa,EAAqB,EAAiB,YAAY,CAAC,YAChE,GAAI,GAA0B,CAAE,aAAc,EAAwB,CACtE,GAAI,EAAiB,aAAe,CAAE,YAAa,EAAiB,YAAa,CACjF,QAAS,KAAO,IAAkB,CAChC,GAAI,CACF,IAAM,EAAW,EAAsB,MAAM,EAAI,EAAM,CAAC,CACxD,GAAI,GAA0B,EAAS,oBAAsB,IAAA,GAC3D,MAAU,MACR,SAAS,EAAK,sFACf,CAEH,OAAO,QACA,EAAO,CAEd,MAAO,CACL,QAAS,CAAC,CAAE,KAAM,OAAiB,KAAM,UAF3B,aAAiB,MAAQ,EAAM,QAAU,OAAO,EAAM,GAEN,CAAC,CAC/D,QAAS,GACV,GAGN,CAED,GAAI,CACF,IAAM,EAAe,EAAa,aAAa,EAAM,CAAE,OAAQ,EAAW,OAAQ,CAAC,CACnF,QAAa,QAAQ,EAAa,CAAC,MAAO,GAAmB,CACtD,EAAW,OAAO,UACrB,EAAW,OAAO,CAClB,QAAQ,KAAK,6BAA6B,EAAK,cAAe,EAAM,GAEtE,OACK,EAAO,CACd,EAAW,OAAO,CAClB,QAAQ,KAAK,6BAA6B,EAAK,cAAe,EAAM,CACpE,OAGF,UAAa,EAAW,OAAO,EAG9B,CAAC,EAAM,EAAa,GAAI,GAAQ,EAAE,CAAE,CAAC,CAEjC,CAAE,QAAO,QAAS,EAAK,QAAO"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "usewebmcp",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Standalone React hooks for strict core WebMCP tool registration with document.modelContext",
   "keywords": [
     "ai",
@@ -29,7 +29,9 @@
     "dist"
   ],
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -41,8 +43,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@mcp-b/webmcp-polyfill": "4.0.0",
-    "@mcp-b/webmcp-types": "4.0.0"
+    "@mcp-b/webmcp-polyfill": "5.0.0",
+    "@mcp-b/webmcp-types": "5.0.0"
   },
   "devDependencies": {
     "@types/node": "22.17.2",
@@ -55,10 +57,14 @@
     "vite-plus": "^0.1.22",
     "vitest": "npm:@voidzero-dev/vite-plus-test@latest",
     "vitest-browser-react": "^2.0.4",
-    "@mcp-b/global": "4.0.0"
+    "zod": "4.4.3",
+    "@mcp-b/global": "5.0.0"
   },
   "peerDependencies": {
-    "react": "^17.0.0 || ^18.0.0 || ^19.0.0"
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "engines": {
+    "node": ">=20"
   },
   "scripts": {
     "build": "vp pack",

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/useWebMCP.ts"],"mappings":";;;;;;;;AAmBA;;;;;;;KAAY,cAAA,MAAoB,CAAA;EAAA,SAAqB,WAAA;IAAA,SAAwB,KAAA;EAAA;AAAA,IACzE,KAAA;EAAA,SAAyB,KAAA;AAAA,IACvB,CAAA,GACA,MAAA,oBACF,CAAA,SAAU,WAAA,GACR,wBAAA,CAAyB,CAAA,IACzB,MAAA;;;;;;;;;;;;KAaM,WAAA,uBACY,sBAAA,iDAEpB,aAAA,qBACA,SAAA,GACA,aAAA,SAAsB,sBAAA,GACpB,eAAA,CAAgB,aAAA,IAChB,SAAA;;;;AAPN;;;;UAgBiB,kBAAA;EAZb;;;;EAiBF,WAAA;EAdI;;;;EAoBJ,UAAA,EAAY,OAAA;EAzBZ;;;;EA+BA,KAAA,EAAO,KAAA;EA3BH;;;;EAiCJ,cAAA;AAAA;;;;;;;;;;;KAaU,mBAAA,sBACW,eAAA,GAAkB,WAAA,wBACjB,sBAAA,6BAEtB,KAAA,EAAO,cAAA,CAAe,YAAA,MACnB,OAAA,CAAQ,WAAA,CAAY,aAAA,KAAkB,WAAA,CAAY,aAAA;;AALvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAKsE;;;;;;;;;;;;;;;;;;;;;UAsD5D,gBAAA,sBACa,eAAA,GAAkB,WAAA,wBACjB,sBAAA;EAYtB;;;;EANA,IAAA;EA2DA;;;;EArDA,WAAA;EAiEgB;;;;;;;;;;;;AAkBuB;;;;;;;;;EA5DvC,WAAA,GAAc,YAAA;EA2EkC;;;;;;;;;;;;;;;;;;;;;;EAnDhD,YAAA,GAAe,aAAA;EAyDX;;;;EAnDJ,WAAA,GAAc,eAAA;EAuDA;;;;;AAiBhB;;;;;EA5DE,YAAA,IAAgB,MAAA,EAAQ,WAAA,CAAY,aAAA;EA+DjB;;;;;;;EAtDnB,SAAA,IAAa,MAAA,EAAQ,WAAA,CAAY,aAAA,GAAgB,KAAA;EAoDjD;;;;;;;EA3CA,OAAA,IAAW,KAAA,EAAO,KAAA,EAAO,KAAA;AAAA;AAAA,KAGtB,0BAAA,sBACkB,eAAA,GAAkB,WAAA,wBACjB,sBAAA;EAyCmB;;;EAnCrC,OAAA,EAAS,mBAAA,CAAoB,YAAA,EAAc,aAAA;EA4CpB;;;EAxCvB,OAAA,GAAU,mBAAA,CAAoB,YAAA,EAAc,aAAA;AAAA;EAgDV;;;EA1ClC,OAAA,EAAS,mBAAA,CAAoB,YAAA,EAAc,aAAA;EAoD9B;;;EAhDb,OAAA,GAAU,mBAAA,CAAoB,YAAA,EAAc,aAAA;AAAA;;;;;;;;;;;;;;;KAiBtC,YAAA,sBACW,eAAA,GAAkB,WAAA,wBACjB,sBAAA,4BACpB,gBAAA,CAAiB,YAAA,EAAc,aAAA,IACjC,0BAAA,CAA2B,YAAA,EAAc,aAAA;;;;;;;;UAS1B,YAAA,uBACO,sBAAA,+CACD,eAAA,GAAkB,WAAA;EChKzB;;;;EDsKd,KAAA,EAAO,kBAAA,CAAmB,WAAA,CAAY,aAAA;ECpKhB;;;;;;;;ED8KtB,OAAA,GAAU,KAAA,EAAO,cAAA,CAAe,YAAA,MAAkB,OAAA,CAAQ,WAAA,CAAY,aAAA;EC1KzD;;;;EDgLb,KAAA;AAAA;;;;AAlTF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;AAgBA;;;;;;;;;;;;;AAoCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBCqDgB,SAAA,sBACO,eAAA,GAAkB,WAAA,wBACjB,sBAAA,yBAAA,CAEtB,MAAA,EAAQ,YAAA,CAAa,YAAA,EAAc,aAAA,GACnC,IAAA,GAAO,cAAA,GACN,YAAA,CAAa,aAAA,EAAe,YAAA"}