@mastergo/magic-mcp
Installed, started with no arguments, no environment and no input, and listed its tools. Run 2026-11-16.
Needs to start: nothing
Returns a result when called with no setup: 1 of 4 tools tried
Contacts while installing and starting: nothing
Its tool definitions changed since version 0.2.17. If you approved the earlier ones, read them again.
What it contacted
Nothing besides the npm registry it was installed from. Watched from outside its sandbox while it was installed and started with no input. Its tools may still contact things when called.
Starting it
npx -y @mastergo/magic-mcp@0.2.18
Installing a package runs its code. Use a sandbox for anything you have not read.
Calling its tools
4 tools that take no input and look read-only were called once with nothing. 1 returned a result.
version_0_2_18 | Returned a result under 0.1 s · 8 characters |
mcp__getDesignSections | No usable answer tool reported an error: {"error":"getDesignSections failed","message":"Either provide fileId with layerId (or sourceLayerId), or provide a shortLink"} |
mcp__getPageLayers | No usable answer tool reported an error: {"error":"getPageLayers failed","message":"Either provide fileId with layerId (or sourceLayerId), or provide a shortLink"} |
mcp__getDsl | No usable answer tool reported an error: "Either provide fileId with layerId (or sourceLayerId), or provide a MasterGo URL" |
During the calls it contacted nothing it had not already contacted.
Only tools whose names read like looking something up, with no required input, are tried, five at most. Tools that need input, and anything that sounds like it changes or sends something, are not called.
What its tools tell an agent
Wording worth reading before an agent does:
- Talks about the user, other tools or earlier instructions in
mcp__getPageLayers:ntains no restorable layers. This is a real empty page — do NOT tell the user to visit the canvas; report it as an empty page. 2. **Page not found / data
7 tools with commands in capitals or very long text
- Gives the agent orders in
mcp__getDesignSections:and digits, e.g. "802:02364", "453:6855"). This check is MANDATORY when the user's URL contains ?page_id= (not ?layer_id=). If you ignore this and call this tool with
- Very long description in
mcp__getDesignSections:3000 characters or more
- Very long description in
mcp__getPageLayers:3000 characters or more
- Gives the agent orders in
mcp__applyDesign:ized code directly to `{outDir}/{outputFileName}` on disk. CRITICAL — outDir is MANDATORY: Always provide outDir so the finalized code is written directly to disk. Thi
- Gives the agent orders in
mcp__downloadExportAssets:ich nodes are slices (nodes with Export settings). Slices MUST be restored as ONE whole image — never decomposed into child layers. WHAT IT RETURNS - `assets[]`:
- Very long description in
mcp__downloadExportAssets:2503 characters or more
- Very long description in
mcp__getExportList:2772 characters or more
Common and usually harmless: it is how many makers stress how a tool should be used.
Found by simple pattern rules in each tool's description (up to 3,000 characters), quoted as written. Parameter descriptions are not scanned. A clean result is not a safety review.
Tools
version_0_2_18
the current version is 0.2.18
mcp__getDesignSections fileId, layerId, shortLink, sourceLayerId, sectionIndex, format
BEFORE calling this tool, CHECK the layerId:
- If a previous call returned error code [10017] (layer exceeds the 20MB limit), do NOT retry that
same layerId and do NOT fall back to mcp__getDsl — it fetches the same oversized data.
Use the page_id from the URL with mcp__getPageLayers to enumerate top-level layers, then restore
them one by one. If one top-level layer is still too large, ask the user to select a smaller
nested container in the MasterGo canvas and copy its link.
- If layerId has NO colon and no digits (e.g. "M", or any short non-numeric id), it is likely a
PAGE-level id, NOT a layer id. Page-level ids return EMPTY from this tool (they cannot be
enumerated via /container).
→ STOP. Call mcp__getPageLayers with the same fileId+layerId first to enumerate the real
layer_ids, then restore each one individually.
- Only proceed with THIS tool when layerId looks like a real layer id (contains a colon and
digits, e.g. "802:02364", "453:6855").
This check is MANDATORY when the user's URL contains ?page_id= (not ?layer_id=). If you ignore
this and call this tool with a page-level id, the server will return an error redirecting you to
mcp__getPageLayers anyway — so save the round-trip and call getPageLayers first.
[PRIMARY] This is the main tool for all designs. Operates in TWO modes:
Mode 1 — Get layout overview (sectionIndex NOT provided):
Returns the list of all sections with id, name, type, nodeCount, textPreview (first TEXT node, 20 chars max), and a page-absolute bounding box (x, y, width, height) for each section, plus totalSections and totalNodes.
Also returns rootMetadata (root layer width/height/name/type/fill) when available. rootContainer CSS properties for the page wrapper. splitContainers for large page regions that were split into child sections.
Use this FIRST to understand the design scope. The per-section bbox tells you exactly where each section sits inside the root container — use it for absolute positioning when generating code.
Example: { "fileId": "123", "layerId": "456:789" }
Mode 2 — Get section DSL (sectionIndex provided):
Returns the full DSL for ONE specific section.
- PATH nodes carry a `svgShortKey` field (a short sequential ID like `S0#0`, `S0#1`). The SVG markup is NOT in the DSL. Place `@@SVG:{svgShortKey}@@` where each icon goes, then call `mcp__applyDesign` at the end to inject the real high-precision SVG. NEVER hand-write `<path d="...">`.
- CRITICAL: After generating the complete code with all `@@SVG:{svgShortKey}@@` placeholders, call `mcp__applyDesign` to replace them with real SVG. Skipping this WILL cause missing icons.
- INSTANCE nodes with a `_variantProps` object carry semantic state labels. Compare these across sibling instances to determine active/selected/hovered states — do NOT default to the first item.
CRITICAL — sectionIndex is SINGULAR: the parameter is sectionIndex (a SINGLE integer per call). There is NO plural sectionIndices parameter — passing an array will be rejectedmcp__getPageLayers fileId, layerId, sourceLayerId, shortLink, format
List ALL layers under a given page (or any container layer) of a MasterGo design file.
This is the ENUMERATION step of the multi-layer restoration workflow — it only lists
layer_ids; it does NOT restore designs.
**Workflow (enumerate → build URLs → restore one by one):**
1. Call this tool with the page_id / parent layerId to get the full layer list.
2. Pick the top-level restorable layers from the result (FRAME/COMPONENT/INSTANCE at
depth 0/1). For each, build a URL: https://mastergo.com/file/{fileId}?layer_id={id}
(URL-encode the id, e.g. 802:02364 → 802%3A02364).
3. Restore them SEQUENTIALLY — take one layer_id, run the full single-layer restoration
(mcp__getDesignSections → fetch all sections → mcp__applyDesign), write its HTML to its
OWN separate .html file (a complete standalone document with <!DOCTYPE html>/<head>/<body>),
THEN move to the next. Do NOT batch-restore. Do NOT merge multiple layers into one HTML file —
ONE layer = ONE standalone .html file.
AUTOMATED PROGRESS TRACKING: once this tool returns layers, a page restore plan is created
automatically. Every subsequent getDesignSections response carries a `pageRestore` position,
and every applyDesign success response carries `pageRestore.next` with the NEXT layer to
restore (layerId + suggested file name). Follow those fields instead of tracking manually —
they are the authoritative progress record for the whole page.
OVERSIZED PARENT LAYER (a previous call to getDesignSections/getDsl/getMeta returned error
code [10017] "layer data exceeds the 20MB limit"):
Do NOT pass the same oversized container layerId to this tool — that downloads the same layer data
and hits the same limit. Use the page-level ID from the URL (page_id) to list that page's top-level
layers, then restore them individually via getDesignSections. If a top-level layer is still too
large, ask the user to select a smaller nested container in the MasterGo canvas and copy its link.
You can provide either:
1. fileId and layerId directly (layerId = the page's layerId, i.e. page_id), or
2. a short link (like https://{domain}/goto/LhGgBAK)
The returned layer list is lightweight: each entry has id, name, type, depth, parentId,
childrenCount, width, height. It does NOT contain DSL/styles/SVG paths — use the section
or DSL tools to restore each layer.
NOTE: This tool cannot enumerate a document's PAGE list from a fileId alone — you must
already know a page_id / layerId to pass in.
The URL marker `page_id=M` means the file's DEFAULT page and IS supported — do NOT ask the
user for "a real layer_id URL" just because the page_id is `M`.
EMPTY RESULT — TWO DISTINCT CASES (must distinguish):
1. **Page genuinely has no layers** (`totalLayers: 0` + `pageName` present + NO `needsCanvasVisit`):
the page EXISTS in this file but contains no restorable layers. This is a real empty page —
do NOT tell the user to visit the canvas; report it as an empty page.
2. **Page not found / datamcp__getDsl fileId, layerId, sourceLayerId, shortLink, format
[FALLBACK] Use only when mcp__getDesignSections is unavailable or returns an error.
This returns the FULL DSL in one response — may be large and exceed context limits for complex designs.
Prefer mcp__getDesignSections as the primary tool for all designs.
You can provide either:
1. fileId and layerId directly, or
2. a short link (like https://{domain}/goto/LhGgBAK)
This tool returns the raw DSL data that you can then parse and analyze. Use the optional 'format' parameter (json/yaml/tree, defaults to json) to control the serialization.
This tool also returns the rules you must follow when generating code.
The DSL data can also be used to transform and generate code for different frameworks.
mcp__getD2c contentId, documentId, outDir
使用此工具从 MasterGo 获取 D2C 数据,并在本地落盘: 1)将返回的 code 写入 html; 2)将返回的 svg / image 资源按 resourcePath 落盘到对应目录; 3)返回落盘摘要,避免把大体积资源塞进上下文。
9 more tools
mcp__C2d filePath, fileId, layerId, shortLink
使用此工具将代码文件发送到 MasterGo MCP 服务进行 C2D(代码转设计)处理,将用户代码同步到设计稿。
参数说明:
- filePath:HTML 文件的完整路径(如 /path/to/file.html),工具会自动读取文件内容并发送给后端。
- fileId: 不提供 shortLink 时至少需要 fileId。layerId 不是必填,没有就不要传。
- layerId: 可选。图层 ID(只读取 URL 参数 layer_id)。不传或解析不到则仅按 file 维度同步;pageid/page_id 不会被当作 layerId。
- shortLink:可选,短链接形式(例如 https://{domain}/goto/xxxx)。
注意事项:只允许使用 URL 中的 layer_id 参数作为 layerId,严禁将 pageid/page_id 等任何页面 ID 当作 layerId。
如果短链接或 URL 中没有解析出 layer_id,则不传 layerId。
工具会读取 filePath 指定文件的内容,并传给后端,附带 fileId 与可选的 layerId。
mcp__getComponentLink url
When the data returned by mcp__getDsl contains a non-empty componentDocumentLinks array, this tool is used to sequentially retrieve URLs from the componentDocumentLinks array and then obtain component documentation data. The returned document data is used for you to generate frontend code based on components.
mcp__getMeta fileId, layerId, sourceLayerId, format
Use this tool when the user intends to build a complete website or needs to obtain high-level site configuration information. You must provide a fileld and layerld to identify the specific design element. This tool returns the rules and results of the site and page. The rules is a markdown file, you must follow the rules and use the results to analyze the site and page.
mcp__getComponentGenerator rootPath, fileId, layerId, sourceLayerId
Users need to actively call this tool to get the component development workflow. When Generator is mentioned, please actively call this tool. This tool provides a structured workflow for component development following best practices. You must provide an absolute rootPath of workspace to save workflow files.
mcp__getFlutterGenerator rootPath, fileId, layerId, sourceLayerId, featureName
Users need to actively call this tool to get the Flutter component development workflow. When Flutter Generator or Flutter Component is mentioned, please actively call this tool. This tool provides a structured workflow for Flutter component development following best practices. It includes MasterGo DSL to Flutter Widget mapping rules, screen adaptation with flutter_screenutil, and feature-based architecture guidance. It also downloads all image resources from the design file to local disk, rewrites CSS and DSL references to point at Flutter asset paths, and generates an asset manifest. You must provide an absolute rootPath of workspace to save workflow files.
mcp__extractSvg fileId, layerId, sourceLayerId, shortLink, backgroundColor, page, pageSize, format
Extract SVG data from MasterGo design files. This tool retrieves the DSL from a design layer, finds all PATH nodes (typically inside INSTANCE/icon components), resolves their color references, and generates SVG markup strings.
You can provide either:
1. fileId and layerId directly, or
2. a short link (like https://{domain}/goto/LhGgBAK)
Pagination: When there are many icons, use the first call without "page" to get totalCount. Then call again with page=0, page=1, etc. (page starts at 0, pageSize defaults to 20, max 100). If hasMore is false, you've fetched all pages.
mcp__applyDesign fileId, layerId, sourceLayerId, shortLink, code, outDir, outputFileName, targetLang
Finalize generated design code: replace ALL placeholders (SVG icons + long text) with real high-precision data from the design cache, then write the final file directly to disk.
WHAT it does:
1. Replaces every `@@SVG:{svgShortKey}@@` placeholder with the real high-precision `<svg>` markup from the SVG cache (character-for-character exact, no rounding).
2. Replaces every `T{sectionIndex}|{nodeId}` text placeholder with the real long text from the text cache.
3. Detects fabricated (hand-written) `<path d="...">` that were NOT injected via placeholders — reports them as errors.
4. Writes the finalized code directly to `{outDir}/{outputFileName}` on disk.
CRITICAL — outDir is MANDATORY: Always provide outDir so the finalized code is written directly to disk. This ensures the server-injected data reaches the file WITHOUT any LLM re-processing. Do NOT copy the code back into your response and re-output it — that causes precision loss. The file written by this tool IS the final deliverable.
PLACEHOLDER FORMATS:
- SVG icons: `@@SVG:{svgShortKey}@@` — svgShortKey comes from the PATH node's svgShortKey field in the section DSL.
Example: <span class="icon">@@SVG:S0#0@@</span>
- Long text: `T{sectionIndex}|{nodeId}` — appears in TEXT nodes whose text was too long for inline DSL.
Example: <p>T3|1:1234:5678</p>
The server escapes the injected data according to the `targetLang` parameter:
- `html` (default, also for Vue templates): place the placeholder in element content (`<span>@@SVG:S0#0@@</span>`, `<p>T3|1:2</p>`). SVG is inserted as-is; long text is HTML-escaped (& < >).
- `dart` (Flutter): place the placeholder inside a single-quoted string literal (`SvgPicture.string('@@SVG:S0#0@@')`, `Text('T3|1:2')`). SVG/text are escaped for that string (\ ' newline). Pass `targetLang: "dart"`.
Pick targetLang to match the code you generated, and place placeholders in that language's standard position shown above.
You can provide either:
1. fileId and layerId directly, or
2. a short link (like https://{domain}/goto/LhGgBAK)
IMPORTANT: Call this tool with the COMPLETE code string. After the tool writes the file, you are DONE — do NOT output or edit the code further.
mcp__downloadExportAssets fileId, layerId, sourceLayerId, shortLink, exportIds, outDir, format
Download the REAL slice images (切图) that the designer configured on a MasterGo design,
and save them as local image files.
WHY THIS TOOL EXISTS
Rendering a slice produces image bytes on the **SERVER's** disk — a `filePath` you cannot open
from your machine. This tool fetches those bytes over HTTP and writes them into YOUR local output
directory, returning paths you can actually use.
WHEN TO USE
- You need the actual PNG / JPG / WEBP slice files to reference in generated code.
- `mcp__getExportList` told you which nodes are slices (nodes with Export settings).
Slices MUST be restored as ONE whole image — never decomposed into child layers.
WHAT IT RETURNS
- `assets[]`: { exportId, layerId, fileName, format, bytes, filePath } — files actually written locally
- `skipped[]`: { exportId, reason } — slices that could not be fetched
- `dir`: the directory the files were written to
- `autoRendered`: true when this call had to render the slices first (nothing was cached yet)
HOW IT WORKS (fully automatic — ONE call is enough)
1. Reads the server's cached slice list for this file/layer.
2. If nothing is cached, it **renders the slices automatically** (no extra call needed from you).
3. Downloads each slice and writes it to `outDir`.
WHY THAT MATTERS
The server caches rendered slice bytes in memory (TTL ~5 minutes). If you call this tool long after
a previous render, the cache may have expired — this tool re-renders on demand instead of failing.
SCOPE SEMANTICS
Scope = the subtree of the `layerId` you pass. Use the SAME layerId you are restoring: a container
returns the slices inside its subtree, a page id returns every slice on that page. A node that is
ITSELF a slice is NOT part of its own subtree, so passing that node's own id will not return it —
pass its PARENT container's id (the scope you are restoring), or the page id when restoring the
whole page.
A nearly-empty result on a page id does NOT prove the design has no slices: some documents return a
minimal page chunk while slice settings live in layer scope. Query the layer you are restoring.
WHAT "NO SLICE" MEANS
If the design genuinely has no Export settings in scope, this tool says so explicitly — in that case
restore the nodes as normal layers (from the DSL), do NOT invent images.
LIMITATIONS
- Only PNG / JPG / WEBP are produced server-side (SVG / PDF / AVIF are not).
- Slices attached to layers INSIDE a component instance are skipped by the renderer.
- At most 20 slices per underlying render call.
mcp__getExportList fileId, layerId, sourceLayerId, shortLink, format
List the Export (切图) settings configured on a MasterGo design, WITHOUT rendering any image.
This is the CHEAP metadata step — it only reads the design's Export configuration.
WHY YOU NEED THIS
Some nodes are marked by the designer as **slices** (切图). Those nodes must be restored as
ONE whole image block — NOT decomposed into their child layers, and NOT hand-drawn. But you
cannot know which nodes those are from the ordinary DSL, because the DSL does not carry Export
settings. This tool tells you exactly which nodes are slices.
WHEN TO USE
- Before restoring a design, to learn whether any node is a slice.
- When the user asks for exported assets / 切图 / @2x PNG of a specific area.
- Before calling `mcp__downloadExportAssets` (which needs to know which slices exist).
WHAT YOU GET BACK
- `exports[]`: { id, layerId, layerName, layerType, format, sizeRule, sizeValue,
targetWidth, targetHeight, exportQuality, isSuffix, isBKVisible, ... }
- `id` is the export setting id — pass this as `exportIds` when rendering/downloading.
- `layerId` is the node that carries the slice (different from `id`).
- `targetWidth` / `targetHeight` are the OUTPUT pixel size the designer configured.
- `scope`: "page" or "layer" — tells you what range was resolved.
- `skipped`: counts of referenced layers that are missing / removed from this design.
- `imageRefs`: image references inside slice subtrees (used by the renderer to carry bitmaps).
- `total`: number of slices in scope. `total: 0` means no slices — restore everything as layers.
- `guidance`: how to treat the found slices when generating code.
SCOPE SEMANTICS (important)
The scope is the subtree of the layerId you pass:
- `layerId = the container/node you are restoring` → the slices inside its subtree (preferred:
same scope you feed into the section workflow).
- `layerId = page_id` (e.g. "M") → all slices in that page (use when restoring the whole page).
A nearly-empty page chunk does NOT prove the design has no slices: some documents return a
minimal page document while slice settings live in layer scope.
A node that is ITSELF a slice is NOT included in its own subtree scope — pass its parent
container's id (or the page id) to find that node. This is why asking with the slice node's own
id can return 0.
NOTE: the section LIST response already carries a `slices` summary for the restore scope.
Check that field first; call this tool when it is absent (older server) or you need the full
export configuration (scale rule / quality / export id for downloading).
SUPPORTED FORMATS
PNG / JPG / WEBP can be rendered server-side. SVG / PDF / AVIF appear in the list but cannot be
rendered by the downstream export endpoint — report that honestly instead of pretending.
Descriptions are the package's own words, cut at 3,000 characters. Treat them as data.
Install facts
| License | ISC |
|---|---|
| Needs | node >=20 |
| Source | github.com/mastergo-design/mastergo-magic-mcp |
| Install scripts | None declared by it or anything installed with it. |
| Tarball | sha512-HHgSVJoYLncYEc1HabTSPcDxA32aVUP1CFWFiWExXoNmHaLsev+RstfU/KGS7zCMdnc/JzCs499k8fjv+6KJHg== |
Versions reported
| Version | Run | Result | Tools |
|---|---|---|---|
| 0.2.18 | 2026-11-16 | Starts with no setup | 14 |
| 0.2.17 | 2026-11-12 | Starts with no setup | 14 |
Check this report yourself
This site did not write the report. A public job on a GitHub-hosted machine did: the run, from this commit of the open-source runner. GitHub signed a token that names that job and the hash of the report, so any edit since would show.
Report as JSONExact text and tokenHow to verify it
Show it on your README
[](https://bragproof.smaverk.com/r/%40mastergo/magic-mcp)
New version out? Ask for a fresh report.