MasterGo MCP

MasterGo MCP 现在有2个不同使用场景的 MCP 服务。

  • Vibe MCP 新版 MCP 服务，用于连接 AI 操作画布功能，也就是大家熟知的 Vibe Design
  • Magic MCP 原 MCP 服务，用于获取 DSL / D2C 数据

开始前准备

请确认以下条件已经满足：

  • 已安装并启动 MasterGo 客户端 。
  • MasterGo 文件已打开，并且 MasterGo MCP 处于连接状态。
  • 当前电脑已安装 Node.js 18.0.0 或以上版本，npm 8.0.0 或以上版本。点击下载 NodeJs
  • 你的 IDE / CLI 支持 MCP 服务配置。
  • 如果需要使用组件库，请确保当前 MasterGo 文件已订阅对应团队库。

start mcp

配置 MCP 服务

以 Cursor 为例，编辑 ~/.cursor/mcp.json。如果文件不存在，可以手动创建。

Vibe MCP 配置

Vibe MCP 运行在本地客户端，无需使用 个人令牌

{
  "mcpServers": {
    "mastergo": {
      "command": "npx",
      "args": ["-y", "@mastergo/vibe-mcp", "--url=http://localhost:50678"]
    }
  }
}

Magic MCP 配置

{
  "mcpServers": {
    "mastergo-magic-mcp": {
      "command": "npx",
      "args": ["-y", "@mastergo/magic-mcp", "--token=你的个人令牌", "--url=https://mastergo.com"],
      "env": {}
    }
  }
}

你可以尝试将上面的 Json 配置发送给你工具的 AI 对话框中，让它教你如何配置。

配置完成后，重启 IDE / CLI，或在对应产品中重新加载 MCP 配置。

Vibe MCP

面向希望在 Cursor、VSCode、Trae 或其他支持 MCP 的 IDE / CLI 中使用 MasterGo 画布能力的用户。@mastergo/vibe-mcp 是连接 AI 工具与 MasterGo 本地 MCP 服务的客户端适配器：IDE 通过 MCP 标准协议调用它，它再通过本机服务把读取、生成、修改、同步等请求送到 MasterGo 画布。也就是大家熟知的 Vibe Design 能力

你可以用它做什么

  • 读取当前选中图层的结构化代码，作为 AI 修改或还原设计的上下文。
  • 根据一句自然语言需求，在 MasterGo 画布中生成完整页面。
  • 基于当前文件变量或团队组件库生成更贴近设计系统的页面。
  • 修改、替换、删除已有图层，例如改文案、改颜色、替换图标或图片。
  • 将本地静态 HTML 同步覆盖到画布，或比较本地基准代码与画布差异。
  • 管理 MasterGo 文件变量，包括读取、创建、更新和删除变量。
  • 创建 MasterGo 母版组件或组件集。

端口说明

默认本地服务地址是：

http://localhost:50678

post

如果本机 50678 端口被占用，MasterGo 本地服务可能会自动切换到新的端口。此时需要把 --url= 后面的地址改成实际端口。

验证连接

  1. 打开 MasterGo 文件。
  2. 在画布中选中一个图层。
  3. 在 IDE / CLI 的 AI 对话框中输入：
使用 MasterGo MCP，获取我当前选中图层的代码。

如果连接正常，AI 会调用 get_selection_code，并返回选中图层的代码信息。选中根节点时，工具会把完整页面代码落盘到当前项目的 .mastergo/design/ 目录；选中子节点时，会返回该节点片段，并在条件允许时合并更新本地基准文件。

常用工作流

1. 生成一个新页面

可以直接描述要做的页面：

使用 MasterGo MCP，为我设计一个深色模式的数据看板页面。

页面级生成会进入 design_page 流程。AI 会先让你确认设计来源：

设计来源适用场景说明
free-draw 自由绘制快速出概念稿只使用基础页面生成规则，适合探索方向
current-file-variables 使用当前文件设计系统希望沿用当前文件变量会先读取并落盘当前文件变量，再用 var(...) 引用变量
component-library 使用组件库希望优先使用团队组件需要选择团队库，并选择构建策略

选择完成后，AI 会生成符合 MasterGo 转译规则的 HTML，并通过 submit_page_to_canvas 发送到画布。

2. 使用当前文件变量生成页面

适合当前文件已经维护了颜色、字号、间距等变量的场景。

使用 MasterGo MCP，基于当前文件设计系统生成一个客户管理列表页。

推荐流程：

  1. AI 调用 get_variables 获取当前文件变量，并写入 .mastergo/variable/{documentId}.json。
  2. AI 调用 design_page，设计来源选择 current-file-variables。
  3. 生成时优先使用变量，例如 var(...)，让新页面贴近现有视觉语言。

3. 使用团队组件库生成页面

