Moonvy UI MCP

フロントエンド開発向けの Moonvy（月维）デザイン稿読み取り MCP。プロジェクトページまたはデザインファイルの URL を入力すると、ページ一覧、フレームサイズ、レイヤーツリー、ノードスタイル、デザイントークン、および書き出し/スナップショット/画像フィルなどのリソースを取得できます。

本プロジェクトは lanhu-mcp のツール境界を参考にしていますが、データ読み取りは Moonvy 向けです。Moonvy のデザインデータファイル（Genome）から正確なパラメータを抽出するため、スクリーンショットから色・フォントサイズ・間隔を推測するのではありません。

できること

moonvy_get_node_style と moonvy_get_ui_spec は以下を返します：

• 絶対位置、および親ノードに対する relativeX / relativeY

• 親ノードの右端・下端までの距離

• 幅高、可視性、不透明度、クリップ状態

• 単色、グラデーション、画像フィルの参照

• フォント、フォントサイズ、フォントウェイト、行高、文字間隔、文字色、配置

• 角丸、ストローク、シャドウ

• そのまま参照できる CSS プロパティオブジェクト

Related MCP server: Figma MCP

データフロー

Moonvy URL
  -> projectId / dirId / fileId
  -> POST https://global-api.moonvy.com/v2/anynode/get
  -> files.genome.url
  -> 下载并解压 Genome JSON
  -> 解析图层、样式、Token、资源
  -> MCP JSON 响应

プロジェクト/ディレクトリの一覧は POST /v2/anynode/list を使用します。これらは Moonvy Web が現在使用している非公開インターフェースであり、将来 Moonvy がインターフェースや Genome 構造を変更した場合は、アダプタ層を同期して更新する必要があります。

インストール

Node.js 20 以降が必要です。

cd C:\path\to\moonvy-ui-mcp
npm install
Copy-Item .env.example .env

Moonvy ログイントークンの設定

1. ブラウザで Moonvy にログインし、読み取りたい Moonvy ページを開きます。

2. 開発者ツールの Console を開きます。

3. 以下を実行します：

copy(window.app?.api?.$options?.token)

4. コピーした値を本プロジェクトの .env に書き込みます：

MOONVY_TOKEN=你的本机令牌

トークンはローカルのみに保存し、チャットに送信したり、Git にコミットしたり、フロントエンドコードに書き込んだりしないでください。サービスレスポンスは JWT とクエリパラメータ付きのリソース URL を自動的に隠します。

セルフチェック

npm run check
npm test
npm start

npm start は stdio MCP サービスです。通常時は通常のログを出力せず、MCP クライアントの接続を待機します。

Codex / ChatGPT デスクトップアプリへの接続

設定で MCP servers -> Add server を選択し、タイプは STDIO を選択します：

• Command：node

• Arguments：C:\path\to\moonvy-ui-mcp\src\server.js

• Working directory：C:\path\to\moonvy-ui-mcp

また、以下を ~/.codex/config.toml または信頼できるプロジェクト内の .codex/config.toml に追加することもできます：

[mcp_servers.moonvy]
command = "node"
args = ["C:/path/to/moonvy-ui-mcp/src/server.js"]
cwd = "C:/path/to/moonvy-ui-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 180

サービスはデフォルトで cwd 配下の .env から MOONVY_TOKEN を読み取ります。ローカルマシンの環境変数から転送したい場合は、以下も追加できます：

env_vars = ["MOONVY_TOKEN"]

保存後、Codex/デスクトップアプリを再起動し、入力ボックスで /mcp を使用して接続を確認します。

Cursor / Windsurf / Claude Code への接続

標準の stdio MCP 設定を使用します：

{
  "mcpServers": {
    "moonvy": {
      "command": "node",
      "args": ["C:/path/to/moonvy-ui-mcp/src/server.js"],
      "cwd": "C:/path/to/moonvy-ui-mcp"
    }
  }
}

現在の Moonvy リンクでの使用順序

現在のリンク：

https://moonvy.com/project/89f75621-a0e7-4122-b9ee-b6b703e1c826/cf67c54c-8e2b-4809-9e4d-fc6512d0e0be

これには projectId + dirId が含まれており、特定のデザインファイルではなくフォルダを指しているため、以下を推奨します：

1. moonvy_list_pages を呼び出してファイル一覧を取得します。

2. 返された結果から具体的なデザイン URL を選択します。

3. moonvy_get_design を呼び出してフレーム一覧を確認します。

4. 対象フレームに対して moonvy_get_ui_spec を呼び出し、最初は maxDepth=4、maxNodes=500 を使用します。

5. 特定の要素を正確に確認する必要がある場合は、まず moonvy_list_layers でノード ID を探し、次に moonvy_get_node_style を呼び出します。

6. アイコン、背景画像、ページスナップショットは moonvy_download_asset で実際のフロントエンドプロジェクトのリソースディレクトリにダウンロードします。

プロンプトの例：

使用 Moonvy MCP 列出这个项目目录里的设计文件。找到“新增学生”页面后，
读取它的 UI spec，保留原始颜色、字号、间距和圆角，并把需要的切图下载到
C:/work/school-web/src/assets/moonvy。

lanhu-mcp との対応関係

現在のバージョンは「デザイン稿 -> フロントエンド実装」に特化しており、藍湖プロジェクトの要件ドキュメント分析、チーム掲示板、飛書コラボレーション機能は複製していません。

セキュリティと制限

• 元々アクセス権限のある Moonvy プロジェクトのみを使用してください。

• .env は .gitignore に追加済みです。それでもトークンを手動でコミットしないようにしてください。

• moonvy_download_asset は絶対出力ディレクトリを要求し、リソースが不明確な場所に誤って書き込まれるのを防ぎます。

• Moonvy トークンが期限切れになった場合は再取得が必要です。

• 本プロジェクトはログイン、プロジェクト権限、または Moonvy サーバー側のアクセス制御を迂回しません。

• Genome 内のデザインツールバージョンによってフィールドが完全に一致しない場合があります。パーサーは一般的な互換フィールドを保持していますが、実際のチームのデザイン稿でエンドツーエンドの受け入れテストを行うことを推奨します。

開発とテスト

ユニットテストは合成 Genome を使用するため、Moonvy の認証情報は不要です：

npm test

実プロジェクトのエンドツーエンドテストには有効な MOONVY_TOKEN が必要です：

1. moonvy_list_pages(文件夹 URL)
2. moonvy_get_design(设计文件 URL)
3. moonvy_get_ui_spec(设计文件 URL)
4. moonvy_get_node_style(设计文件 URL, 节点 ID)