MCP Apps 核心概念入门用 Skybridge 理解 Tools、Views 与 State 三大基石【免费下载链接】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/skybridgeSkybridge 是一个全栈 TypeScript 框架专为构建运行在 ChatGPT 和 Claude 中的MCP Apps而设计。MCP Apps 与传统 Web 应用最大的不同它不是用户 ↔ 应用的双向系统而是应用、用户、模型三方协作的系统。理解这三方之间如何流动信息只需要掌握三大基石Tools工具、Views视图、State状态。本文用最少的代码带你完整走一遍这三块拼图。为什么 MCP Apps 是三方系统先建立一个心智模型后面所有概念都围绕它展开角色它能看到什么它的盲区 用户对话 渲染出来的视图看不到工具背后的数据流 模型工具输出、共享状态看不见 UI除非你显式同步回去 你的应用服务器数据 共享状态无法直接替用户做决定最关键的洞察模型是盲的。用户在界面上点选了什么、购物车里加了什么模型统统不知道——除非你通过 Tool 输出或 State 把信息递给它。这正是三大基石分工的由来Tool定义能做什么——模型和用户可调用的能力入口View决定长什么样——渲染在对话流中的交互式 React 界面State解决谁看见什么——在视图与模型之间建立信息通道官方对这一架构的完整阐述见 docs/get-started/architecture.mdx。基石一Tool工具——应用的入口把 Tool 想象成你应用的API每个工具有且只有一个职责模型读取工具的描述后在合适的对话时机自动调用它。一个 Tool 由四部分组成元信息name/title/description——写给模型看的说明书描述质量直接决定模型选不选它输入输出 Schema——用 Zod 声明模型必须传什么、你会返回什么实现端到端类型安全Handler——真正的业务逻辑返回值分三个通道content只给模型、structuredContent模型和视图都可见、_meta只给视图模型永远看不到视图绑定——view: { component: xxx }指向views/目录下的组件模型每次调用工具就在对话中挂载一个新实例// 最精简的一个 Tool 定义 server.registerTool( { name: search-products, description: Show products matching a query in a carousel., inputSchema: { query: z.string() }, view: { component: carousel }, // 绑定视图 }, async ({ query }) ({ structuredContent: { products: await search(query) }, }), );几个值得记住的要点 没有绑定视图的 Tool 是无头的只返回数据不渲染界面⚠️ 每个工具可声明行为注解只读破坏性操作宿主会据此决定是否弹确认框 返回值选哪个通道是一个设计决策图片 URL 这类模型用不上的数据放进_meta就不会挤占模型上下文完整讲解在 docs/build/tools.mdx框架中工具注册与执行的实现位于 packages/core/src/server/。基石二View视图——渲染在对话里的界面View 是应用的脸面一个普通的 React 组件存放在views/目录运行在宿主ChatGPT、Claude提供的沙箱 iframe 中。它做三件事读工具结果useToolInfo钩子提供工具的输入参数、structuredContent输出和_meta元数据并跟踪 pending → success 的生命周期方便你渲染加载骨架屏回调工具useCallTool让用户点击按钮时直接调用服务器上的任意工具不经过模型——比如点结算按钮直接调create-checkout管理状态下一节详述新手最容易踩的两个认知坑按实例思考同一对话里模型两次调用搜索工具就是两个相互独立的视图实例不是单例CSP 默认全封锁iframe 只放行你自己服务器的域名需要访问外部 API 或 CDN 资源时必须在服务端视图配置里显式声明域名Skybridge 会自动生成类型安全的辅助钩子helpers.ts视图里写useToolInfosearch-products()就能获得完整的参数与返回类型自动补全。细节见 docs/build/view.mdx。基石三State状态——让模型看见屏幕这是 MCP Apps 与传统 Web 开发差异最大的一块。工具调用之间模型对用户交互完全失明但它回答下一句话时又常常需要知道屏幕上发生了什么。Skybridge 给出三条通道选型逻辑一目了然使用场景推荐 API模型可见重开会话后保留对话要依赖的数据购物车、选中项、草稿useViewState✅✅ 持久化屏幕内容的自然语言描述data-llm属性✅每次渲染重算模型完全不需要知道的 UI 细节悬停、动画ReactuseState❌❌useViewState可以理解为增强版 useState多了两个超能力宿主帮你持久化关闭对话再打开状态还在以及模型可读下一轮对话时模型能看到它。而data-llm是给模型的旁白——用一句自然语言描述当前画面比如购物车里有 3 件商品。正是它让用户的口语化追问你觉得这件怎么样里的这件能被模型正确解析。const [cart, setCart] useViewState{ ids: string[] }({ ids: [] }); // 共享、持久 const [hovered, setHovered] useStatestring | null(null); // 模型不可见 return ( div />实战串联一个私人导购小助手用官方架构文档中的购物例子把三大基石串成完整故事用户说我想找冬天的衣服→ 模型调用search-products(winter)工具返回商品列表宿主在对话中挂载商品轮播视图Tool → View用户点选夹克加入轮播 → 视图写入useViewState购物车View → State用户问还有什么推荐→ 模型读取购物车状态结合屏幕上已有的商品给出搭配建议State → Model用户点去结算 → 视图直接回调create-checkout绕开模型完成支付跳转View → Tool数据在三个角色之间各司其职地流动模型负责理解意图和给出建议视图负责交互状态负责在两者之间搭桥。这套个人购物模式正是电商类 MCP App 的骨架参考 examples/ecom-carousel/ 示例项目。动手验证本地 DevTools 快速调试 MCP App概念都懂了怎么验证你的应用真的能跑不用注册连接、不用等模型猜对工具——Skybridge 自带DevTools 模拟器一条命令启动npx skybridge create # 脚手架生成项目 npm run dev # 启动本地服务器打开http://localhost:3000/即可使用左侧栏自动列出你注册的所有工具点击任意工具可直接调用并看到完整响应content/structuredContent/_meta三通道一目了然、状态检查器、以及视图实时预览还能一键切换 ChatGPT / Claude 两种会话外壳、亮暗主题和手机视口提前发现布局问题。保存文件即热更新测试循环从注册连接器 反复 prompt缩短到存一下文件。更多调试手段隧道联调真实宿主、Playground、自动化评测见 docs/test/。快速上手路线与延伸阅读想做什么去哪里看10 分钟跑通第一个 MCP Appdocs/get-started/quickstart.mdx深入架构与三方数据流docs/get-started/architecture.mdx工具、视图、状态完整文档docs/build/完整示例合集购物、棋类、游戏、认证examples/部署上线docs/ship/记住这张图三大基石就不乱了Tool是入口定义能力模型和用户都能触发️View是界面React 组件活在对话流里State是桥梁决定模型看见什么并让它跨会话存活掌握谁在什么时候看到什么你就掌握了 MCP Apps 的全部设计精髓。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考