# @frontmcp/plugin-webmcp 中文文档

规范地址：https://npmcn.com/package/%40frontmcp/plugin-webmcp/

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

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

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

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

- 包体积（解压后）：103 kB，26 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：1 个
- peer 依赖：@frontmcp/sdk 1\.12\.2，@frontmcp/lazy-zod 1\.12\.2
- 首次发布：2026-10-03T23:03:51.383Z
- 最新版本发布：2026-11-14T21:10:32.772Z
- 近 30 天下载量：5152（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：47（近 12 个月 47 个）

## 中文简介

FrontMCP的WebMCP插件 - 打开浏览器FrontMCP服务器的工具通过文档浏览器代理. modelContext

## 安装

```sh
npm install @frontmcp/plugin-webmcp
```

也可以使用：`pnpm add @frontmcp/plugin-webmcp`、`yarn add @frontmcp/plugin-webmcp`、`bun add @frontmcp/plugin-webmcp`

## README

# @ frontmcp/ 插件- webmcp

提供工具 [前线MCP](https://frontmcp.dev/) 运行的服务器 **在页面中** 给用户的代理 浏览器,通过 [网络MCP](https://webmachinelearning.github.io/webmcp/) (单位:千美元)`document.modelContext`: 浏览器自己的 助手、扩展或开发工具。 在创建页面中FrontMCP服务器的网站上使用它,经常 下级 `@frontmcp/react`。插件将服务器的工具注册,并随着工具的来去保持同步,并运行每个工具 代理通过服务器自身流量调用.

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

## 安装

```bash
npm install @frontmcp/sdk @frontmcp/plugin-webmcp
```

对两个软件包使用相同的版本. 插件的对等依赖 `@frontmcp/lazy-zod` 和SDK一起来。 这个 构建时间助手 `listWebMcpTools()` 运行于节点.js 24或后.

## 使用量

```typescript
import { WebMcpPlugin } from '@frontmcp/plugin-webmcp';
import { create } from '@frontmcp/sdk';

const server = await create({
  info: { name: 'shop', version: '1.0.0' },
  tools: [SearchProducts, AddToCart],
  plugins: [WebMcpPlugin.init({ prefix: 'shop.' })],
});
```

注册插件为 `WebMcpPlugin.init()`,有无选项; `plugins: [WebMcpPlugin]` 使用默认值. 安装一次: 它提供服务器列表的每一个工具, 不论它注册的应用程序是什么 .

一旦服务器准备好,它列出的每一个工具 `'webmcp'` 表面注册为 `document.modelContext.registerTool()`数字 :

-   **保持同步 .** 以后添加或删除的工具,包括添加的工具 `server.registerTool()` 和反应 `useDynamicTool()`,在变化时登记或未登记.
-   **清净已.** 每个工具在 `server.dispose()` 运行.

代理电话运行服务器 `tools:call-tool` 因此,钩子,权威,配额和 `availableWhen` 对其适用 就像他们对MCP客户一样.

## 选项

所有选择.

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `prefix` | `string` | `''` | 准备每个被曝光的工具名, 例如 . `'shop.'`。 。 。 . |
| `include` | `(tool) => boolean` | 每个工具 | 决定公布清单所列哪些工具。 运行后 `availableWhen` 和当局. |
| `exposedTo` | `string[]` |  | 提供其他来源(例如iframe的父)工具. |
| `authContext` | `DirectAuthContext | () => DirectAuthContext` | 一个匿名电话, `anon:webmcp` | 服务器看见谁打电话了 每一次上市和每次通话,都再次要求一个函数. |
| `modelContext` | `ModelContext` | `document.modelContext` | 要注册的上下文:多填充或测试双填. |
| `result` | `'structured' | 'content' | 'both'` | `'structured'` | 什么样的呼吁决定(见 [结果](https://npmcn.com/package/%40frontmcp/plugin-webmcp/#readme-how-tools-are-translated)) (中文(简体) ). |

无 `authContext`每一个电话都来自匿名电话 所以拒绝匿名电话的工具拒绝 探员也一样 让代理担任使用页面的人,通过该用户,例如 `authContext: () => ({ user: { sub: userId, roles: ['agent'] } })`。 。 。 .

## 选择哪些工具代理

工具通过 `'webmcp'` 调用表面,所以 `availableWhen` 决定每个工具:

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

@Tool({ name: 'checkout', description: 'Check out the cart', inputSchema: {}, availableWhen: { surface: ['webmcp'] } })
export class Checkout extends ToolContext {
  async execute() {
    return { ordered: true };
  }
}

@Tool({ name: 'admin_reset', description: 'Reset the store', inputSchema: {}, availableWhen: { surface: ['mcp'] } })
export class AdminReset extends ToolContext {
  async execute() {
    return { reset: true };
  }
}
```

`checkout` 仅提供给浏览者 `admin_reset` 从不通过 WebMCP.

## 工具的翻译方式

-   **名称.** 名称成为WebMCP-验证. 外部字符 `[A-Za-z0-9_.-]` 变成 `_` (这样) `app:tool` 变成 `app_tool`),名字被切为128个字符,相撞得到 `_2`, (中文(简体) ), `_3`,, , , , , , , ,
-   **说明.** MCP的音乐 `readOnlyHint` 地图到 `readOnlyHint`明确 `destructiveHint: true` 地图到 `consequentialHint`,并明确 `openWorldHint: true` 改为 `untrustedContentHint`。 。 。 .
-   **结果.** 一个代理将整个结果读作文本,所以默认它得到每个结果一次. 与 `result: 'structured'` (默认)呼叫解决工具的 `structuredContent` 仅限内容时 重复一遍:一个文字块与相同的JSON,或者原始的a `{ content }` 如服务器所写, 包装器会坚守 用于不读取结构化输出的客户端. 否则,它决心 `{ content }`附加时 `structuredContent` 当有一个,所以文字 说更多,图像保存. `'content'` 总是决心 `{ content }`,以及 `'both'` 改为 `{ content, structuredContent }` 作为MCP客户端获得它们(形状可达1.9.4). `_meta` 永远 包含.
-   **错误.** 错误结果( E)`isError`),或服务器错误,以其消息拒绝.

## 在服务器加载前注册工具

页面中的服务器是一个大捆绑,开始是一个很长的任务. 要不装入页面,请计算工具 在构建时列出并在页面中注册; 服务器在代理机的第一个呼叫中加载.

`server.ts`,用于构建脚本和页面的一厂:

```typescript
import { WebMcpPlugin, type ModelContext } from '@frontmcp/plugin-webmcp';
import { create } from '@frontmcp/sdk';

export function createShopServer({ modelContext }: { modelContext?: ModelContext } = {}) {
  return create({
    info: { name: 'shop', version: '1.0.0' },
    tools: [SearchProducts, AddToCart],
    plugins: [WebMcpPlugin.init({ prefix: 'shop.', modelContext })],
  });
}
```

构建脚本( Node.js) :

```typescript
import { writeFile } from 'node:fs/promises';

import { listWebMcpTools } from '@frontmcp/plugin-webmcp';

import { createShopServer } from './server';

const tools = await listWebMcpTools((modelContext) => createShopServer({ modelContext }));
await writeFile('src/webmcp-tools.json', JSON.stringify(tools));
```

页面条目, 一个块, 没有 SDK :

```typescript
import { registerWebMcpTools, resolveDocumentModelContext } from '@frontmcp/plugin-webmcp/register';

import tools from './webmcp-tools.json';

void registerWebMcpTools(resolveDocumentModelContext(), tools, (modelContext) =>
  import('./server').then(({ createShopServer }) => createShopServer({ modelContext })),
);
```

-   `listWebMcpTools(factory)` 用一个 `modelContext` 记录插件注册的内容,返回 这些描述符(名称、标题、描述、输入方案、提示)并处理服务器。 工厂必须经过 `modelContext` 它被赋予 `WebMcpPlugin.init()`。 。 。 .
-   `registerWebMcpTools(modelContext, tools, loadServer, { exposedTo? })` 立即登记名单。 第一个电话 装入服务器 `loadServer` (无论有多少电话一起到来)并贯穿插件;失败 加载拒绝这个调用( 它所建的服务器被处理, 列出的工具被保留), 而下一个调用再次尝试 . 从那时起,随着服务器工具的变化,插件注册和取消注册工具,以及 `server.dispose()` 不登记他们。 挂载服务器缺少的列表工具未注册 。 没有 `modelContext` (没有WebMCP)它做 没什么.
-   `@frontmcp/plugin-webmcp/register` 不导入 `@frontmcp/sdk`这是几千字节。 出口 `registerWebMcpTools`, (中文(简体) ), `resolveDocumentModelContext` 财务报告和审定财务报表 `isWebMcpSupported`。 。 。 .

## 浏览器支持

WebMCP是一个草稿. Chrome和Edge在国旗或原产地试验后面;为了地方发展,打开 `chrome://flags/#enable-webmcp-testing`. 插件沿用了2026-09-30的草稿. 见 [浏览器](https://frontmcp.dev/reference/plugins/webmcp#browsers) 地点 `document.modelContext` 已提供.

何处 `document.modelContext` 缺少, 插件无所事事, 服务器像以前一样工作 ; `isWebMcpSupported()` 告诉你前面。 要支持其他浏览器, 加载安装的多填充 `document.modelContext` 在创建服务器之前, 例如 [`@mcp-b/global`](https://www.npmjs.com/package/@mcp-b/global),或者通过一个 `modelContext`。 。 。 .

WebMCP只曝光工具:资源和提示只保留MCP.

## 文档

-   [WebMCP 插件引用](https://frontmcp.dev/reference/plugins/webmcp): 选项, 翻译, 服务器所看到的 打电话 找麻烦.
-   [在浏览器中运行](https://frontmcp.dev/reference/deployment/browser): FrontMCP 服务器在网络中可以做什么 页 次.

## 相关软件包

-   [`@frontmcp/sdk`](https://www.npmjs.com/package/@frontmcp/sdk): " 总统府论坛 " 框架,包括 `create()` (单位:千美元) 服务器.
-   [`@frontmcp/react`](https://www.npmjs.com/package/@frontmcp/react): 用于服务器的反钩和组件 页; 添加组件的工具 `useDynamicTool()` 当它被安装时,它被提供给特工.

## 捐款

资料来源: [`plugins/plugin-webmcp`](https://github.com/agentfront/frontmcp/tree/main/plugins/plugin-webmcp)B. 议题和议题 欢迎拉请求;见 [捐款额](https://github.com/agentfront/frontmcp/blob/main/CONTRIBUTING.md)。 。 。 .

## 许可证

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

## 常见问题

### @frontmcp/plugin-webmcp 是什么？

FrontMCP的WebMCP插件 - 打开浏览器FrontMCP服务器的工具通过文档浏览器代理\. modelContext

### 如何安装 @frontmcp/plugin-webmcp？

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

### @frontmcp/plugin-webmcp 支持 TypeScript 吗？

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

### @frontmcp/plugin-webmcp 支持 ESM 还是 CommonJS？

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

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

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

### @frontmcp/plugin-webmcp 可以商用吗？

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

### @frontmcp/plugin-webmcp 的下载量有多少？

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

### @frontmcp/plugin-webmcp 还在维护吗？

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