@mcp-b/react-webmcp 0.0.0-beta-20260109203913

package/dist/index.d.ts

@@ -0,0 +1,1113 @@
+import { ElicitationFormParams, ElicitationParams, ElicitationParams as ElicitationParams$1, ElicitationResult, ElicitationResult as ElicitationResult$1, ElicitationUrlParams, ModelContext as ModelContextProtocol, PromptDescriptor, ResourceDescriptor, SamplingRequestParams, SamplingRequestParams as SamplingRequestParams$1, SamplingResult, SamplingResult as SamplingResult$1, ToolDescriptor } from "@mcp-b/global";
+import { DependencyList, ReactElement, ReactNode } from "react";
+import { z } from "zod";
+import { CallToolResult, Resource, Resource as Resource$1, ServerCapabilities, ServerCapabilities as ServerCapabilities$1, Tool, Tool as Tool$1 } from "@modelcontextprotocol/sdk/types.js";
+import { PromptMessage, ResourceContents, ToolAnnotations } from "@mcp-b/webmcp-ts-sdk";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+
+//#region src/types.d.ts
+
+/**
+ * Utility type to infer the output type from a Zod schema object.
+ *
+ * When `TOutputSchema` is a non-empty Zod schema object, this resolves to
+ * `z.infer<z.ZodObject<TOutputSchema>>`. When it's empty (`Record<string, never>`),
+ * it falls back to the provided `TFallback` type.
+ *
+ * @template TOutputSchema - Zod schema object for output validation
+ * @template TFallback - Fallback type when no schema is provided
+ * @internal
+ */
+type InferOutput<TOutputSchema extends Record<string, z.ZodTypeAny>, TFallback = unknown> = TOutputSchema extends Record<string, never> ? TFallback : z.infer<z.ZodObject<TOutputSchema>>;
+/**
+ * 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 handler
+ * @public
+ */
+interface ToolExecutionState<TOutput = unknown> {
+  /**
+   * Indicates whether the tool is currently executing.
+   * Use this to show loading states in your UI.
+   */
+  isExecuting: boolean;
+  /**
+   * The result from the most recent successful execution.
+   * Will be `null` if the tool hasn't been executed or last execution failed.
+   */
+  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.
+   */
+  error: Error | null;
+  /**
+   * Total number of times this tool has been executed.
+   * Increments on both successful and failed executions.
+   */
+  executionCount: number;
+}
+/**
+ * Configuration options for the `useWebMCP` hook.
+ *
+ * Defines a tool's metadata, schema, handler, and lifecycle callbacks.
+ * Supports full Zod type inference for both input and output schemas.
+ *
+ * @template TInputSchema - Zod schema object defining input parameters
+ * @template TOutputSchema - Zod schema object defining output structure (enables structuredContent)
+ *
+ * @public
+ *
+ * @example Basic tool without output schema:
+ * ```typescript
+ * const config: WebMCPConfig = {
+ *   name: 'posts_like',
+ *   description: 'Like a post by its ID',
+ *   inputSchema: {
+ *     postId: z.string().uuid(),
+ *   },
+ *   handler: async ({ postId }) => {
+ *     await api.likePost(postId);
+ *     return { success: true };
+ *   },
+ * };
+ * ```
+ *
+ * @example Tool with output schema (enables MCP structuredContent):
+ * ```typescript
+ * const config: WebMCPConfig<
+ *   { postId: z.ZodString },
+ *   { likes: z.ZodNumber; likedAt: z.ZodString }
+ * > = {
+ *   name: 'posts_like',
+ *   description: 'Like a post and return updated like count',
+ *   inputSchema: {
+ *     postId: z.string().uuid(),
+ *   },
+ *   outputSchema: {
+ *     likes: z.number().describe('Updated like count'),
+ *     likedAt: z.string().describe('ISO timestamp of the like'),
+ *   },
+ *   // Handler return type is inferred from outputSchema
+ *   handler: async ({ postId }) => {
+ *     const result = await api.likePost(postId);
+ *     return { likes: result.likes, likedAt: new Date().toISOString() };
+ *   },
+ * };
+ * ```
+ */
+interface WebMCPConfig<TInputSchema extends Record<string, z.ZodTypeAny> = Record<string, never>, TOutputSchema extends Record<string, z.ZodTypeAny> = Record<string, never>> {
+  /**
+   * Unique identifier for the tool (e.g., 'posts_like', 'graph_navigate').
+   * Must follow naming conventions: lowercase with underscores.
+   */
+  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: string;
+  /**
+   * Zod schema object defining the input parameters for the tool.
+   * Each key is a parameter name, and the value is a Zod type definition.
+   *
+   * @example
+   * ```typescript
+   * inputSchema: {
+   *   postId: z.string().uuid().describe('The ID of the post to like'),
+   *   userId: z.string().optional(),
+   * }
+   * ```
+   */
+  inputSchema?: TInputSchema;
+  /**
+   * **Recommended:** Zod schema object defining the expected output structure.
+   *
+   * When provided, this enables three key features:
+   * 1. **Type Safety**: The handler's 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
+   *
+   * This is the recommended way to define tool outputs. The schema provides
+   * both compile-time type checking and runtime structure for MCP clients.
+   *
+   * @see {@link https://spec.modelcontextprotocol.io/specification/server/tools/#output-schemas}
+   *
+   * @example
+   * ```typescript
+   * outputSchema: {
+   *   counter: z.number().describe('The current counter value'),
+   *   timestamp: z.string().describe('ISO timestamp'),
+   *   metadata: z.object({
+   *     updatedBy: z.string(),
+   *   }).describe('Additional metadata'),
+   * }
+   * ```
+   */
+  outputSchema?: TOutputSchema;
+  /**
+   * Optional metadata annotations providing hints about tool behavior.
+   * See {@link ToolAnnotations} for available options.
+   */
+  annotations?: ToolAnnotations;
+  /**
+   * The function that executes when the tool is called.
+   * Can be synchronous or asynchronous.
+   *
+   * When `outputSchema` is provided, the return type is inferred from the schema.
+   * Otherwise, any return type is allowed.
+   *
+   * @param input - Validated input parameters matching the inputSchema
+   * @returns The result data or a Promise resolving to the result
+   */
+  handler: (input: z.infer<z.ZodObject<TInputSchema>>) => Promise<InferOutput<TOutputSchema>> | InferOutput<TOutputSchema>;
+  /**
+   * 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 handler
+   * @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 handler
+   * @param input - The input that was passed to the handler
+   */
+  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 handler
+   */
+  onError?: (error: Error, input: unknown) => void;
+}
+/**
+ * Return value from the `useWebMCP` hook.
+ * Provides access to execution state and methods for manual tool control.
+ *
+ * @template TOutputSchema - Zod schema object defining output structure
+ * @public
+ */
+interface WebMCPReturn<TOutputSchema extends Record<string, z.ZodTypeAny> = Record<string, never>> {
+  /**
+   * 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 handler throws
+   */
+  execute: (input: unknown) => Promise<InferOutput<TOutputSchema>>;
+  /**
+   * Reset the execution state to its initial values.
+   * Clears results, errors, and resets the execution count.
+   */
+  reset: () => void;
+}
+/**
+ * Configuration options for the `useWebMCPPrompt` hook.
+ * Defines a prompt's metadata, argument schema, and message generator.
+ *
+ * @template TArgsSchema - Zod schema object defining prompt arguments
+ * @public
+ *
+ * @example
+ * ```typescript
+ * const config: WebMCPPromptConfig = {
+ *   name: 'review_code',
+ *   description: 'Review code for best practices',
+ *   argsSchema: {
+ *     code: z.string().describe('The code to review'),
+ *     language: z.string().optional().describe('Programming language'),
+ *   },
+ *   get: async ({ code, language }) => ({
+ *     messages: [{
+ *       role: 'user',
+ *       content: { type: 'text', text: `Review this ${language ?? ''} code:\n${code}` }
+ *     }]
+ *   }),
+ * };
+ * ```
+ */
+interface WebMCPPromptConfig<TArgsSchema extends Record<string, z.ZodTypeAny> = Record<string, never>> {
+  /**
+   * Unique identifier for the prompt (e.g., 'review_code', 'summarize_text').
+   */
+  name: string;
+  /**
+   * Optional description explaining what the prompt does.
+   * This helps AI assistants understand when to use the prompt.
+   */
+  description?: string;
+  /**
+   * Optional Zod schema object defining the arguments for the prompt.
+   * Each key is an argument name, and the value is a Zod type definition.
+   */
+  argsSchema?: TArgsSchema;
+  /**
+   * Function that generates the prompt messages.
+   * Can be synchronous or asynchronous.
+   *
+   * @param args - Validated arguments matching the argsSchema
+   * @returns Object containing the prompt messages
+   */
+  get: (args: z.infer<z.ZodObject<TArgsSchema>>) => Promise<{
+    messages: PromptMessage[];
+  }> | {
+    messages: PromptMessage[];
+  };
+}
+/**
+ * Return value from the `useWebMCPPrompt` hook.
+ * Indicates whether the prompt is registered.
+ *
+ * @public
+ */
+interface WebMCPPromptReturn {
+  /**
+   * Whether the prompt is currently registered with the Model Context API.
+   */
+  isRegistered: boolean;
+}
+/**
+ * Configuration options for the `useWebMCPResource` hook.
+ * Defines a resource's metadata and read handler.
+ *
+ * @public
+ *
+ * @example Static resource
+ * ```typescript
+ * const config: WebMCPResourceConfig = {
+ *   uri: 'config://app-settings',
+ *   name: 'App Settings',
+ *   description: 'Application configuration',
+ *   mimeType: 'application/json',
+ *   read: async (uri) => ({
+ *     contents: [{ uri: uri.href, text: JSON.stringify(settings) }]
+ *   }),
+ * };
+ * ```
+ *
+ * @example Dynamic resource with URI template
+ * ```typescript
+ * const config: WebMCPResourceConfig = {
+ *   uri: 'user://{userId}/profile',
+ *   name: 'User Profile',
+ *   description: 'User profile data',
+ *   read: async (uri, params) => ({
+ *     contents: [{
+ *       uri: uri.href,
+ *       text: JSON.stringify(await fetchUser(params?.userId ?? ''))
+ *     }]
+ *   }),
+ * };
+ * ```
+ */
+interface WebMCPResourceConfig {
+  /**
+   * The resource URI or URI template.
+   * - Static: "config://app-settings"
+   * - Template: "user://{userId}/profile" where {userId} becomes a parameter
+   */
+  uri: string;
+  /**
+   * Human-readable name for the resource.
+   */
+  name: string;
+  /**
+   * Optional description of what the resource provides.
+   */
+  description?: string;
+  /**
+   * Optional MIME type of the resource content.
+   */
+  mimeType?: string;
+  /**
+   * Function that reads and returns the resource content.
+   *
+   * @param uri - The resolved URI being requested
+   * @param params - Parameters extracted from URI template (if applicable)
+   * @returns Resource contents with the data
+   */
+  read: (uri: URL, params?: Record<string, string>) => Promise<{
+    contents: ResourceContents[];
+  }>;
+}
+/**
+ * Return value from the `useWebMCPResource` hook.
+ * Indicates whether the resource is registered.
+ *
+ * @public
+ */
+interface WebMCPResourceReturn {
+  /**
+   * Whether the resource is currently registered with the Model Context API.
+   */
+  isRegistered: boolean;
+}
+//#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.navigator.modelContext`
+ * - Manages execution state (loading, results, errors)
+ * - Validates input using Zod schemas
+ * - 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: { userId: z.string() },
+ *   outputSchema: {
+ *     id: z.string(),
+ *     name: z.string(),
+ *     email: z.string().email(),
+ *   },
+ *   handler: 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:
+ *
+ * - **Memoized JSON conversion**: Zod-to-JSON schema conversions are memoized to
+ *   avoid recomputation on every render.
+ *
+ * - **Ref-based callbacks**: `handler`, `onSuccess`, `onError`, and `formatOutput`
+ *   are stored in refs, so changing these functions won't trigger re-registration.
+ *
+ * **IMPORTANT**: If `inputSchema`, `outputSchema`, or `annotations` are defined inline
+ * or change on every render, the tool will re-register unnecessarily. To avoid this,
+ * memoize these values using `useMemo` or define them outside your component:
+ *
+ * ```tsx
+ * // Good: Memoized schema (won't change unless deps change)
+ * const outputSchema = useMemo(() => ({
+ *   count: z.number(),
+ *   items: z.array(z.string()),
+ * }), []);
+ *
+ * // Good: Static schema defined outside component
+ * const OUTPUT_SCHEMA = {
+ *   count: z.number(),
+ *   items: z.array(z.string()),
+ * };
+ *
+ * // Bad: Inline schema (creates new object every render)
+ * useWebMCP({
+ *   outputSchema: { count: z.number() }, // Re-registers every render!
+ * });
+ * ```
+ *
+ * **What triggers re-registration:**
+ * - Changes to `name` or `description`
+ * - Changes to `inputSchema`, `outputSchema`, or `annotations` (reference comparison)
+ * - Changes to any value in the `deps` argument (reference comparison)
+ *
+ * **What does NOT trigger re-registration:**
+ * - Changes to `handler`, `onSuccess`, `onError`, or `formatOutput` functions
+ *
+ * @template TInputSchema - Zod schema object defining input parameter types
+ * @template TOutputSchema - Zod schema object defining output structure (enables structuredContent)
+ *
+ * @param config - Configuration object for the tool
+ * @param deps - Optional dependency array that triggers tool re-registration when values change.
+ *   Similar to React's `useEffect` dependencies. When any value changes (by reference),
+ *   the tool will be unregistered and re-registered. Prefer primitive values over
+ *   objects/arrays to minimize re-registrations.
+ *
+ * @returns Object containing execution state and control methods
+ *
+ * @remarks
+ * The hook uses React refs to store callbacks (`handler`, `onSuccess`, `onError`, `formatOutput`)
+ * which prevents re-registration when these functions change. This is a performance optimization
+ * that follows the "latest ref" pattern.
+ *
+ * When `outputSchema` is provided, the MCP response includes both text content and
+ * `structuredContent` per the MCP specification. The type system ensures that the handler's
+ * return type matches the output schema through Zod's type inference.
+ *
+ * @public
+ *
+ * @example
+ * Basic tool with outputSchema (recommended):
+ * ```tsx
+ * function PostActions() {
+ *   const likeTool = useWebMCP({
+ *     name: 'posts_like',
+ *     description: 'Like a post by ID',
+ *     inputSchema: {
+ *       postId: z.string().uuid().describe('The ID of the post to like'),
+ *     },
+ *     outputSchema: {
+ *       success: z.boolean().describe('Whether the like was successful'),
+ *       likeCount: z.number().describe('Updated like count'),
+ *     },
+ *     handler: async ({ postId }) => {
+ *       const result = await api.posts.like(postId);
+ *       return { success: true, likeCount: result.likes };
+ *     },
+ *   });
+ *
+ *   // likeTool.state.lastResult is typed as { success: boolean; likeCount: number } | null
+ *   if (likeTool.state.isExecuting) {
+ *     return <Spinner />;
+ *   }
+ *
+ *   return <div>Likes: {likeTool.state.lastResult?.likeCount ?? 0}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * Tool with annotations and callbacks:
+ * ```tsx
+ * const deleteTool = useWebMCP({
+ *   name: 'posts_delete',
+ *   description: 'Delete a post permanently',
+ *   inputSchema: {
+ *     postId: z.string().uuid(),
+ *   },
+ *   outputSchema: {
+ *     deleted: z.boolean(),
+ *     deletedAt: z.string().describe('ISO timestamp of deletion'),
+ *   },
+ *   annotations: {
+ *     destructiveHint: true,
+ *     idempotentHint: false,
+ *   },
+ *   handler: async ({ postId }) => {
+ *     await api.posts.delete(postId);
+ *     return { deleted: true, deletedAt: new Date().toISOString() };
+ *   },
+ *   onSuccess: () => {
+ *     navigate('/posts');
+ *     toast.success('Post deleted');
+ *   },
+ *   onError: (error) => {
+ *     toast.error(`Failed to delete: ${error.message}`);
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * Tool with deps for automatic re-registration:
+ * ```tsx
+ * function SitesManager({ sites }: { sites: Site[] }) {
+ *   // Without deps, you'd need getter functions like: getSiteCount: () => sites.length
+ *   // With deps, values can be used directly in description and handler
+ *   const sitesTool = useWebMCP(
+ *     {
+ *       name: 'sites_query',
+ *       description: `Query available sites. Current count: ${sites.length}`,
+ *       outputSchema: {
+ *         count: z.number(),
+ *         sites: z.array(z.object({ id: z.string(), name: z.string() })),
+ *       },
+ *       handler: async () => ({
+ *         count: sites.length,
+ *         sites: sites.map(s => ({ id: s.id, name: s.name })),
+ *       }),
+ *     },
+ *     [sites] // Re-register tool when sites array changes (by reference)
+ *   );
+ *
+ *   return <SitesList sites={sites} />;
+ * }
+ * ```
+ *
+ * @example
+ * Optimizing with memoization and deps:
+ * ```tsx
+ * function OptimizedSites({ sites }: { sites: Site[] }) {
+ *   // Memoize schema to prevent re-registration on every render
+ *   const outputSchema = useMemo(() => ({
+ *     sites: z.array(z.object({ id: z.string(), name: z.string() })),
+ *   }), []);
+ *
+ *   // Use primitive values in deps for better control
+ *   const siteIds = sites.map(s => s.id).join(',');
+ *   const siteCount = sites.length;
+ *
+ *   const sitesTool = useWebMCP(
+ *     {
+ *       name: 'sites_query',
+ *       description: `Query ${siteCount} available sites`,
+ *       outputSchema,
+ *       handler: async () => ({
+ *         sites: sites.map(s => ({ id: s.id, name: s.name })),
+ *       }),
+ *     },
+ *     [siteIds, siteCount] // Only re-register when IDs or count actually change
+ *   );
+ *
+ *   return <SitesList sites={sites} />;
+ * }
+ * ```
+ */
+declare function useWebMCP<TInputSchema extends Record<string, z.ZodTypeAny> = Record<string, never>, TOutputSchema extends Record<string, z.ZodTypeAny> = Record<string, never>>(config: WebMCPConfig<TInputSchema, TOutputSchema>, deps?: DependencyList): WebMCPReturn<TOutputSchema>;
+//#endregion
+//#region src/useWebMCPContext.d.ts
+/**
+ * Convenience hook for exposing read-only context data to AI assistants.
+ *
+ * This is a simplified wrapper around {@link useWebMCP} specifically designed for
+ * context tools that expose data without performing actions. The hook automatically
+ * configures appropriate annotations (read-only, idempotent) and handles value
+ * serialization.
+ *
+ * Note: This hook does not use an output schema, so the result will not include
+ * `structuredContent` in the MCP response. Use {@link useWebMCP} directly with
+ * `outputSchema` if you need structured output for MCP compliance.
+ *
+ * @template T - The type of context data to expose
+ *
+ * @param name - Unique identifier for the context tool (e.g., 'context_current_post')
+ * @param description - Human-readable description of the context for AI assistants
+ * @param getValue - Function that returns the current context value
+ * @returns Tool execution state and control methods
+ *
+ * @public
+ *
+ * @example
+ * Expose current post context:
+ * ```tsx
+ * function PostDetailPage() {
+ *   const { postId } = useParams();
+ *   const { data: post } = useQuery(['post', postId], () => fetchPost(postId));
+ *
+ *   useWebMCPContext(
+ *     'context_current_post',
+ *     'Get the currently viewed post ID and metadata',
+ *     () => ({
+ *       postId,
+ *       title: post?.title,
+ *       author: post?.author,
+ *       tags: post?.tags,
+ *       createdAt: post?.createdAt,
+ *     })
+ *   );
+ *
+ *   return <PostContent post={post} />;
+ * }
+ * ```
+ *
+ * @example
+ * Expose user session context:
+ * ```tsx
+ * function AppRoot() {
+ *   const { user, isAuthenticated } = useAuth();
+ *
+ *   useWebMCPContext(
+ *     'context_user_session',
+ *     'Get the current user session information',
+ *     () => ({
+ *       isAuthenticated,
+ *       userId: user?.id,
+ *       email: user?.email,
+ *       permissions: user?.permissions,
+ *     })
+ *   );
+ *
+ *   return <App />;
+ * }
+ * ```
+ */
+declare function useWebMCPContext<T>(name: string, description: string, getValue: () => T): WebMCPReturn;
+//#endregion
+//#region src/useWebMCPPrompt.d.ts
+/**
+ * React hook for registering Model Context Protocol (MCP) prompts.
+ *
+ * This hook handles the complete lifecycle of an MCP prompt:
+ * - Registers the prompt with `window.navigator.modelContext`
+ * - Converts Zod schemas to JSON Schema for argument validation
+ * - Automatically unregisters on component unmount
+ *
+ * @template TArgsSchema - Zod schema object defining argument types
+ *
+ * @param config - Configuration object for the prompt
+ * @returns Object indicating registration status
+ *
+ * @public
+ *
+ * @example
+ * Simple prompt without arguments:
+ * ```tsx
+ * function HelpPrompt() {
+ *   const { isRegistered } = useWebMCPPrompt({
+ *     name: 'help',
+ *     description: 'Get help with using the application',
+ *     get: async () => ({
+ *       messages: [{
+ *         role: 'user',
+ *         content: { type: 'text', text: 'How do I use this application?' }
+ *       }]
+ *     }),
+ *   });
+ *
+ *   return <div>Help prompt {isRegistered ? 'ready' : 'loading'}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * Prompt with typed arguments:
+ * ```tsx
+ * function CodeReviewPrompt() {
+ *   const { isRegistered } = useWebMCPPrompt({
+ *     name: 'review_code',
+ *     description: 'Review code for best practices',
+ *     argsSchema: {
+ *       code: z.string().describe('The code to review'),
+ *       language: z.string().optional().describe('Programming language'),
+ *     },
+ *     get: async ({ code, language }) => ({
+ *       messages: [{
+ *         role: 'user',
+ *         content: {
+ *           type: 'text',
+ *           text: `Please review this ${language ?? ''} code:\n\n${code}`
+ *         }
+ *       }]
+ *     }),
+ *   });
+ *
+ *   return <div>Code review prompt {isRegistered ? 'ready' : 'loading'}</div>;
+ * }
+ * ```
+ */
+declare function useWebMCPPrompt<TArgsSchema extends Record<string, z.ZodTypeAny> = Record<string, never>>(config: WebMCPPromptConfig<TArgsSchema>): WebMCPPromptReturn;
+//#endregion
+//#region src/useWebMCPResource.d.ts
+/**
+ * React hook for registering Model Context Protocol (MCP) resources.
+ *
+ * This hook handles the complete lifecycle of an MCP resource:
+ * - Registers the resource with `window.navigator.modelContext`
+ * - Supports both static URIs and URI templates with parameters
+ * - Automatically unregisters on component unmount
+ *
+ * @param config - Configuration object for the resource
+ * @returns Object indicating registration status
+ *
+ * @public
+ *
+ * @example
+ * Static resource:
+ * ```tsx
+ * function AppSettingsResource() {
+ *   const { isRegistered } = useWebMCPResource({
+ *     uri: 'config://app-settings',
+ *     name: 'App Settings',
+ *     description: 'Application configuration',
+ *     mimeType: 'application/json',
+ *     read: async (uri) => ({
+ *       contents: [{
+ *         uri: uri.href,
+ *         text: JSON.stringify({ theme: 'dark', language: 'en' })
+ *       }]
+ *     }),
+ *   });
+ *
+ *   return <div>Settings resource {isRegistered ? 'ready' : 'loading'}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * Dynamic resource with URI template:
+ * ```tsx
+ * function UserProfileResource() {
+ *   const { isRegistered } = useWebMCPResource({
+ *     uri: 'user://{userId}/profile',
+ *     name: 'User Profile',
+ *     description: 'User profile data by ID',
+ *     mimeType: 'application/json',
+ *     read: async (uri, params) => {
+ *       const userId = params?.userId ?? '';
+ *       const profile = await fetchUserProfile(userId);
+ *       return {
+ *         contents: [{
+ *           uri: uri.href,
+ *           text: JSON.stringify(profile)
+ *         }]
+ *       };
+ *     },
+ *   });
+ *
+ *   return <div>User profile resource {isRegistered ? 'ready' : 'loading'}</div>;
+ * }
+ * ```
+ */
+declare function useWebMCPResource(config: WebMCPResourceConfig): WebMCPResourceReturn;
+//#endregion
+//#region src/useElicitationHandler.d.ts
+/**
+ * State for elicitation requests, tracking the current request and results.
+ */
+interface ElicitationState {
+  /** Whether an elicitation request is currently in progress */
+  isLoading: boolean;
+  /** The last elicitation result received */
+  result: ElicitationResult$1 | null;
+  /** Any error that occurred during the last request */
+  error: Error | null;
+  /** Total number of requests made */
+  requestCount: number;
+}
+/**
+ * Configuration options for the useElicitation hook.
+ */
+interface UseElicitationConfig {
+  /**
+   * Optional callback invoked when an elicitation request completes successfully.
+   */
+  onSuccess?: (result: ElicitationResult$1) => void;
+  /**
+   * Optional callback invoked when an elicitation request fails.
+   */
+  onError?: (error: Error) => void;
+}
+/**
+ * Return value from the useElicitation hook.
+ */
+interface UseElicitationReturn {
+  /** Current state of elicitation */
+  state: ElicitationState;
+  /** Function to request user input from the connected client */
+  elicitInput: (params: ElicitationParams$1) => Promise<ElicitationResult$1>;
+  /** Reset the state */
+  reset: () => void;
+}
+/**
+ * React hook for requesting user input from the connected MCP client.
+ *
+ * Elicitation allows the server (webpage) to request user input from the
+ * connected client. This is useful when the page needs additional information
+ * from the user, such as API keys, configuration options, or confirmations.
+ *
+ * There are two modes:
+ * 1. **Form mode**: For non-sensitive data collection using a schema-driven form.
+ * 2. **URL mode**: For sensitive data collection via a web URL (API keys, OAuth, etc.).
+ *
+ * @param config - Optional configuration including callbacks
+ * @returns Object containing state and the elicitInput function
+ *
+ * @example Form elicitation:
+ * ```tsx
+ * function ConfigForm() {
+ *   const { state, elicitInput } = useElicitation({
+ *     onSuccess: (result) => console.log('Got input:', result),
+ *     onError: (error) => console.error('Elicitation failed:', error),
+ *   });
+ *
+ *   const handleConfigure = async () => {
+ *     const result = await elicitInput({
+ *       message: 'Please provide your configuration',
+ *       requestedSchema: {
+ *         type: 'object',
+ *         properties: {
+ *           apiKey: { type: 'string', title: 'API Key', description: 'Your API key' },
+ *           model: { type: 'string', enum: ['gpt-4', 'gpt-3.5'], title: 'Model' }
+ *         },
+ *         required: ['apiKey']
+ *       }
+ *     });
+ *
+ *     if (result.action === 'accept') {
+ *       console.log('Config:', result.content);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleConfigure} disabled={state.isLoading}>
+ *       Configure
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example URL elicitation (for sensitive data):
+ * ```tsx
+ * const { elicitInput } = useElicitation();
+ *
+ * const handleOAuth = async () => {
+ *   const result = await elicitInput({
+ *     mode: 'url',
+ *     message: 'Please authenticate with GitHub',
+ *     elicitationId: 'github-oauth-123',
+ *     url: 'https://github.com/login/oauth/authorize?client_id=...'
+ *   });
+ *
+ *   if (result.action === 'accept') {
+ *     console.log('OAuth completed');
+ *   }
+ * };
+ * ```
+ */
+declare function useElicitation(config?: UseElicitationConfig): UseElicitationReturn;
+//#endregion
+//#region src/useSamplingHandler.d.ts
+/**
+ * State for sampling requests, tracking the current request and results.
+ */
+interface SamplingState {
+  /** Whether a sampling request is currently in progress */
+  isLoading: boolean;
+  /** The last sampling result received */
+  result: SamplingResult$1 | null;
+  /** Any error that occurred during the last request */
+  error: Error | null;
+  /** Total number of requests made */
+  requestCount: number;
+}
+/**
+ * Configuration options for the useSampling hook.
+ */
+interface UseSamplingConfig {
+  /**
+   * Optional callback invoked when a sampling request completes successfully.
+   */
+  onSuccess?: (result: SamplingResult$1) => void;
+  /**
+   * Optional callback invoked when a sampling request fails.
+   */
+  onError?: (error: Error) => void;
+}
+/**
+ * Return value from the useSampling hook.
+ */
+interface UseSamplingReturn {
+  /** Current state of sampling */
+  state: SamplingState;
+  /** Function to request LLM completion from the connected client */
+  createMessage: (params: SamplingRequestParams$1) => Promise<SamplingResult$1>;
+  /** Reset the state */
+  reset: () => void;
+}
+/**
+ * React hook for requesting LLM completions from the connected MCP client.
+ *
+ * Sampling allows the server (webpage) to request LLM completions from the
+ * connected client. This is useful when the page needs AI capabilities like
+ * summarization, generation, or analysis.
+ *
+ * @param config - Optional configuration including callbacks
+ * @returns Object containing state and the createMessage function
+ *
+ * @example Basic usage:
+ * ```tsx
+ * function AIAssistant() {
+ *   const { state, createMessage } = useSampling({
+ *     onSuccess: (result) => console.log('Got response:', result),
+ *     onError: (error) => console.error('Sampling failed:', error),
+ *   });
+ *
+ *   const handleAsk = async () => {
+ *     const result = await createMessage({
+ *       messages: [
+ *         { role: 'user', content: { type: 'text', text: 'What is 2+2?' } }
+ *       ],
+ *       maxTokens: 100,
+ *     });
+ *     console.log(result.content);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleAsk} disabled={state.isLoading}>
+ *         Ask AI
+ *       </button>
+ *       {state.result && <p>{JSON.stringify(state.result.content)}</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useSampling(config?: UseSamplingConfig): UseSamplingReturn;
+//#endregion
+//#region src/client/McpClientProvider.d.ts
+/**
+ * Context value provided by McpClientProvider.
+ *
+ * @internal
+ */
+interface McpClientContextValue {
+  client: Client;
+  tools: Tool$1[];
+  resources: Resource$1[];
+  isConnected: boolean;
+  isLoading: boolean;
+  error: Error | null;
+  capabilities: ServerCapabilities$1 | null;
+  reconnect: () => Promise<void>;
+}
+/**
+ * Props for the McpClientProvider component.
+ *
+ * @public
+ */
+interface McpClientProviderProps {
+  /**
+   * React children to render within the provider.
+   */
+  children: ReactNode;
+  /**
+   * MCP Client instance to use for communication.
+   */
+  client: Client;
+  /**
+   * Transport instance for the client to connect through.
+   */
+  transport: Transport;
+  /**
+   * Optional request options for the connection.
+   */
+  opts?: RequestOptions;
+}
+/**
+ * Provider component that manages an MCP client connection and exposes
+ * tools, resources, and connection state to child components.
+ *
+ * This provider handles:
+ * - Establishing and maintaining the MCP client connection
+ * - Fetching available tools and resources from the server
+ * - Listening for server notifications about tool/resource changes
+ * - Managing connection state and errors
+ * - Automatic cleanup on unmount
+ *
+ * @param props - Component props
+ * @returns Provider component wrapping children
+ *
+ * @public
+ *
+ * @example
+ * Connect to an MCP server via tab transport:
+ * ```tsx
+ * import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+ * import { TabClientTransport } from '@mcp-b/transports';
+ * import { McpClientProvider } from '@mcp-b/react-webmcp';
+ *
+ * const client = new Client(
+ *   { name: 'my-app', version: '1.0.0' },
+ *   { capabilities: {} }
+ * );
+ *
+ * const transport = new TabClientTransport('mcp', {
+ *   clientInstanceId: 'my-app-instance',
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <McpClientProvider client={client} transport={transport}>
+ *       <MyAppContent />
+ *     </McpClientProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Access tools from child components:
+ * ```tsx
+ * function MyAppContent() {
+ *   const { tools, isConnected, isLoading } = useMcpClient();
+ *
+ *   if (isLoading) {
+ *     return <div>Connecting to MCP server...</div>;
+ *   }
+ *
+ *   if (!isConnected) {
+ *     return <div>Failed to connect to MCP server</div>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <h2>Available Tools:</h2>
+ *       <ul>
+ *         {tools.map(tool => (
+ *           <li key={tool.name}>{tool.description}</li>
+ *         ))}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function McpClientProvider({
+  children,
+  client,
+  transport,
+  opts
+}: McpClientProviderProps): ReactElement;
+/**
+ * Hook to access the MCP client context.
+ * Must be used within an {@link McpClientProvider}.
+ *
+ * @returns The MCP client context including client instance, tools, resources, and connection state
+ * @throws Error if used outside of McpClientProvider
+ *
+ * @public
+ *
+ * @example
+ * ```tsx
+ * function ToolsList() {
+ *   const { tools, isConnected, error, reconnect } = useMcpClient();
+ *
+ *   if (error) {
+ *     return (
+ *       <div>
+ *         Error: {error.message}
+ *         <button onClick={reconnect}>Retry</button>
+ *       </div>
+ *     );
+ *   }
+ *
+ *   if (!isConnected) {
+ *     return <div>Not connected</div>;
+ *   }
+ *
+ *   return (
+ *     <ul>
+ *       {tools.map(tool => (
+ *         <li key={tool.name}>{tool.description}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+declare function useMcpClient(): McpClientContextValue;
+//#endregion
+export { type CallToolResult, type ElicitationFormParams, type ElicitationState as ElicitationHandlerState, type ElicitationState, type ElicitationParams, type ElicitationResult, type ElicitationUrlParams, type InferOutput, McpClientProvider, type McpClientProviderProps, type ModelContextProtocol, type PromptDescriptor, type PromptMessage, type Resource, type ResourceContents, type ResourceDescriptor, type SamplingState as SamplingHandlerState, type SamplingState, type SamplingRequestParams, type SamplingResult, type ServerCapabilities, type Tool, type ToolAnnotations, type ToolDescriptor, type ToolExecutionState, type UseElicitationConfig, type UseElicitationConfig as UseElicitationHandlerConfig, type UseElicitationReturn as UseElicitationHandlerReturn, type UseElicitationReturn, type UseSamplingConfig, type UseSamplingConfig as UseSamplingHandlerConfig, type UseSamplingReturn as UseSamplingHandlerReturn, type UseSamplingReturn, type WebMCPConfig, type WebMCPPromptConfig, type WebMCPPromptReturn, type WebMCPResourceConfig, type WebMCPResourceReturn, type WebMCPReturn, useElicitation, useElicitation as useElicitationHandler, useMcpClient, useSampling, useSampling as useSamplingHandler, useWebMCP, useWebMCPContext, useWebMCPPrompt, useWebMCPResource };
+//# sourceMappingURL=index.d.ts.map