OpenParable
Skip to content
← Back to skills

MCP Apps Project Standard

Development
mcp-apps-project-standard

MCP Apps Project Standard is an Agent Skill for development published in the bage2014/study repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

MCP Apps项目规范 - 后端驱动UI渲染架构。所有页面由后端生成HTML通过MCP协议返回渲染。Invoke when developing or maintaining MCP Apps projects, especially when creating new pages, tools, or stores.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/bage2014/study/blob/HEAD/study-ai-mcp-apps/.trae/skills/mcp-apps-project-standard/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/mcp-apps-project-standard, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

MCP Apps 项目规范

核心架构原则

后端驱动UI渲染(MVP模式)

  • Model(数据层):后端存储和管理所有业务数据
  • View(视图层):前端仅负责渲染,不包含业务逻辑
  • Presenter(展示层):后端生成完整的HTML页面,通过MCP协议返回

数据流向

用户操作 → iframe → postMessage → MCP Host → MCP Tool Call → 后端处理 → 返回结果
                                                              │
                                                              ▼
                                                     更新数据/生成新UI
                                                              │
                                                              ▼
                                                     返回UI Resource → 重新渲染iframe

目录结构

src/
├── components/           # 前端组件(仅Host)
│   └── MCPHost.tsx      # MCP客户端Host
├── server/              # 后端服务
│   ├── tools/           # MCP工具定义
│   ├── ui/              # UI页面生成器(HTML模板)
│   ├── stores/          # 数据存储层
│   └── index.ts         # 服务器入口
├── shared/              # 共享类型定义
├── App.tsx              # 前端入口
└── main.tsx             # React挂载点

工具命名规范

工具类型命名格式示例
UI获取get{PageName}UIgetFamilyTreeUI, getMemberManageUI
数据查询list{Entity}, get{Entity}listFamilies, getMemberById
数据创建create{Entity}createFamily, createMember
数据更新update{Entity}updateFamily, updateMember
数据删除delete{Entity}deleteFamily, deleteMember

UI页面生成规范

HTML模板结构

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>页面标题</title>
  <script src="https://cdn.tailwindcss.com"></script>
  <style>/* 自定义样式 */</style>
</head>
<body class="bg-gray-100 min-h-screen p-4">
  <!-- 页面内容 -->
  <script>
    function mcpCallTool(toolName, params) {
      return new Promise((resolve, reject) => {
        const messageId = 'msg-' + Date.now() + '-' + Math.random();
        const handler = (event) => {
          if (event.data && event.data.messageId === messageId) {
            window.removeEventListener('message', handler);
            if (event.data.error) {
              reject(new Error(event.data.error));
            } else {
              resolve(event.data.response);
            }
          }
        };
        window.addEventListener('message', handler);
        window.parent.postMessage({
          messageId: messageId,
          type: 'tool',
          payload: { toolName, params }
        }, '*');
      });
    }
  </script>
</body>
</html>

样式规范

  • 主色调:绿色系列 (#10B981)
  • 辅助色:蓝色系列 (#3B82F6)
  • 成功色:#10B981
  • 警告色:#F59E0B
  • 错误色:#EF4444

JavaScript规范

  1. 防抖机制:防止重复请求导致界面闪烁
  2. innerHTML渲染:使用innerHTML一次性渲染,优化性能
  3. 错误处理:完善的错误捕获和用户提示

开发工作流

  1. 创建数据存储(Store)
  2. 创建MCP工具(Tools)
  3. 创建UI页面(HTML)
  4. 注册工具到Server
  5. 更新前端菜单
  6. 测试验证

质量保证

  • 使用严格模式TypeScript
  • 使用Zod进行参数验证
  • 完善的错误处理
  • 防抖机制防止闪烁
  • 输入验证防止XSS