Frontend MCP Design System

前端MCP Monorepo

Monorepo展示了集中式设计系统的“近生产”架构 故事书, 独立MCP HTTP服务器，以及通过工作区消费的团队应用程序。

🎯 概述

此monorepo模拟了一个生产环境，其中：

• packages/design-system 是中央存储库：

- 设计系统（React组件） - 故事书（设计系统文档） - 独立MCP HTTP服务器（读取故事书静态构建） - MCP服务器部署的Dockerfile

• packages/demo-timeA 和 packages/demo-timeB 团队应用程序：

- 消费 @org/design-system 通过工作区打包 - 不知道设计系统的内部代码 - 使用设计系统公开的MCP HTTP端点

建筑

graph TB
    DS[packages/design-system
Design System + Storybook + MCP Server]
    
    DS -->|npm workspace| TA[packages/demo-timeA
Port 3000]
    DS -->|npm workspace| TB[packages/demo-timeB
Port 3001]
    
    DS -->|HTTP MCP
localhost:13316| TA
    DS -->|HTTP MCP
localhost:13316| TB
    
    subgraph "Design System Package"
        DS1[React Components]
        DS2[Storybook Docs]
        DS3[MCP HTTP Server]
        DS4[Dockerfile]
    end
    
    DS -.-> DS1
    DS -.-> DS2
    DS -.-> DS3
    DS -.-> DS4

📋 先决条件

• Node.js 18+（推荐20+）
• pnpm 8+（或带工作区的npm/yarn）
• 码头工人 （用于生产模式）
• 光标 或 VS Code （有MCP支持）

🚀 开发模式（本地）

1.安装依赖项

pnpm install

2.为设计系统构建故事书

首先，构建静态Storybook构建：

pnpm --filter @org/design-system storybook:build

这会产生 packages/design-system/storybook-static/ 以及必要的文件。

3.启动本地MCP服务器

在终端中，启动MCP服务器：

pnpm --filter @org/design-system mcp:dev

服务器将在以下位置可用：

• MCP端点： http://localhost:13316/mcp
• 健康检查： http://localhost:13316/healthz

4.启动故事书（可选，用于可视化）

在另一个终端中：

pnpm storybook

故事书将在 http://localhost:6006.

5.启动团队应用程序

在单独的终端中：

# Team A
pnpm demo-timeA:dev
# or: pnpm --filter demo-timeA dev
# App at http://localhost:3000

# Team B
pnpm demo-timeB:dev
# or: pnpm --filter demo-timeB dev
# App at http://localhost:3001

6.配置MCP的游标/VS代码

每个应用程序都有自己的 .cursor/mcp.json 指向MCP服务器：

{
  "mcpServers": {
    "org-design-system-mcp": {
      "transport": "http",
      "url": "http://localhost:13316/mcp"
    }
  }
}

重新加载编辑器以检测配置。

🐳 “模拟生产”模式（Docker）

1.构建故事书

pnpm --filter @org/design-system storybook:build

2.构建MCP服务器

pnpm --filter @org/design-system mcp:build

3.构建Docker镜像

pnpm --filter @org/design-system docker:build

这将创建图像 org/design-system-mcp:local.

4.运行容器

pnpm --filter @org/design-system docker:run

容器在端口上公开MCP服务器 13316.

5.在实际生产中

在实际生产中，您将拥有：

• 地形 配置：

- Kubernetes集群（或Lambda/API网关） - 服务/进入暴露 https://design-system-mcp.your-company.com/mcp

• CI/CD 做：

- 故事书构建 - MCP服务器构建 - Docker镜像构建 - 推送到注册表 - 部署到集群

• 团队应用 使用：

- @org/design-system 来自npm注册表的包 - MCP服务器URL通过env变量： MCP_STORYBOOK_URL

🔧 可用脚本

Monorepo根

