Lanhu MCP Server

Ein Model Context Protocol (MCP)-Server für die Design-Kollaborationsplattform Lanhu (蓝湖).

Ermöglicht LLMs und KI-Code-Assistenten, Design-Zeichenflächen direkt zu inspizieren, pixelgenaue CSS-Eigenschaften und Ebenenhierarchien zu extrahieren und exportierbare Assets herunterzuladen – mit null Vision-Token-Overhead.

English • 简体中文

💡 Warum Lanhu MCP?

Bei der Umsetzung von UI-Designs mit KI-Code-Assistenten (Claude, Cursor, Copilot, Antigravity usw.) führt das Übergeben von Screenshots häufig zu:

• Hohen Token-Kosten für Vision-Modelle

• Ungenauer Positionierung, geratenen Abständen und ungefähren Farben

• Halluzinierten Schriftgrößen und Zeilenhöhen

• Der Unfähigkeit, SVG- und Bild-Assets automatisch zu extrahieren und herunterzuladen

Lanhu MCP Server parst Lanhus strukturierte Design-Spezifikationen direkt in typisierte Datenbäume:

• ⚡ Null Vision-Token-Overhead: Reine JSON-Strukturdaten statt großer, schwerer Screenshots.

• 📐 Pixelgenaue Genauigkeit: Exakte Ebenen-Grenzen (x, y, width, height), Farben (HEX/RGBA), Typografie (fontSize, fontWeight, fontFamily, lineHeight), Eckenradius, Flächenfüllungen, Rahmen und Schatten.

• 🎨 Intelligente Asset-Extraktion: Erkennt Slice-Assets automatisch, stellt direkte CDN-Download-Links bereit und unterstützt die verlustfreie Konvertierung in moderne Formate WebP oder SVG.

• 🔄 Robuste Authentifizierung: Persistente Sitzungsverwaltung mit automatisiertem, automatisiertem Token-Refresh über Playwright.

Related MCP server: Lanhu MCP Server

✨ Hauptfunktionen

• Team & Projekt-Erkundung: Teams, Workspace-Design-Dateien und Projekte abrufen und nahtlos durchsuchen.

• Zeichenflächen-Prüfung: Zeichenflächen (screens) auflisten, Thumbnails anzeigen und Screens nach dem Namen durchsuchen.

• Detaillierte Ebenen-Annotationen: Rekursiv den vollständigen Ebenenbaum mit vollständigen CSS-/UI-Style-Attributen abrufen.

• Asset-Pipeline: SVG-Vektoren und Bitmap-Bilder direkt in den lokalen Arbeitsbereich herunterladen.

• Automatische Sitzungs-Wächterin: Ein headlessly laufendes Playwright-Skript hält die Lanhu-Sitzung im Hintergrund aktiv, ohne wiederholte manuelle Anmeldungen zu benötigen.

📋 Anforderungen

• Python: >= 3.10

• Paketmanager: uv (dringend empfehlenswert)

• MCP-Client: Cursor, Claude Desktop, Claude Code, Antigravity, Windsurf, Cline, Codex, VS Code oder ein anderes MCP-kompatibles Werkzeug.

🚀 Schnellstart

1. Mit uvx ausführen (keine Installation erforderlich)

Du kannst lanhu MCP-Server direkt mit lanhu-mcp ausführen, ohne das Repository zu klonen:

uvx --from git+https://github.com/xinayida/lanhu-mcp.git lanhu-mcp

2. Aus dem Quellcode ausführen

# Clone the repository
git clone https://github.com/xinayida/lanhu-mcp.git
cd lanhu-mcp

# Sync environment and dependencies
uv sync

# Run the server (stdio mode)
uv run lanhu-mcp

🔐 Authentifizierung

Lanhu MCP verbindet sich über Browser-Session-Cookies mit lanhuapp.com. Es liest aus ~/.lanhu/cookie (Dateiberechtigung 0600).

Methode 1: Automatische Anmeldung & Aktualisierung (empfohlen)

Führe das bereitgestellte Playwright-Skript aus:

uv run scripts/refresh_cookie.py

• Bereits angemeldet: Grenzt die Sitzung headless prüft, das Token erneuert und in ~/.lanhu/cookie schreibt.

• Sitzung abgelaufen: Öffnet automatisch ein Chrome-Fenster für die einmalige Anmeldung (SMS-Code oder Passwort). Nach der Authentifizierung wird die Sitzung gespeichert und der Browser geschlossen.

Hinweis für gesteuerte Aufgaben (Scheduled Task): In Cron-Jobs mit --headless-only laufen lassen, um das Cookie regelmäßig zu erneuern, ohne Fenster zu öffnen:

uv run scripts/refresh_cookie.py --headless-only

Methode 2: Dynamisch über Chat-Tool setzen

Rufe das MCP-Tool direkt in deinem KI-Chat auf:

lanhu_set_cookie(cookie="session=...; user_token=...")

So erhältst du das Cookie manuell:

1. Öffne lanhuapp in Chrome und öffne DevTools (F12).

2. Gehe zum Network-Tab und klicke auf eine beliebige Anfrage an lanhuapp.com.

3. Kopiere unter Request Headers den vollständigen Cookie-String, der session und user_token enthält.

