@ag-ui/mcp-apps-middle软件
MCP 磁共振 应用AG-UI的中间软件,从MCP(模式上下文协议)服务器中启用UI启用的工具.
安装
npm install @ag-ui/mcp-apps-middleware
# or
pnpm add @ag-ui/mcp-apps-middleware
使用量
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和结果继续代理. 该模型可以在没有单独用户消息的情况下完成转会. 它等待未解决的前端工具调用,并保存中断或取消的运行. 工具链限制为十发;超过限制会使流出故障.
配置
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 只有这个.
活动快照
中间软件释放出活动快照,其结构如下:
{
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数字 :
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。 。 。 .
出口公用事业
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 公共集成测试 :
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 已存在.