Mastergo Magic Mcp

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 中预览：

Extract SVG and preview in HTML: https://{domain}/file/{fileId}?layer_id={layerId}

将设计还原为代码：

Restore design: https://{domain}/file/{fileId}?layer_id={layerId}

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

Restore design: https://{domain}/goto/{shortLink}

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

Restore design, save as HTML file: https://{domain}/file/{fileId}?layer_id={layerId}

你也可以使用短链接：

Restore design, save as HTML file: https://{domain}/goto/{shortLink}

使用方法

获取 MG_MCP_TOKEN

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

权限要求

重要：如果工具已连接，但返回“无权限”错误，请检查以下情况：

1. 账户版本要求：

   • 需要使用 Team Edition 或更高版本的 MasterGo 账户
   • 个人免费版不支持访问 MCP 工具

2. 文件位置要求：

   • 设计文件必须放在 Team Projects 中
   • 无法通过 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 代理 URL（例如 http://127.0.0.1:7890），也支持 HTTPS_PROXY / HTTP_PROXY 环境变量
• --header "Key: Value"（可选）：自定义 HTTP 请求标头，可多次使用。值包含空格时请加引号。自定义标头会覆盖默认值，包括 Content-Type 和身份验证令牌，因此覆盖时请确保键名与默认值完全一致。也可通过 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) 代理 URL（--proxy 参数优先级更高）

工具输出格式

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

值	描述
json	默认值。 精简 JSON——适用于将输出传递给需要 JSON 的工具。与之前的行为逐字节一致。
yaml	对于典型设计，所需词元比 JSON 更少（具有重复值的扁平布局收益最大）。
tree	实验性精简格式。结构键（id、name、type）按位置编码在每个节点行中，样式值则在 globalVars 块中去重。大量复用样式的设计可节省最多词元。

AI 模型会针对每次工具调用选择格式。若要影响格式，请在提示词中注明所需格式，例如：

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

注意：

• tree 适用于以下六种工具的所有响应：mcp__getDesignSections（分区列表和各分区 DSL）、mcp__getDsl、mcp__getDesignSvgs、mcp__getDesignTexts、mcp__extractSvg 和 mcp__getMeta。在 tree 格式下，mcp__getMeta 会回退到 JSON，因为其 rules 字段采用 markdown 格式（树形布局会破坏 markdown 的标题和代码块）；其他负载则以树形格式呈现。真正未知的数据结构也会回退到 JSON——不会错误地格式化任何数据。
• 对于 mcp__getDesignTexts，建议使用 json 以最大程度地保证文本原样保留——不过，所有格式都可以无损往返转换。
• 所有格式都可以无损往返转换。无效或未指定的 format 值会回退到 json。

通过 Smithery Marketplace 安装

Smithery 是一个 MCP 服务市场，可帮助您轻松安装和管理 MCP 服务。

方法 1：通过 Smithery 网站安装

1. 访问 Smithery Marketplace
2. 点击“Connect”或“Install”按钮
3. 选择您的 MCP 客户端（例如，Claude Desktop、Cursor 等）
4. 按照提示完成安装和配置

LINGMA 使用方法

在 VSCode 扩展市场中搜索 LINGMA 并安装。

登录后，点击聊天框中的 [MCP tools]。

点击顶部的 [MCP Square] 进入 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 服务：

选项 1：使用命令行参数

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

选项 2：使用环境变量

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

选项 3：使用 SSE（流式 HTTP）

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

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

cline 使用方法

选项 1：使用命令行参数

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

选项 2：使用环境变量

{
  "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 使用包含 type: "local" 和 command 数组的 mcp 配置块：

{
  "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. 添加包含你自己的 token 的本地 MCP 配置

"mastergo-mcp-local": {
  "command": "node",
  "args": [
    "absolute/path/to/dist/index.js",
    "--token=mg_xxxxxx",
    "--url=https://mastergo.com",
    "--debug"
  ],
  "env": {}
},

4. 重启编辑器，确保已启用本地 MCP

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

欢迎贡献代码，期待与你一起构建 MasterGo 的 MCP 服务。

许可证

ISC