# @ag-ui/mcp-apps-middleware 中文文档

规范地址：https://npmcn.com/package/%40ag-ui/mcp-apps-middleware/

版本：0\.1\.3
npm 元数据更新时间：2026-10-30T21:04:35.682Z
中文译文更新时间：2026-11-05T17:05:03.107Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ag-ui/mcp-apps-middleware
原文对照：https://npmcn.com/package/%40ag-ui/mcp-apps-middleware/?lang=original
项目主页：https://github.com/ag-ui-protocol/ag-ui#readme
源码仓库：https://github.com/ag-ui-protocol/ag-ui

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

- 包体积（解压后）：116 kB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：rxjs 7\.8\.1，@ag-ui/client \>=1\.0\.0
- 首次发布：2025-12-05T12:39:48.381Z
- 最新版本发布：2026-10-30T21:04:35.345Z
- 近 30 天下载量：1419879（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

MCP 磁共振 应用AG-UI的中间软件,从MCP(模式上下文协议)服务器中启用UI启用的工具.

## 安装

```sh
npm install @ag-ui/mcp-apps-middleware
```

也可以使用：`pnpm add @ag-ui/mcp-apps-middleware`、`yarn add @ag-ui/mcp-apps-middleware`、`bun add @ag-ui/mcp-apps-middleware`

## README

# @ag-ui/mcp-apps-middle软件

MCP 磁共振 应用AG-UI的中间软件,从MCP(模式上下文协议)服务器中启用UI启用的工具.

## 安装

```bash
npm install @ag-ui/mcp-apps-middleware
# or
pnpm add @ag-ui/mcp-apps-middleware
```

## 使用量

```typescript
import { MCPAppsMiddleware } from "@ag-ui/mcp-apps-middleware";

const agent = new YourAgent().use(
  new MCPAppsMiddleware({
    mcpServers: [
      {
        type: "http",
        url: "http://localhost:3001/mcp",
        serverId: "weather-server",
      },
    ],
  }),
);
```

## 特征

-   从 MCP 服务器中发现模式可见工具,包括没有UI 元数据的先决条件
-   将工具注入代理工具列表
-   执行工具调用并返回其结果; 仅为使用 UI 资源 URI 的工具发布活动快照
-   支持代理 MCP 前端资源获取请求

工具默认是模式可见的. 明确 `_meta.ui.visibility` 列表必须包含 `"model"` 将一个工具暴露给代理; 通过 iframe 代理仍然可以使用只应用的工具。 例如, Excalidraw 的 `read_me` 返回格式指南作为普通工具结果,同时 `create_view` 还会产生UI活性.

在工具返回后,包括一个UI工具,中间软件以原始调用ID和结果继续代理. 该模型可以在没有单独用户消息的情况下完成转会. 它等待未解决的前端工具调用,并保存中断或取消的运行. 工具链限制为十发;超过限制会使流出故障.

## 配置

```typescript
interface MCPAppsMiddlewareConfig {
  mcpServers?: MCPClientConfig[];
  discoveryFailureMode?: "continue" | "throw"; // Default: "continue"
}

type MCPClientConfig =
  | {
      type: "http";
      url: string;
      headers?: Record<string, string>;
      serverId?: string;
    }
  | {
      type: "sse";
      url: string;
      headers?: Record<string, string>;
      serverId?: string;
    };
```

### 服务器标识

可选 `serverId` 字段为服务器提供了稳定的标识符。 这在下列情况下是有用的:

-   服务器 URL 可能会改变( 例如, 不同的环境)
-   要人可读的服务器识别
-   前端代码需要按名称引用服务器

若为 `serverId` 未提供服务器,服务器通过运输的MD5散列识别 `type` 财务报告和审定财务报表 `url` 只有这个.

## 活动快照

中间软件释放出活动快照,其结构如下:

```typescript
{
  type: "ACTIVITY_SNAPSHOT",
  activityType: "mcp-apps",
  content: {
    result: MCPToolCallResult,     // Result from the tool execution
    resourceUri: string,           // URI of the UI resource to fetch
    serverHash: string,            // MD5 hash of transport type and URL only
    serverId?: string,           // Server ID (if configured)
    toolInput: Record<string, unknown>  // Arguments passed to the tool
  },
  replace: true
}
```

前端应使用代理 MCP 请求获取资源内容 `resourceUri` 和两个 `serverHash` 或者说 `serverId`。 。 。 .

## 近期 MCP 请求

中间软件支持由前端代理的MCP请求. 通过 a `ProxiedMCPRequest` 内 `forwardedProps.__proxiedMCPRequest`数字 :

