npm package: @manwang/figma-to-code-mcp
Description: MCP工具：根据ID获取Figma HTML片段、生成组件、组件文档、保存组件到服务器
Latest version: 1.2.3

# 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. 安装依赖

```bash
npm install
```

### 2. 构建

```bash
npm run build
```

### 3. 配置到 Cursor

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

```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" 的组件
```

**返回格式：**

```json
{
  "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: "是否显示" }
]
```

**生成的文档结构：**

```markdown
# 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`：

```typescript
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 封装和错误处理
- ✅ 模块化的代码结构