# MOKE MCP

将**摹客（Mockplus）设计数据**接入 AI 编码助手的 MCP Server。对标 Figma MCP，实现设计到代码的自动化工作流。

- Node.js >= 18 | Python 3 | [MIT License](./LICENSE)

## 功能特性

| 能力 | MCP Tool | 说明 |
|---|---|---|
| 元数据 | `get_metadata` | 获取页面/分组层级树（XML 格式） |
| 设计上下文 | `get_design_context` | 完整设计数据（YAML/JSON），含布局、样式、颜色、排版 |
| 截图 | `get_screenshot` | 整页 @2x PNG 截图（base64） |
| 设计变量 | `get_variable_defs` | Design Token 提取（颜色、字体、间距） |
| 切图下载 | `download_design_images` | 按需下载 PNG/SVG 切图到本地 |
| 设计数据 | `get_design_data` | `get_design_context` 别名（兼容 Figma MCP） |
| 设计规范 | `create_design_system_rules` | 生成 Tailwind/CSS 设计系统 Markdown 文档 |

**设计数据经过：** 包含树重建 → 坐标相对化 → Token 去重 → 机械蒸馏，AI 可直接消费。

> 代码生成（`code_gen`）当前不对外提供，推荐由大模型直接分析设计稿数据生成目标平台代码（如 Swift/React 等），效果更佳。

---

## 前置要求

- **Node.js** >= 18
- **Python 3**（数据转换脚本依赖）

```bash
# macOS
brew install python3

# Windows（任选其一，安装时勾选 Add python.exe to PATH）
#   https://www.python.org/downloads/
winget install Python.Python.3

# 验证（macOS / Linux）
python3 --version
# 验证（Windows）
python --version   # 或 py -3 --version
```

运行时会自动查找解释器：Windows 依次尝试 `python` → `py -3` → `python3`，其他平台依次尝试 `python3` → `python`。如需指定解释器（conda / venv / 多版本共存），设置环境变量 `MOKE_PYTHON` 为解释器路径即可。

---

## 安装

### 方式 1：npx 一键使用（推荐）

无需安装，直接运行：

```bash
npx @moke-mcp/cli@latest serve
```

### 方式 2：全局安装

```bash
npm install -g @moke-mcp/cli@latest
moke-mcp serve
```

升级到最新版本（CLI 与 server 需同时更新）：

```bash
npm install -g @moke-mcp/server@latest @moke-mcp/cli@latest
```

### 方式 3：本地开发

```bash
git clone https://github.com/bosong/MOKE_MCP.git
cd MOKE_MCP
cd packages/server && npm install && npm run build && cd ../..
cd packages/cli && npm install && npm run build && cd ../..
node packages/cli/dist/index.js serve
```

---

## 配置 Cookie（首次使用必须）

摹客 API 需要浏览器 Cookie 认证，有效期约 30 天。

### 获取 Cookie

