Design MCP

Design MCP（Model Context Protocol）是腾讯设计提供的标准化接口，让 AI Agent 和编程助手能够直接读取和操作设计稿数据，实现设计到代码的无缝衔接。

什么是 Design MCP

Design MCP 基于 Model Context Protocol 规范，通过在本地运行 MCP Server，让 Claude、Cursor、Windsurf 等 AI 工具能够：

• 读取画布上的图层结构、属性和样式
• 获取设计截图
• 查询设计系统变量和 Style Guide
• 执行创建、修改、删除图层等操作

架构概览

AI Agent (Claude Desktop / Cursor / Windsurf)
        ↓  MCP Protocol (stdio)
  Gateway Server (本地进程，端口 50501)
        ↓  Socket.io
   Relay Server (转发层)
        ↓  WebSocket
  腾讯设计编辑器 (浏览器/客户端)
        ↓  Adapter
     编辑器引擎

各组件说明：

组件	路径	职责
Gateway Server	packages/common/design-mcp/gateway-server	接收 AI Agent 的 MCP 请求，转发到 Relay Server
Relay Server	packages/common/design-mcp/relay-server	在 Gateway 和编辑器之间转发消息
Adapter	packages/common/design-mcp/adapter	在编辑器内执行实际的图层操作
VS Code 扩展	packages/frontend/vscode-extension	提供 IDE 集成能力

---

快速配置

前置条件

• Node.js >= 20
• 已安装腾讯设计桌面端或在浏览器中打开设计文件

安装与启动

# 安装 MCP 包
npm install -g @tencent/cocraft-design-mcp

# 启动 Gateway Server（固定端口 50501）
cocraft-mcp --port 50501

配置 Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "cocraft": {
      "command": "node",
      "args": ["/path/to/dist/gateway-server/cli.mjs", "--port", "50501"],
      "type": "stdio"
    }
  }
}

配置 Cursor

在项目 .cursor/mcp.json 中添加：

{
  "mcpServers": {
    "cocraft": {
      "command": "node",
      "args": ["/path/to/dist/gateway-server/cli.mjs", "--port", "50501"]
    }
  }
}

连接编辑器

打开带有 ?embed=true 参数的设计文件链接，编辑器会自动连接到 Relay Server：

http://localhost:5800/file/{file_id}?embed=true

---

MCP 工具列表

Design MCP 提供以下 15 个工具：

查询类

工具名	说明
get_editor_state	获取当前编辑器状态（打开的文件、选中节点）
batch_get	批量查询节点，支持按 name/type 正则搜索
get_screenshot	获取指定节点或整个画布的截图
snapshot_layout	获取页面布局结构快照（嵌套层级）
search_all_unique_properties	搜索画布中的唯一属性值（颜色、字体等）

设计系统

工具名	说明
get_style_guide	获取设计系统 Style Guide（颜色、字体、间距规范）
get_style_guide_tags	获取 Style Guide 标签分类
get_variables	读取设计变量（Design Token）
set_variables	写入设计变量
get_guidelines	获取代码规范（支持 code/table/tailwind 等格式）

编辑操作

工具名	说明
batch_design	批量执行设计操作：Insert/Copy/Update/Replace/Move/Delete
open_document	打开指定 .pen 文件或新建文档
find_empty_space_on_canvas	在画布上找到空白区域（用于插入新内容）
replace_all_matching_properties	全局替换匹配的属性（如批量改色）
update_properties	更新指定节点的属性

---

使用示例

以 Claude 为例，连接后可进行以下操作：

读取设计数据：

用户：帮我获取当前设计稿中所有 Button 组件的样式
Claude：[调用 batch_get，按 type=COMPONENT 搜索 Button]

生成代码：

用户：基于设计稿中的登录页面，帮我生成 React 组件代码
Claude：[调用 get_screenshot + batch_get 获取布局信息，生成代码]

批量修改：

用户：将设计稿中所有主色从 #0052D9 替换为 #FF4D4F
Claude：[调用 replace_all_matching_properties 执行批量替换]

读取设计变量：

用户：获取设计稿中的所有颜色 Token
Claude：[调用 get_variables 返回所有设计变量集合]

获取代码规范：

用户：以 Tailwind CSS 格式输出设计稿的间距规范
Claude：[调用 get_guidelines 并指定 format=tailwind]

---

调试

使用 MCP Inspector 调试工具：

pnpm mcp:debug
# 或
npx @modelcontextprotocol/inspector node /path/to/dist/gateway-server/cli.mjs

打开浏览器 http://localhost:5173，可视化测试每个工具的调用和响应。

开发时可使用实时编译模式，修改代码后自动生效：

pnpm watch

---

VS Code 扩展集成

安装腾讯设计 VS Code 扩展后，Design MCP 可自动与编辑器同步：

1. 在 VS Code 命令面板执行 CoCraft: Open Webview
2. 执行 CoCraft: Set File ID 绑定目标设计文件
3. MCP Gateway 自动连接已绑定的文件

绑定后，在 Cursor 等 AI 编码工具中可直接引用设计稿，无需手动切换窗口。