# MCP 应用程序构建器技能此技能将指导您使用 LeanMCP UI SDK 构建 MCP 应用程序 - 具有交互式 React UI 的 MCP 服务器。 ## 何时使用此技能 * 用户请求“MCP with UI” * 用户想要“交互式 MCP 服务器” * 用户提到“MCP App”或“leanmcp UI” * 用户需要“MCP工具仪表板” * 用户想要“人工智能工具的可视化界面” * 用户提及“@leanmcp/ui”或“@UIApp” * 用户请求“ChatGPT App”或“GPT App” ## 什么是 MCP 应用程序？ MCP 应用程序扩展了 MCP 服务器以提供交互式 UI。应用程序在沙盒 iframe 中运行，并通过 postMessage 通过 JSON-RPC 进行通信。调用工具时，UI 可以与工具响应一起显示。 ## 核心架构 1. **服务文件** (`mcp/*/index.ts`) - 用 `@Tool` 和 `@UIApp` 修饰的工具方法 2. **组件文件** (`mcp/*/*.tsx`) - 使用 `@leanmcp/ui` 组件的 React 组件 3. **CLI 处理其余的** \- `leanmcp dev` 使用 AppProvider 构建和包装组件 ## 所需的依赖项 { “依赖项”：{ "@leanmcp/core": "^0.4.7", "@leanmcp/ui": "^0.3.7", “反应”：“^18.0.0”， "react-dom": "^18.0.0", “dotenv”：“^16.5.0” }, “开发依赖项”：{ "@leanmcp/cli": "最新", "@types/react": "^18.0.0", "@types/react-dom": "^18.0.0", "@types/node": "^20.0.0", “打字稿”：“^5.6.3” } } ## TypeScript 配置 { “编译器选项”：{ “experimentalDecorators”：正确， “emitDecoratorMetadata”：true， “目标”：“ES2020”， “模块”：“ESNext”， "moduleResolution": "节点", "jsx": "react-jsx", "jsxImportSource": "反应", "outDir": "./dist", “严格”：正确 }, “包括”：[“**/*.ts”，“**/*.tsx”，“mcp/**/*.ts”，“mcp/**/*.tsx”] } ## 项目结构我的-mcp-应用程序/ ├── main.ts # 入口点 ├── mcp/ │ └── 产品/ │ ├── index.ts # 使用@Tool + @UIApp 的服务 │ └── ProductsDashboard.tsx # React 组件 ├── package.json └── tsconfig.json ## 两个导入路径（关键）进口|用于 |内容 ---|---|--- `@leanmcp/ui/server` |服务文件（`index.ts`）|仅“UIApp”、“GPTApp”装饰器 `@leanmcp/ui` |组件文件 (`.tsx`) | React 组件、钩子、样式 ## @UIApp 装饰器 **关键：@UIApp 是一个 METHOD 装饰器，而不是一个类装饰器！** ### 正确用法 // mcp/products/index.ts 从“@leanmcp/core”导入{工具}；从'@leanmcp/ui/server'导入{UIApp}； // 服务器导入！导出类 ProductsService { @Tool({ 描述: '列出产品' }) @UIApp({ component: './ProductsDashboard' }) // 使用 @Tool 的方法异步 listProducts(args: { page?: number }) { 返回 { 产品：[...]，总计：100 }； } } ### 错误 - 切勿这样做 // 错误：@UIApp 在类上 @UIApp({ component: './Dashboard' }) // 错误！导出类 MyService { ... } ### @UIApp 选项 @UIApp({ component: './ComponentName', // 必填：相对路径（字符串，不导入） uri: 'ui://custom/path', // 可选：自定义 URI title: '页面标题', // 可选 styles: 'body { ... }' // 可选：附加 CSS }) ## React 组件开发 ### 基本组件 // mcp/products/ProductsDashboard.tsx 从 '@leanmcp/ui' 导入 { RequireConnection, ToolDataGrid }; 导入'@leanmcp/ui/styles.css'; 导出函数 ProductsDashboard() { 返回（正在加载...}>

产品

<工具数据网格 dataTool="列表产品" 列={[ { key: '名称', header: '名称', 可排序: true }, { key: '价格', header: '价格' } ]} 变换数据={（结果）=>（{ 行：结果.产品，总计：结果.总计 })} 分页 />