1. 浏览器打开 [app.mockplus.cn](https://app.mockplus.cn) 并登录
2. 按 `F12` → **Application** → **Cookies** → `app.mockplus.cn`
3. **全量复制**该域名下 Cookie 的所有 `key=value` 键值对，按 **Header String**（请求头 Cookie 字符串）格式拼接：`k1=v1; k2=v2; ...`，即每个键值对用 `; `（分号+空格）连接

   ```
   mockuuid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx; mockuuid.sig=xxxxx; _c_WBKFRo=xxxxx; ds.sid=ds:sess:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx; ds.sid.sig=xxxxx; _ga=GA1.2.xxxxxxxxxx.xxxxxxxxxx
   ```

   > **建议全量复制所有 key=value 键值对，不要只挑选部分 key**：`ds.sid` 与 `ds.sid.sig` 是登录态凭证（最关键），`mockuuid`、`mockuuid.sig`、`_c_WBKFRo` 等也不可缺少，遗漏会导致 401。最终格式必须是 Header String：`k1=v1; k2=v2; ...`。

### 配置方式（三选一，按优先级）

#### 方式 1：环境变量（推荐，Agent 中直接设置）

```bash
export MOKE_COOKIE="mockuuid=xxxxx; mockuuid.sig=xxxxx; _c_WBKFRo=xxxxx; ds.sid=ds:sess:xxxxx; ds.sid.sig=xxxxx; _ga=GA1.2.xxxxx.xxxxx"
```

在 AI 编辑器的 MCP 配置中也可直接写入 `env` 字段（见下方编辑器配置）。

#### 方式 2：CLI 交互式

```bash
moke-mcp cookie set
# 粘贴 cookie → 回车 → Ctrl+D 完成
```

#### 方式 3：手动文件

```bash
mkdir -p ~/.config/mockplus
echo "你的cookie" > ~/.config/mockplus/cookie
chmod 600 ~/.config/mockplus/cookie
```

### 验证配置

```bash
moke-mcp cookie status
```

---

## 快速开始

```bash
# 1. 配置 Cookie
export MOKE_COOKIE="你的cookie"

# 2. 启动 Server
npx @moke-mcp/cli@latest serve

# 3. 在 AI 编辑器中配置 MCP（见下方各编辑器 JSON）
# 4. 在 AI 对话中粘贴摹客设计稿 URL 即可
```

---

## AI 编辑器 MCP 配置

### Trae（字节跳动 AI IDE）

Trae MCP 配置文件位于项目目录的 `.trae/mcp.json`：

```json
{
  "mcpServers": {
    "moke-mcp": {
      "command": "npx",
      "args": ["-y", "@moke-mcp/cli@latest", "serve"],
      "env": {
        "MOKE_COOKIE": "你的cookie"
      }
    }
  }
}
```

配置后在 Trae 中直接发送摹客设计稿 URL，AI 即可读取设计数据。

### Cursor

配置文件：`.cursor/mcp.json`（项目根目录下）

```json
{
  "mcpServers": {
    "moke-mcp": {
      "command": "npx",
      "args": ["-y", "@moke-mcp/cli@latest", "serve"],
      "env": {
        "MOKE_COOKIE": "你的cookie"
      }
    }
  }
}
```

配置后重启 Cursor，在 Composer 中粘贴摹客 URL 即可使用。

### Claude Desktop

配置文件路径：

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "moke-mcp": {
      "command": "npx",
      "args": ["-y", "@moke-mcp/cli@latest", "serve"],
      "env": {
        "MOKE_COOKIE": "你的cookie"
      }
    }
  }
}
```

配置后重启 Claude Desktop，在对话中粘贴摹客 URL 即可。

### VS Code Copilot

配置文件：`.vscode/mcp.json`（项目根目录下）

```json
{
  "servers": {
    "moke-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@moke-mcp/cli@latest", "serve"],
      "env": {
        "MOKE_COOKIE": "你的cookie"
      }
    }
  }
}
```

配置后打开 VS Code Copilot Chat，使用 Agent 模式粘贴摹客 URL。

### Qoder（阿里灵码）

配置文件：`.qoder/mcp.json`（项目根目录下）

```json
{
  "mcpServers": {
    "moke-mcp": {
      "command": "npx",
      "args": ["-y", "@moke-mcp/cli@latest", "serve"],
      "env": {
        "MOKE_COOKIE": "你的cookie"
      }
    }
  }
}
```

配置后在灵码对话中粘贴摹客 URL 即可。

---

## MCP Tools 参考

### get_metadata

获取设计文件的页面/分组层级树。

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `url` | string | ✅ | 摹客设计稿 URL |

```text
用户：看看这个设计稿有哪些页面
https://app.mockplus.cn/app/xxx/develop/design/yyy
```

### get_design_context

获取完整设计上下文，返回结构化 YAML（含节点树、样式、布局、文本）。

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `url` | string | ✅ | 摹客设计稿 URL |
| `format` | `"yaml"` \| `"json"` | ❌ | 输出格式，默认 `yaml` |

> **scale 单位缩放（默认 `1`，通常无需设置）**：设计稿原始数值基于 Sketch 画布像素（如 device `ios2x`）。默认不填 scale 时直接输出画布原始像素值，绝大多数场景不需要任何配置 —— AI 可依据返回数据 `metadata` 中的 `device` 与 `size`（如 `ios2x`、`750 × 1630`）自行推算出正确的逻辑宽度（375pt）进行布局：
>
> ```yaml
> metadata:
>   name: 会场页面 - 黑版直播
>   device: ios2x           # 源设计稿设备标记
>   size: {width: 750, height: 1630}
> ```
>
> 仅当目标端需要特殊换算时，才按以下方式传入系数，例如设置输出 scale 为 `0.5`：
> 1. 环境变量：`MOKE_SCALE=0.5`
> 2. 项目配置：`.moke-mcp.json` 中 `"output": { "scale": 0.5 }`
> 3. CLI 本地调用：`moke-mcp tool get_design_context <url> --scale 0.5`（优先级最高）
>
> 设置后所有长度值（坐标/尺寸/字号/圆角/线宽/效果偏移）被等比缩放，返回数据的 `metadata.scale` 会记录该系数 —— **数值已换算，勿再按 device 物理倍率二次缩放**。

```text
用户：把这个设计稿还原成 Vue 组件
https://app.mockplus.cn/app/xxx/develop/design/yyy
```

### get_screenshot

获取整页 @2x PNG 截图（base64 编码）。

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `url` | string | ✅ | 摹客设计稿 URL |

```text
用户：给我看看这个页面的截图
https://app.mockplus.cn/app/xxx/develop/design/yyy
```

### get_variable_defs

提取设计文件中的 Design Token（颜色、字体、间距等）。

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `url` | string | ✅ | 摹客设计稿 URL |

```text
用户：提取这个设计稿的颜色和字体变量
https://app.mockplus.cn/app/xxx/develop/design/yyy
```

### download_design_images

下载切图资源（PNG/SVG）到本地目录。

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `url` | string | ✅ | 摹客设计稿 URL |
| `imageRefs` | string[] | ✅ | 切图 hash 列表（从 globalVars.styles 中提取 type: IMAGE 的 imageRef） |
| `outputDir` | string | ❌ | 输出目录，默认 `./mockplus-assets` |

```text
用户：把这个页面的所有切图下载到 ./assets 目录
https://app.mockplus.cn/app/xxx/develop/design/yyy
```

### get_design_data

`get_design_context` 的别名，兼容 Figma MCP 命名习惯。参数同上。

### create_design_system_rules

基于 Design Token 生成设计系统规范文档。

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `url` | string | ✅ | 摹客设计稿 URL |
| `framework` | `"react"` \| `"vue"` | ❌ | 目标框架，默认 `react` |
| `styleLibrary` | `"tailwind"` \| `"css-modules"` \| `"styled-components"` | ❌ | 样式方案，默认 `tailwind` |

```text
用户：基于这个设计稿生成 Tailwind 设计系统规范
https://app.mockplus.cn/app/xxx/develop/design/yyy
```

---

## CLI 命令参考

```bash
moke-mcp init             # 初始化项目配置（.moke-mcp.json）
moke-mcp serve            # 启动 MCP Server

