Lanhu MCP

面向 AI 编程的蓝湖（Lanhu）设计稿 MCP Server。把设计稿解析成结构化图层树，枚举 iOS / Android / Flutter 客户端开发所需的全部视觉属性与布局关系，并内置切图清单与按需加载——不依赖 DDS「设计图转代码」，任何稿子都能稳定读取。

目录

• 为什么用它

• 快速开始

• 工具一览

• design_structure 属性参考

• 按需加载与超大设计稿

• 架构原则：不依赖 DDS

• 隐私与凭据

• 测试 · 致谢 · License

Related MCP server: lanhu-mcp-server

为什么用它

• 不依赖 DDS，稳定不失败 — 直接清洗蓝湖原始 Sketch / Figma / MasterGo JSON，设计师未开启「设计图转代码」也照常工作。

• 属性齐全，面向客户端 — 坐标/尺寸/字号统一逻辑点 pt，颜色统一干净 rgb()/rgba()；覆盖颜色、渐变、边框、逐角圆角、阴影、模糊、透明度、旋转、裁剪、字体全套，直接对应 iOS 属性。

• 父子 + 兄弟布局 — 嵌套 children 图层树；容器带 padding（子相对父）与 gaps{direction,gap,align}（兄弟方向/间距/对齐），直接映射 UIStackView/LinearLayout，配合绝对坐标完整还原。

• 组件完整优先 — 默认返回完整节点树，不因 token 预算静默裁剪组件；只有显式传入 max_depth、node_id 或 child_offset 才分页。结果带 truncated / childrenTruncated 时，必须继续展开对应组件后再出码。

• 切图不丢 — 图片节点内联 imageUrl，顶层 slices[] 汇总；lanhu_download_design_slices 负责实际下载、校验和失败明细。

快速开始

1. 安装（Python 3.10+）

git clone https://github.com/JmoVxia/lanhu-mcp.git
cd lanhu-mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

2. 配置蓝湖 Cookie

浏览器登录 lanhuapp.com → F12 → Network → 刷新 → 点任意 lanhuapp.com 请求 → Headers → 复制请求头里 Cookie: 的整段值（图文详版见 GET-COOKIE-TUTORIAL.md）。填入 .env：

cp .env.example .env

LANHU_COOKIE=粘贴整段Cookie

Cookie 会过期，失效后按同样方法更新。其余可选项（DATA_DIR / LOG_LEVEL / HTTP_TIMEOUT …）见 .env.example。

3. 接入 MCP 客户端（Claude Code / Cursor 等，stdio）

run-stdio.sh 会自动加载同目录 .env，Cookie 放 .env 即可；也可直接写进 env。

{
  "mcpServers": {
    "lanhu": {
      "command": "/bin/bash",
      "args": ["/绝对路径/lanhu-mcp/run-stdio.sh"],
      "env": { "LANHU_USER_NAME": "yourname", "LANHU_USER_ROLE": "Developer" }
    }
  }
}

4. 使用 — 把设计链接交给 AI：

用 lanhu_get_design_structure 解析这个设计稿并生成 iOS 代码：
https://lanhuapp.com/web/#/item/project/detailDetach?pid=xxx&image_id=xxx

工具一览

design_structure 属性参考

坐标 / 尺寸 / 字号均为逻辑点 pt，颜色为干净 rgb()/rgba()。每个节点带稳定唯一 id（定位句柄）、name、type（container/text/shape/image）。

示例（片段）：

{
  "id": "2:1042", "name": "标题栏", "type": "container",
  "x": 0, "y": 44, "width": 375, "height": 44,
  "color": "rgb(255,255,255)",
  "padding": { "left": 16, "top": 12, "right": 16, "bottom": 12 },
  "gaps": { "direction": "row", "gap": 8, "align": "center" },
  "children": [
    { "id": "2:1043", "name": "返回", "type": "image",
      "imageUrl": "https://.../back.png", "format": "png", "category": "icon",
      "x": 16, "y": 54, "width": 24, "height": 24 },
    { "id": "2:1044", "name": "页面标题", "type": "text", "text": "我的",
      "fontSize": 17, "fontWeight": 500, "color": "rgb(34,34,34)", "align": "center" }
  ]
}

iOS 映射：color→backgroundColor · radius→layer.cornerRadius（逐角用 maskedCorners）· border→layer.borderWidth/borderColor · shadow→layer.shadow* · blur→UIVisualEffectView · opacity→alpha · clip→clipsToBounds · gradient→CAGradientLayer（用 angle/from/to 定方向）· gaps→UIStackView(axis/spacing/alignment)。

完整读取与超大设计稿

目标：组件级属性完整优先；需要省 token 时只能显式分页，不能静默丢字段。

lanhu_get_design_structure 的参数：

机制：完整树始终解析并写盘（savedTo），默认返回完整树；只有显式分页时才返回局部视图。同一版本重复读取/逐分支展开走进程内缓存（json_url 版本键），跳过重复下载与解析；版本变化自动失效。

典型流程：

默认调用 → 完整节点树（每节点带 id）
  → 只有需要控制输出时才用 node_id=<目标容器 id> 展开该分支
    → 若是超宽列表：child_offset=0 / nextChildOffset 逐页翻，直到没有 nextChildOffset

富文本的 `textRuns` 必须整体应用。例如“曝光提升 3 倍”的数字 `3` 应为 `#FC9B40`、16pt、
`Source Han Sans-Medium`、`fontWeight=500`；不要用整句默认样式覆盖局部样式。图层级 `opacity`
与文字颜色是两个独立属性，必须同时处理，例如副文案是 `#66676C` + `opacity=0.5`。

架构原则：不依赖 DDS

这是架构级约束，不是可选项：

• 为什么 — 大量蓝湖稿未开启「设计图转代码」（DDS store_schema_revise）。以 DDS 为主链路的方案遇到这类稿会失败或残缺。

• 怎么做 — 核心链路一律走 /api/project/image 的原始设计 JSON，由 design_structure.py 清洗成图层树。lanhu_get_design_structure / lanhu_get_design_slices 全程零 DDS。

• 边界 — 仅 lanhu_get_ai_analyze_design_result（生成 HTML，可选/遗留）会尝试 DDS，且不可用时自动降级为原始 JSON 的 sketch-HTML，不硬依赖。

隐私与凭据

• 不自动登录、不采集账号信息。 服务只用你手动配置的 LANHU_COOKIE，以你的身份调用蓝湖官方接口。

• Cookie 仅存本地 .env（已被 .gitignore 忽略，不进版本库）；data/、logs/ 同样忽略。

• 内置 Playwright 仅用于跟随蓝湖前端跳转（邀请/detail 链接），复用你提供的 Cookie，不做任何凭据抓取。

测试

./venv/bin/python -m pytest tests/ -q

致谢

• 基于 dsphper/lanhu-mcp（MIT）二次开发。

• 图层树 / 切图分类思路参考 starql/lanhu-mcp；稳定 node_id 寻址、按需加载参考 Framelink Figma MCP。

License

MIT · Copyright (c) 2025 Lanhu MCP Server Contributors · Copyright (c) 2026 JmoVxia