```typescript
interface ProxiedMCPRequest {
  serverHash: string; // MD5 hash of transport type and URL only
  serverId?: string; // Optional server ID for lookup
  method: string; // MCP method (e.g., "resources/read", "tools/call")
  params?: Record<string, unknown>;
}
```

服务器搜索偏好 `serverId` 如果提供,则返回到 `serverHash`。 。 。 .

## 出口公用事业

```typescript
import {
  MCPAppsActivityType, // "mcp-apps" constant
  getServerHash, // Hash transport type and URL; excludes headers
} from "@ag-ui/mcp-apps-middleware";
```

## 代理连接

要求数 `@modelcontextprotocol/sdk >=1.15.0`。1.15.0版本是第一个发布 带有自定义 `fetch` 支持 HTTP 和 SSE 客户端传输,它包括 HTTP 密码 `terminateSession()`。这些API 执行原发地守卫和会话清理. 锁文件将这个软件包的 SDK 指向1.15.0 所以CI测试了最小支持的版本.

中间软件只接受 `tools/call`, (中文(简体) ), `resources/read`, (中文(简体) ), `notifications/message`,以及 `ping` 从 iframe 代理请求. 它在连接到MCP服务器之前拒绝其他方法. HTTP 发现,工具调用,和代理请求在关闭客户端前删除其MCP会话. 会话删除使用它自己的三秒中止信号,因此在握手失败后可以进行清理以中止SDK信号. 如果服务器拒绝删除会话或在三秒内不回复,客户端仍会关闭并保存原始操作结果.

服务器散列排除了信头,因此浏览器可见的引用不包含证书的校验和. 此修改配置有信头的服务器的散列 。 升级后重建活动信息; 稳定使用 `serverId` 用于必须幸存配置变化的引用值. 如果多个配置共享一个传输类型和 URL,则每个配置必须有一个不同的 `serverId`。 。 。 . 仅针对该终点的散列请求被拒绝,因为它们无法识别预定的证书范围.

MCP连接不遵循重定向,运输请求必须停留在所配置的来源上. URL必须使用HTTP(S),不得包含嵌入式用户证书.

发现在默认情况下继续通过无法使用的服务器 。 设定 `discoveryFailureMode: "throw"` 如果任何配置的服务器无法提供其工具,则在引用代理之前停止. 代理响应和抛出发现错误省略了原始上游响应机构. 服务器侧诊断包括: `serverId`,无证书服务器散列,以及 发现模式和代理失败的原始错误。 将这些日志视为 只有操作者的数据:上游错误可以包括私人响应机构.

## 工具可见度

发现读取 `_meta.ui.resourceUri`,与 `_meta["ui/resourceUri"]` 作为遗产的后退. 何时 `_meta.ui.visibility` 中省略,默认情况下,工具仍为模型可见. 明确的知名度清单必须包括: `"model"` 为模型化的发现. 标记工具 `["app"]` 保留对模型的隐藏,并通过 iframe 代理调用.

## 许可证

麻省理工学院

## 核查

从寄存器根运行 Excalidraw 公共集成测试 :

```sh
MCP_APPS_LIVE_TEST=1 pnpm exec nx run @ag-ui/mcp-apps-middleware:test --skip-nx-cache
```

这个练习了真正的MCP工具的发现,先决条件和UI工具执行,以及UI资源检索. 模型选择,浏览器渲染,再播放行为需要下游应用验证.

失败的中间软件结果 `metadata["ag-ui:tool-result"].error`. 字符串标记(包括空字符串)在不改变结果有效载荷的情况下,通过客户端历史保存出错状态. Claude SDK 恢复在没有明确工具信息时读取此标记 `error` 已存在.

## 常见问题

### @ag-ui/mcp-apps-middleware 是什么？

MCP 磁共振 应用AG-UI的中间软件,从MCP\(模式上下文协议\)服务器中启用UI启用的工具\.

### 如何安装 @ag-ui/mcp-apps-middleware？

在项目目录运行 npm install @ag-ui/mcp-apps-middleware，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：rxjs（7\.8\.1）、@ag-ui/client（\>=1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ag-ui/mcp-apps-middleware 支持 TypeScript 吗？

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

### @ag-ui/mcp-apps-middleware 支持 ESM 还是 CommonJS？

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

### @ag-ui/mcp-apps-middleware 可以商用吗？

@ag-ui/mcp-apps-middleware 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ag-ui/mcp-apps-middleware 的下载量有多少？

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

### @ag-ui/mcp-apps-middleware 还在维护吗？

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