@mastergo/magic-mcp 0.2.1 → 0.2.2

package/README.md

@@ -73,7 +73,7 @@ Restore design, save as HTML file: https://{domain}/goto/{shortLink}
 ### Command Line Options
 
 ```
-npx @mastergo/magic-mcp --token=YOUR_TOKEN [--url=API_URL] [--rule=RULE_NAME] [--proxy=PROXY_URL] [--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] [--no-rule]
 ```
 
 #### Parameters:
@@ -82,13 +82,15 @@ npx @mastergo/magic-mcp --token=YOUR_TOKEN [--url=API_URL] [--rule=RULE_NAME] [-
 - `--url=API_URL` (optional): API base URL, defaults to http://localhost:3000
 - `--rule=RULE_NAME` (optional): Add design rules to apply, can be used multiple times
 - `--proxy=PROXY_URL` (optional): HTTP/HTTPS proxy URL (e.g., `http://127.0.0.1:7890`), also supports `HTTPS_PROXY` / `HTTP_PROXY` environment variables
+- `--header "Key: Value"` (optional): Custom HTTP request header, can be used multiple times. **Quote the value** when it contains spaces. Custom headers override the defaults — including `Content-Type` and the auth token — so match the default key exactly when overriding. Also settable via the `MG_EXTRA_HEADERS` environment variable as a JSON object (e.g. `MG_EXTRA_HEADERS='{"X-Custom":"val"}'`); CLI headers take precedence over env.
+- `--format=FORMAT` (optional): Default output format for design-data tools — one of `json` (default), `yaml`, `tree`. An explicit per-call `format` tool parameter overrides this. Also settable via the `DEFAULT_FORMAT` environment variable.
 - `--debug` (optional): Enable debug mode for detailed error information
 - `--no-rule` (optional): Disable default rules
 
 You can also use space-separated format for parameters:
 
 ```
-npx @mastergo/magic-mcp --token YOUR_TOKEN --url API_URL --rule RULE_NAME --proxy PROXY_URL --debug
+npx @mastergo/magic-mcp --token YOUR_TOKEN --url API_URL --rule RULE_NAME --proxy PROXY_URL --format FORMAT --header "Key: Value" --debug
 ```
 
 #### Environment Variables
@@ -98,8 +100,31 @@ Alternatively, you can use environment variables instead of command line argumen
 - `MG_MCP_TOKEN` or `MASTERGO_API_TOKEN`: MasterGo API token
 - `API_BASE_URL`: API base URL
 - `RULES`: JSON array of rules (e.g., `'["rule1", "rule2"]'`)
+- `DEFAULT_FORMAT`: Default output format for design-data tools (`json` | `yaml` | `tree`); the `--format` argument and an explicit per-call `format` tool parameter take precedence.
 - `HTTPS_PROXY` / `https_proxy` / `HTTP_PROXY` / `http_proxy`: HTTP(S) proxy URL (the `--proxy` argument takes priority)
 
+### Tool Output Format
+
+The design-data tools (`mcp__getDesignSections`, `mcp__getDsl`, `mcp__getDesignSvgs`, `mcp__getDesignTexts`, `mcp__extractSvg`, `mcp__getMeta`) accept an optional `format` parameter that controls how the payload is serialized. It defaults to `json`, or to the value set via `--format` / `DEFAULT_FORMAT` (see [Command Line Options](#command-line-options)).
+
+| Value | Description |
+| --- | --- |
+| `json` | **Default.** Compact JSON — useful when piping output into tools that expect JSON. Byte-identical to the prior behavior. |
+| `yaml` | Fewer tokens than JSON for typical designs (flat layouts with repeated values benefit most). |
+| `tree` | Experimental compact format. Structural keys (`id`, `name`, `type`) are encoded positionally on each node line, and style values stay deduplicated in a `globalVars` block. Designs with heavy style reuse see the largest token savings. |
+
+The format is chosen per tool call by the AI model. To influence it, mention the desired format in your prompt, for example:
+
+```
+Restore design, use tree format: https://{domain}/file/{fileId}?layer_id={layerId}
+```
+
+Notes:
+
+- `tree` applies to all six tools' responses: `mcp__getDesignSections` (section list and per-section DSL), `mcp__getDsl`, `mcp__getDesignSvgs`, `mcp__getDesignTexts`, `mcp__extractSvg`, and `mcp__getMeta`. `mcp__getMeta` falls back to JSON under `tree` because its `rules` field is markdown (the tree layout would corrupt the markdown's headings/code blocks); other payloads render as tree. Truly unknown shapes also fall back to JSON — no data is ever mis-formatted.
+- For `mcp__getDesignTexts`, `json` is recommended for maximum verbatim-text fidelity — though all formats round-trip without data loss.
+- All formats round-trip without data loss. An invalid or omitted `format` value falls back to `json`.
+
 ### Installing via Smithery Marketplace
 
 Smithery is an MCP server marketplace that makes it easy to install and manage MCP services.

package/README.zh-CN.md

@@ -73,7 +73,7 @@ MCP 服务连接成功后，可以在 AI 对话中使用以下提示词：
 ### 命令行选项
 
 ```
-npx @mastergo/magic-mcp --token=YOUR_TOKEN [--url=API_URL] [--rule=RULE_NAME] [--proxy=PROXY_URL] [--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] [--no-rule]
 ```
 
 #### 参数:
@@ -82,13 +82,15 @@ npx @mastergo/magic-mcp --token=YOUR_TOKEN [--url=API_URL] [--rule=RULE_NAME] [-
 - `--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 --debug
+npx @mastergo/magic-mcp --token YOUR_TOKEN --url API_URL --rule RULE_NAME --proxy PROXY_URL --format FORMAT --header "Key: Value" --debug
 ```
 
 #### 环境变量
@@ -98,8 +100,31 @@ npx @mastergo/magic-mcp --token YOUR_TOKEN --url API_URL --rule RULE_NAME --prox
 - `MG_MCP_TOKEN` 或 `MASTERGO_API_TOKEN`: MasterGo API 令牌
 - `API_BASE_URL`: API 基础 URL
 - `RULES`: 规则的 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 市场安装