）； } ### 关键规则 1. **切勿使用 AppProvider 包装** \- CLI 自动执行此操作 2. **始终使用 RequireConnection** \- 显示加载直到主机连接 3. **导入样式** \- `import '@leanmcp/ui/styles.css'` 4. **导出匹配名称** \- 文件 `Foo.tsx` 导出 `function Foo()` 5. **使用字符串路径** \- `'./Component'` 不直接导入 ## 核心组件 ### 工具按钮调用具有加载状态和确认的工具的按钮：从 '@leanmcp/ui' 导入 { ToolButton }； <工具按钮工具=“删除项目” args={{ id: item.id }} 确认={{ title: '删除项目？', 描述：“此操作无法撤消。” }} 变体=“破坏性” 结果显示=“吐司” onToolSuccess={() => 重新获取()} > 删除 **道具：** * `tool` \- 要调用的工具名称 * `args` \- 要传递的参数 * `confirm` \- 确认对话框配置 * `变体` \- `默认`、`破坏性`、`轮廓`、`幽灵` * `resultDisplay` \- `toast`, `inline`, `none` * `onToolSuccess` / `onToolError` \- 回调 ### 工具表单提交给工具的表单：从 '@leanmcp/ui' 导入 { ToolForm }； <工具窗体工具名称=“创建产品” 字段={[ { name: '名称', label: '产品名称', type: '文本', required: true }, { name: '价格', label: '价格', type: '数字', 分钟: 0 }, { 名称：'类别'，标签：'类别'，类型：'选择'，选项：[ { 值：'电子产品'，标签：'电子产品' }， { 值：'服装'，标签：'服装' } ]}, { name: 'inStock', label: 'In Stock', type: 'switch' } ]} 提交文本=“创建产品” 显示成功Toast 成功重置 onSuccess={(结果) => console.log('已创建：', 结果)} /> **字段类型：** `文本`、`数字`、`电子邮件`、`文本区域`、`选择`、`开关`、`滑块`、`日期` ### 工具数据网格具有排序和行操作的服务器分页表：从 '@leanmcp/ui' 导入 { ToolDataGrid }； <工具数据网格 dataTool="listProducts" // 不是“工具名称”！列={[ { key: 'name', header: 'Name', sortable: true }, // 不是 'field'/'headerName'！ { key: 'price', header: 'Price', render: (v) => `$${v.toFixed(2)}` } ]} TransformData={(r) => ({ 行: r.products, 总计: r.total })} 分页页面大小={20} freshInterval={30000} // 不是“自动刷新”！行动作={[ { 标签：'编辑'，工具：“编辑产品”， getArgs: (行) => ({ id: row.id }) }, { 标签：'删除'，工具：“删除产品”， getArgs: (row) => ({ id: row.id }), 变体：“破坏性”，确认：{标题：'删除？'，描述：'无法撤消'} } ]} /> **要避免的常见错误：** * 使用`dataTool`而不是`toolName` * 使用`key`/`header`而不是`field`/`headerName` * 使用 `refreshInterval` 而不是 `autoRefresh` * 始终提供`transformData` ### 工具选择选择带有基于工具的选项的下拉菜单：从 '@leanmcp/ui' 导入 { ToolSelect }； <工具选择 optionsTool =“列表类别” TransformOptions={(r) => r.categories.map(c => ({ value: c.id, label: c.name }))} onSelectTool="设置类别" argName="类别ID" placeholder=“选择类别” /> ### 资源视图通过自动刷新显示 MCP 资源：从'@leanmcp/ui'导入{ResourceView}； <资源视图 uri =“配置：//设置” 刷新间隔={5000} 渲染={（数据）=>（

{JSON.stringify(data, null, 2)}

)} /> ## 核心挂钩 ### 使用工具以编程方式调用 MCP 工具：从'@leanmcp/ui'导入{useTool}；函数 MyComponent() { const { 调用、结果、加载、错误 } = useTool('get-data', { 重试：3，变换：(r) => r.data }); 使用效果（（）=> { 调用（{过滤器：'活动'}）； }, []); if (loading) return

正在加载...

; if (error) return

错误: {error.message}

; return

{结果?.值}

; } ### 使用资源阅读 MCP 资源：从'@leanmcp/ui'导入{useResource}；函数配置视图（）{ const { 数据、加载、刷新 } = useResource('config://settings', { 刷新间隔：5000 }); 返回（

{正在加载&&

正在加载...

} {data &&

{JSON.stringify(data, null, 2)}

}

）； } ### useHostContext 访问宿主环境（主题、视口）：从'@leanmcp/ui'导入{useHostContext}；函数 ThemedComponent() { const { 主题，视口 } = useHostContext(); 返回（

内容

）； } ## GPT 应用 SDK 挂钩对于 ChatGPT 应用程序集成： ### 使用工具输出从工具响应中访问“结构化内容”：从'@leanmcp/ui'导入{useToolOutput}；函数 ChannelsView() { const toolOutput = useToolOutput<{ 通道: Channel[] }>(); if (!toolOutput?.channels) return

无通道

; 返回（

{ch.name}

