# @frontmcp/ui 中文文档

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

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

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

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

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

- 包体积（解压后）：996 kB，230 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：1 个
- peer 依赖：katex ^0\.16\.0，react ^18\.0\.0 \|\| ^19\.0\.0，leaflet ^1\.9\.0，mermaid ^11\.0\.0，recharts ^2\.13\.0，dompurify ^3\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，react-pdf ^9\.0\.0，pdfjs-dist ^4\.0\.0，rehype-raw ^7\.0\.0，remark-gfm ^4\.0\.0，@types/react ^18\.0\.0 \|\| ^19\.0\.0，react-player ^2\.16\.0，@mui/material ^7\.0\.0 \|\| ^8\.0\.0 \|\| ^9\.0\.0，@xyflow/react ^12\.0\.0，react-leaflet ^5\.0\.0，@emotion/react ^11\.0\.0，react-markdown ^9\.0\.0，@emotion/styled ^11\.0\.0，@types/react-dom ^18\.0\.0 \|\| ^19\.0\.0，rehype-highlight ^7\.0\.0
- 首次发布：2025-12-11T16:57:51.003Z
- 最新版本发布：2026-11-14T21:11:08.888Z
- 近 30 天下载量：5230（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：116（近 12 个月 116 个）

## 中文简介

为 ChatGPT 、 Claude 和其他 MCP Apps 主机中的 FrontMCP 工具部件提供反应组件、桥钩和内容渲染器( 在 MUI 上建造)

## 安装

```sh
npm install @frontmcp/ui
```

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

## README

# @ frontmcp/ ui (英语)