# Cookie 管理
moke-mcp cookie set       # 交互式设置 Cookie
moke-mcp cookie status    # 查看 Cookie 状态
moke-mcp cookie clear     # 清除 Cookie
moke-mcp cookie guide     # 显示 Cookie 配置完整指南

# 配置管理
moke-mcp config show      # 显示当前配置
moke-mcp config set <key> <value>  # 设置配置项

# Tool 命令组（本地直接调用 MCP Tools，无需 MCP 客户端）
moke-mcp tool get_metadata <url>              # 获取页面/分组 XML 层级树
moke-mcp tool get_design_context <url>        # 获取设计数据（YAML/JSON）
  --format yaml|json                          #   输出格式，默认 yaml
  --raw                                       #   输出未蒸馏原文
  --scale <num>                               #   （可选）单位缩放系数，如 0.5；覆盖 MOKE_SCALE/配置
  -o, --out <path>                            #   导出到文件
moke-mcp tool get_screenshot <url>            # 获取整页 @2x 截图
  -o, --output <path>                         #   PNG 保存路径
  --base64                                    #   输出 base64 到 stdout
moke-mcp tool get_variable_defs <url>         # 提取 Design Token
moke-mcp tool download_design_images <url>    # 下载切图
  --refs <hash1,hash2,...>                    #   imageRef 列表
  -o, --output <dir>                          #   输出目录
