Fetch Figma Data MCP 工具

这是什么？

这是一个 MCP (Model Context Protocol) 工具，配合 Claude AI 将数据库中的 HTML 片段自动转换为 Vue 3 组件，生成组件文档，并保存到本地项目或服务器。

工作流程：

数据库 → MCP工具(获取HTML) → Claude AI(分析&转换) → MCP工具(保存/生成文档) → Vue组件文件/文档

解决的问题：

• ✅ 自动从数据库获取 HTML 设计稿
• ✅ AI 智能转换为规范的 Vue 3 组件
• ✅ 自动保存到项目指定目录
• ✅ 自动生成组件文档（支持 Props 表格、组件预览）
• ✅ 使用 VitePress 构建静态文档页面并将页面连同组件源码一同保存到服务器

安装配置

1. 安装依赖

npm install

2. 构建

npm run build

3. 配置到 Cursor

编辑 ~/.cursor/mcp.json，添加：

{
  "mcpServers": {
    "fetch-figma-data": {
      "command": "node",
      "args": ["/Users/joey/mico/mcp/fetchFigmaData/dist/index.js"]
    }
  }
}

注意： 请将路径替换为你的实际构建产物路径。

4. 重启 Cursor

关闭并重新打开 Cursor，让配置生效。

工具说明

1. fetch-html-fragment

功能： 根据 ID 从数据库获取 HTML 片段

参数：

• id (string): HTML 片段 ID

API 接口： GET /api/html-fragments/{id}

示例：

使用 fetch-html-fragment 获取 ID 为 "modal-001" 的组件

返回格式：

{
  "id": "片段ID",
  "html": "HTML代码",
  "description": "描述"
}

2. save-vue-component

功能： 保存 AI 生成的 Vue 组件到本地文件系统

参数：

• componentName (string): 组件名（PascalCase，如 GameWelcomeModal）
• vueCode (string): AI 生成的完整 Vue 组件代码
• projectPath (string): 项目根目录的绝对路径
• description (string, 可选): 组件描述

保存位置： {projectPath}/src/{componentName}/index.vue

示例：

使用 save-vue-component 保存组件
组件名：GameWelcomeModal
项目路径：/Users/joey/myproject
描述：游戏新手福利弹窗组件

生成的文件结构：

/Users/joey/myproject/
└── src/
        └── GameWelcomeModal/
            └── index.vue

3. generate-component-doc

功能： 根据组件文件夹路径生成组件的 markdown 格式文档

参数：

• componentFolderPath (string): 组件文件夹路径（该文件夹包含 index.vue 文件）
• props (array, 可选): 组件的 Props 定义列表
  • name (string): 参数名
  • type (string): 类型
  • required (boolean, 可选): 是否必需
  • default (string, 可选): 默认值
  • description (string, 可选): 描述

生成内容：

• 组件标题
• 组件预览（使用 Preview 组件）
• Props 表格（参数名、类型、是否必需、默认值、描述）
• 源码展示（包含文件夹内所有文件）

保存位置： {projectPath}/docs/index.md

注意： 文档保存在项目根目录的 docs 文件夹中，而不是组件文件夹中。

示例：

使用 generate-component-doc 生成组件文档
组件文件夹路径：/Users/joey/myproject/src/GameWelcomeModal
Props: [
  { name: "coinAmount", type: "number", required: true, description: "金币数量" },
  { name: "visible", type: "boolean", default: "false", description: "是否显示" }
]

生成的文档结构：

# GameWelcomeModal

## Preview

<Preview :codeList="codeList">
  <Component />
</Preview>

## Props

| 参数名     | 类型    | 是否必需 | 默认值 | 描述     |
| ---------- | ------- | -------- | ------ | -------- |
| coinAmount | number  | 是       | -      | 金币数量 |
| visible    | boolean | 否       | false  | 是否显示 |

4. save-component-to-server

功能： 将 Vue 组件信息保存到服务器数据库中

参数：

• name (string): 组件名称
• needId (string): 需求 ID
• framework (string, 可选): 框架类型，默认为 "vue3"
• componentFolderPath (string): 组件文件夹路径（该文件夹包含 index.vue 文件）

前置要求： 项目根目录的 docs 文件夹中必须存在 index.md 文件（通常由 generate-component-doc 工具生成）

工作流程：

1. 验证组件文件夹是否存在
2. 验证项目根目录的 docs/index.md 文件是否存在
3. 创建构建产物目录 component-builds
4. 创建与组件同名的子目录，并在其中创建 src 目录
5. 复制组件文件夹中的所有文件到 src 目录
6. 使用 VitePress 构建 docs/index.md 为静态页面（构建产物在 docs/.vitepress/dist）
7. 将构建产物复制到组件构建目录的 dist 子目录
8. 将整个 component-builds 目录打包成 zip
9. 调用 API 保存到服务器

构建产物结构：

component-builds/
└── {组件名}/
    ├── src/     # 源码（包含所有组件文件）
    └── dist/    # 构建后的静态页面（从 docs/.vitepress/dist 复制）

注意： 最终打包的是整个 component-builds 目录，而不是单个组件目录。

API 接口： POST /api/components

示例：

使用 save-component-to-server 保存组件到服务器
组件名：GameWelcomeModal
需求ID：need-001
组件文件夹路径：/Users/joey/myproject/src/GameWelcomeModal

完整工作流示例

场景：从数据库获取 HTML，转换为 Vue 组件，生成文档并保存到服务器

在 Cursor 中输入：

请帮我完成以下任务：

1. 使用 fetch-html-fragment 工具获取 ID 为 "test001" 的 HTML 组件

