Lanhu MCP Server

Un servidor del Model Context Protocol (MCP) para la plataforma de colaboración de diseño Lanhu (蓝湖).

Permite a los LLM y a los asistentes de codificación con IA inspeccionar directamente mesas de trabajo de diseño, extraer propiedades CSS y jerarquías de capas perfectas a nivel de píxel y descargar recursos exportables, con cero coste adicional de tokens de visión.

English • 简体中文

💡 ¿Por qué Lanhu MCP?

Al implementar diseños de interfaz con agentes de codificación con IA (Claude, Cursor, Copilot, Antigravity, etc.), enviar capturas de pantalla suele resultar en:

• Coste elevado de tokens para los modelos de visión

• Posicionamiento impreciso, márgenes supuestos y colores aproximados

• Tamaños de fuente y alturas de línea alucinados

• Imposibilidad de extraer y descargar automáticamente recursos SVG/imagen

Lanhu MCP Server analiza las especificaciones de diseño estructuradas de Lanhu directamente en árboles de datos tipados:

• ⚡ Cero coste adicional de tokens de visión: Datos JSON estructurados en lugar de capturas pesadas.

• 📐 Precisión perfecta en píxeles: Límites exactos de capa (x, y, width, height), colores (HEX/RGBA), tipografía (fontSize, fontWeight, fontFamily, lineHeight), radio de borde, rellenos, bordes y sombras.

• 🎨 Extracción inteligente de recursos: Descubre automáticamente recursos de corte, proporciona enlaces directos de descarga por CDN y admite conversión sin pérdida a formatos modernos WebP o SVG.

• 🔄 Autenticación resiliente: Gestión de sesiones persistente con renovación automática de tokens en modo headless mediante Playwright.

Related MCP server: Lanhu MCP Server

✨ Características principales

• Exploración de equipos y proyectos: Consulta equipos, archivos de diseño del espacio de trabajo y busca proyectos sin problemas.

• Inspección de mesas de trabajo: Lista mesas de trabajo (screens), previsualiza miniaturas y busca pantallas por nombre.

• Anotaciones profundas de capas: Recupera de forma recursiva árboles de capas completos con atributos de estilo CSS/UI exhaustivos.

• Canal de recursos: Descarga vectores SVG e imágenes de mapa de bits directamente a tu espacio de trabajo local.

• Mantenedor de sesión automático: Un script Playwright headless mantiene viva tu sesión de Lanhu en segundo plano sin tener que iniciar sesión manualmente una y otra vez.

📋 Requisitos

• Python: >= 3.10

• Gestor de paquetes: uv (muy recomendado)

• Cliente MCP: Cursor, Claude Desktop, Claude Code, Antigravity, Windsurf, Cline, Codex, VS Code o cualquier otra herramienta compatible con MCP.

🚀 Inicio rápido

1. Ejecutar con uvx (sin necesidad de instalar)

Puedes ejecutar lanhu-mcp directamente sin clonar el repositorio:

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

2. Ejecutar desde el código fuente

# 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

🔐 Autenticación

Lanhu MCP se conecta a lanhuapp.com mediante cookies de sesión del navegador. Lee desde ~/.lanhu/cookie (permiso de archivo 0600).

Método 1: Acceso automático y renovación (Recomendado)

Ejecuta el script de automatización de Playwright incluido:

uv run scripts/refresh_cookie.py

• Si ya has iniciado sesión: Verifica en segundo plano la sesión, renueva el token y lo escribe en ~/.lanhu/cookie.

• Si la sesión ha caducado: Abre automáticamente una ventana de Chrome para un único acceso (código SMS o contraseña). Una vez autenticado, guarda la sesión y cierra el navegador.

Consejo para tareas programadas: Ejecuta con --headless-only en trabajos cron para renovar periódicamente la cookie sin mostrar ventanas:

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

Método 2: Configuración dinámica mediante la herramienta de chat

Llama directamente a la herramienta MCP desde tu chat de IA:

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

Para obtener tu cookie manualmente:

1. Abre lanhuapp.com en Chrome y abre DevTools (F12).

2. Ve a la pestaña Red y haz clic en cualquier solicitud a lanhuapp.com.

3. En Request Headers, copia la cadena Cookie completa que contiene session y user_token.

Método 3: Variable de entorno

Crea el archivo .env en la raíz del proyecto o pasa la variable LANHU_COOKIE:

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

🛠️ Configuración del cliente MCP

Añade lanhu-mcp a tu cliente MCP favorito:

Ve a Cursor Settings -> MCP -> Añadir nuevo servidor MCP:

• Nombre: lanhu

• Tipo: command

• Comando:

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

O configúralo a través de ~/.cursor/mcp.json:

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

Añádelo en claude_desktop_config.json (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"]
    }
  }
}

Usa la CLI de Claude Code:

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

Añádelo a la configuración de Antigravity o en settings.json:

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

Añádelo a ~/.codeium/windsurf/mcp_config.json:

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

Añádelo a tu cline_mcp_settings.json:

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

Añádelo usando la CLI de Codex:

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

O edita ~/.codex/config.toml:

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

Añádelo mediante la extensión MCP de VS Code o a través de su configuración:

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

🧰 Herramientas disponibles

🧭 Flujo de trabajo típico de programación en pareja con IA

Cuando pidas a tu agente de IA que implemente una UI desde Lanhu:

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

El agente ejecutará de forma autónoma la siguiente cadena:

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]

Ejemplo de invocación de herramienta

# 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"
)

📦 Estructura de datos de las anotaciones

Llamar a lanhu_get_annotations devuelve JSON estructurado:

{
  "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://..."
    }
  ]
}

⚙️ Variables de entorno

⚠️ Aviso legal

Este proyecto es una herramienta de código abierto, independiente, desarrollada con fines educativos, de prueba y de estudio de productividad en IA. Interactúa con Lanhu a través de interfaces web de cuestionario inversa. Por favor, respeta las Condiciones de servicio delanteras de Lanhu al usar esta herramienta. Los desarrolladores no se hacen spasibles de cualquier mal uso.

📄 Licencia

Este proyecto está bajo la Licencia MIT.