moke-mcp tool get_design_data <url>           # get_design_context 别名
moke-mcp tool create_design_system_rules <url> # 生成设计系统规范
  --framework react|vue                       #   目标框架，默认 react
  --style tailwind|css-modules|styled-components
```

### Tool 命令示例

```bash
# 查看页面树
moke-mcp tool get_metadata "https://app.mockplus.cn/app/xxx/develop/design/yyy"

# 获取设计数据并导出为 JSON 文件
moke-mcp tool get_design_context "https://app.mockplus.cn/app/xxx/develop/design/yyy" \
  --format json -o design.json

# 默认：按画布物理像素单位输出（无需 --scale，AI 依据 device/size 自行换算）
moke-mcp tool get_design_context "https://app.mockplus.cn/app/xxx/develop/design/yyy"

# 特殊需求：按 ios2x 逻辑单位输出（物理像素 ÷ 2）
moke-mcp tool get_design_context "https://app.mockplus.cn/app/xxx/develop/design/yyy" \
  --scale 0.5

# 获取截图
moke-mcp tool get_screenshot "https://app.mockplus.cn/app/xxx/develop/design/yyy" \
  -o ./preview.png

# 提取设计变量
moke-mcp tool get_variable_defs "https://app.mockplus.cn/app/xxx/develop/design/yyy"

# 生成 Tailwind 设计规范
moke-mcp tool create_design_system_rules "https://app.mockplus.cn/app/xxx/develop/design/yyy" \
  --framework react --style tailwind
```

---

## 工作流示例

### 示例 1：读取设计稿并生成代码

```text
你：把这个设计稿还原成 Vue 组件
   https://app.mockplus.cn/app/xxx/develop/design/yyy

AI：→ get_metadata  → 发现页面"首页"
   → get_design_context → 获取完整设计数据（YAML）
   → 分析节点树、颜色、字体、布局
   → 生成 Vue SFC 组件 + Tailwind 类名
```

### 示例 2：导出切图资源

```text
你：下载这个页面所有切图到 ./public/assets
   https://app.mockplus.cn/app/xxx/develop/design/yyy

AI：→ get_design_context → 扫描 globalVars 中 IMAGE fill 的 imageRef
   → download_design_images → 批量下载到指定目录
```

### 示例 3：生成设计系统规范

```text
你：为这个设计稿生成 Tailwind 配置和设计规范文档
   https://app.mockplus.cn/app/xxx/develop/design/yyy

AI：→ create_design_system_rules → 生成含颜色调色板、
   字体层级、Tailwind 配置的 Markdown 文档
```

---

## 项目结构

```
MOKE_MCP/
├── packages/
│   ├── server/             # MCP Server 核心包
│   │   └── src/
│   │       ├── api/        # HTTP 客户端（Python 子进程封装）
│   │       ├── mcp/        # MCP Tools 注册
│   │       └── services/   # 设计上下文/截图/变量提取/代码生成
│   └── cli/                # CLI 工具包
│       └── src/
│           ├── commands/   # init / serve / config / cookie / tool
│           └── utils/      # version / config-file
├── scripts/
│   └── mockplus/           # Python 数据转换脚本（基于 mockplus-context）
└── .moke-mcp.json          # 项目配置文件
```

---

## 原理

```
AI Client (Trae/Cursor/Claude)
  │ stdio (MCP JSON-RPC)
  ▼
