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