# @frontmcp/react 中文文档

规范地址：https://npmcn.com/package/%40frontmcp/react/

版本：1\.12\.2
npm 元数据更新时间：2026-11-14T21:12:34.050Z
中文译文更新时间：2026-11-15T15:35:12.021Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40frontmcp/react
原文对照：https://npmcn.com/package/%40frontmcp/react/?lang=original
项目主页：https://frontmcp.dev/reference/react
源码仓库：https://github.com/agentfront/frontmcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：431 kB，156 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：2 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，@frontmcp/sdk 1\.12\.2，@frontmcp/utils 1\.12\.2，react-router-dom ^7\.0\.0，@frontmcp/lazy-zod 1\.12\.2
- 首次发布：2026-03-16T18:08:50.039Z
- 最新版本发布：2026-11-14T21:12:33.706Z
- 近 30 天下载量：5067（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：98（近 12 个月 98 个）

## 中文简介

在 React app 内运行 FrontMCP 服务器: 提供者、 钩子、 组件和 AI SDK 集成

## 安装

```sh
npm install @frontmcp/react
```

也可以使用：`pnpm add @frontmcp/react`、`yarn add @frontmcp/react`、`bun add @frontmcp/react`

## README

# @ frontmcp/ 反应

`@frontmcp/react` 在 React 应用程序内运行 FrontMCP 服务器。 您使用 `create()`,在同一进程中,和 `FrontMcpProvider` 连接客户端到它。 组件调用其工具,读取其资源并用钩子得到其提示,在被挂起时可以添加自有工具,因此一个模型可以填入卡片,绕行应用或读取其状态. 用它来制作一个反应软件 一个代理可以驱动的东西。 要构建用户界面, 请使用 ChatGPT 或 Claude 等 AI 主机内的工具显示 [`@frontmcp/ui`](https://www.npmjs.com/package/@frontmcp/ui) 换句话说.

[![npm](https://img.shields.io/npm/v/@frontmcp/react.svg)](https://www.npmjs.com/package/@frontmcp/react) [![License](https://img.shields.io/npm/l/@frontmcp/react.svg)](https://github.com/agentfront/frontmcp/blob/main/LICENSE)

## 安装

```bash
npm install @frontmcp/react react react-dom
```

-   `react` 财务报告和审定财务报表 `react-dom` 18或19是同伴依赖关系.
-   `@frontmcp/sdk` 财务报告和审定财务报表 `@frontmcp/utils` 带着它,在同一版本. `@frontmcp/react` 重新从 SDK 中输出应用程序需要的内容(`create`, (中文(简体) ), `connect` 及其变体、装饰器及其功能形式、上下文类和 `z`),所以你不会导入 `@frontmcp/sdk` 你自己来 npm 7 并随后安装其端点 `@frontmcp/lazy-zod`,以及 `zod` 带着它.
-   `react-router-dom` 7是一个可选的同伴,仅需要用于 `@frontmcp/react/router`。 。 。 .
-   在浏览器中,一个跟随 `browser` 导出条件, 如 Vite , 选择 SDK 的浏览器构建 ([在浏览器中运行](https://frontmcp.dev/reference/react#running-in-a-browser)) (中文(简体) ). 在Node,用于测试或服务器渲染,使用Node.js 24或后期.

## 使用量

一个工具,服务器,以及一个调用它的组件:

```tsx
import { create, FrontMcpProvider, Tool, ToolContext, useCallTool, z } from '@frontmcp/react';

@Tool({ name: 'greet', description: 'Greet someone by name', inputSchema: { name: z.string() } })
class GreetTool extends ToolContext {
  async execute({ name }: { name: string }) {
    return { message: `Hello, ${name}!` };
  }
}

const server = await create({ info: { name: 'my-app', version: '1.0.0' }, tools: [GreetTool] });

function Greeter() {
  const [greet, { data, loading, error }] = useCallTool<{ name: string }, { structuredContent?: { message: string } }>(
    'greet',
  );

  return (
    <div>
      <button disabled={loading} onClick={() => greet({ name: 'Ada' })}>
        Greet
      </button>
      {data?.structuredContent && <p>{data.structuredContent.message}</p>}
      {error && <p role="alert">{error.message}</p>}
    </div>
  );
}

export function App() {
  return (
    <FrontMcpProvider server={server}>
      <Greeter />
    </FrontMcpProvider>
  );
}
```

单击按钮显示 `Hello, Ada!`。 。 。 . `useCallTool()` 返回时 `[call, state, reset]`,以及 `data` 是客户端得到的 MCP 结果,所以工具的返回值在 `data.structuredContent`。一个失败的工具会随着 `isError: true` 内 `data`· ; `error` 只有在无法打电话时才设定,例如 `FrontMCP not connected`装饰者需要 `"experimentalDecorators": true` 内 `tsconfig.json`。 。 。 .

### 入境点

| 导入 | 里面有什么东西 |
| --- | --- |
| `@frontmcp/react` | `FrontMcpProvider`钩子 部件, `mcpComponent`, (中文(简体) ), `serverRegistry`, (中文(简体) ), `DynamicRegistry` 财务报告和审定财务报表 `bindDynamicTools`,商店适配器,以及上面列出的SDK再出口. |
| `@frontmcp/react/state` | `useStoreResource`, (中文(简体) ), `useReduxResource`, (中文(简体) ), `useValtioResource`:从组件内部曝光一商店. |
| `@frontmcp/react/api` | `useApiClient`, (中文(简体) ), `parseOpenApiSpec`, (中文(简体) ), `createFetchClient`: 将 OpenAPI 操作注册为工具. |
| `@frontmcp/react/ai` | `useAITools`, (中文(简体) ), `useTools`, (中文(简体) ), `createToolCallHandler`:将服务器的工具交给AI SDK. |
| `@frontmcp/react/router` | `useRouterBridge`, (中文(简体) ), `createRouterEntries`,则 `navigate`, (中文(简体) ), `go_back` 财务报告和审定财务报表 `route://current` 条目。 需求 `react-router-dom` 7. 联合国. |

### `FrontMcpProvider`

| Prop | 默认 | 说明 |
| --- | --- | --- |
| `server` |  | **要求.** 服务器来自 `create()`。 。 。 . |
| `name` | `"default"` | 服务器名称在 `serverRegistry`,没有钩子 `server` 选项使用. |
| `servers` |  | 更多服务器,名称。 钩子拿来 `{ server: 'name' }`。 。 。 . |
| `components` |  | 构成部分 `DynamicRenderer`,由URI,喜欢 `{ 'component://Card': Card }`。 。 。 . |
| `stores` |  | 将适配器储存起来,作为资源和工具加以曝光([显示应用状态](https://npmcn.com/package/%40frontmcp/react/#readme-exposing-app-state)) (中文(简体) ). |
| `dynamicToolApps` |  | 组件工具的应用程序通过服务器名称加入. 只针对一个拥有多个应用程序的服务器. |
| `autoConnect` | `true` | 连接上挂载 。 与 `false`电话 `connect()` 从 `useFrontMcp()`。 。 。 . |
| `onConnected` |  | 一旦客户端连接并加载了列表,就呼叫. |
| `onError` |  | 当连接失败时调用, 当服务器拒绝一个工具时, 组件会注册 。 没有它,拒绝就是一种警告. |

### 钩子

钩子都拿来 `{ server: 'name' }` 用来使用提供商之一的 `servers`。 。 。 .

| 钩子 | 回返 |
| --- | --- |
| `useFrontMcp(name?)` | `{ name, server, client, status, error, tools, resources, resourceTemplates, prompts, registry, connect }` |
| `useCallTool(name, options?)` | `[call, { data, loading, error, called }, reset]`选项: `onSuccess`, (中文(简体) ), `onError`, (中文(简体) ), `resetOnToolChange`。 。 。 . |
| `useReadResource(uri, options?)` | 在挂载上读取 : `{ data, loading, error, refetch }`没有URI, `[read, state]` 根据要求阅读. |
| `useGetPrompt(name, options?)` | `[getPrompt, { data, loading, error }]` |
| `useListTools()`, (中文(简体) ), `useListPrompts()` | 服务器的工具或提示, 保持当前 . |
| `useListResources()` | `{ resources, resourceTemplates }` |
| `useStoreResource(uri)` | `{ data, loading, error, refetch }` (单位:千美元) `state://` 资源,当服务器说更改时再次读取. |
| `useDynamicTool(options)` | 在组件挂起时注册一个工具( W)[下级](https://npmcn.com/package/%40frontmcp/react/#readme-giving-the-model-a-tool-from-a-component)) (中文(简体) ). |
| `useDynamicResource(options)` | 注册资源, `{ uri, name, description?, mimeType?, read }`,而组件已挂起. |
| `useComponentTree({ rootRef, uri?, ... })` | 注册资源( E)`react://component-tree` (默认情况下),在 `rootRef`,由每个元素的 `data-component`。 。 。 . |

### 从组件中给模型一个工具

```tsx
import { useDynamicTool, z } from '@frontmcp/react';

export function Cart({ isLoggedIn }: { isLoggedIn: boolean }) {
  useDynamicTool({
    name: 'add_to_cart',
    description: 'Add an item to the shopping cart',
    schema: z.object({ itemId: z.string(), quantity: z.number().optional() }),
    execute: async ({ itemId, quantity }) => {
      addToCart(itemId, quantity ?? 1);
      return { content: [{ type: 'text', text: 'Added to cart' }] };
    },
    enabled: isLoggedIn,
  });

  return <div>Cart</div>;
}
```

对输入进行核对 `schema` 在此之前 `execute` 运行,和 `execute` 把它打出来 一个生的JSON Schema在 `inputSchema` 还行 提供者将工具登记在服务器上,作为真正的工具,通过 `server.registerTool()`,所以它的呼叫贯穿了服务器的流量(插件钩子,权威, `availableWhen`),每个客户端都看到了,一个页面内代理通过 [`@frontmcp/plugin-webmcp`](https://www.npmjs.com/package/@frontmcp/plugin-webmcp) 包含。 服务器已经存在的名称被拒绝并通过提供者报告 `onError`。 。 。 .

### 让模型显示组件

`mcpComponent()` 包入一个组件,使一个模型能够显示它:当它挂载时,它会记录一个工具,以及工具的输入,对照 `schema`,成为组件的道具.

```tsx
import { mcpComponent, z } from '@frontmcp/react';

export const WeatherCard = mcpComponent(
  ({ city, temp }) => (
    <div>
      <h2>{city}</h2>
      <p>{temp}°</p>
    </div>
  ),
  {
    name: 'show_weather',
    description: 'Show the weather for a city',
    schema: z.object({ city: z.string(), temp: z.number() }),
    fallback: <p>Waiting for weather data…</p>,
  },
);

// Render it like any component: <WeatherCard />
```

支持你通过自己,喜欢 `<WeatherCard city="Oslo" />`并被合并到模型的。 打电话 `mcpComponent()` 在模块级别,不在一个组件内。 第一个论据也可能是包裹着的懒惰的输入 `mcpLazy(() => import('./HeavyChart'))`,或 `null` 带有 `columns` 选项,用于普通表格,工具使用时 `{ rows: [...] }`数字 :

```tsx
export const OrderTable = mcpComponent(null, {
  name: 'show_orders',
  description: 'Show a list of orders',
  schema: z.object({ id: z.string(), product: z.string(), price: z.number() }),
  columns: [
    { key: 'id', header: 'Order ID' },
    { key: 'product', header: 'Product' },
    { key: 'price', header: 'Price', render: (value) => `$${value}` },
  ],
});
```

### 构成部分

| 构成部分 | 说明 |
| --- | --- |
| `ToolForm` | 从工具生成的窗体 `inputSchema`。没有样式,或您自己的田地 `renderField`。 。 。 . |
| `PromptForm` | 由 poil 参数生成的表单 . |
| `ResourceViewer` | 显示读取结果, `{ contents }`。 。 。 . |
| `OutputDisplay` | 以文本或缩进的 JSON 显示工具或即时结果 . |
| `DynamicRenderer`, (中文(简体) ), `ComponentRegistry` | 生出一棵树 `{ type, props?, children? }` 有URI注册的组件的节点. |
| `readDomById`, (中文(简体) ), `readDomBySelector` | 作为资源结果读取页面,作为资源模板. |
| `AgentContent`, (中文(简体) ), `AgentSearch` | 折旧:使用 `mcpComponent()`。 。 。 . |

### 显示应用状态

每个适配器在提供者 `stores` 成为全州的资源(`state://<name>`),每个选择者的资源(`state://<name>/<selector>`)和每项行动的工具(`<name>_<action>`:

```tsx
import { createStore, FrontMcpProvider, reduxStore, valtioStore } from '@frontmcp/react';

const stores = [
  reduxStore({
    store: todoStore,
    selectors: { todos: (state) => (state as { todos: unknown[] }).todos },
    actions: { addTodo: (text) => ({ type: 'todos/add', text }) },
  }),
  valtioStore({ proxy: settings, subscribe, paths: { userName: 'user.name' } }),
  createStore({ name: 'counter', getState: getCounter, subscribe: onCounterChange }),
];

export function Root() {
  return (
    <FrontMcpProvider server={server} stores={stores}>
      <App />
    </FrontMcpProvider>
  );
}
```

`reduxStore` 命名其存储 `redux` 除非你通过 `name`,并发送每个动作创建者返回的内容. `valtioStore` 默认为 `valtio`传过来 `subscribe` 从 `valtio/utils`保留 `stores` 组件外的数组。 仅在组件挂载时曝光商店, 请使用来自 `@frontmcp/react/state` 具有相同选项的: `useReduxResource()`, (中文(简体) ), `useValtioResource()`,以及 `useStoreResource()`,这需要 `createStore()`选择 那个 `useStoreResource()` 注册商店; 从 `@frontmcp/react` 读取 `state://` 资源.

### 将 API 操作注册为工具

```tsx
import { createFetchClient, parseOpenApiSpec, useApiClient } from '@frontmcp/react/api';

const operations = parseOpenApiSpec(openApiDocument);
const client = createFetchClient();

export function ApiTools() {
  useApiClient({ baseUrl: 'https://api.example.com', operations, client });
  return null;
}
```

每个操作都变成一个工具 `api_<operationId>` (一组) `prefix` 更改 `api`) (中文(简体) ). `client` 使用任意 `HttpClient`对象 `request({ method, url, headers, body? })`,因此您可以使用轴或客户端添加认证头.

### 把工具交给AI SDK

```tsx
import { useAITools } from '@frontmcp/react/ai';

export function useOpenAITools() {
  const { tools, callTool, loading } = useAITools('openai');
  return { tools, callTool, ready: !loading && tools !== null };
}
```

`tools` 是服务器的工具列表,组件的工具包含在平台的格式中; `callTool(name, args)` 运行工具并转换其结果. `useAITools()` 带 `"openai"`, (中文(简体) ), `"claude"`, (中文(简体) ), `"langchain"`, (中文(简体) ), `"vercel-ai"` 或者说 `"raw"`。 。 。 . `useTools(platform)`,用于 `"openai"`, (中文(简体) ), `"claude"` 或者说 `"vercel-ai"`返回 `processToolCalls(calls)` 相反,它运行了一批模型的工具调用并返回要发送的信件. 外面的反应, `createToolCallHandler(server, platform)` 也给你一样的 `callTool`。将 API 密钥保存在自己的服务器上.

### 让一个模型在应用程序周围移动

将路由器条目放入服务器并呼叫 `useRouterBridge()` 在路由器和提供者的组件中:

```tsx
import { BrowserRouter, Route, Routes } from 'react-router-dom';

import { create, FrontMcpProvider } from '@frontmcp/react';
import { createRouterEntries, useRouterBridge } from '@frontmcp/react/router';

const { tools, resources } = createRouterEntries();
const server = await create({ info: { name: 'my-app', version: '1.0.0' }, tools, resources });

function RouterBridge() {
  useRouterBridge();
  return null;
}

export function App() {
  return (
    <BrowserRouter>
      <FrontMcpProvider server={server}>
        <RouterBridge />
        <Routes>
          <Route path="/home" element={<h1>Home</h1>} />
          <Route path="/settings" element={<h1>Settings</h1>} />
        </Routes>
      </FrontMcpProvider>
    </BrowserRouter>
  );
}
```

然后服务器有 `navigate` 工具 (`{ path, replace? }`页:1 `go_back` 工具与工具 `route://current` 资源. `useRouterBridge()` 只连接 React 路由器到它们; 没有它挂载, 它们就回答 `Router bridge not connected`。 。 。 .

## 文档

-   [`@frontmcp/react` 参考文献](https://frontmcp.dev/reference/react):提供者, `serverRegistry`,存储,在浏览器中运行,在节点测试
-   [反应钩](https://frontmcp.dev/reference/react/hooks): 每个钩子,包括 `/state`, (中文(简体) ), `/api` 财务报告和审定财务报表 `/ai`
-   [反应组件](https://frontmcp.dev/reference/react/components)数字 : `mcpComponent()`,表单, `DynamicRenderer`, DOM 资源,路由器工具
-   [`create()`](https://frontmcp.dev/reference/sdk/create): 构建服务商连接到的服务器

## 相关软件包

-   [`@frontmcp/sdk`](https://www.npmjs.com/package/@frontmcp/sdk): 服务器框架; `create()`工具、资源和提示来自此.
-   [`@frontmcp/plugin-webmcp`](https://www.npmjs.com/package/@frontmcp/plugin-webmcp):向内浏览器代理提供服务器的工具,组件的工具包括.
-   [`@frontmcp/ui`](https://www.npmjs.com/package/@frontmcp/ui): 对在 AI 主机内渲染部件的反应组件和钩子 .

## 捐款

资料来源: [`libs/react`](https://github.com/agentfront/frontmcp/tree/main/libs/react)欢迎提出问题和拉动请求;见 [捐款额](https://github.com/agentfront/frontmcp/blob/main/CONTRIBUTING.md)。 。 。 .

## 许可证

阿帕奇2.0 (英语). 见 [自由主义](https://github.com/agentfront/frontmcp/blob/main/LICENSE)。 。 。 .

## 常见问题

### @frontmcp/react 是什么？

在 React app 内运行 FrontMCP 服务器: 提供者、 钩子、 组件和 AI SDK 集成

### 如何安装 @frontmcp/react？

在项目目录运行 npm install @frontmcp/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）、@frontmcp/sdk（1\.12\.2）、@frontmcp/utils（1\.12\.2）、@frontmcp/lazy-zod（1\.12\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @frontmcp/react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @frontmcp/react 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @frontmcp/react 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @frontmcp/react 可以商用吗？

@frontmcp/react 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @frontmcp/react 的下载量有多少？

根据 npm 官方下载统计，@frontmcp/react 在 2026/10/16 – 2026/11/14 这 30 天内被下载 5,067 次，日均约 169 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @frontmcp/react 还在维护吗？

最新版本 1\.12\.2 发布于 2026/11/15（1 天前）；至今共发布 98 个版本，其中过去 12 个月发布了 98 个；首次发布于 2026/03/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。