From c4683f57a300c64e805786ddf4b8827fb3704a39 Mon Sep 17 00:00:00 2001 From: docs-syncer-npm-packages Date: Sat, 13 Jun 2026 01:42:36 +0000 Subject: [PATCH 1/3] docs: sync @mcp-b/react-webmcp overview from npm-packages@bf03420 --- docs/packages/react-webmcp/overview.mdx | 156 ++++++++++++++++++++++++ 1 file changed, 156 insertions(+) create mode 100644 docs/packages/react-webmcp/overview.mdx diff --git a/docs/packages/react-webmcp/overview.mdx b/docs/packages/react-webmcp/overview.mdx new file mode 100644 index 0000000..c3e1682 --- /dev/null +++ b/docs/packages/react-webmcp/overview.mdx @@ -0,0 +1,156 @@ +--- +title: "@mcp-b/react-webmcp Overview" +description: "React hooks for Model Context Protocol (MCP) - Let AI agents like Claude, ChatGPT, Cursor, and Copilot control your React components" +--- + +> React hooks for Model Context Protocol (MCP) - Let AI agents like Claude, ChatGPT, Cursor, and Copilot control your React components + +[![npm version](https://img.shields.io/npm/v/@mcp-b/react-webmcp?style=flat-square)](https://www.npmjs.com/package/@mcp-b/react-webmcp) +[![npm downloads](https://img.shields.io/npm/dm/@mcp-b/react-webmcp?style=flat-square)](https://www.npmjs.com/package/@mcp-b/react-webmcp) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT) +[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?style=flat-square)](https://www.typescriptlang.org/) +[![React](https://img.shields.io/badge/React-18+-61DAFB?style=flat-square&logo=react)](https://reactjs.org/) + +**[Full Documentation](https://docs.mcp-b.ai/packages/react-webmcp)** | **[Quick Start](https://docs.mcp-b.ai/quickstart)** | **[AI Framework Integration](https://docs.mcp-b.ai/ai-frameworks)** + +**@mcp-b/react-webmcp** provides React hooks that expose your components as AI-callable tools via the Model Context Protocol. Build AI-powered React applications where Claude, ChatGPT, Gemini, Cursor, and Copilot can interact with your app's functionality. + +## Why Use @mcp-b/react-webmcp? + +| Feature | Benefit | +| ---------------------------- | ---------------------------------------------------------------------------- | +| **React-First Design** | Hooks follow React patterns with automatic cleanup and StrictMode support | +| **Type-Safe with Zod** | Full TypeScript support with Zod schema validation for inputs/outputs | +| **Two-Way Integration** | Both expose tools TO AI agents AND consume tools FROM MCP servers | +| **Execution State Tracking** | Built-in loading, success, and error states for UI feedback | +| **Works with Any AI** | Compatible with Claude, ChatGPT, Gemini, Cursor, Copilot, and any MCP client | + +## Installation + +```bash +pnpm add @mcp-b/react-webmcp zod +``` + +If you only want strict core WebMCP hooks (without MCP-B extension APIs like prompts/resources/sampling/elicitation), use `usewebmcp` instead. + +For client functionality, you'll also need: + +```bash +pnpm add @mcp-b/transports @modelcontextprotocol/sdk +``` + +**Prerequisites:** Provider hooks require the `document.modelContext` API. Install `@mcp-b/global` or use a browser that implements the Web Model Context API. + +Provider hooks register tools with `document.modelContext.registerTool(tool, { signal })` and abort the controller on unmount. The hooks retain a `navigator.modelContext` fallback for older preview runtimes, but `document.modelContext` is the canonical v3 surface. On Chrome Beta 147 native (which ignores the second arg) cleanup cannot remove the tool. Install `@mcp-b/global` for spec-aligned behavior. + +## Quick Start - Provider (Registering Tools) + +```tsx +import { useWebMCP } from '@mcp-b/react-webmcp'; +import { z } from 'zod'; + +function PostsPage() { + const likeTool = useWebMCP({ + name: 'posts_like', + description: 'Like a post by ID. Increments the like count.', + inputSchema: { + postId: z.string().uuid().describe('The post ID to like'), + }, + annotations: { + title: 'Like Post', + readOnlyHint: false, + idempotentHint: true, + }, + handler: async (input) => { + await api.posts.like(input.postId); + return { success: true, postId: input.postId }; + }, + formatOutput: (result) => `Post ${result.postId} liked successfully!`, + }); + + return ( +
+ {likeTool.state.isExecuting && } + {likeTool.state.error && } +
+ ); +} +``` + +## Quick Start - Client (Consuming Tools) + +```tsx +import { McpClientProvider, useMcpClient } from '@mcp-b/react-webmcp'; +import { Client } from '@modelcontextprotocol/sdk/client/index.js'; +import { TabClientTransport } from '@mcp-b/transports'; + +const client = new Client({ name: 'MyApp', version: '1.0.0' }); +const transport = new TabClientTransport('mcp', { clientInstanceId: 'my-app' }); + +function App() { + return ( + + + + ); +} + +function ToolConsumer() { + const { client, tools, isConnected } = useMcpClient(); + + const handleCallTool = async () => { + const result = await client.callTool({ name: 'posts_like', arguments: { postId: '123' } }); + console.log('Result:', result.content[0].text); + }; + + return ( +
+

Connected: {isConnected ? 'Yes' : 'No'}

+

Available Tools: {tools.length}

+ +
+ ); +} +``` + +## API Overview + +### Provider Hooks + +| Hook | Description | +| ----------------------------------------------- | --------------------------------------------------------- | +| `useWebMCP(config, deps?)` | Register a tool with full control over behavior and state | +| `useWebMCPContext(name, description, getValue)` | Simplified hook for read-only context exposure | + +### Client Hooks + +| Hook / Component | Description | +| ------------------- | --------------------------------------------------------- | +| `McpClientProvider` | Provider component managing an MCP client connection | +| `useMcpClient()` | Access client, tools, connection status, and capabilities | + +## Zod Version Compatibility + +This package supports **Zod 3.25.76+** (3.x only). + +## Documentation + +For full API reference, output schemas, memoization patterns, migration guide, best practices, and complete examples, see the [React WebMCP Guide](../../docs/react-webmcp-guide.md). + +## Related Packages + +- [`@mcp-b/global`](https://docs.mcp-b.ai/packages/global) - W3C Web Model Context API polyfill (required for provider hooks) +- [`@mcp-b/transports`](https://docs.mcp-b.ai/packages/transports) - Browser-specific MCP transports +- [`@mcp-b/chrome-devtools-mcp`](https://docs.mcp-b.ai/packages/chrome-devtools-mcp) - Connect desktop AI agents to browser tools +- [`usewebmcp`](../usewebmcp) - React hooks for strict core WebMCP API only + +## Resources + +- [WebMCP Documentation](https://docs.mcp-b.ai) +- [Model Context Protocol Spec](https://modelcontextprotocol.io) + +## License + +MIT - see [LICENSE](../../LICENSE) for details From 3f7d1b8d362131fc79a346a19819dfa70fdcffb4 Mon Sep 17 00:00:00 2001 From: docs-syncer-npm-packages Date: Sat, 13 Jun 2026 01:43:56 +0000 Subject: [PATCH 2/3] docs: sync @mcp-b/react-webmcp overview from npm-packages@bf03420 From d6a3b83d75f62439588343c86db0e74cc2465cff Mon Sep 17 00:00:00 2001 From: docs-syncer-npm-packages Date: Sat, 13 Jun 2026 01:47:33 +0000 Subject: [PATCH 3/3] docs: sync npm-packages documentation --- packages/react-webmcp/overview.mdx | 174 ++++++++++++++++++++++++----- 1 file changed, 143 insertions(+), 31 deletions(-) diff --git a/packages/react-webmcp/overview.mdx b/packages/react-webmcp/overview.mdx index dc03341..d59f128 100644 --- a/packages/react-webmcp/overview.mdx +++ b/packages/react-webmcp/overview.mdx @@ -1,44 +1,156 @@ --- -title: "@mcp-b/react-webmcp overview" -description: "When to use the full React integration package, how it differs from usewebmcp, and which runtime stack it expects." -keywords: ["@mcp-b/react-webmcp", "overview", "react", "MCP-B", "useWebMCP", "McpClientProvider"] -icon: "react" +title: "@mcp-b/react-webmcp" +description: "React hooks for Model Context Protocol (MCP) - Let AI agents like Claude, ChatGPT, Cursor, and Copilot control your React components" --- -`@mcp-b/react-webmcp` is the full React surface for MCP-B. It covers tool registration, prompt and resource hooks, sampling and elicitation helpers, and client/provider APIs for consuming MCP servers from a React tree. +> React hooks for Model Context Protocol (MCP) - Let AI agents like Claude, ChatGPT, Cursor, and Copilot control your React components -## When to use this package +[![npm version](https://img.shields.io/npm/v/@mcp-b/react-webmcp?style=flat-square)](https://www.npmjs.com/package/@mcp-b/react-webmcp) +[![npm downloads](https://img.shields.io/npm/dm/@mcp-b/react-webmcp?style=flat-square)](https://www.npmjs.com/package/@mcp-b/react-webmcp) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT) +[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?style=flat-square)](https://www.typescriptlang.org/) +[![React](https://img.shields.io/badge/React-18+-61DAFB?style=flat-square&logo=react)](https://reactjs.org/) -- You want the full MCP-B feature set from React. -- You want Zod v3 object-map support in hook configuration. -- You need client/provider hooks in addition to browser-exposed tools. +**[Full Documentation](https://docs.mcp-b.ai/packages/react-webmcp)** | **[Quick Start](https://docs.mcp-b.ai/quickstart)** | **[AI Framework Integration](https://docs.mcp-b.ai/ai-frameworks)** -## When not to use this package +**@mcp-b/react-webmcp** provides React hooks that expose your components as AI-callable tools via the Model Context Protocol. Build AI-powered React applications where Claude, ChatGPT, Gemini, Cursor, and Copilot can interact with your app's functionality. -- You only need strict-core `registerTool` behavior. Use [`usewebmcp`](/packages/usewebmcp/overview). -- You are not using a BrowserMcpServer-based runtime such as [`@mcp-b/global`](/packages/global/overview). +## Why Use @mcp-b/react-webmcp? -## Where it sits in the package graph +| Feature | Benefit | +| ---------------------------- | ---------------------------------------------------------------------------- | +| **React-First Design** | Hooks follow React patterns with automatic cleanup and StrictMode support | +| **Type-Safe with Zod** | Full TypeScript support with Zod schema validation for inputs/outputs | +| **Two-Way Integration** | Both expose tools TO AI agents AND consume tools FROM MCP servers | +| **Execution State Tracking** | Built-in loading, success, and error states for UI feedback | +| **Works with Any AI** | Compatible with Claude, ChatGPT, Gemini, Cursor, Copilot, and any MCP client | -This package sits above the full runtime stack. It expects `navigator.modelContext` to come from a browser-native implementation or from the MCP-B runtime that wraps the strict core with `BrowserMcpServer`. +## Installation -## First step +```bash +pnpm add @mcp-b/react-webmcp zod +``` -Initialize the runtime with [`@mcp-b/global`](/packages/global/overview), then add the hook or provider that matches your React use case. The [reference page](/packages/react-webmcp/reference) covers tool hooks, prompt/resource hooks, and client/provider APIs. +If you only want strict core WebMCP hooks (without MCP-B extension APIs like prompts/resources/sampling/elicitation), use `usewebmcp` instead. -## Related pages +For client functionality, you'll also need: - - - Hook APIs, provider APIs, Zod support, and return types. - - - Guided tutorial for registering a React tool. - - - Apply the full MCP-B React surface. - - - Decide whether the full React surface is necessary. - - +```bash +pnpm add @mcp-b/transports @modelcontextprotocol/sdk +``` + +**Prerequisites:** Provider hooks require the `document.modelContext` API. Install `@mcp-b/global` or use a browser that implements the Web Model Context API. + +Provider hooks register tools with `document.modelContext.registerTool(tool, { signal })` and abort the controller on unmount. The hooks retain a `navigator.modelContext` fallback for older preview runtimes, but `document.modelContext` is the canonical v3 surface. On Chrome Beta 147 native (which ignores the second arg) cleanup cannot remove the tool. Install `@mcp-b/global` for spec-aligned behavior. + +## Quick Start - Provider (Registering Tools) + +```tsx +import { useWebMCP } from '@mcp-b/react-webmcp'; +import { z } from 'zod'; + +function PostsPage() { + const likeTool = useWebMCP({ + name: 'posts_like', + description: 'Like a post by ID. Increments the like count.', + inputSchema: { + postId: z.string().uuid().describe('The post ID to like'), + }, + annotations: { + title: 'Like Post', + readOnlyHint: false, + idempotentHint: true, + }, + handler: async (input) => { + await api.posts.like(input.postId); + return { success: true, postId: input.postId }; + }, + formatOutput: (result) => `Post ${result.postId} liked successfully!`, + }); + + return ( +
+ {likeTool.state.isExecuting && } + {likeTool.state.error && } +
+ ); +} +``` + +## Quick Start - Client (Consuming Tools) + +```tsx +import { McpClientProvider, useMcpClient } from '@mcp-b/react-webmcp'; +import { Client } from '@modelcontextprotocol/sdk/client/index.js'; +import { TabClientTransport } from '@mcp-b/transports'; + +const client = new Client({ name: 'MyApp', version: '1.0.0' }); +const transport = new TabClientTransport('mcp', { clientInstanceId: 'my-app' }); + +function App() { + return ( + + + + ); +} + +function ToolConsumer() { + const { client, tools, isConnected } = useMcpClient(); + + const handleCallTool = async () => { + const result = await client.callTool({ name: 'posts_like', arguments: { postId: '123' } }); + console.log('Result:', result.content[0].text); + }; + + return ( +
+

Connected: {isConnected ? 'Yes' : 'No'}

+

Available Tools: {tools.length}

+ +
+ ); +} +``` + +## API Overview + +### Provider Hooks + +| Hook | Description | +| ----------------------------------------------- | --------------------------------------------------------- | +| `useWebMCP(config, deps?)` | Register a tool with full control over behavior and state | +| `useWebMCPContext(name, description, getValue)` | Simplified hook for read-only context exposure | + +### Client Hooks + +| Hook / Component | Description | +| ------------------- | --------------------------------------------------------- | +| `McpClientProvider` | Provider component managing an MCP client connection | +| `useMcpClient()` | Access client, tools, connection status, and capabilities | + +## Zod Version Compatibility + +This package supports **Zod 3.25.76+** (3.x only). + +## Documentation + +For full API reference, output schemas, memoization patterns, migration guide, best practices, and complete examples, see the [React WebMCP Guide](../../docs/react-webmcp-guide.md). + +## Related Packages + +- [`@mcp-b/global`](https://docs.mcp-b.ai/packages/global) - W3C Web Model Context API polyfill (required for provider hooks) +- [`@mcp-b/transports`](https://docs.mcp-b.ai/packages/transports) - Browser-specific MCP transports +- [`@mcp-b/chrome-devtools-mcp`](https://docs.mcp-b.ai/packages/chrome-devtools-mcp) - Connect desktop AI agents to browser tools +- [`usewebmcp`](../usewebmcp) - React hooks for strict core WebMCP API only + +## Resources + +- [WebMCP Documentation](https://docs.mcp-b.ai) +- [Model Context Protocol Spec](https://modelcontextprotocol.io) + +## License + +MIT - see [LICENSE](../../LICENSE) for details