Moke MCP Server (Node.js)
  │ child_process.spawn(自动探测的 Python 3 / MOKE_PYTHON)
  ▼
mockplus-context scripts (Python)
  │ HTTP（Cookie 认证）
  ▼
app.mockplus.cn REST API + CDN
```

设计数据通过摹客 DT 的 Sketch JSON API 获取，经过 Python 脚本的包含树重建、坐标相对化和 Token 去重后，以结构化 YAML 形式返回给 AI。

---

## 常见问题

**Q: 提示 "Cookie 未配置" 怎么办？**

A: 运行 `moke-mcp cookie guide` 查看完整配置指南，或直接 `export MOKE_COOKIE="你的cookie"`。

**Q: Cookie 过期了怎么办？**

A: 重新从浏览器获取 cookie，运行 `moke-mcp cookie set` 或更新环境变量。有效期约 30 天。

**Q: 提示 "Python 3 未找到"？**

A: macOS 执行 `brew install python3`；Windows 从 [python.org](https://www.python.org/downloads/) 下载安装（勾选 Add python.exe to PATH）或执行 `winget install Python.Python.3`。已安装但仍找不到时，可设置环境变量 `MOKE_PYTHON` 指定解释器路径。

**Q: Windows 上升级后报 `UnicodeDecodeError: 'utf-8' codec can't decode byte ...`？**

A: 旧版本在 Windows 上按系统代码页（GBK）写入了本地缓存，新版本统一按 UTF-8 读写。升级后删除一次缓存目录即可（下次调用会自动重建）：默认为 `~/.cache/mockplus`（Windows 即 `%USERPROFILE%\.cache\mockplus`）；如设置了 `MOCKPLUS_CACHE_DIR`，则删除该目录。

**Q: 支持摹客 RP 吗？**

A: 当前仅支持摹客 DT（app.mockplus.cn），不支持摹客 RP（原型工具）。

**Q: 与 Figma MCP 的关系？**

A: Moke MCP 对标 Figma MCP 的工具集，输出格式兼容，但数据源为摹客 DT。详见 [Figma MCP 对比](./.trae/documents/moke-mcp-data-source-analysis.md)。

---

## 致谢

MOKE_MCP 的设计灵感来自以下两个优秀项目：

- **[mockplus-context](https://github.com/MySwallow/mockplus-context)** by [MySwallow](https://github.com/MySwallow) — Agent Skill 形式的摹客设计数据获取方案，其中 `mockplus.py` 脚本（REST API 调用、Cookie 认证、Sketch JSON 的 transform/distill 管线）被 MOKE_MCP 通过子进程方式复用，是数据获取的核心
- **[mockplus-rp-skill](https://github.com/Retohsaka/mockplus-rp-skill)** by [Retohsaka](https://github.com/Retohsaka) — 摹客 RP 原型工具的数据解析方案，为多产品线支持提供了参考思路

感谢两位作者的开源贡献。

---

## License 与使用声明

### 许可证

本项目采用 [MIT License](./LICENSE)。

### 使用声明

本项目是**独立开发的第三方工具**，与摹客（Mockplus）等平台无官方关联，相关商标、产品名称及数据归各自权利人所有。

本作品仅供交流，**不建议用于商业用途**；使用者应依法自行承担使用本作品产生的法律责任，上述用途建议仅为作者倡议。

### 免责声明

- 请仅处理**已获授权**的数据，并遵守适用法律及平台条款。
- 提交内容、日志和附件可能发送至所配置的服务及智能体，请先检查其中是否包含敏感信息。
- 软件按**「现状」**提供，不作任何担保；责任限制以 MIT 许可证及适用法律为准。

### 权利争议

如对本项目的内容、标识或使用方式存在权利争议，请提交 [Issue](https://github.com/bosong/MOKE_MCP/issues) 或联系作者，说明具体情况，我们将核实并视情况更正或移除相关内容。