Moonvy UI MCP

MCP zum Lesen von Moonvy-Designs für die Frontend-Entwicklung. Durch Eingabe einer Projektseiten- oder Designdatei-URL können Seitenliste, Artboard-Größen, Layer-Baum, Knotenstile, Design-Tokens sowie Slice-/Snapshot-/Bildfüll-Ressourcen abgerufen werden.

Dieses Projekt orientiert sich an den Tool-Grenzen von lanhu-mcp, liest die Daten jedoch speziell für Moonvy: Es extrahiert präzise Parameter aus den Moonvy-Designdatendateien (Genome), anstatt Farben, Schriftgrößen und Abstände anhand von Screenshots zu erraten.

Funktionen

moonvy_get_node_style und moonvy_get_ui_spec liefern:

• Absolute Position sowie relativeX / relativeY relativ zum übergeordneten Knoten

• Abstand zur rechten und unteren Kante des übergeordneten Knotens

• Breite/Höhe, Sichtbarkeit, Deckkraft, Beschneidungsstatus

• Verweise auf Volltonfarben, Verläufe und Bildfüllungen

• Schriftart, Schriftgröße, Schriftgewicht, Zeilenhöhe, Zeichenabstand, Textfarbe und Ausrichtung

• Eckenradius, Kontur, Schatten

• Direkt referenzierbares CSS-Eigenschaftenobjekt

Related MCP server: Figma MCP

Datenpfad

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

Projekt-/Verzeichnislisten verwenden POST /v2/anynode/list. Dies sind nicht-öffentliche Schnittstellen, die derzeit von Moonvy Web verwendet werden. Sollte Moonvy die Schnittstellen oder die Genome-Struktur in Zukunft anpassen, muss die Anpassungsschicht synchron aktualisiert werden.

Installation

Erfordert Node.js 20 oder höher.

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

Moonvy-Anmeldetoken konfigurieren

1. Bei Moonvy im Browser anmelden und die zu lesende Moonvy-Seite öffnen.

2. Die Entwicklertools öffnen und zur Konsole wechseln.

3. Ausführen:

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

4. Den kopierten Wert in die .env-Datei dieses Projekts schreiben:

MOONVY_TOKEN=你的本机令牌

Das Token wird nur lokal gespeichert. Es darf nicht in Chats gesendet, in Git committet oder in Frontend-Code geschrieben werden. Die Dienstantworten blenden JWT und Ressourcen-URLs mit Abfrageparametern automatisch aus.

Selbsttest

npm run check
npm test
npm start

npm start ist ein stdio-MCP-Dienst, der normalerweise keine regulären Logs ausgibt und auf eine MCP-Client-Verbindung wartet.

Integration in Codex / ChatGPT-Desktop-App

In den Einstellungen MCP servers -> Add server wählen und den Typ STDIO auswählen:

• Command: node

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

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

Alternativ kann Folgendes in ~/.codex/config.toml oder in eine .codex/config.toml innerhalb eines vertrauenswürdigen Projekts eingefügt werden:

[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

Der Dienst liest MOONVY_TOKEN standardmäßig aus der .env-Datei im cwd. Falls das Token aus lokalen Umgebungsvariablen weitergeleitet werden soll, kann zusätzlich Folgendes hinzugefügt werden:

env_vars = ["MOONVY_TOKEN"]

Nach dem Speichern Codex/Desktop-App neu starten und im Eingabefeld /mcp verwenden, um die Verbindung zu prüfen.

Integration in Cursor / Windsurf / Claude Code

Standard-stdio-MCP-Konfiguration verwenden:

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

Verwendungsreihenfolge für aktuelle Moonvy-Links

Aktueller Link:

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

Er enthält projectId + dirId und zeigt auf einen Ordner statt auf eine konkrete Designdatei. Daher wird Folgendes empfohlen:

1. moonvy_list_pages aufrufen, um die Dateiliste abzurufen.

2. Eine konkrete Design-URL aus den zurückgegebenen Ergebnissen auswählen.

3. moonvy_get_design aufrufen, um die Artboard-Liste anzuzeigen.

4. Für das Ziel-Artboard moonvy_get_ui_spec mit maxDepth=4 und maxNodes=500 aufrufen.

5. Falls ein bestimmtes Element genau geprüft werden soll, zuerst moonvy_list_layers verwenden, um die Knoten-ID zu finden, dann moonvy_get_node_style aufrufen.

6. Icons, Hintergrundbilder oder Seiten-Snapshots mit moonvy_download_asset in das Ressourcenverzeichnis des tatsächlichen Frontend-Projekts herunterladen.

Beispiel-Prompt:

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

Entsprechung zu lanhu-mcp

Die aktuelle Version konzentriert sich auf „Design → Frontend-Implementierung" und übernimmt nicht die Anforderungsdokumentanalyse, das Team-Message-Board und die Feishu-Kollaborationsfunktionen aus dem Lanhu-Projekt.

Sicherheit und Einschränkungen

• Nur Moonvy-Projekte verwenden, auf die Sie ohnehin Zugriffsrechte haben.

• .env ist in .gitignore enthalten; dennoch sollte das Token nicht manuell committet werden.

• moonvy_download_asset erfordert ein absolutes Ausgabeverzeichnis, um zu verhindern, dass Ressourcen versehentlich an unklare Orte geschrieben werden.

• Nach Ablauf des Moonvy-Tokens muss es neu abgerufen werden.

• Dieses Projekt umgeht keine Anmeldung, Projektberechtigungen oder Zugriffskontrollen des Moonvy-Servers.

• Die Felder im Genome können je nach Design-Tool-Version leicht abweichen; der Parser behält gängige Kompatibilitätsfelder bei, dennoch wird eine End-to-End-Abnahme mit einem realen Team-Design empfohlen.

Entwicklung und Tests

Unit-Tests verwenden synthetische Genome und benötigen keine Moonvy-Anmeldedaten:

npm test

End-to-End-Tests mit echten Projekten erfordern ein gültiges 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)