Mastergo Magic Mcp

MasterGo Magic MCP

MasterGo Magic MCP は、MasterGo のデザインツールと AI モデルを接続するために設計された、スタンドアロンの MCP（Model Context Protocol）サービスです。AI モデルが MasterGo のデザインファイルから DSL データを直接取得できるようにします。

主な機能

• MasterGo のデザインファイルから DSL データを取得
• npx で直接実行
• 外部依存関係は不要で、Node.js 環境のみ必要

チュートリアル

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

プロンプトの例

MCP サーバーに接続すると、AI チャットで次のプロンプトを使用できます。

SVG を抽出して HTML でプレビューする：

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

デザインをコードに復元する：

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

{domain}、{fileId}、{layerId} を実際の値に置き換えてください。短縮リンクも使用できます。

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

デザインを復元して HTML ファイルとして保存する：

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

短縮リンクも使用できます。

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

使用方法

MG_MCP_TOKEN の取得

1. https://mastergo.com にアクセスします
2. 個人設定を開きます
3. 「Security Settings」タブをクリックします
4. 個人用アクセストークンを探します
5. クリックしてトークンを生成します

権限要件

重要：ツールに接続できても「権限がありません」というエラーが返される場合は、次の条件を確認してください。

1. アカウントのバージョン要件：

   • MasterGo のチーム版以上のアカウントが必要です
   • 個人向け無料版は MCP ツールへのアクセスに対応していません

2. ファイルの場所に関する要件：

   • デザインファイルはチームプロジェクトに配置する必要があります
   • 下書きボックス内のファイルには MCP ツールからアクセスできません

コマンドラインオプション

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]

パラメーター：

• --token=YOUR_TOKEN（必須）：認証に使用する MasterGo API トークン
• --url=API_URL（任意）：API のベース URL。デフォルトは http://localhost:3000 です
• --rule=RULE_NAME（任意）：適用するデザインルールを追加します。複数回指定できます
• --proxy=PROXY_URL（任意）：HTTP/HTTPS プロキシの URL（例：http://127.0.0.1:7890）。HTTPS_PROXY / HTTP_PROXY 環境変数にも対応しています
• --header "Key: Value"（任意）：カスタム HTTP リクエストヘッダー。複数回指定できます。値に空白が含まれる場合は、値を引用符で囲んでください。カスタムヘッダーは、Content-Type や認証トークンを含むデフォルト値を上書きするため、上書きする場合はデフォルトと完全に同じキーを指定してください。JSON オブジェクトとして MG_EXTRA_HEADERS 環境変数からも設定できます（例：MG_EXTRA_HEADERS='{"X-Custom":"val"}'）。CLI のヘッダーは環境変数より優先されます
• --format=FORMAT（任意）：デザインデータツールのデフォルト出力形式です。json（デフォルト）、yaml、tree のいずれかを指定します。ツール呼び出しごとに format パラメーターを明示すると、こちらが優先されます。DEFAULT_FORMAT 環境変数からも設定できます
• --debug（任意）：デバッグモードを有効にして、詳細なエラー情報を表示します
• --no-rule（任意）：デフォルトのルールを無効にします
• --no-prefix（任意）：mcp__ の名前プレフィックスを付けずにツールを登録します（例：mcp__getDsl ではなく getDsl）。一部の MCP クライアント（Grok Build など）は、完全修飾された server__tool 名に __ 区切り文字が複数含まれるツールを黙ってスキップします。サーバーにはすでにプレフィックスが付いているため、mcp__getDsl というツール名は server__mcp__getDsl となり、除外されます。これらのクライアントでは、このフラグを有効にしてください。MG_NO_PREFIX 環境変数（1／true／yes）からも設定できます

パラメーターには、スペース区切りの形式も使用できます。

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

環境変数

コマンドライン引数の代わりに、環境変数を使用することもできます。

• MG_MCP_TOKEN または MASTERGO_API_TOKEN：MasterGo API トークン
• API_BASE_URL：API のベース URL
• RULES：ルールの JSON 配列（例：'["rule1", "rule2"]'）
• DEFAULT_FORMAT：デザインデータツールのデフォルト出力形式（json | yaml | tree）。--format 引数と、ツール呼び出しごとに明示的に指定する format パラメーターが優先されます。
• MG_NO_PREFIX：1／true／yes に設定すると、mcp__ の名前プレフィックスなしでツールを登録します（--no-prefix 引数が優先されます）。
• HTTPS_PROXY / https_proxy / HTTP_PROXY / http_proxy：HTTP(S) プロキシ URL（--proxy 引数が優先されます）

ツールの出力形式

デザインデータツール（mcp__getDesignSections、mcp__getDsl、mcp__getDesignSvgs、mcp__getDesignTexts、mcp__extractSvg、mcp__getMeta）では、ペイロードのシリアル化方法を指定する format パラメーターを任意で指定できます。デフォルトは json です。または、--format / DEFAULT_FORMAT で設定した値になります（コマンドラインオプションを参照）。

