{"report":{"v":1,"package":"@mastergo/magic-mcp","version":"0.2.18","ranAt":"2026-11-16T11:24:51.452Z","install":{"ok":true,"integrity":"sha512-HHgSVJoYLncYEc1HabTSPcDxA32aVUP1CFWFiWExXoNmHaLsev+RstfU/KGS7zCMdnc/JzCs499k8fjv+6KJHg==","deps":113,"scripts":[],"bins":["mastergo-magic-mcp"],"license":"ISC","engines":"node >=20","repository":"git+https://github.com/mastergo-design/mastergo-magic-mcp.git","bin":"mastergo-magic-mcp"},"start":{"ok":true,"ms":114,"serverName":"MasterGoMcpServer","serverVersion":"0.2.18","protocol":"2025-06-18"},"tools":[{"name":"version_0_2_18","description":"the current version is 0.2.18","params":[]},{"name":"mcp__getDesignSections","description":"\nBEFORE calling this tool, CHECK the layerId:\n- If a previous call returned error code [10017] (layer exceeds the 20MB limit), do NOT retry that\n  same layerId and do NOT fall back to mcp__getDsl — it fetches the same oversized data.\n  Use the page_id from the URL with mcp__getPageLayers to enumerate top-level layers, then restore\n  them one by one. If one top-level layer is still too large, ask the user to select a smaller\n  nested container in the MasterGo canvas and copy its link.\n- If layerId has NO colon and no digits (e.g. \"M\", or any short non-numeric id), it is likely a\n  PAGE-level id, NOT a layer id. Page-level ids return EMPTY from this tool (they cannot be\n  enumerated via /container).\n  → STOP. Call mcp__getPageLayers with the same fileId+layerId first to enumerate the real\n  layer_ids, then restore each one individually.\n- Only proceed with THIS tool when layerId looks like a real layer id (contains a colon and\n  digits, e.g. \"802:02364\", \"453:6855\").\nThis check is MANDATORY when the user's URL contains ?page_id= (not ?layer_id=). If you ignore\nthis and call this tool with a page-level id, the server will return an error redirecting you to\nmcp__getPageLayers anyway — so save the round-trip and call getPageLayers first.\n\n[PRIMARY] This is the main tool for all designs. Operates in TWO modes:\n\nMode 1 — Get layout overview (sectionIndex NOT provided):\nReturns 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.\nAlso 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.\nUse 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.\nExample: { \"fileId\": \"123\", \"layerId\": \"456:789\" }\n\nMode 2 — Get section DSL (sectionIndex provided):\nReturns the full DSL for ONE specific section.\n- 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=\"...\">`.\n- 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.\n- 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.\n\nCRITICAL — sectionIndex is SINGULAR: the parameter is sectionIndex (a SINGLE integer per call). There is NO plural sectionIndices parameter — passing an array will be rejected","params":["fileId","layerId","shortLink","sourceLayerId","sectionIndex","format"]},{"name":"mcp__getPageLayers","description":"\nList ALL layers under a given page (or any container layer) of a MasterGo design file.\nThis is the ENUMERATION step of the multi-layer restoration workflow — it only lists\nlayer_ids; it does NOT restore designs.\n\n**Workflow (enumerate → build URLs → restore one by one):**\n  1. Call this tool with the page_id / parent layerId to get the full layer list.\n  2. Pick the top-level restorable layers from the result (FRAME/COMPONENT/INSTANCE at\n     depth 0/1). For each, build a URL: https://mastergo.com/file/{fileId}?layer_id={id}\n     (URL-encode the id, e.g. 802:02364 → 802%3A02364).\n  3. Restore them SEQUENTIALLY — take one layer_id, run the full single-layer restoration\n     (mcp__getDesignSections → fetch all sections → mcp__applyDesign), write its HTML to its\n     OWN separate .html file (a complete standalone document with <!DOCTYPE html>/<head>/<body>),\n     THEN move to the next. Do NOT batch-restore. Do NOT merge multiple layers into one HTML file —\n     ONE layer = ONE standalone .html file.\n\n  AUTOMATED PROGRESS TRACKING: once this tool returns layers, a page restore plan is created\n  automatically. Every subsequent getDesignSections response carries a `pageRestore` position,\n  and every applyDesign success response carries `pageRestore.next` with the NEXT layer to\n  restore (layerId + suggested file name). Follow those fields instead of tracking manually —\n  they are the authoritative progress record for the whole page.\n\nOVERSIZED PARENT LAYER (a previous call to getDesignSections/getDsl/getMeta returned error\ncode [10017] \"layer data exceeds the 20MB limit\"):\nDo NOT pass the same oversized container layerId to this tool — that downloads the same layer data\nand hits the same limit. Use the page-level ID from the URL (page_id) to list that page's top-level\nlayers, then restore them individually via getDesignSections. If a top-level layer is still too\nlarge, ask the user to select a smaller nested container in the MasterGo canvas and copy its link.\n\nYou can provide either:\n1. fileId and layerId directly (layerId = the page's layerId, i.e. page_id), or\n2. a short link (like https://{domain}/goto/LhGgBAK)\n\nThe returned layer list is lightweight: each entry has id, name, type, depth, parentId,\nchildrenCount, width, height. It does NOT contain DSL/styles/SVG paths — use the section\nor DSL tools to restore each layer.\n\nNOTE: This tool cannot enumerate a document's PAGE list from a fileId alone — you must\nalready know a page_id / layerId to pass in.\n\nThe URL marker `page_id=M` means the file's DEFAULT page and IS supported — do NOT ask the\nuser for \"a real layer_id URL\" just because the page_id is `M`.\n\nEMPTY RESULT — TWO DISTINCT CASES (must distinguish):\n1. **Page genuinely has no layers** (`totalLayers: 0` + `pageName` present + NO `needsCanvasVisit`):\n   the page EXISTS in this file but contains no restorable layers. This is a real empty page —\n   do NOT tell the user to visit the canvas; report it as an empty page.\n2. **Page not found / data","params":["fileId","layerId","sourceLayerId","shortLink","format"]},{"name":"mcp__getDsl","description":"\n[FALLBACK] Use only when mcp__getDesignSections is unavailable or returns an error.\nThis returns the FULL DSL in one response — may be large and exceed context limits for complex designs.\nPrefer mcp__getDesignSections as the primary tool for all designs.\nYou can provide either:\n1. fileId and layerId directly, or\n2. a short link (like https://{domain}/goto/LhGgBAK)\nThis 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.\nThis tool also returns the rules you must follow when generating code.\nThe DSL data can also be used to transform and generate code for different frameworks.\n","params":["fileId","layerId","sourceLayerId","shortLink","format"]},{"name":"mcp__getD2c","description":"\n使用此工具从 MasterGo 获取 D2C 数据，并在本地落盘：\n1）将返回的 code 写入 html；\n2）将返回的 svg / image 资源按 resourcePath 落盘到对应目录；\n3）返回落盘摘要，避免把大体积资源塞进上下文。\n","params":["contentId","documentId","outDir"]},{"name":"mcp__C2d","description":"\n使用此工具将代码文件发送到 MasterGo MCP 服务进行 C2D（代码转设计）处理，将用户代码同步到设计稿。\n\n参数说明：\n- filePath：HTML 文件的完整路径（如 /path/to/file.html），工具会自动读取文件内容并发送给后端。\n- fileId： 不提供 shortLink 时至少需要 fileId。layerId 不是必填，没有就不要传。\n- layerId： 可选。图层 ID（只读取 URL 参数 layer_id）。不传或解析不到则仅按 file 维度同步；pageid/page_id 不会被当作 layerId。\n- shortLink：可选，短链接形式（例如 https://{domain}/goto/xxxx）。\n  注意事项：只允许使用 URL 中的 layer_id 参数作为 layerId，严禁将 pageid/page_id 等任何页面 ID 当作 layerId。\n  如果短链接或 URL 中没有解析出 layer_id，则不传 layerId。\n\n工具会读取 filePath 指定文件的内容，并传给后端，附带 fileId 与可选的 layerId。\n","params":["filePath","fileId","layerId","shortLink"]},{"name":"mcp__getComponentLink","description":"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.","params":["url"]},{"name":"mcp__getMeta","description":"\nUse this tool when the user intends to build a complete website or needs to obtain high-level site\nconfiguration information. You must provide a fileld and layerld to identify the specific design element.\nThis tool returns the rules and results of the site and page. The rules is a markdown file, you must\nfollow the rules and use the results to analyze the site and page.\n","params":["fileId","layerId","sourceLayerId","format"]},{"name":"mcp__getComponentGenerator","description":"\nUsers need to actively call this tool to get the component development workflow. When Generator is mentioned, please actively call this tool.\nThis tool provides a structured workflow for component development following best practices.\nYou must provide an absolute rootPath of workspace to save workflow files.\n","params":["rootPath","fileId","layerId","sourceLayerId"]},{"name":"mcp__getFlutterGenerator","description":"\nUsers 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.\nThis tool provides a structured workflow for Flutter component development following best practices.\nIt includes MasterGo DSL to Flutter Widget mapping rules, screen adaptation with flutter_screenutil, and feature-based architecture guidance.\nIt 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.\nYou must provide an absolute rootPath of workspace to save workflow files.\n","params":["rootPath","fileId","layerId","sourceLayerId","featureName"]},{"name":"mcp__extractSvg","description":"\nExtract 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.\nYou can provide either:\n1. fileId and layerId directly, or\n2. a short link (like https://{domain}/goto/LhGgBAK)\n\nPagination: 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.\n","params":["fileId","layerId","sourceLayerId","shortLink","backgroundColor","page","pageSize","format"]},{"name":"mcp__applyDesign","description":"\nFinalize 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.\n\nWHAT it does:\n1. Replaces every `@@SVG:{svgShortKey}@@` placeholder with the real high-precision `<svg>` markup from the SVG cache (character-for-character exact, no rounding).\n2. Replaces every `T{sectionIndex}|{nodeId}` text placeholder with the real long text from the text cache.\n3. Detects fabricated (hand-written) `<path d=\"...\">` that were NOT injected via placeholders — reports them as errors.\n4. Writes the finalized code directly to `{outDir}/{outputFileName}` on disk.\n\nCRITICAL — 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.\n\nPLACEHOLDER FORMATS:\n- SVG icons: `@@SVG:{svgShortKey}@@` — svgShortKey comes from the PATH node's svgShortKey field in the section DSL.\n  Example: <span class=\"icon\">@@SVG:S0#0@@</span>\n- Long text: `T{sectionIndex}|{nodeId}` — appears in TEXT nodes whose text was too long for inline DSL.\n  Example: <p>T3|1:1234:5678</p>\n\nThe server escapes the injected data according to the `targetLang` parameter:\n- `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 (& < >).\n- `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\"`.\nPick targetLang to match the code you generated, and place placeholders in that language's standard position shown above.\n\nYou can provide either:\n1. fileId and layerId directly, or\n2. a short link (like https://{domain}/goto/LhGgBAK)\n\nIMPORTANT: 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.\n","params":["fileId","layerId","sourceLayerId","shortLink","code","outDir","outputFileName","targetLang"]},{"name":"mcp__downloadExportAssets","description":"\nDownload the REAL slice images (切图) that the designer configured on a MasterGo design,\nand save them as local image files.\n\nWHY THIS TOOL EXISTS\nRendering a slice produces image bytes on the **SERVER's** disk — a `filePath` you cannot open\nfrom your machine. This tool fetches those bytes over HTTP and writes them into YOUR local output\ndirectory, returning paths you can actually use.\n\nWHEN TO USE\n- You need the actual PNG / JPG / WEBP slice files to reference in generated code.\n- `mcp__getExportList` told you which nodes are slices (nodes with Export settings).\n  Slices MUST be restored as ONE whole image — never decomposed into child layers.\n\nWHAT IT RETURNS\n- `assets[]`: { exportId, layerId, fileName, format, bytes, filePath } — files actually written locally\n- `skipped[]`: { exportId, reason } — slices that could not be fetched\n- `dir`: the directory the files were written to\n- `autoRendered`: true when this call had to render the slices first (nothing was cached yet)\n\nHOW IT WORKS (fully automatic — ONE call is enough)\n1. Reads the server's cached slice list for this file/layer.\n2. If nothing is cached, it **renders the slices automatically** (no extra call needed from you).\n3. Downloads each slice and writes it to `outDir`.\n\nWHY THAT MATTERS\nThe server caches rendered slice bytes in memory (TTL ~5 minutes). If you call this tool long after\na previous render, the cache may have expired — this tool re-renders on demand instead of failing.\n\nSCOPE SEMANTICS\nScope = the subtree of the `layerId` you pass. Use the SAME layerId you are restoring: a container\nreturns the slices inside its subtree, a page id returns every slice on that page. A node that is\nITSELF a slice is NOT part of its own subtree, so passing that node's own id will not return it —\npass its PARENT container's id (the scope you are restoring), or the page id when restoring the\nwhole page.\nA nearly-empty result on a page id does NOT prove the design has no slices: some documents return a\nminimal page chunk while slice settings live in layer scope. Query the layer you are restoring.\n\nWHAT \"NO SLICE\" MEANS\nIf the design genuinely has no Export settings in scope, this tool says so explicitly — in that case\nrestore the nodes as normal layers (from the DSL), do NOT invent images.\n\nLIMITATIONS\n- Only PNG / JPG / WEBP are produced server-side (SVG / PDF / AVIF are not).\n- Slices attached to layers INSIDE a component instance are skipped by the renderer.\n- At most 20 slices per underlying render call.\n","params":["fileId","layerId","sourceLayerId","shortLink","exportIds","outDir","format"]},{"name":"mcp__getExportList","description":"\nList the Export (切图) settings configured on a MasterGo design, WITHOUT rendering any image.\nThis is the CHEAP metadata step — it only reads the design's Export configuration.\n\nWHY YOU NEED THIS\nSome nodes are marked by the designer as **slices** (切图). Those nodes must be restored as\nONE whole image block — NOT decomposed into their child layers, and NOT hand-drawn. But you\ncannot know which nodes those are from the ordinary DSL, because the DSL does not carry Export\nsettings. This tool tells you exactly which nodes are slices.\n\nWHEN TO USE\n- Before restoring a design, to learn whether any node is a slice.\n- When the user asks for exported assets / 切图 / @2x PNG of a specific area.\n- Before calling `mcp__downloadExportAssets` (which needs to know which slices exist).\n\nWHAT YOU GET BACK\n- `exports[]`: { id, layerId, layerName, layerType, format, sizeRule, sizeValue,\n                   targetWidth, targetHeight, exportQuality, isSuffix, isBKVisible, ... }\n  - `id` is the export setting id — pass this as `exportIds` when rendering/downloading.\n  - `layerId` is the node that carries the slice (different from `id`).\n  - `targetWidth` / `targetHeight` are the OUTPUT pixel size the designer configured.\n- `scope`: \"page\" or \"layer\" — tells you what range was resolved.\n- `skipped`: counts of referenced layers that are missing / removed from this design.\n- `imageRefs`: image references inside slice subtrees (used by the renderer to carry bitmaps).\n- `total`: number of slices in scope. `total: 0` means no slices — restore everything as layers.\n- `guidance`: how to treat the found slices when generating code.\n\nSCOPE SEMANTICS (important)\nThe scope is the subtree of the layerId you pass:\n- `layerId = the container/node you are restoring` → the slices inside its subtree (preferred:\n  same scope you feed into the section workflow).\n- `layerId = page_id` (e.g. \"M\") → all slices in that page (use when restoring the whole page).\n  A nearly-empty page chunk does NOT prove the design has no slices: some documents return a\n  minimal page document while slice settings live in layer scope.\n  A node that is ITSELF a slice is NOT included in its own subtree scope — pass its parent\n  container's id (or the page id) to find that node. This is why asking with the slice node's own\n  id can return 0.\n\nNOTE: the section LIST response already carries a `slices` summary for the restore scope.\nCheck that field first; call this tool when it is absent (older server) or you need the full\nexport configuration (scale rule / quality / export id for downloading).\n\nSUPPORTED FORMATS\nPNG / JPG / WEBP can be rendered server-side. SVG / PDF / AVIF appear in the list but cannot be\nrendered by the downstream export endpoint — report that honestly instead of pretending.\n","params":["fileId","layerId","sourceLayerId","shortLink","format"]}],"toolsHash":"d94110bb2ec7b50e2db8db8fff9c1ea62189b77f4c45160a17fa8f47d8867c11","wrote":[],"callsAt":"2026-11-16T11:24:57.873Z","calls":[{"tool":"version_0_2_18","ok":true,"ms":3,"bytes":8},{"tool":"mcp__getDesignSections","ok":false,"ms":1,"bytes":0,"error":"tool reported an error: {\"error\":\"getDesignSections failed\",\"message\":\"Either provide fileId with layerId (or sourceLayerId), or provide a shortLink\"}"},{"tool":"mcp__getPageLayers","ok":false,"ms":1,"bytes":0,"error":"tool reported an error: {\"error\":\"getPageLayers failed\",\"message\":\"Either provide fileId with layerId (or sourceLayerId), or provide a shortLink\"}"},{"tool":"mcp__getDsl","ok":false,"ms":0,"bytes":0,"error":"tool reported an error: \"Either provide fileId with layerId (or sourceLayerId), or provide a MasterGo URL\""}],"host":{"commit":"eaaffffaf52255d1b77dc4aacffdfaf353f0c12c","run":"https://github.com/itsHaddad/bragproof/actions/runs/43857070216"},"network":{"names":["registry.npmjs.org"],"conns":[],"callNames":[],"callConns":[]}},"summary":{"outcome":"started","needs":[],"contacts":[],"flags":[{"kind":"orders","tool":"mcp__getDesignSections","quote":"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"},{"kind":"very-long","tool":"mcp__getDesignSections","quote":"3000 characters or more"},{"kind":"about-others","tool":"mcp__getPageLayers","quote":"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"},{"kind":"very-long","tool":"mcp__getPageLayers","quote":"3000 characters or more"},{"kind":"orders","tool":"mcp__applyDesign","quote":"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"},{"kind":"orders","tool":"mcp__downloadExportAssets","quote":"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[]`:"},{"kind":"very-long","tool":"mcp__downloadExportAssets","quote":"2503 characters or more"},{"kind":"very-long","tool":"mcp__getExportList","quote":"2772 characters or more"}],"tools":14,"wrote":0,"callsTried":4,"callsAnswered":1,"callContacts":[]},"history":[{"package":"@mastergo/magic-mcp","version":"0.2.18","ranAt":"2026-11-16T11:24:51.452Z","outcome":"started","tools":14,"contacts":0,"flags":8,"serious":1,"toolsHash":"d94110bb2ec7b50e2db8db8fff9c1ea62189b77f4c45160a17fa8f47d8867c11"},{"package":"@mastergo/magic-mcp","version":"0.2.17","ranAt":"2026-11-12T17:46:31.946Z","outcome":"started","tools":14,"contacts":0,"flags":8,"serious":1,"toolsHash":"9adf195578fb938fdbe7a59eee6bd08fec59d6e004bcaadc1446749bb6957bd3"}],"page":"https://bragproof.smaverk.com/r/%40mastergo/magic-mcp"}