@mastergo/magic-mcp
v0.2.2
Published
MasterGo MCP standalone service
Readme
MasterGo Magic MCP
MasterGo Magic MCP 是一个独立的 MCP（Model Context Protocol）服务，旨在连接 MasterGo 设计工具与 AI 模型。它使 AI 模型能够直接从 MasterGo 设计文件中获取 DSL 数据。
主要特性
- 从 MasterGo 设计文件中获取 DSL 数据
- 可直接通过 npx 运行
- 仅需 Node.js 环境，无需其他外部依赖
教程
示例提示词
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
- 访问 https://mastergo.com
- 进入个人设置
- 点击安全设置选项卡
- 找到个人访问令牌
- 点击生成令牌
权限要求
重要提示：如果工具已连接但返回"没有权限"错误，请检查以下条件：
账户版本要求：
- 需要 团队版 或 团队版以上 的 MasterGo 账户
- 个人免费版不支持 MCP 工具访问
文件位置要求：
- 设计文件必须放在 团队项目 中
- 草稿箱中的文件无法通过 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]参数:
--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(可选): 禁用默认规则
你也可以使用空格分隔的参数格式:
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 基础 URLRULES: 规则的 JSON 数组 (例如:'["rule1", "rule2"]')DEFAULT_FORMAT: 设计数据工具的默认输出格式（json|yaml|tree）；--format参数和工具调用时显式传入的format参数优先级更高。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 网站安装
- 访问 Smithery 市场
- 选择你的 MCP 客户端（如 Claude Desktop、Cursor 等）
- one-click install 打开对应客户端，弹出tools&mcp 点击install
- 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：组件开发工作流程文档，指导结构化组件开发过程
本地开发
- 运行
yarn和yarn build，安装依赖并构建代码 - 查看
dist/index.js的绝对路径 - 在 MCP 配置中添加本地 MCP 配置，其中 token 为您获取的 token
"mastergo-mcp-local": {
"command": "node",
"args": [
"dist/index.js绝对路径地址",
"--token=mg_xxxxxx",
"--url=https://mastergo.com",
"--debug"
],
"env": {}
},- 重启编辑器，确认本地 MCP 已开启
运行成功后，就可以基于本地运行的结果进行调试。您可以基于自己的修改构建自己的 MCP 服务。
欢迎您为我们提供代码贡献，并期待大家一起共建 MasterGo 的 MCP 服务。
许可证
ISC