适合团队已经沉淀组件库，希望生成结果更接近真实产品界面的场景。

使用 MasterGo MCP，用当前文件已订阅的团队组件库生成 CRM 客户管理页面。

推荐流程：

  1. 调用 get_library_list 获取当前文件可用团队库。
  2. 你明确选择团队库，例如“使用 Design System 团队库”。
  3. 调用 get_component_info 远端拉取组件、图标和变量快照，并落盘到 .mastergo/library/。
  4. 调用 design_page，设计来源选择 component-library。
  5. 选择构建策略：
    • full-components：优先全量使用组件库组件，适合规范严格的页面。
    • hybrid：关键区域使用组件，其他区域自由绘制，适合视觉探索与效率平衡。

4. 读取图层并局部修改

先读取上下文，再执行修改，是最稳妥的局部编辑方式。

使用 MasterGo MCP，先获取我当前选中按钮的代码。

然后继续说：

把这个按钮背景改成黑色，文字改成白色。

AI 通常会按以下顺序操作：

  1. get_selection_code 读取当前节点代码。
  2. agent_update_node 提交局部修改。
  3. 修改完成后再次 get_selection_code，刷新 .mastergo 本地基准文件。

如果你要替换图标或图片，可以明确说“替换”：

使用 MasterGo MCP，把当前选中的图标替换为搜索图标。

此时会优先使用 agent_replace_node。

5. 获取预览图作为视觉参考

如果你希望 AI 对照视觉效果进行还原或微调，可以让它获取选中图层预览图：

使用 MasterGo MCP，获取当前选中页面的预览图，然后帮我检查视觉层级。

get_selection_image 会返回图片给模型作为视觉输入，并把图片保存到：

.mastergo/.preview/{documentId}/{pageId}/{nodeId}.png

日常只做代码读取或小修时，使用 get_selection_code 即可；需要“看一眼设计稿”时再使用预览图。

6. 对比本地代码与画布差异

当你已经通过 get_selection_code 保存过本地基准代码后，可以比较当前画布与本地文件的差异：

使用 MasterGo MCP，对比当前选中页面和本地基准代码的差异。

AI 会调用 get_design_diff，返回 JSON 形式的差异结果，便于把画布上的改动合并回业务代码或 .mastergo 基准文件。

7. 将本地 HTML 同步到画布

当你已经有一份静态 HTML，希望覆盖同步到 MasterGo 画布时，可以明确发出同步指令：

使用 MasterGo MCP，将这个本地 HTML 文件同步到当前页面根节点。

agent_sync_design 是全量同步工具，只在你明确要求“同步到画布”时执行。它需要读取本地静态 HTML 文件，并建议传入页面根节点 ID，避免覆盖错误对象。

注意：不要把 .vue、.tsx 等业务源码文件直接作为同步文件传入，应使用可被 MasterGo 转译的静态 HTML。

8. 管理变量

读取变量：

使用 MasterGo MCP，获取当前文件变量。

创建或更新变量时，推荐遵循固定流程：

  1. get_variables 获取并落盘当前变量。
  2. update_variables 先提交基础变量。
  3. 再次 get_variables 刷新快照。
  4. update_variables 提交引用基础变量的语义变量。
  5. 最后再次 get_variables 确认结果。

删除变量是高危操作，不使用 update_variables，而是使用 agent_remove_variable。能提供变量 id 时优先提供 id；没有 id 时，需要明确集合、变量名和类型，降低误删风险。

9. 创建母版组件或组件集

可以让 AI 生成 MasterGo 母版组件：

使用 MasterGo MCP，为我创建一套按钮组件，包含大中小尺寸和默认、悬停、禁用状态。

创建组件会使用 agent_create_component。如果要创建组件集，根节点需要是 data-type="component-set"，每个变体作为直接子节点，并使用 data-variant-* 声明变体属性。

本地文件会保存在哪里

@mastergo/vibe-mcp 会把部分上下文落盘到当前工作区的 .mastergo 目录，方便 AI 后续继续读取和对比。

目录用途
.mastergo/design/通过 get_selection_code 或页面生成保存的设计 HTML 基准
.mastergo/.preview/通过 get_selection_image 导出的预览图
.mastergo/variable/当前文件变量快照
.mastergo/library/团队库组件、图标、变量快照

这些文件是 AI 与画布协作时的重要上下文。排查问题时，可以先确认对应目录是否已经生成。

工具说明

你可以参考一下工具，根据自己团队的需求编排进 Skill。

