Skybridge 工具系统实战：如何注册 Tools 定义你的 MCP App 能力边界

Skybridge 工具系统实战：如何注册 Tools 定义你的 MCP App 能力边界

【免费下载链接】skybridgeSkybridge is a full-stack TypeScript framework for MCP Apps and ChatGPT Apps. Type-safe. React-powered. Platform-agnostic.项目地址: https://gitcode.com/gh_mirrors/skybr/skybridge

🛠️Skybridge是面向MCP App与 ChatGPT Apps 的全栈 TypeScript 框架，而registerTool 工具注册正是它的核心能力：你通过它声明 MCP App 能做什么、接受什么参数、返回什么结构，从而为应用划定清晰的"能力边界"。本文用一个可运行的示例带你快速上手工具系统，并讲透view、annotations、auth这些关键配置项。

图片文件：docs/images/tools.webp

工具是什么：MCP App 的"能力边界"

在 Skybridge 里，一个Tool（工具）就是模型可以调用的一次"动作"：

• 对模型：name、description、inputSchema构成它的"提示词表面"，模型据此决定何时调用；
• 对用户：绑定了view的工具会渲染出 React 交互界面，而不只是一段纯文本回复；
• 对你：工具返回的structuredContent是带类型的结构化数据，可被前端 Hook 直接消费。

一句话概括：你注册了多少工具，你的 MCP App 就能做多宽的事——这就是能力边界。

实战：5 行注册一个工具

Skybridge 应用的最小形态是在handler中链式调用 server.registerTool：

server.registerTool( { name: "search-products", title: "Search products", description: "按关键词和可选的价格上限搜索商品目录。", inputSchema: { query: z.string().describe("用户想找什么") }, }, async ({ query }) => ({ content: `Found products for ${query}` }), );

完整字段（outputSchema、view、annotations、auth、openai等）可查阅官方文档 register-tool.mdx。

完整示例：世界首都探索器

仓库内置的 capitals 示例 是一个教科书级的工具注册案例：

server.registerTool( { name: "explore-capitals", description: "探索世界首都，展示带人口、货币与照片的交互式地图……", inputSchema: { name: z.string().describe("英语首都名，如 'Paris'、'Tokyo'"), }, annotations: { readOnlyHint: true, openWorldHint: true, destructiveHint: false }, view: { component: "explore-capitals", csp: { resourceDomains: ["https://upload.wikimedia.org"] }, }, }, async ({ name }) => { const capital = await getCapitalByName(name); return { content: formatCapitalForModel(capital), // 给模型看的文字 structuredContent: { capital }, // 给视图看的类型化数据 }; }, );

对应的 React 视图位于 explore-capitals.tsx，最终呈现为一张可交互的世界地图：

图片文件：docs/images/showcase-capitals.png

关键配置速览：写对 description 与 schema

1. 为模型而写的 name / title / description

这三个字段是模型的"决策依据"。官方建议把description写成明确的触发条件，例如 capitals 示例中的"Always use it when users ask about capitals, countries…"——模型读得越懂，调用时机越准。

2. 用.describe()给每个字段补说明书

inputSchema使用 Zod（4.2+）等 Standard Schema 校验器，既校验入参、又为 handler 入参推导类型。给字段加.describe()能显著降低模型"传错参数"的概率。outputSchema则告诉模型预期返回结构。

3. 返回值的三层结构

字段	谁能看到	用途
content	模型 + 对话界面	文本/图片等内容块
structuredContent	模型 + 视图	类型化数据，视图通过useToolInfo读取
_meta	仅视图（对模型隐藏）	如 capitals 示例中塞入全量首都列表，避免"淹没"模型上下文

进阶配置：annotations、CSP 与每工具鉴权

• annotations：标准 MCP 提示位（readOnlyHint、destructiveHint、idempotentHint、openWorldHint），宿主可据此排序和标注调用，但从不据此拦截；
• view.csp：视图运行在沙箱 iframe 中，你的服务域名自动放行，外部资源域名需按指令显式声明（如 capitals 放行了 Mapbox 与 Wikimedia）；
• auth：推荐的每工具鉴权声明。默认要求登录（安全默认值）；{ allowsAnonymous: true }允许匿名调用；{ scopes: [...] }要求具备指定权限，未达标调用会在 handler 执行前被拒。

图片文件：docs/images/devtools.webp

开发时，Skybridge 的 DevTools 本地模拟器可以直接观察每个工具的定义、入参校验与视图渲染效果，是验证"能力边界"的最快方式。

类型安全一路打穿：从 registerTool 到前端 Hooks

registerTool的妙处不止于运行时——每次链式调用都会把工具的输入/输出结构累积到 server 类型上（见 McpServer 实现）。借助 generateHelpers 可以"零泛型"地在视图侧拿到全自动补全的 Hook：

// helpers.ts：类型只导入一次 export const { useCallTool, useToolInfo } = generateHelpers<AppType>();

之后useToolInfo<"search-products">()的output、useCallTool("checkout")的入参类型全部自动推导——这就是 Skybridge 主打的tRPC 式端到端类型安全。

图片文件：docs/images/mcp-apps.webp

上手清单：三步注册好你的第一个工具

1. ✅ 在handler中调用server.registerTool(config, handler)，name用小写短横线；
2. ✅description面向模型写清"何时调用 + 能做什么"，每个字段加.describe()；
3. ✅ 需要交互界面时绑定view: { component: "xxx" }（文件名对应views/下的文件，自动类型检查），并按需配置 CSP 与annotations。

更多可运行案例可参考 examples/everything 示例（多工具 + 文件输入）与 capitals 示例。完整 API 说明见 api-reference。

💡小结：registerTool是 Skybridge 中定义 MCP App 能力边界的唯一入口——写好它是模型调对工具、视图渲染对界面、前端拿到对类型的地基。

【免费下载链接】skybridgeSkybridge is a full-stack TypeScript framework for MCP Apps and ChatGPT Apps. Type-safe. React-powered. Platform-agnostic.项目地址: https://gitcode.com/gh_mirrors/skybr/skybridge