mastergo

MasterGo Magic MCP

MasterGo Magic MCP 是一个独立的 MCP（Model Context Protocol）服务，旨在连接 MasterGo 设计工具与 AI 模型。它使 AI 模型能够直接从 MasterGo 设计文件中获取 DSL 数据。

主要特性

• 从 MasterGo 设计文件中获取 DSL 数据
• 可直接通过 npx 运行
• 仅需 Node.js 环境，无需其他外部依赖

教程

• https://mastergo.com/file/192644601973042

示例提示词

MCP 服务连接成功后，可以在 AI 对话中使用以下提示词：

提取 SVG，放到 html 中预览：

提取 SVG，放到 html 中预览：https://{domain}/file/{fileId}?layer_id={layerId}

还原设计稿为代码：

还原设计稿：https://{domain}/file/{fileId}?layer_id={layerId}

将 {domain}、{fileId}、{layerId} 替换为实际值。也可以使用短链接：

还原设计稿：https://{domain}/goto/{shortLink}

还原设计稿并保存为 HTML 文件：

还原设计稿，保存为 html 文件：https://{domain}/file/{fileId}?layer_id={layerId}

也可以使用短链接：

还原设计稿，保存为 html 文件：https://{domain}/goto/{shortLink}

使用方法

获取 MG_MCP_TOKEN

1. 访问 https://mastergo.com
2. 进入个人设置
3. 点击安全设置选项卡
4. 找到个人访问令牌
5. 点击生成令牌

权限要求

重要提示：如果工具已连接但返回"没有权限"错误，请检查以下条件：

1. 账户版本要求：

   • 需要 团队版 或 团队版以上 的 MasterGo 账户
   • 个人免费版不支持 MCP 工具访问

2. 文件位置要求：

   • 设计文件必须放在 团队项目 中
   • 草稿箱中的文件无法通过 MCP 工具访问

命令行选项

npx @mastergo/magic-mcp --token=YOUR_TOKEN [--url=API_URL] [--rule=RULE_NAME] [--proxy=PROXY_URL] [--format=FORMAT] [--header "Key: Value"] [--debug] [--no-rule] [--no-prefix]

参数:

• --token=YOUR_TOKEN (必需): MasterGo API 认证令牌
• --url=API_URL (可选): API 基础 URL，默认为 http://localhost:3000
• --rule=RULE_NAME (可选): 添加要应用的设计规则，可多次使用
• --proxy=PROXY_URL (可选): HTTP/HTTPS 代理地址（如 http://127.0.0.1:7890），也支持 HTTPS_PROXY / HTTP_PROXY 环境变量
• --header "Key: Value" (可选): 自定义 HTTP 请求头，可多次使用。值含空格时必须加引号。自定义头会覆盖默认头（含 Content-Type 和鉴权 token），覆盖时请与默认 key 完全一致。也可通过 MG_EXTRA_HEADERS 环境变量以 JSON 对象形式设置（如 MG_EXTRA_HEADERS='{"X-Custom":"val"}'）；命令行传入的头优先级更高。
• --format=FORMAT (可选): 设计数据工具的默认输出格式 —— 取值 json（默认）、yaml、tree。工具调用时显式传入的 format 参数优先级更高。也可通过 DEFAULT_FORMAT 环境变量设置。
• --debug (可选): 启用调试模式，提供详细错误信息
• --no-rule (可选): 禁用默认规则
• --no-prefix (可选): 工具注册时不带 mcp__ 名称前缀（如 getDsl 而非 mcp__getDsl）。部分 MCP 客户端（如 Grok Build）会静默跳过全限定名 server__tool 中含多个 __ 分隔符的工具——服务端名已带前缀时，mcp__getDsl 会变成 server__mcp__getDsl 而被丢弃。为这类客户端启用此开关即可。也可通过 MG_NO_PREFIX 环境变量设置（1/true/yes）。

你也可以使用空格分隔的参数格式:

npx @mastergo/magic-mcp --token YOUR_TOKEN --url API_URL --rule RULE_NAME --proxy PROXY_URL --format FORMAT --header "Key: Value" --debug

环境变量

您也可以使用环境变量代替命令行参数：

• MG_MCP_TOKEN 或 MASTERGO_API_TOKEN: MasterGo API 令牌
• API_BASE_URL: API 基础 URL
• RULES: 规则的 JSON 数组 (例如: '["rule1", "rule2"]')
• DEFAULT_FORMAT: 设计数据工具的默认输出格式（json | yaml | tree）；--format 参数和工具调用时显式传入的 format 参数优先级更高。
• MG_NO_PREFIX: 设为 1/true/yes 时工具注册不带 mcp__ 名称前缀（--no-prefix 参数优先级更高）。
• HTTPS_PROXY / https_proxy / HTTP_PROXY / http_proxy: HTTP(S) 代理地址（--proxy 参数优先级更高）

工具输出格式

设计数据工具（mcp__getDesignSections、mcp__getDsl、mcp__getDesignSvgs、mcp__getDesignTexts、mcp__extractSvg、mcp__getMeta）接受一个可选的 format 参数，用于控制数据的序列化方式。默认值为 json，或通过 --format / DEFAULT_FORMAT 设置的值（见命令行选项）。

取值	说明
json	默认。 紧凑 JSON —— 适合将输出传递给期望 JSON 的工具。与历史行为逐字节一致。
yaml	对于典型设计比 JSON 更省 token（扁平布局、重复值较多的设计收益最大）。
tree	实验性紧凑格式。结构键（id、name、type）按位置编码在每个节点行上，样式值去重后保留在 globalVars 块中。样式复用较多的设计省 token 效果最明显。

该格式由 AI 模型在每次工具调用时选择。如需影响其选择，可在提示词中指明所需格式，例如：