工具作用典型使用时机
get_guidelines加载 MasterGo 页面、组件、变量生成规则AI 准备生成或提交画布内容前
design_page页面设计主入口新建页面、新建界面、生成 UI
submit_page_to_canvas将完整 HTML 提交到画布design_page 生成最终 HTML 后内部使用
get_selection_code获取选中图层代码修改前读取上下文，或保存根节点基准
get_selection_image获取选中图层预览图需要视觉参考、复刻、检查还原度
agent_update_node局部修改已有节点改颜色、文案、尺寸、布局等
agent_replace_node替换节点内部内容替换图标、图片或结构节点
agent_remove_node删除图层删除当前选中或指定 ID 图层
agent_sync_design全量同步本地 HTML 到画布明确要求同步或覆盖画布
get_design_diff获取本地基准与画布差异合并设计改动回代码前
get_variables读取当前文件变量使用设计系统或管理变量前
update_variables创建、修改、排序变量批量提交变量更新
agent_remove_variable删除变量明确删除变量时
get_library_list获取当前文件团队库列表使用组件库生成前
get_component_info拉取团队库组件信息并落盘选定团队库后
agent_create_component创建母版组件或组件集生成可复用组件

使用建议

  • MCP 在操作画布的时候，请勿切换页面。如果你希望AI在操作画布的同时也不阻断你的设计创作，建议你在浏览器也打开一个画布。
  • 生成页面时，尽量描述页面类型、目标用户、信息结构、视觉倾向和关键模块。
  • 修改已有图层时，先选中目标图层，再让 AI 读取代码；这样比直接描述“那个第二行的第三个按钮”更准确。
  • 涉及父容器修改时，要让 AI 保留全部子元素结构，避免局部更新时丢失子节点。
  • 使用组件库时，每次都明确团队库名称；如果名称相近，优先使用团队库 ID。
  • 做全量同步前，确认目标是页面根节点，并明确说“同步到画布”。
  • 删除节点或变量前，尽量提供准确 名称 或 ID，尤其变量删除建议优先使用完整的分类名称加变量名称 如： 设计系统/背景色/主背景色。

常见问题

MCP 工具没有出现

请检查：

  • IDE / CLI 是否已重启或重新加载 MCP 配置。
  • mcp.json 是否是合法 JSON。
  • Node.js 版本是否满足 >=18.0.0。
  • command 是否为 npx，args 中是否包含 @mastergo/vibe-mcp。

提示“未找到 API 终结点或活跃连接”

通常表示 IDE 已启动 MCP 客户端，但 MasterGo 本地服务没有连接成功。请检查：

  • MasterGo 是否已打开。
  • 当前文件中 MasterGo MCP 是否在线。
  • --url= 端口是否与本地服务实际端口一致。
  • 如果端口被占用，是否已更新为 MasterGo 自动切换后的新端口。

获取选中图层失败

请先在 MasterGo 画布中选中一个图层。如果是多选场景，get_selection_code 和 get_selection_image 也支持批量读取，但需要确保所有目标图层都在当前文件中可访问。

生成页面没有使用组件库

请确认你已经选择 component-library 设计来源，并完成以下步骤：

  • 调用 get_library_list 查看团队库。
  • 明确选择具体团队库。
  • 调用 get_component_info 远端拉取并落盘组件信息。
  • 选择 full-components 或 hybrid 构建策略。

同步到画布被拦截

这是安全设计。agent_sync_design 只有在你明确要求“同步到画布”后才允许执行，并且需要读取静态 HTML 文件。请确认同步目标、根节点 ID 和文件路径后再执行。

Magic MCP

主要用于通过远程服务器获取设计稿的 DSL / D2C 数据 远程 MCP @mastergo/magic-mcp 提供特定功能的轻量级程序，通过标准化的 Model Context Protocol 向客户端暴露多种能力。 例如，向 Cursor、Trae 等支持 MCP 的客户端提供获取设计图数据的能力。

配置 MCP

获取MG_MCP_TOKEN

  1. 访问 https://mastergo.com 。

  2. 进入个人设置。

  3. 点击安全设置选项卡。

  4. 找到个人访问令牌。

  5. 点击生成令牌。 3.png

使用 MCP

如遇权限不足提示，请检查token是否正确、是否有团队版及团队版以上权限，文件是否拖入有权限的团队中

下面以claude code 和cursor为例，演示mcp使用方法

  • claudecode：将配置粘贴到cc的全局配置中

cc.png

  • cursor： 将配置粘贴到mcp.json中

cursor.png

mcp_getDsl方法

  • 注意：先选中图层，layerId为必传参数

mcp_getD2c方法

  • 注意：先点击发送数据按钮，将d2c数据发送的同时会将contentId复制到剪切板，将其粘贴至大模型进行对话即可

Vscode 拓展中使用 MCP

评价此篇文章：👍🏻 有帮助 👎🏻 无帮助

👉本篇文章对你是否有帮助？👍🏻 有帮助 👎🏻 无帮助，我们期待着你的反馈。

MasterGo For VSCode 流程与流程起始点