`@frontmcp/ui` 是 FrontMCP 部件的回放一面: UI 是一个在像 ChatGPT 或 Claude 这样的 AI 主机内显示的工具 。 您将一个部件写为反应组件, 并指定工具的 `ui.template` at it; FrontMCP 将文件捆绑并包入 `McpBridgeProvider` 并挂载它与呼叫的数据。 这个软件包给通过主机读取调用和调用工具的组件钩子,基于MUI(Matrial UI)的11个组件,一个主题,以及图表,PDF,地图和图表等内容的渲染器. 作为 HTML 模板编写的部件不需要它([带有 UI 的工具](https://frontmcp.dev/learn/tools-with-a-ui)) (中文(简体) ). 要制作一个代理可以驱动,使用的反应应用程序 [`@frontmcp/react`](https://www.npmjs.com/package/@frontmcp/react) 换句话说.

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

## 安装

```bash
npm install @frontmcp/ui react react-dom @mui/material @emotion/react @emotion/styled
```

-   对于部件文件,请在服务器的项目中安装它, 即使部件没有导入它: 代码 FrontMCP 添加以挂载部件文件导入 `McpBridgeProvider` 从 `@frontmcp/ui/react`。 。 。 .
-   所需要的同行是: `react` 财务报告和审定财务报表 `react-dom` 18或19岁, `@mui/material` 7、8或9,以及 `@emotion/react` 财务报告和审定财务报表 `@emotion/styled` 11. npm 7, 后与包件一同安装 `@types/react` 财务报告和审定财务报表 `@types/react-dom`。 。 。 .
-   FrontMCP 组合部件文件 `esbuild`,可选的对等点 `@frontmcp/uipack` 没有什么可以为你安装。 一个来自 `frontmcp create` 有它; 其他任何地方,运行 `npm install esbuild` 并保持它的依赖性,而不是dev的依赖性,因为工具被调用时它被加载了.
-   服务器需要节点.js 24或后.

### 渲染器的可选同伴

渲染器的库是可选的同位素,没有安装软件包 :

| 渲染器 | 入境点 | 可选同伴 |
| --- | --- | --- |
| 图表 | `@frontmcp/ui/renderer/charts` | `recharts` |
| 专题报告 | `@frontmcp/ui/renderer/pdf` | `react-pdf`, (中文(简体) ), `pdfjs-dist` |
| 流程图 | `@frontmcp/ui/renderer/flow` | `@xyflow/react` |
| 地图 | `@frontmcp/ui/renderer/maps` | `react-leaflet`, (中文(简体) ), `leaflet` |
| 美人鱼图 | `@frontmcp/ui/renderer/mermaid` | `mermaid` |
| 数学 | `@frontmcp/ui/renderer/math` | `katex` |
| 视频和音频 | `@frontmcp/ui/renderer/media` | `react-player` |
| 马克德和MDX | `@frontmcp/ui/renderer/mdx` | `react-markdown`, (中文(简体) ), `remark-gfm`, (中文(简体) ), `rehype-highlight`, (中文(简体) ), `rehype-raw` |
| HTML 语言 | `@frontmcp/ui/renderer/html` | `dompurify`; 没有它, HTML 将显示已逃出 |
| CSV,图像,反应JSX | `/renderer/csv`, (中文(简体) ), `/renderer/image`, (中文(简体) ), `/renderer/react` | 无。 JSX由Babel编译,由esm.sh装入. |

每个渲染器在运行时加载其库,这是它第一次制作:根据页面可以解析的软件包名称(在节点下安装的端口或dev服务器,或导入地图),或者从其它角度 [esm.sh (英语)](https://esm.sh/) 在浏览器中。 地图、数学和流图以及PDF.js工人的样式表总是来自esm.sh.

## 使用量

指着工具 `ui.template` 绝对路径的部件文件 :

```ts
import { join } from 'node:path';

import { Tool, ToolContext, z } from '@frontmcp/sdk';

@Tool({
  name: 'get_weather',
  description: 'Current weather for a city',
  inputSchema: { city: z.string() },
  outputSchema: { city: z.string(), tempC: z.number(), conditions: z.string() },
  ui: { template: { file: join(__dirname, 'weather.widget.tsx') } },
})
export class GetWeather extends ToolContext {
  async execute({ city }: { city: string }) {
    return { city, tempC: 21, conditions: 'Sunny' };
  }
}
```

导出组件为默认 `weather.widget.tsx`数字 :

```tsx
import { Badge, Card } from '@frontmcp/ui/components';
import { FrontMcpThemeProvider } from '@frontmcp/ui/theme';

type Weather = { city: string; tempC: number; conditions: string };

export default function WeatherWidget({ output }: { output: Weather | null }) {
  if (!output?.city) return <p>Loading…</p>;
  return (
    <FrontMcpThemeProvider>
      <Card title={output.city} subtitle="Current weather">
        <p>{output.tempC}°C</p>
        <Badge label={output.conditions} variant="success" />
      </Card>
    </FrontMcpThemeProvider>
  );
}
```

部件得到三个道具: `output`, (中文(简体) ), `input` 财务报告和审定财务报表 `loading`。检查需要的字段,比如 `output?.city`,而不是为了 `output`:一个失败的结果的错误文本也是真实的 。 在 ES 模块服务器中,使用 `join(import.meta.dirname, 'weather.widget.tsx')`名称部件文件 `*.widget.tsx` 让他们离开服务器 `tsc` 建造; `frontmcp build` 复制到其输出中. [构建部件文件](https://frontmcp.dev/reference/ui/components#building-a-widget-file) 覆盖相对路径, `resourceMode` 和每个主机得到的.

### 从部件调用工具

```tsx
import { useCallTool } from '@frontmcp/ui/react';

type Weather = { city: string; tempC: number };

export default function Refreshable({ output }: { output: Weather | null }) {
  const [refresh, { data, loading, error }] = useCallTool<{ city: string }, Weather>('get_weather');

  const weather = data?.structuredContent ?? (output?.city ? output : null);
  return (
    <div>
      <p>{weather ? `${weather.city}: ${weather.tempC}°C` : 'No data yet'}</p>
      <button disabled={loading} onClick={() => refresh({ city: 'Bergen' })}>
        Bergen
      </button>
      {error && <p role="alert">{error.message}</p>}
    </div>
  );
}
```

`useCallTool()` 返回数组,而不是对象. `call(args)` 要求主机调用工具并用主机的全部结果解决,因此工具的输出在 `data.structuredContent`。一个失败的工具通常会随着 `isError: true` 内 `data`· ; `error` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}是给那些不能打的电话的 `Tool calls not supported on this platform (ext-apps)` 从一个从未接过电话的东道主那里.

### 入境点

| 导入 | 里面有什么东西 |
| --- | --- |
| `@frontmcp/ui/react` | `McpBridgeProvider` 和钩. `@frontmcp/ui` 也出口,与桥梁. |
| `@frontmcp/ui/components` | 这11个组件。 每个都有自己的入口点 比如 `@frontmcp/ui/components/Card`。 。 。 . |
| `@frontmcp/ui/theme` | `FrontMcpThemeProvider`, (中文(简体) ), `createFrontMcpTheme`, (中文(简体) ), `defaultTheme`, (中文(简体) ), `darkTheme`, (中文(简体) ), `useFrontMcpTheme`。 。 。 . |
| `@frontmcp/ui/renderer` | `ContentView`, (中文(简体) ), `renderContent`, (中文(简体) ), `detectContentType`, (中文(简体) ), `registerAllRenderers`, (中文(简体) ), `registerRenderer`和每个渲染器。 每个渲染器也有自己的切入点; `/renderer/common` 有共享的帮助者. |
| `@frontmcp/ui/bridge` | 桥梁作为一个阶级, `FrontMcpBridge` 财务报告和审定财务报表 `createBridge()`及其适配器和 `generateBridgeIIFE()`,对于页面 FrontMCP 不构建. |
| `@frontmcp/ui/runtime` | `detectContentType`,以及 `transpileJsx()` 用它用的"贝贝"装载器. |
| `@frontmcp/ui/auth`, (中文(简体) ), `@frontmcp/ui/auth/vanilla` | A 的组件和助手 [自定义登录 UI](https://frontmcp.dev/reference/auth/login-ui); 数据 `vanilla` 条目没有反应. |

### 钩子

部件文件已经在里面 `McpBridgeProvider`。在提供者之外,钩子返回空值,并且 `call()` 失败 `Bridge not initialized`。 。 。 .

| 钩子 | 回返 |
| --- | --- |
| `useToolOutput<T>()` | 呼叫的输出:嵌入到页面中的输出,然后每个结果主机发送. |
| `useToolInput<T>()` | 唤作辩才. |
| `useStructuredContent<T>()` | 这个 `structuredContent` 以显示寄件者所发送的结果;空到一个到达为止. |
| `useCallTool<In, Out>(name, options?)` | `[call, { data, loading, error, called }, reset]`选项: `onSuccess`, (中文(简体) ), `onError`, (中文(简体) ), `resetOnToolChange` (默认) `true`) (中文(简体) ). |
| `useToolCalls({ key: toolName, ... })` | `{ key: { call, data, loading, error, reset }, ... }`数字 : `useCallTool` 用于几种工具. |
| `useSendMessage()` | `[send(text), { loading, error, sent }]`:在对话中添加一个消息,其中主机允许. |
| `useOpenLink()` | `open(url)`,通过主机. |
| `useTheme()`, (中文(简体) ), `useDisplayMode()` | `"light"` 或者说 `"dark"`,以及 `"inline"`, (中文(简体) ), `"fullscreen"` 或者说 `"pip"`,正如主办方报告的那样. |
| `useHostContext()` | 主持人对自己说的话: `{ theme, displayMode, locale, userAgent, safeArea, viewport?, ... }`。 。 。 . |
| `useCapability(name)` | 主机能否做到这一点 `name`一样 `"canCallTools"`。 。 。 . `false` 直到主持人回答握手. |
| `useMcpBridge()`, (中文(简体) ), `useMcpBridgeContext()` | 桥,和 `{ bridge, loading, error, ready, adapterId, capabilities, revision }`。 。 。 . |

### 构成部分

`@frontmcp/ui/components` 是在MUI上构建的反应组件。 把它们放进去 `FrontMcpThemeProvider`。 。 。 .

| 构成部分 | 主要道具 | 渲染器 |
| --- | --- | --- |
| `Button` | `variant` (单位:千美元)`primary`, (中文(简体) ), `secondary`, (中文(简体) ), `danger`, (中文(简体) ), `ghost`, (中文(简体) ), `size`, (中文(简体) ), `loading`, (中文(简体) ), `disabled`, (中文(简体) ), `onClick` | 一个MUI `Button`· ; `loading` 增加一转相. |
| `Card` | `title`, (中文(简体) ), `subtitle`, (中文(简体) ), `headerActions`, (中文(简体) ), `footer`, (中文(简体) ), `elevation`, (中文(简体) ), `clickable`, (中文(简体) ), `slotProps` | 一个MUI `Card`。 。 。 . |
| `Alert` | `severity`, (中文(简体) ), `title`, (中文(简体) ), `dismissible`, (中文(简体) ), `onDismiss`, (中文(简体) ), `icon` | 一个MUI `Alert`。 。 。 . |
| `Badge` | `label` (必须), `variant`, (中文(简体) ), `size`, (中文(简体) ), `dot`, (中文(简体) ), `removable`, (中文(简体) ), `onRemove` | 一个MUI `Chip`。 。 。 . |
| `Avatar` | `src`, (中文(简体) ), `alt`, (中文(简体) ), `size`, (中文(简体) ), `variant` | 一个MUI `Avatar`。 。 。 . |
| `Modal` | `open` 财务报告和审定财务报表 `onClose` (必须), `title`, (中文(简体) ), `actions`, (中文(简体) ), `maxWidth`, (中文(简体) ), `slotProps` | 一个MUI `Dialog`。 。 。 . |
| `Table` | `columns` (单位:千美元)`{ key, label, align? }[]`, (中文(简体) ), `rows`, (中文(简体) ), `size`, (中文(简体) ), `stickyHeader`, (中文(简体) ), `maxHeight` | 一个MUI `Table`。 。 。 . |
| `TextField` | `label`, (中文(简体) ), `value`, (中文(简体) ), `onChange(value)`, (中文(简体) ), `type`, (中文(简体) ), `multiline`, (中文(简体) ), `error`, (中文(简体) ), `helperText` | 一个MUI `TextField`· ; `onChange` 得到价值. |
| `Select` | `options` (单位:千美元)`{ value, label }[]`, (中文(简体) ), `label`, (中文(简体) ), `value`, (中文(简体) ), `onChange(value)` | MUI 选择字段 . |
| `List` | `items` (单位:千美元)`{ id, primary, secondary?, icon?, onClick?, divider? }[]`, (中文(简体) ), `dense` | 一个MUI `List`。 。 。 . |
| `Loader` | `variant` (单位:千美元)`spinner`, (中文(简体) ), `bar`, (中文(简体) ), `skeleton`, (中文(简体) ), `overlay`, (中文(简体) ), `label`, (中文(简体) ), `determinate`, (中文(简体) ), `value` | 一个旋转器,进步栏,骨架或背景. |

`LoaderProvider` 替换每 `Loader` 在它下,你自己的制造功能。 主题来自 `createFrontMcpTheme({ palette?, typography?, shape?, mode? })`,或现成 `defaultTheme` 财务报告和审定财务报表 `darkTheme`,转至 `FrontMcpThemeProvider` 作为 `theme`。 。 。 .

### 渲染器

```tsx
import { ContentView, registerAllRenderers } from '@frontmcp/ui/renderer';

registerAllRenderers();

export function Report({ content }: { content: string }) {
  return <ContentView content={content} />;
}
```

`ContentView` 检测字符串中的内容类型, 如 CSV、 美人鱼图、 图表的 JSON 或图像 URL , 并将其与匹配的渲染器相接, 包裹在 `Suspense`。 。 。 . `renderContent(content, options?)` 在没有 `Suspense` 边界,和 `detectContentType(content)` 只有名字的种类。 当多个渲染器相匹配时,更高的优先级获胜,依此顺序为:pdf,图,流,图,美人鱼,数学,图像,视频,音频,csv,jsx,mdx,html. `registerRenderer()` 自己加进去 `{ type, priority?, canHandle(content), render(content, options?) }`。 。 。 .

## 文档

-   [部件](https://frontmcp.dev/reference/ui/components): 构建部件文件、道具、钩子、组件、主题和渲染器
-   [用回放构建部件](https://frontmcp.dev/learn/building-widgets-with-react):分步骤指南
-   [带有 UI 的工具](https://frontmcp.dev/learn/tools-with-a-ui): 模板或反应,以及部件如何服务
-   [这个 `ui` 选项](https://frontmcp.dev/reference/ui): 工具部件、服务模式、内容安全政策的每个选项
-   [主机和平台](https://frontmcp.dev/reference/ui/hosts):每个主持人都得到什么, 和桥钩说话

## 相关软件包

-   [`@frontmcp/sdk`](https://www.npmjs.com/package/@frontmcp/sdk): 服务器框架; 工具的 `ui` 选项来自它.
-   [`@frontmcp/uipack`](https://www.npmjs.com/package/@frontmcp/uipack): 创建服务器上每个部件页面的无反动核心 `html` 模板帮助.
-   [`@frontmcp/testing`](https://www.npmjs.com/package/@frontmcp/testing): 测试助手, 并配对工具制成的部件 .
-   [`@frontmcp/react`](https://www.npmjs.com/package/@frontmcp/react):用于在React app内部运行FrontMCP服务器的钩和组件.

## 捐款

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

源代码下每个输入点有一个文件夹 `src/`数字 : `react/` (供应商和钩子), `components/` (每个部件一个文件夹), `theme/`, (中文(简体) ), `renderer/` (每个渲染器一个文件夹,加 `common/`, (中文(简体) ), `bridge/` (适应器、登记和桥梁类), `runtime/` (内容检测和 Babel 加载器)和 `auth/`。服务器在每个页面中的桥接脚本来自 `@frontmcp/uipack`在单曲中:

```bash
nx build ui
nx test ui
nx lint ui
```

## 许可证

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

## 常见问题

### @frontmcp/ui 是什么？

为 ChatGPT 、 Claude 和其他 MCP Apps 主机中的 FrontMCP 工具部件提供反应组件、桥钩和内容渲染器\( 在 MUI 上建造\)

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

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

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

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

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

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

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

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

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

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

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

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

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

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