値	説明
json	デフォルト。 コンパクトな JSON です。JSON を想定するツールに出力を渡す場合に便利です。以前の動作とバイト単位で同一です。
yaml	一般的なデザインでは、JSON よりトークン数が少なくなります（値が繰り返されるフラットなレイアウトで最も効果があります）。
tree	実験的なコンパクト形式です。構造キー（id、name、type）は各ノード行に位置ベースでエンコードされ、スタイル値は globalVars ブロック内で重複を排除して保持されます。スタイルが多く再利用されるデザインでは、トークン数を最も大きく削減できます。

形式は、AI モデルがツール呼び出しごとに選択します。形式を指定したい場合は、たとえば次のように、プロンプトで希望する形式を伝えてください。

Restore design, use tree format: https://{domain}/file/{fileId}?layer_id={layerId}

注意事項：

• tree は、6 つすべてのツールの応答に適用されます。対象は mcp__getDesignSections（セクション一覧とセクションごとの DSL）、mcp__getDsl、mcp__getDesignSvgs、mcp__getDesignTexts、mcp__extractSvg、mcp__getMeta です。mcp__getMeta は、rules フィールドが Markdown であるため、tree では JSON にフォールバックします（tree レイアウトでは Markdown の見出しやコードブロックが破損するためです）。その他のペイロードは tree 形式で出力されます。形式がまったく不明なデータも JSON にフォールバックするため、データが誤った形式になることはありません。
• mcp__getDesignTexts では、テキストを最大限そのままの状態で保持するために json をおすすめします。ただし、どの形式でもデータを損失なく往復変換できます。
• どの形式でもデータを損失なく往復変換できます。format の値が無効な場合、または省略された場合は、json にフォールバックします。

Smithery Marketplace 経由でのインストール

Smithery は、MCP サービスを簡単にインストールして管理できる MCP サーバーのマーケットプレイスです。

方法 1：Smithery Website 経由でインストール

1. Smithery Marketplace にアクセスします
2. 「接続」または「インストール」ボタンをクリックします
3. MCP クライアント（例：Claude Desktop、Cursor など）を選択します
4. 画面の指示に従って、インストールと設定を完了します

LINGMA の使用方法

VSCode 拡張機能マーケットプレイスで LINGMA を検索し、インストールします。

ログイン後、チャットボックスで［MCP tools］をクリックします。

上部の［MCP Square］をクリックして MCP マーケットプレイスを開き、MasterGo デザインコラボレーションツールを見つけてインストールします。

インストール後、［MCP Servers］に戻り、MCP サービスを編集して、ご自身の MasterGo トークンに置き換えます。

最後に、チャット画面でチャットモードをエージェントモードに切り替えます。

cursor の使用方法

Cursor の MCP 使用ガイドはこちらを参照してください：https://docs.cursor.com/context/model-context-protocol#using-mcp-tools-in-agent

コマンドライン引数または環境変数を使用して、MCP サーバーを設定できます。

オプション 1：コマンドライン引数を使用する

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

オプション 2：環境変数を使用する

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

オプション 3：SSE（Streamable HTTP）を使用する

ローカルへのインストールは不要です。MCP サーバーはリモートで実行され、SSE 経由でアクセスします。

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

cline の使用方法

オプション 1：コマンドライン引数を使用する

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

オプション 2：環境変数を使用する

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

Open Code の使用方法

Open Code では、type: "local" と command 配列を含む mcp 設定ブロックを使用します。

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

プロジェクト構成

src ディレクトリ

src ディレクトリには、MasterGo Magic MCP サービスのコア実装が含まれています。

• index.ts：アプリケーションのエントリーポイントです。MCP サーバーを初期化し、すべてのツールを登録します
• http-util.ts：MasterGo API への HTTP リクエストを処理するユーティリティです
• types.d.ts：プロジェクトの TypeScript 型定義です

src/tools

MCP ツールの実装が含まれています。

• base-tool.ts：すべての MCP ツールの基底クラスです
• get-dsl.ts：MasterGo のデザインファイルから DSL（ドメイン固有言語）データを取得するツールです
• get-component-link.ts：リンクからコンポーネントのドキュメントを取得するツールです
• get-meta.ts：メタデータ情報を取得するツールです
• get-component-workflow.ts：Vue および React コンポーネント向けの、構造化されたコンポーネント開発ワークフローを提供するツールです。ワークフローファイルとコンポーネント仕様を生成します

src/markdown

追加ドキュメントを含む Markdown ファイルが格納されています。

• meta.md：メタデータの構造と使用方法に関するドキュメントです
• component-workflow.md：コンポーネント開発プロセスを構造化するためのガイドとなるワークフロードキュメントです

ローカル開発

1. yarn と yarn build を実行して、依存関係をインストールし、コードをビルドします
2. dist/index.js の絶対パスを確認します
3. ご自身のトークンを使用して、ローカル MCP の設定を追加します

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

4. エディターを再起動して、ローカル MCP が有効になっていることを確認します

正常に実行できたら、ローカルでの実行結果をもとにデバッグできます。変更を加えて、独自の MCP サービスを構築できます。

コードの貢献を歓迎します。MasterGo の MCP サービスを一緒に構築できることを楽しみにしています。

ライセンス

ISC