MasterGo Magic MCP：将设计稿变成 AI 可读的「数字语言」

一、场景切入：设计师和 AI 之间，隔着一道「翻译」墙

凌晨两点，前端工程师李明收到产品经理的消息：「这版 UI 改好了，上线吧。」他打开设计文件，发现是一堆 MasterGo 上的图层、组件和样式标注——没有直接的代码输出。他只能逐层手动还原，一行行写 CSS、对齐像素、还原圆角和阴影。三个小时后，设计稿终于「变成」了网页。

这是每一个同时做设计和前端产品的团队都会遇到的老问题：设计文件 ≠ 可执行代码，中间总有一道繁琐的人工翻译工序。MasterGo Magic MCP 的出现，正是要在这道墙上开一扇门——让 AI 模型直接「读懂」MasterGo 设计稿，把设计师的意图翻译成代码。

二、项目背景：MasterGo 的 AI 进化之路

MasterGo 是国内主流的在线协作设计工具，类似于 Figma，但更针对中文互联网团队的产品设计场景。MasterGo Magic MCP 由 MasterGo 官方团队（mastergo-design）开发并维护，2025 年初正式开源，是一个独立部署的 MCP（Model Context Protocol）服务。截至分析时，GitHub 获星 266 个，被收录于 Smithery.ai、MCPMarket、FlowHunt 等多个 MCP 市场。

MCP 是 Anthropic 提出的标准化协议，旨在让 AI 模型安全、可控地调用外部工具和数据源。相比传统的 API 集成，MCP 的优势在于：一次配置，处处可用——只要 MCP 客户端（Claude Desktop、Cursor、LINGMA 等）支持，就能自动发现并连接 MasterGo Magic MCP 提供的工具。

三、技术原理：DSL —— 设计稿的「结构化密码」

MasterGo 设计稿的核心数据格式是 DSL（Domain Specific Language）——一种 MasterGo 自研的结构化描述语言，记录了每个图层的类型、位置、尺寸、样式、层级关系等信息。传统的做法是让 AI 直接「看」设计稿截图，但截图丢失了大量语义信息（组件层级、约束关系、变量引用）。

MasterGo Magic MCP 的思路截然不同：它通过 MCP 协议，让 AI 模型实时查询 MasterGo 的 DSL 数据。具体来说，它暴露了以下核心工具：

Section 分段加载机制是本项目最重要的设计决策之一。复杂设计稿的 DSL 可能非常大，如果一次性返回，不仅容易超过 AI 的上下文窗口限制，还会导致响应超时。MasterGo Magic MCP 采用了「先总览后分片」的策略：先调用 mcp__getDesignSections（不带参数）获取整体布局和分节信息，再逐段（sectionIndex=0,1,2...）批量获取，每批 3-5 段，兼顾效率和稳定性。

四、代码架构：TypeScript + MCP SDK 的插件化设计

项目采用 TypeScript 开发，主要依赖：

• @modelcontextprotocol/sdk：Anthropic 官方 MCP 协议 SDK，封装了 stdio 通信和服务注册逻辑
• axios：HTTP 客户端，负责与 MasterGo API 服务通信
• zod：Schema 验证，确保工具输入参数合法
• js-yaml：支持 YAML 格式的 DSL 输出
• https-proxy-agent：代理支持，适用于企业内网环境

核心架构为插件化工具集：

src/
├── index.ts              # 入口：McpServer 注册 + 所有工具挂载
├── tools/
│   ├── base-tool.ts      # 工具基类，统一 execute 流程
│   ├── get-dsl.ts        # 全量 DSL 查询
│   ├── get-design-sections.ts  # 分段 DSL（主工具）
│   ├── get-design-svgs.ts      # SVG 提取
│   ├── get-design-texts.ts     # 文本提取
│   ├── get-meta.ts       # 站点级元信息
│   ├── get-d2c.ts        # 设计稿转 HTML（落盘逻辑）
│   ├── get-c2d.ts / get-flutter-workflow.ts  # 组件级转换
│   └── extract-svg.ts    # 单个 SVG 提取
├── utils/
│   ├── api.ts            # Axios 实例 + 代理配置 + 请求头管理
│   ├── args.ts           # 命令行参数解析（token/rule/format/debug）
│   └── format.ts         # 输出格式控制（json/yaml/tree）
└── markdown/
    └── meta.md           # 站点级生成规则（内置 prompt）

api.ts 中的 HTTP 层做了充分的工程化设计：请求头采用缓存机制（_commonHeaderCache），避免每次请求重复拼接；支持从环境变量（MG_MCP_TOKEN）或命令行参数（--token）读取认证令牌；代理配置自动检测环境变量，兼顾开发调试和企业内网部署。

五、部署体验：npx 即开即用

MasterGo Magic MCP 提供了两种启动方式：

方式一：npx（推荐）

npx @mastergo/magic-mcp --token=YOUR_MG_TOKEN --url=https://mastergo.com

只需一行命令，不需要 clone 仓库，不需要安装依赖。npx 会自动下载并执行包。

方式二：Docker

docker run -e MG_MCP_TOKEN=YOUR_TOKEN mastergo/magic-mcp

容器基于 node:lts-alpine，镜像体积小（约 180MB），适合在服务器或 CI 环境中托管 MCP 服务。

接入 MCP 客户端时需要注意两点：

1. 必须使用团队版 MasterGo 账户——个人免费版不支持 MCP 工具调用
2. 设计文件必须在团队项目中——草稿箱里的文件无法被 MCP 访问

六、实际效果：能做什么，不能做什么

从 README 中的示例提示词来看，MasterGo Magic MCP 目前最能发挥价值的场景有三个：

• SVG 提取与预览：将 MasterGo 中的矢量图标提取出来，嵌入 HTML 页面
• 设计稿还原：将 MasterGo 图层信息翻译成 HTML/CSS 代码
• 批量文本提取：提取设计稿中的文案，生成翻译或内容文档

但也要看到局限：MasterGo Magic MCP 本身不「生成」代码，它只是把设计稿的结构化数据传递给 AI 模型，最终代码质量取决于所调用的 AI 模型（Claude、GPT-4 等）的能力。复杂设计稿（多状态组件、动态交互、第三方依赖）在当前阶段仍需要人工介入修正。

七、行业意义：从「人读设计稿」到「AI 读设计稿」

MasterGo Magic MCP 代表了一个明确趋势：设计工具与 AI 编程工具的深度集成。过去，AI 辅助编程工具（如 GitHub Copilot、Cursor）只能依靠截图或人工描述来理解 UI 设计稿，而 MCP 协议让 AI 能够直接获取像素级精度的结构化数据。这意味着前端开发的效率天花板有望被大幅抬高——从「一天还原一个页面」进化到「几分钟生成基础代码框架」。

从生态角度看，MasterGo Magic MCP 进入 Smithery.ai、MCPMarket 等 MCP 市场，也意味着它正在成为 AI × 设计工作流的标准节点之一。随着 MCP 协议被更多工具支持（Cursor 已经在 2025 年全面拥抱 MCP），这类设计稿转代码工具的价值会持续放大。

本报告基于 GitHub 仓库 v0.2.2 版本（分析时间：2026-07-07）分析生成