Methode 3: Umgebungsvariable

Erstelle .env im Projektverzeichnis und setze also LANHU_COOKIE:

cp .env.example .env
# Edit .env and set LANHU_COOKIE=session=...; user_token=...

🛠️ MCP-Client-Konfiguration

Füge lanhu-mcp zu deinem liebsten MCP-Client hinzu:

Gehe zu Cursor-Settings -> MCP -> New MCP Server hinzufügen:

• Name: `lanhu`

• Typ: `command`

• Command:

  uvx --from git+https://github.com/xinayida/lanhu-mcp.git lanhu-mcp

Oder konfiguriere über ~/.cursor/mcp.json:

{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]
    }
  }
}

Füge zu deiner claude_desktop_config.json hinzu (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]
    }
  }
}

Nutze die Claude Code CLI:

claude mcp add lanhu uvx --from git+https://github.com/xinayida/lanhu-mcp.git lanhu-mcp

Füge das in Sachen Antigravity-Konfiguration oder settings.json ein:

{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]
    }
  }
}

Füge zu ~/.codeium/windsurf/mcp_config.json hinzu:

{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]
    }
  }
}

Füge zu deiner cline_mcp_settings.json hinzu:

{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Füge über den Codex CLI ein:

codex mcp add lanhu uvx "--from" "git+https://github.com/xinayida/lanhu-mcp.git" "lanhu-mcp"

Oder bearbeite ~/.codex/config.toml:

[mcp_servers.lanhu]
command = "uvx"
args = ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]

Füge über die VS Code MCP-Weiterweiterung oder über die Einstellungen hinzu:

{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]
    }
  }
}

🧰 Verfügbare Tools

🧭 Typischer KI-Pair-Programming-Workflow

Wenn du deinen KI-Agenten bittest, eine UI aus Lanhu zu implementieren:

User: "Please implement the checkout screen from our Lanhu project and download necessary icons."

Der Agent führt danach die folgende Kette selbstständig aus:

graph LR
    A[1. lanhu_get_teams] --> B[2. lanhu_get_projects]
    B --> C[3. lanhu_get_screens]
    C --> D[4. lanhu_get_annotations]
    D --> E[5. Generate Code CSS/HTML/React/Flutter]
    D --> F[6. lanhu_download_asset]

Beispielhafter Tool-Aufruf

# 1. Fetch team list
teams = lanhu_get_teams()
team_id = teams[0]["id"]

# 2. Get project list
projects = lanhu_get_projects(team_id=team_id)
project_id = projects[0]["id"]

# 3. Get artboards list
screens = lanhu_get_screens(project_id=project_id, team_id=team_id)
image_id = screens[0]["id"]

# 4. Extract full annotations
annotations = lanhu_get_annotations(
    project_id=project_id,
    image_id=image_id,
    team_id=team_id
)

# 5. Download icons/slices
assets = lanhu_get_assets(project_id=project_id, image_id=image_id, team_id=team_id)
lanhu_download_asset(
    asset_id=assets[0]["id"],
    asset_name=assets[0]["name"],
    download_url=assets[0]["download_url"],
    format="webp" # or "svg"
)

📦 Annotation-Datenstruktur

Ein Aufruf von lanhu_get_annotations` ergibt ein strukturiertes JSON:

{
  "id": "651234567890abcdef",
  "name": "Checkout Page",
  "width": 375.0,
  "height": 812.0,
  "thumbnail_url": "https://...",
  "layers": [
    {
      "id": "layer_01",
      "name": "Submit Button",
      "type": "rect",
      "bounds": { "x": 16.0, "y": 740.0, "width": 343.0, "height": 48.0 },
      "border_radius": 8.0,
      "opacity": 1.0,
      "visible": true,
      "fills": [
        { "type": "color", "color": "#0066FF", "opacity": 1.0 }
      ],
      "shadows": [
        { "x": 0.0, "y": 4.0, "blur": 12.0, "spread": 0.0, "color": "#0066FF33" }
      ],
      "children": [
        {
          "id": "layer_02",
          "name": "Button Label",
          "type": "text",
          "text": "Confirm & Pay",
          "bounds": { "x": 140.0, "y": 754.0, "width": 95.0, "height": 20.0 },
          "font": {
            "size": 16.0,
            "weight": "600",
            "family": "PingFang SC",
            "line_height": 20.0,
            "letter_spacing": 0.0,
            "color": "#FFFFFF",
            "text_align": "center"
          }
        }
      ]
    }
  ],
  "assets": [
    {
      "id": "asset_01:svg",
      "name": "icon_cart",
      "format": "svg",
      "download_url": "https://..."
    }
  ]
}

⚙️ Umgebungsvariablen

⚠️ Haftungsausschluss

Dieses Projekt ist ein unabhängiges Open-Source-Werkzeug, das für Bildungs-, Test- und KI-Produktivitätsforschungszwecke entwickelt wurde. Es interagiert mit Lanhu über reverse-engineered Webschnittstellen. Bei der Nutzung dieses Tools müssen die Nutzungsbedingungen von Lanhu eingehalten werden. Die Autoren sind nicht verantwortlich für Missbrauch.

📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.