MasterGo Magic MCP

MasterGo Magic MCP is a standalone MCP (Model Context Protocol) service designed to connect MasterGo design tools with AI models. It enables AI models to directly retrieve DSL data from MasterGo design files.

Key Features

• Retrieves DSL data from MasterGo design files
• Runs directly with npx
• No external dependencies required, only Node.js environment needed

Tutorial

• https://mastergo.com/file/192644601973042

Example Prompts

Once the MCP server is connected, you can use the following prompts in your AI chat:

Extract SVG and preview in HTML:

Extract SVG and preview in HTML: https://{domain}/file/{fileId}?layer_id={layerId}

Restore a design to code:

Restore design: https://{domain}/file/{fileId}?layer_id={layerId}

Replace `{domain}`, `{fileId}`, and `{layerId}` with your actual values. You can also use short links:

Restore design: https://{domain}/goto/{shortLink}

Restore a design and save as an HTML file:

Restore design, save as HTML file: https://{domain}/file/{fileId}?layer_id={layerId}

You can also use short links:

Restore design, save as HTML file: https://{domain}/goto/{shortLink}

Usage

Obtaining MG_MCP_TOKEN

1. Visit https://mastergo.com

2. Enter personal settings

3. Click the Security Settings tab

4. Find the personal access token

5. Click to generate the token

Permission Requirements

Important: If the tool is connected but returns a "no permission" error, please check the following conditions:

1. Account Version Requirement:

2. File Location Requirement:

Command Line Options

npx @mastergo/magic-mcp --token=YOUR_TOKEN [--url=API_URL] [--rule=RULE_NAME] [--proxy=PROXY_URL] [--format=FORMAT] [--header "Key: Value"] [--debug] [--no-rule] [--no-prefix]

Parameters:

• `--token=YOUR_TOKEN` (required): MasterGo API token for authentication
• `--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
• `--no-prefix` (optional): Register tools without the `mcp__` name prefix (e.g. `getDsl` instead of `mcp__getDsl`). Some MCP clients (such as Grok Build) silently skip tools whose fully-qualified `server__tool` name contains more than one `__` separator — since the server is already prefixed, a `mcp__getDsl` tool name becomes `server__mcp__getDsl` and is dropped. Enable this flag for those clients. Also settable via the `MG_NO_PREFIX` environment variable (`1`/`true`/`yes`).

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 --format FORMAT --header "Key: Value" --debug

Environment Variables

Alternatively, you can use environment variables instead of command line arguments:

• `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.
• `MG_NO_PREFIX`: Set to `1`/`true`/`yes` to register tools without the `mcp__` name prefix (the `--no-prefix` argument takes priority).
• `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).

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.

Method 1: Install via Smithery Website

1. Visit Smithery Marketplace

2. Click the "Connect" or "Install" button

3. Select your MCP client (e.g., Claude Desktop, Cursor, etc.)

4. Follow the prompts to complete installation and configuration

LINGMA Usage

Search for LINGMA in the VSCode extension marketplace and install it.

After logging in, click on [MCP tools] in the chat box.

Click on [MCP Square] at the top to enter the MCP marketplace, find the MasterGo design collaboration tool and install it.

After installation, go back to [MCP Servers], and edit our MCP service to replace it with your own MasterGo token.

Finally, switch the chat mode to agent mode in the chat interface.

cursor Usage

Cursor Mcp usage guide reference: https://docs.cursor.com/context/model-context-protocol#using-mcp-tools-in-agent

You can configure the MCP server using either command line arguments or environment variables:

Option 1: Using command line arguments

{
  "mcpServers": {
    "mastergo-magic-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@mastergo/magic-mcp",
        "--token=",
        "--url=https://mastergo.com"
      ],
      "env": {}
    }
  }
}

Option 2: Using environment variables

{
  "mcpServers": {
    "mastergo-magic-mcp": {
      "command": "npx",
      "args": ["-y", "@mastergo/magic-mcp"],
      "env": {
        "MG_MCP_TOKEN": "",
        "API_BASE_URL": "https://mastergo.com"
      }
    }
  }
}

Option 3: Using SSE (Streamable HTTP)

No local installation required. The MCP server runs remotely and is accessed via SSE:

{
  "mcpServers": {
    "mastergo-magic-mcp": {
      "type": "http",
      "url": "https://mastergo.com/mcp/xf/sse",
      "headers": {
        "x-mg-useraccesstoken": ""
      }
    }
  }
}

cline Usage

Option 1: Using command line arguments

{
  "mcpServers": {
    "@master/mastergo-magic-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@mastergo/magic-mcp",
        "--token=",
        "--url=https://mastergo.com"
      ],
      "env": {}
    }
  }
}

Option 2: Using environment variables

{
  "mcpServers": {
    "@master/mastergo-magic-mcp": {
      "command": "npx",
      "args": ["-y", "@mastergo/magic-mcp"],
      "env": {
        "MG_MCP_TOKEN": "",
        "API_BASE_URL": "https://mastergo.com"
      }
    }
  }
}

Open Code Usage

Open Code uses a `mcp` configuration block with `type: "local"` and `command` array:

{
  "mcp": {
    "mastergo-magic-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@mastergo/magic-mcp",
        "--token=",
        "--url=https://mastergo.com"
      ],
      "environment": {
        "NPM_CONFIG_REGISTRY": "https://registry.npmjs.org/"
      },
      "enabled": true
    }
  }
}

Project Structure

src Directory

The `src` directory contains the core implementation of the MasterGo Magic MCP service:

• `index.ts`: Entry point of the application that initializes the MCP server and registers all tools
• `http-util.ts`: Utility for handling HTTP requests to the MasterGo API
• `types.d.ts`: TypeScript type definitions for the project

src/tools

Contains implementations of MCP tools:

• `base-tool.ts`: Base class for all MCP tools
• `get-dsl.ts`: Tool for retrieving DSL (Domain Specific Language) data from MasterGo design files
• `get-component-link.ts`: Tool for retrieving component documentation from links
• `get-meta.ts`: Tool for retrieving metadata information
• `get-component-workflow.ts`: Tool providing structured component development workflow for Vue and React components, generating workflow files and component specifications

src/markdown

Contains markdown files with additional documentation:

• `meta.md`: Documentation about metadata structure and usage
• `component-workflow.md`: Component development workflow documentation guiding structured component development process

Local Development

1. Run `yarn` and `yarn build` to install dependencies and build the code

2. Find the absolute path of `dist/index.js`

3. Add local MCP configuration with your token

"mastergo-mcp-local": {
  "command": "node",
  "args": [
    "absolute/path/to/dist/index.js",
    "--token=mg_xxxxxx",
    "--url=https://mastergo.com",
    "--debug"
  ],
  "env": {}
},

4. Restart your editor to ensure the local MCP is enabled

After successful execution, you can debug based on the local running results. You can build your own MCP service based on your modifications.

We welcome your code contributions and look forward to building MasterGo's MCP service together.

License

ISC