MasterGo MCP Server for AI Design Data

Overview

MasterGo MCP Server implements the Model Context Protocol (MCP) for MasterGo design files. It makes design DSL (domain-specific language) data and related assets available over a simple HTTP API so AI models and tools can retrieve structured design context during generation, analysis, or automation workflows. By exposing design metadata, layers, tokens, and exportable assets, the server bridges MasterGo design sources and AI-driven developer or design assistants.

This server is useful when you want programmatic access to design semantics (components, tokens, layout info) rather than raw image exports. AI models can request the DSL for a specific file or component to ground responses, generate code that matches the design system, or perform design-aware transformations without embedding full file blobs in prompts.

Features

• Exposes MasterGo design DSL and asset data via MCP-compatible REST endpoints
• Authentication via API token (Bearer) for secure access
• Local caching/storage layer to speed repeated retrievals
• Docker-ready for containerized deployments
• Simple health and metadata endpoints for orchestration
• Designed to be integrated as a tool in LLM workflows (retrieve context on demand)

Installation / Configuration

Requirements: Node.js (>=16) and npm, or Docker.

1. Clone and install

git clone https://github.com/mastergo-design/mastergo-magic-mcp.git
cd mastergo-magic-mcp
npm ci

2. Create a .env file (example)

# Server options
PORT=8080

# MasterGo or partner API token used to fetch design files
MASTERGO_TOKEN=your_mastergo_token_here

# Optional local storage directory for caching
STORAGE_DIR=./cache

# Optional host override
MASTERGO_HOST=https://api.mastergo.design

3. Start the server

npm start
# or for development
npm run dev

4. Docker

# build image
docker build -t mastergo-mcp .

# run container
docker run -p 8080:8080 \
  -e MASTERGO_TOKEN=your_mastergo_token_here \
  -e STORAGE_DIR=/data/cache \
  mastergo-mcp

By default the server listens on PORT and expects a Bearer token in Authorization to fetch protected MasterGo resources.

Available Resources

Below are typical endpoints exposed by the MCP server. Actual endpoint paths may vary; check the repository for exact route names.

Example response snippet for DSL:

{
  "id": "file-123",
  "name": "Landing Page",
  "components": [
    {
      "id": "btn-1",
      "type": "button",
      "tokens": { "color": "primary", "radius": "sm" },
      "frame": { "x": 16, "y": 24, "w": 120, "h": 40 }
    }
  ],
  "tokens": {
    "color.primary": "#0066ff",
    "spacing.sm": 8
  }
}

Authentication: include header Authorization: Bearer <MASTERGO_TOKEN> for protected routes.

Use Cases

• Grounded conversational assistant

  • When an LLM answers design questions about a specific file, call the MCP endpoint to fetch the file DSL and include that structured context in the prompt. This avoids embedding full file blobs and provides precise, queryable context.

• Auto-generate frontend code

  • Fetch component tokens and frames from the DSL to automatically generate React or CSS code that matches spacing, color tokens, and component structure.

• Design change detection and CI

  • Use the resources endpoint from a pipeline to compare DSL snapshots on each commit. Fail builds if core tokens or layout constraints change unexpectedly.

• Asset extraction for rapid prototyping

  • Request specific asset endpoints to retrieve SVGs or images for quick prototyping or for feeding into downstream image processing pipelines.

Concrete example (curl) — fetch DSL for a file:

curl -H "Authorization: Bearer ${MASTERGO_TOKEN}" \
  "http://localhost:8080/mcp/v1/resource/file-123/dsl" \
  -o file-123-dsl.json

Example integrating with an LLM tool (pseudo-Python):

import requests

token = "your_token"
file_id = "file-123"
r = requests.get(
    f"http://localhost:8080/mcp/v1/resource/{file_id}/dsl",
    headers={"Authorization": f"Bearer {token}"}
)
dsl = r.json()

# Pass `dsl` to your LLM as a context object/tool result

Notes and Next Steps

• Check repository for exact route names and any additional configuration flags (rate limits, logging, CORS).
• Production deployments should secure the server with network controls and monitor usage.
• The server is designed to be used as an MCP tool: call it on-demand from your LLM orchestration layer to provide accurate, structured design context to models.

Source and contributions: https://github.com/mastergo-design/mastergo-magic-mcp