内容
# webmcp-react
用于在 `document.modelContext` 上公开类型化工具的 React 钩子，与当前的 [WebMCP](https://github.com/webmachinelearning/webmcp) 规范保持一致。
[](https://www.npmjs.com/package/webmcp-react)
[](./LICENSE)
[](https://github.com/MCPCat/webmcp-react/actions/workflows/ci.yml)
[](https://github.com/MCPCat/webmcp-react/pulls)
> 实验性。WebMCP 仍在不断发展，因此可能会有小的 API 和行为变化。
- **基于 Zod.** 使用 Zod 定义输入并在处理程序中获得完整的类型推断
- **JSON 模式备用。** 当您不想要 Zod 时，请传递原始 JSON 模式
- **内置 polyfill.** 在原生 WebMCP 不可用时使用轻量级 polyfill
- **SSR 安全。** 与 Next.js、Remix 和其他服务器渲染框架一起工作
- **StrictMode 安全。** 避免重复注册和孤立的工具
## 安装
```bash
npm install webmcp-react zod
```
## 游乐场
实时试用：[**WebMCP Wordle Demo**](https://mcpcat.github.io/webmcp-react/playground/)
一个完全可玩的 Wordle 克隆，展示了 `webmcp-react` 钩子。工具在游戏进入不同阶段（空闲、正在玩、赢/输）时动态注册和注销，可以通过键盘或通过连接的 MCP 代理进行猜测。包括一个用于检查工具状态的 DevPanel 和一个启用提示工具的简单模式切换。安装 Chrome 扩展程序，将工具连接到像 Claude 和 Cursor 这样的 AI 客户端。
## 快速开始
用 `<WebMCPProvider>` 包裹您的应用，并使用 `useMcpTool` 注册工具：
```tsx
import { WebMCPProvider, useMcpTool } from "webmcp-react";
import { z } from "zod";
function SearchTool() {
useMcpTool({
name: "search",
description: "搜索目录",
input: z.object({ query: z.string() }),
handler: async ({ query }) => ({
content: [{ type: "text", text: `结果为：${query}` }],
}),
});
return null;
}
export default function App() {
return (
<WebMCPProvider name="my-app" version="1.0">
<SearchTool />
</WebMCPProvider>
);
}
```
就是这样。该工具已在 `document.modelContext` 上注册，可以由 WebMCP 兼容的代理调用。
### 使用 AI 代理？
此存储库附带 [代理技能](./skills)，可以为您设置 webmcp-react 并为您的工具提供脚手架。使用 [技能 CLI](https://skills.sh) 安装它们：
```bash
npx skills add mcpcat/webmcp-react
```
与 Cursor、Claude Code、GitHub Copilot、Cline 和 [其他 18+ 个代理](https://vercel.com/docs/agent-resources/skills) 配合使用。
## 工作原理
[WebMCP](https://github.com/webmachinelearning/webmcp) 是一个新兴的 Web 标准，它在浏览器中添加了 `document.modelContext`，一个 API，允许任何页面向 AI 代理公开类型化的、可调用的工具。原生浏览器支持仍处于实验阶段，可能会迅速发展。Chrome 最近 [发布了早期预览版](https://developer.chrome.com/blog/webmcp-epp)。
该库为该 API 提供了 React 绑定。`<WebMCPProvider>` 安装了一个 polyfill（当原生支持存在时跳过），每个 `useMcpTool` 调用都会注册一个代理可以发现和执行的工具。
## 连接到 AI 客户端
像 Claude Code 和 Cursor 这样的桌面 MCP 客户端无法直接访问 `document.modelContext`。 [WebMCP Bridge 扩展程序](https://chromewebstore.google.com/detail/webmcp-bridge/chgjbookknohehmaocfijekhaocaanaf) 将您注册的工具连接到任何 MCP 客户端。
1. 从 [Chrome 网上应用店](https://chromewebstore.google.com/detail/webmcp-bridge/chgjbookknohehmaocfijekhaocaanaf) 安装扩展程序。
2. 配置您的 MCP 客户端 - 有关详细信息，请参阅 [扩展程序设置指南](./extension/README.md)。
一旦 Chrome 原生支持此桥接功能，我就会弃用该扩展程序。
## 食谱
### 执行状态
`useMcpTool` 返回可用于构建工具执行 UI 的响应式状态：
```tsx
function TranslateTool() {
const { state, execute } = useMcpTool({
name: "translate",
description: "将文本翻译成西班牙语",
input: z.object({ text: z.string() }),
handler: async ({ text }) => {
const result = await translate(text, "es");
return { content: [{ type: "text", text: result }] };
},
});
return (
<div>
<button onClick={() => execute({ text: "Hello" })} disabled={state.isExecuting}>
{state.isExecuting ? "翻译中..." : "翻译"}
</button>
{state.lastResult && <p>{state.lastResult.content[0].text}</p>}
{state.error && <p className="error">{state.error.message}</p>}
</div>
);
}
```
### 标题和注释
给工具一个人类友好的显示标题，并提示 AI 代理了解其行为。根据当前的 WebMCP 规范，注释仅限于 `readOnlyHint` 和 `untrustedContentHint`:
```tsx
useMcpTool({
name: "search_users",
title: "搜索用户",
description: "按姓名或电子邮件查找用户",
input: z.object({ query: z.string() }),
annotations: {
readOnlyHint: true,
},
handler: async ({ query }) => { /* ... */ },
});
```
### 动态工具
工具在安装时注册，在卸载时注销。像任何 React 组件一样有条件地渲染它们：
```tsx
function App({ user }) {
return (
<WebMCPProvider name="app" version="1.0">
<PublicTools />
{user.isAdmin && <AdminTools />}
</WebMCPProvider>
);
}
```
### 回调
在成功或失败时运行副作用：
```tsx
useMcpTool({
name: "checkout",
description: "完成购买",
input: z.object({ cartId: z.string() }),
handler: async ({ cartId }) => { /* ... */ },
onSuccess: (result) => analytics.track("checkout_complete"),
onError: (error) => toast.error(error.message),
});
```
### JSON 模式
不需要 Zod？直接传递 `inputSchema`：
```tsx
useMcpTool({
name: "calculate",
description: "基本算术",
inputSchema: {
type: "object",
properties: {
a: { type: "number" },
b: { type: "number" },
op: { type: "string", enum: ["add", "subtract", "multiply", "divide"] },
},
required: ["a", "b", "op"],
},
handler: async (args) => {
const { a, b, op } = args as { a: number; b: number; op: string };
const result = { add: a + b, subtract: a - b, multiply: a * b, divide: a / b }[op];
return { content: [{ type: "text", text: String(result) }] };
},
});
```
### SSR
开箱即用支持 Next.js、Remix 和任何服务器渲染框架。构建中包含 `"use client"` 横幅，因此不需要额外的配置。
## 0.2.0 中的重大更改
0.2.0 版本使库与当前的 [WebMCP](https://github.com/webmachinelearning/webmcp) 规范保持一致。如果您从 0.1.0 版本升级：
- **API 移至 `document.modelContext`。** 工具在 `document.modelContext` 上注册，而不是 `navigator.modelContext`。（测试/消费者 API 仍在 `navigator.modelContextTesting` 上。）
- **`registerTool` 返回 `Promise`。** polyfill 的 `registerTool(tool, options?)` 返回一个 `Promise<undefined>`，如果输入无效（名称错误/重复/为空，描述为空，执行非函数，`inputSchema` 不可序列化，`exposedTo` 源不受信任，或信号已中止），则拒绝。
- **注销仅限 AbortSignal。** 没有 `unregisterTool` - 传递 `{ signal }` 并中止它。`useMcpTool` 在卸载时为您执行此操作。
- **处理程序接受单个参数。** `handler(args)` / `execute(input)` 不再接收第二个 `client` 参数；`ModelContextClient` 和 `requestUserInteraction` 已删除。
- **`annotations` 缩小到 `{ readOnlyHint, untrustedContentHint }`。** 经典提示（`destructiveHint`、`idempotentHint`、`openWorldHint`）和 `annotations.title` 已删除。新顶级字段 `title?` 替换 `annotations.title`。
- **新的 `exposedTo?: string[]`** 控制跨帧源可见性（更改它会重新注册工具）。
- **新的 `toolchange` 事件。** `document.modelContext` 是一个 `EventTarget`，在工具注册/注销时触发一个纯粹的 `toolchange` 事件；还支持 `ontoolchange` 处理程序。
`outputSchema`（Zod `output` / JSON-Schema `outputSchema`）和结果上的 `structuredContent` 作为文档化的库扩展保留。
## API
请参阅 [完整的 API 参考](./docs/api.md)。
## 许可证
[MIT](./LICENSE)
连接信息
猜你喜欢
暂无推荐服务器