）； } ### useWidgetState 跨会话的持久状态：从'@leanmcp/ui'导入{useWidgetState}；函数 FilteredView() { const [state, setState] = useWidgetState<{ 过滤器: string }>({ 过滤器: 'all' }); 返回（ <选择值={状态.过滤器} onChange={(e) => setState({ filter: e.target.value })} > <选项值=“全部”>全部 <选项值=“活动”>活动）； } ## @GPTApp 装饰器特别对于 ChatGPT 应用程序：从“@leanmcp/core”导入{工具}；从'@leanmcp/ui/server'导入{GPTApp}；导出类 SlackService { @Tool({ 描述: '撰写 Slack 消息' }) @GPTApp({ 组件：'./SlackComposer'，名称： 'slack-composer' }) 异步 composeMessage() { 返回 { 频道：[...] }; } } ## 完整示例 ### 服务文件 // mcp/仪表板/index.ts 从“@leanmcp/core”导入{工具、资源、SchemaConstraint}；从'@leanmcp/ui/server'导入{UIApp}；类创建项目输入{ @SchemaConstraint({ 描述: '项目名称', minLength: 1 }) 名称！：字符串； @SchemaConstraint({ 描述: '项目值', 最小值: 0 }) 值！：数字； } 导出类 DashboardService { 私有项目：any[] = []； @Tool({ description: '查看带有项目的仪表板' }) @UIApp({ 组件: './仪表板' }) 异步 viewDashboard() { return { items: this.items, 总计: this.items.length }; } @Tool({ 描述: '创建一个新项目', inputClass: CreateItemInput }) 异步createItem（输入：CreateItemInput）{ const item = { id: crypto.randomUUID(), ...input, createdAt: new Date().toISOString() }; this.items.push(item); 返回{成功：true，项目}； } @Tool({ description: '删除项目' }) 异步deleteItem(args: { id: string }) { this.items = this.items.filter(i => i.id !== args.id); 返回 { 成功：真 }; } @Resource({ 描述: '仪表板统计信息' }) 异步统计() { 返回{ 内容：[{ uri: '仪表板://统计', mimeType: 'application/json', 文本：JSON.stringify({ 总计：this.items.length， TotalValue: this.items.reduce((sum, i) => sum + i.value, 0) }) }] }; } } ### 组件文件 // mcp/仪表板/Dashboard.tsx 从 '@leanmcp/ui' 导入 { RequireConnection、ToolDataGrid、ToolForm、ToolButton、useResource }；导入'@leanmcp/ui/styles.css'; 导出函数仪表板（）{ const { 数据：统计信息，刷新 } = useResource('dashboard://stats'); 返回（正在连接...}>

仪表板

{/* 统计数据 */} {统计数据 && (

总项目：{stats.total}

总价值：${stats.totalValue}

)} {/* 创建表单 */}

创建项目

<工具窗体工具名称=“创建项目” 字段={[ { name: 'name', label: 'Name', type: 'text', required: true }, { name: 'value', label: 'Value', type: 'number', min: 0, required: true } ]} 提交文本=“创建” 显示成功Toast 成功重置 onSuccess={() => 刷新()} />

{/* 项目表 */}

项目

<工具数据网格数据工具=“视图仪表板” 列={[ { key: '名称', header: '名称', 可排序: true }, { key: 'value', header: 'Value', render: (v) => `$${v}` }, { key: 'createdAt', header: 'Created', render: (v) => new Date(v).toLocaleDateString() } ]} TransformData={(r) => ({ 行: r.items, 总计: r.total })} 行动作={[ { 标签：'删除'，工具：'删除项目'， getArgs: (row) => ({ id: row.id }), 变体：“破坏性”，确认：{标题：'删除项目？'，描述：'此操作无法撤消。' } } ]} 分页显示刷新 getRowKey={(行) => row.id} />

）； } ## 主题化应用程序通过 CSS 变量自动适应主机主题：：根{ --颜色背景主色：#ffffff； --颜色文本主色：#171717； } .暗{ --颜色背景主色：#0a0a0a； --颜色文本主色：#fafafa； } 在 React 中访问： const { 主题 } = useHostContext(); const isDark = 主题 === '黑暗'; ## 编辑指南 ### 做 * 在服务“index.ts”文件旁边创建“.tsx”文件 * 在与“@Tool”配对的方法上使用“@UIApp” * 从服务文件中的`@leanmcp/ui/server`导入 * 从组件文件中的`@leanmcp/ui`导入 * 始终将内容包装在 `RequireConnection` 中 * 导入`@leanmcp/ui/styles.css` ### 不要 * 用AppProvider封装组件 * 将`@UIApp`放在类上 * 在 `@UIApp({ component: ... })` 中使用直接导入 * 使用错误的属性名称（toolName、field、autoRefresh） * 在响应中添加终端命令

Mcp 应用程序生成器

包含技能