企业官网建设流程全解析

Skybridge 端到端类型安全完整揭秘：tRPC 风格类型推导如何打通 MCP 服务器与 React 视图

【免费下载链接】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 Apps 和 ChatGPT Apps 的全栈 TypeScript 框架，它的核心卖点是端到端类型安全：你在 MCP 服务器上用 Zod 定义工具的输入输出结构之后，React 视图侧的工具名、参数、返回值全部自动获得类型推导，就像 tRPC 打通前后端 API 一样，中间无需手写任何契约。本文拆解这套类型推导机制的三层结构，带你看懂 Skybridge 类型安全是如何落地的。

为什么 MCP Apps 需要端到端类型安全 🛠️

在没有类型推导的 MCP 应用里，你通常会遇到三个痛点：

1. 工具名是裸字符串——拼错name只有运行时才发现；
2. 返回数据是unknown——视图读取structuredContent时全是指针式猜字段；
3. 视图组件名不受检——view: { component: "cousel" }这种笔误在注册时毫无提示。

Skybridge 的思路借鉴了 tRPC：不让你重复声明 API 形状，而是从服务器端已知的 schema一路推导到视图端的 Hook。类型只写一次，全链路生效。

第一层推导：registerTool 把工具形状固化进服务器类型

注册工具时，你用 Zod 声明inputSchema和outputSchema。Skybridge 会把每个工具固化为一个类型标记 ToolDef，它携带三样东西：

export type ToolDef<TInput, TOutput, TResponseMetadata> = { input: TInput; output: TOutput; responseMetadata: TResponseMetadata; };

关键在于这些工具类型会被收集进服务器实例的$types属性上（见 McpServerTypes）。它利用的是 TypeScript 的结构化类型：视图侧不依赖McpServer类本身，只要对象上有$types就能提取出完整工具表，因此可以跨包边界推导。提取逻辑集中在 inferUtilityTypes.ts，提供了一组工具类型：

更多配置细节可参考 register-tool.mdx。

第二层推导：generateHelpers 一键生成类型安全 Hooks ✨

拿到typeof app后，只需一行generateHelpers<AppType>()，就能生成带完整推导的useCallTool和useToolInfo，实现在 generate-helpers.ts。官方示例 capitals 项目的 helpers.ts 全文只有 4 行：

import { generateHelpers } from "skybridge/web"; import type { AppType } from "./server.js"; export const { useCallTool, useToolInfo } = generateHelpers<AppType>();

从此在视图里：

const { callTool, data } = useCallTool("create-checkout"); // 工具名：错拼直接报类型错误 // callTool 的参数：由 inputSchema 推导 // data.structuredContent：由 outputSchema 推导

工具名是联合类型而不是任意字符串，拼错一个字母 IDE 立刻标红——这正是 tRPC 风格"零契约"体验的精髓。

第三层保障：视图组件名同样参与类型检查 🗺️

工具绑定视图时写的component也不是普通字符串。构建时 Vite 插件会扫描src/views目录，把每个视图文件名写入生成的.skybridge/views.d.ts，扩展 ViewNameRegistry 接口，生成逻辑在 scan-views.ts。于是：

• view: { component: "carousel" }会被检查成真实存在的视图文件名的联合类型；
• 视图文件重命名或拼错，服务器端直接报编译错误。

下面这张图就是 capitals 示例的地图视图，它绑定的component正是被这层机制保护着的：

视图端体验：数据不再是 unknown 🛒

有了类型链路，视图读取工具结果时字段全部可推导、可补全。以电商轮播视图为例，useToolInfo<"search-products">()返回的output.products类型完全来自服务器端的outputSchema，无需任何类型断言：

用 Devtools 验证类型数据流 🔍

类型推导发生在编译期，而运行期的数据流可以在 Skybridge Devtools 中直接观察：左侧是注册的工具列表，中间是structuredContent的 JSON 输出，下方日志区能看到callTool请求/响应与setWidgetState的完整往返——这正是类型链路在运行时对应的数据通道：

总结：4 步获得 tRPC 风格的端到端类型安全

1. 服务器端用 Zod 声明inputSchema/outputSchema，工具形状固化为ToolDef；
2. 导出type AppType = typeof app；
3. 视图端一行generateHelpers<AppType>()生成类型安全 Hooks；
4. 视图名、工具名、参数、返回值全链路推导，笔误在编译期暴露。

延伸阅读：架构指南、useCallTool API、generate-helpers API。类型只写一次，全链路零断言——这就是 Skybridge 类型安全的完整答案。

【免费下载链接】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