2. 分析这个 HTML，将它转换为一个优化的 Vue 3 组件，要求：
   - 使用 TypeScript
   - 使用 Composition API + <script setup>
   - 将 inline style 转换为 scoped style
   - 提取可配置的 props（如金币数量、按钮文本等）
   - 添加事件处理（如 onClose、onConfirm）
   - 优化代码结构和可读性

3. 使用 save-vue-component 工具保存组件
   组件名：GameWelcomeModal
   项目路径：/Users/joey/myproject
   描述：游戏新手福利弹窗组件

4. 使用 generate-component-doc 工具生成组件文档
   组件文件夹路径：/Users/joey/myproject/src/GameWelcomeModal
   Props: [
     { name: "coinAmount", type: "number", required: true, description: "金币数量" },
     { name: "visible", type: "boolean", default: "false", description: "是否显示" }
   ]

5. 使用 save-component-to-server 工具保存到服务器
   组件名：GameWelcomeModal
   需求ID：need-001
   组件文件夹路径：/Users/joey/myproject/src/GameWelcomeModal

AI 会自动完成以下步骤：

1. 获取 HTML 片段 - 从数据库获取设计稿
2. AI 分析并转换 - 转换为规范的 Vue 3 组件
3. 保存到本地 - 创建组件目录并保存文件
4. 生成文档 - 创建包含预览和 Props 表格的 markdown 文档
5. 构建并保存到服务器 - 使用 VitePress 构建静态页面并上传

项目结构

fetchFigmaData/
├── src/
│   ├── api/                    # API 请求封装
│   │   ├── index.ts            # API 接口函数
│   │   ├── request.ts          # 封装的 fetch 请求工具
│   │   └── types.ts            # API 类型定义
│   ├── config/                 # 配置文件
│   │   └── index.ts            # API 基础地址配置
│   ├── demo/                   # 预览组件
│   │   └── preview.vue         # 组件预览组件
│   ├── tools/                  # MCP 工具函数
│   │   ├── fetchHtmlFragment.ts        # 获取 HTML 片段
│   │   ├── saveVueComponent.ts         # 保存 Vue 组件
│   │   ├── generateComponentDoc.ts    # 生成组件文档
│   │   └── saveComponentToServer.ts    # 保存组件到服务器
│   ├── utils/                  # 工具函数
│   │   ├── genCompDoc.ts       # 生成文档模板
│   │   ├── buildWithVitePress.ts # VitePress 构建工具
│   │   └── packageComponent.ts # 组件打包工具
│   └── index.ts                # MCP 服务器入口
├── dist/                       # 构建输出
├── package.json
├── tsconfig.json
└── README.md

配置说明

修改 API 地址

编辑 src/config/index.ts：

export const API_BASE_URL = "https://your-api-url.com";

然后重新运行 npm run build。

常见问题

Q: 组件保存在哪里？

默认保存在项目的 src/ 目录下。

Q: 如何调整生成的代码风格？

在提问时明确说明你的需求，例如：

• "使用 Element Plus 组件"
• "使用 Tailwind CSS"
• "使用 Options API"

Q: generate-component-doc 需要什么文件？

组件文件夹必须包含 index.vue 文件。工具会自动读取文件夹内的所有文件（忽略 node_modules、.git 等）。

Q: save-component-to-server 需要什么文件？

项目根目录的 docs 文件夹中必须包含 index.md 文件（通常由 generate-component-doc 工具生成）。工具会：

1. 验证 docs/index.md 文件是否存在
2. 复制组件文件夹中的所有文件到构建目录的 src 子目录
3. 使用 VitePress 构建 docs/index.md 为静态页面
4. 将构建产物复制到组件构建目录的 dist 子目录
5. 将整个 component-builds 目录打包成 zip 并上传

Q: 工具没有响应？

1. 检查 ~/.cursor/mcp.json 配置
2. 确认路径正确
3. 重启 Cursor
4. 查看 Cursor 开发者工具控制台

Q: API 请求失败怎么办？

1. 确认 API_BASE_URL 配置正确（src/config/index.ts）
2. 确认接口可以正常访问
3. 检查传入的 ID 是否存在

Q: VitePress 构建失败？

1. 确保项目根目录的 docs 文件夹包含 index.md 文件
2. 确保 docs/.vitepress 目录存在且配置正确
3. 检查是否有必要的依赖（工具会自动安装）
4. 查看错误信息，可能是 VitePress 配置问题

技术栈

• Node.js >= 18
• TypeScript
• MCP SDK - Model Context Protocol
• node-fetch - HTTP 请求
• archiver - ZIP 压缩
• VitePress - 静态站点生成（用于构建文档）

依赖说明

运行时依赖

• @modelcontextprotocol/sdk - MCP SDK
• node-fetch - HTTP 请求库
• archiver - ZIP 压缩库
• zod - 参数验证

开发依赖

• typescript - TypeScript 编译器
• @types/node - Node.js 类型定义
• @types/archiver - archiver 类型定义
• @types/node-fetch - node-fetch 类型定义

更多帮助

遇到问题？在使用时直接问 AI：

这个 MCP 工具怎么使用？请给我一个完整的例子。

AI 会根据你的项目情况给出具体指导。

更新日志

v1.0.0

• ✅ 支持从数据库获取 HTML 片段
• ✅ 支持保存 Vue 组件到本地
• ✅ 支持生成组件文档（包含预览和 Props 表格）
• ✅ 支持使用 VitePress 构建静态页面并保存到服务器
• ✅ 完整的 API 封装和错误处理
• ✅ 模块化的代码结构