Restore design, use tree format: https://{domain}/file/{fileId}?layer_id={layerId}

注意事项：

• tree 适用于全部六个工具的响应：mcp__getDesignSections（section 列表与单个 section DSL）、mcp__getDsl（完整 DSL）、mcp__getDesignSvgs、mcp__getDesignTexts、mcp__extractSvg、mcp__getMeta。其中 mcp__getMeta 在 tree 下回退为 JSON —— 它的 rules 字段是 markdown，强行套用 tree 布局会破坏 markdown 的标题/代码块；其余 payload 正常渲染为 tree。只有真正未知的 shape 才回退为 JSON —— 数据不会被错误格式化。
• 对于 mcp__getDesignTexts，建议使用 json 以保证文本的逐字还原精度 —— 尽管所有格式均可无损往返。
• 所有格式均可无损往返。无效或省略的 format 值会回退为 json。

通过 Smithery 市场安装

方式一：通过 Smithery 网站安装

1. 访问 Smithery 市场
2. 选择你的 MCP 客户端（如 Claude Desktop、Cursor 等）
3. one-click install 打开对应客户端，弹出tools&mcp 点击install
4. connect->open->optional setting中填入token->connect

LINGMA 使用方法

在 vscode 拓展市场中搜索 LINGMA -> 然后安装该拓展

登录后 -> 在聊天框中点击 [MCP tools]

点击顶部 [MCP Sqaure] 进入mcp市场，在市场中找到 Mastergo设计协作工具并安装

安装完成后，需要回到 [MCP Servers], 并编辑我们的mcp服务，将自己的mastergo token 替换上去

最后在聊天界面中将聊天模式切换为agent模式。

Cursor 使用方法

Cursor Mcp 使用指南参考：https://docs.cursor.com/context/model-context-protocol#using-mcp-tools-in-agent

您可以使用命令行参数或环境变量来配置 MCP 服务：

方式一：使用命令行参数

{
  "mcpServers": {
    "mastergo-magic-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@mastergo/magic-mcp",
        "--token=<YOUR_TOKEN>",
        "--url=https://mastergo.com"
      ],
      "env": {}
    }
  }
}

方式二：使用环境变量

{
  "mcpServers": {
    "mastergo-magic-mcp": {
      "command": "npx",
      "args": ["-y", "@mastergo/magic-mcp"],
      "env": {
        "MG_MCP_TOKEN": "<YOUR_TOKEN>",
        "API_BASE_URL": "https://mastergo.com"
      }
    }
  }
}

方式三：使用 SSE（Streamable HTTP）

无需本地安装，MCP 服务在远端运行，通过 SSE 访问：

{
  "mcpServers": {
    "mastergo-magic-mcp": {
      "type": "http",
      "url": "https://mastergo.com/mcp/xf/sse",
      "headers": {
        "x-mg-useraccesstoken": "<YOUR_TOKEN>"
      }
    }
  }
}

cline 使用方法

方式一：使用命令行参数

{
  "mcpServers": {
    "@master/mastergo-magic-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@mastergo/magic-mcp",
        "--token=<YOUR_TOKEN>",
        "--url=https://mastergo.com"
      ],
      "env": {}
    }
  }
}

方式二：使用环境变量

{
  "mcpServers": {
    "@master/mastergo-magic-mcp": {
      "command": "npx",
      "args": ["-y", "@mastergo/magic-mcp"],
      "env": {
        "MG_MCP_TOKEN": "<YOUR_TOKEN>",
        "API_BASE_URL": "https://mastergo.com"
      }
    }
  }
}

Open Code 使用方法

Open Code 使用 mcp 配置块，通过 type: "local" 和 command 数组来配置：

{
  "mcp": {
    "mastergo-magic-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@mastergo/magic-mcp",
        "--token=<YOUR_TOKEN>",
        "--url=https://mastergo.com"
      ],
      "environment": {
        "NPM_CONFIG_REGISTRY": "https://registry.npmjs.org/"
      },
      "enabled": true
    }
  }
}

项目结构

src 目录

src 目录包含 MasterGo Magic MCP 服务的核心实现：

• index.ts：应用程序入口点，初始化 MCP 服务器并注册所有工具
• http-util.ts：处理与 MasterGo API 通信的 HTTP 请求工具
• types.d.ts：项目的 TypeScript 类型定义

src/tools

包含 MCP 工具的实现：

• base-tool.ts：所有 MCP 工具的基类
• get-dsl.ts：从 MasterGo 设计文件中获取 DSL（领域特定语言）数据的工具
• get-component-link.ts：从链接中获取组件文档的工具
• get-meta.ts：获取元数据信息的工具
• get-component-workflow.ts：提供结构化的组件开发工作流工具，支持 Vue 和 React 组件开发，生成所需的工作流文件和组件规范

src/markdown

包含附加文档的 markdown 文件：

• meta.md：关于元数据结构和用法的文档
• component-workflow.md：组件开发工作流程文档，指导结构化组件开发过程

本地开发

1. 运行 yarn 和 yarn build，安装依赖并构建代码
2. 查看 dist/index.js 的绝对路径
3. 在 MCP 配置中添加本地 MCP 配置，其中 token 为您获取的 token

"mastergo-mcp-local": {
  "command": "node",
  "args": [
    "dist/index.js绝对路径地址",
    "--token=mg_xxxxxx",
    "--url=https://mastergo.com",
    "--debug"
  ],
  "env": {}
},

4. 重启编辑器，确认本地 MCP 已开启

运行成功后，就可以基于本地运行的结果进行调试。您可以基于自己的修改构建自己的 MCP 服务。

欢迎您为我们提供代码贡献，并期待大家一起共建 MasterGo 的 MCP 服务。

许可证

ISC