• pnpm dev -以开发模式启动所有应用程序
• pnpm build -构建所有包
• pnpm storybook -启动设计系统的故事书
• pnpm storybook:build -静态故事书构建
• pnpm mcp:dev -在开发模式下启动MCP服务器
• pnpm mcp:build -构建MCP服务器

设计体系(packages/design-system)

• pnpm --filter @org/design-system storybook -故事书开发
• pnpm --filter @org/design-system storybook:build -静态构建
• pnpm --filter @org/design-system mcp:dev -MCP服务器开发
• pnpm --filter @org/design-system mcp:build -构建MCP
• pnpm --filter @org/design-system mcp:start -启动MCP（生产）
• pnpm --filter @org/design-system docker:build -构建Docker
• pnpm --filter @org/design-system docker:run -运行容器

应用

• pnpm demo-timeA:dev -A队开发
• pnpm demo-timeB:dev -B组开发

🔌 MCP端点

MCP服务器公开：

• 发布 /mcp -MCP协议

- tools/list -列出可用工具 - tools/call -执行工具： - list-all-components -列出所有组件 - find-component-by-name -按名称查找组件 - get-component-stories -获取组件的故事 - get-component-documentation -获取组件文档 - suggest-composition -建议用例的组成

• 获取 /healthz -健康检查

- 返回状态、加载的故事数等。

🌍 环境变量

MCP服务器

• PORT -服务器端口（默认值： 13316)
• STORYBOOK_STATIC_PATH -静态构建路径（默认： storybook-static)
• STORYBOOK_URL -故事书开发URL（默认值： http://localhost:5173)
• LOG_LEVEL -日志级别： debug, info, warn, error （默认值： info)
• NODE_ENV -环境： development 或 production

应用程序（生产）

• MCP_STORYBOOK_URL -生产中的MCP服务器URL

- 例子： https://design-system-mcp.internal/mcp

📖 如何使用AI

看 AI_RULES.md 用于：

• AI行为规则
• 即用型命令
• 推荐工作流程

快速示例

1. 启动MCP服务器： pnpm mcp:dev
2. 在其中一个应用程序中打开光标/VS代码
3. 在聊天中，键入：

   Use the org-design-system-mcp MCP to list all available components and suggest an onboarding screen.

1. AI将使用MCP来发现组件并生成代码

🐛 故障排除

MCP服务器找不到故事书

1. 确保你跑了 storybook:build:

   pnpm --filter @org/design-system storybook:build

1. 检查是否 packages/design-system/storybook-static/index.json 存在
2. 检查 STORYBOOK_STATIC_PATH 服务器中的变量

应用程序找不到 @org/design-system

1. 确保你跑了 pnpm install 根
2. 检查根目录中是否正确配置了工作区 package.json

Docker构建失败

1. 确保故事书是先构建的
2. 检查是否存在所有必要的文件
3. 必要时根据您的环境调整Dockerfile

MCP图标在光标中为黄色

1. 检查MCP服务器是否正在运行： curl http://localhost:13316/healthz
2. 验证 .cursor/mcp.json 配置
3. 完全重新启动Cursor（而不仅仅是重新加载窗口）
4. 检查服务器日志是否有错误

🎓 后续步骤

1. 探索故事书中的组件： http://localhost:6006
2. 测试MCP服务器： http://localhost:13316/healthz
3. 尝试以下命令 AI_RULES.md
4. 在设计系统中创建新组件
5. 使用团队应用程序中的组件
6. 使用Docker模拟生产部署

📝 重要说明

• 不要使用 @storybook/mcp：此项目实现了自己的MCP HTTP服务器
• MCP服务器读取静态构建：服务器读取 storybook-static/index.json 发现组件
• 本地工作空间：在生产中，应用程序将安装 @org/design-system 来自npm注册表
• dev中的固定端口:

- 故事书： 5173 （dev）或 6006 （明确） - MCP： 13316 - A组： 3000 - B组： 3001

📄 许可证

这是一个示范项目。请随意将其用作基础。

______________________________________________________________________

开发用于在近生产环境中演示MCP的集中式设计系统架构。