Lanhu UI MCP

一个只做一件事的 MCP：以尽量少的 Token，把蓝湖 UI 设计稿高还原地交给编码 Agent。

读取模型

精确元素参数 lanhu_ui_region
蓝湖切图下载 lanhu_ui_assets

两个工具都直接接受包含 pid 和 image_id（或 docId）的蓝湖详情 URL。 设计稿选择、版本同步、区域发现和切图索引均由 MCP 内部完成。

Related MCP server: Framelink MCP for Figma

为什么 Token 少

• 元素和切图强制分页，每页最多 100 项。

• MCP 不返回原始 Schema、完整图层树、远程 URL 清单或图片二进制。

• 区域详情写入 JSON 文件；响应只返回文件路径和图层统计。

• 可按矩形、图层类型、可见性、名称/文本和字段过滤。

• 支持 compact、implementation、raw 三种详情配置。

• 项目索引使用 TTL 缓存；设计稿按蓝湖版本指纹增量更新。

• 切图逐页下载，已经存在的文件不重复下载。

为什么还原度高

每张设计稿会保存：

.lanhu-cache/<project>/designs/<design>/
├── raw-schema.json       # 蓝湖原始图层数据，最终权威来源
├── dds-schema.json       # DDS 精细标注，可用时保存
├── original.png          # 原始视觉基准
├── overview.json         # 画布、版本、统计和路径
├── regions.json          # 可分页区域索引
├── design-tokens.json    # 颜色、字体、字号、圆角、阴影
├── assets.json           # 蓝湖切图索引
├── RESTORE.md            # 针对该设计稿的还原说明
├── queries/              # 过滤后的区域精确规格及区域裁剪图
└── downloaded-slices/    # 已下载切图

区域详情保留精确坐标、尺寸、文本、样式、效果、约束和资源引用。裁剪图会根据设计画布与原图像素的比例自动换算，不假设固定的 1x/2x 倍率。

安装

需要 Python 3.10 及以上版本。

python -m venv .venv

Windows：

.\.venv\Scripts\Activate.ps1
pip install -e .
Copy-Item .env.example .env

macOS/Linux：

source .venv/bin/activate
pip install -e .
cp .env.example .env

登录蓝湖后，从浏览器开发者工具任意一个 lanhuapp.com/api/ 请求中复制完整的 Cookie 请求头，填写到：

LANHU_COOKIE=你的完整Cookie

启动

python -m lanhu_ui_mcp

Codex/其他 MCP 客户端配置示例：

{
  "mcpServers": {
    "lanhu-ui": {
      "command": "D:/mcp/lanhu-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "lanhu_ui_mcp"],
      "cwd": "D:/mcp/lanhu-mcp"
    }
  }
}

两个工具

lanhu_ui_region

返回 URL 指向设计稿的精确元素参数。不传 region_id 时读取完整画布；传入区域 ID 或序号时只读取该区域。参数：

• region_id=可选区域ID或序号

• profile=compact|implementation|raw

• clip={x,y,width,height}

• layer_types=[...]

• visible_only=true

• query=关键词

• fields=id,name,bbox,text,style

• cursor / limit

• crop_image=true

• collapse_slices=true（默认把切图视为原子元素，不返回其内部图层）

• force_refresh=false

精确详情写入 queries/*.json，区域视觉基准写入同名 PNG。

bbox 始终表示设计稿测量坐标，不代表必须使用绝对定位。layout_hint 和 implementation_guidance 会优先推荐正常文档流、Flexbox 或 Grid；只有存在真实重叠、 越界装饰或明确的悬浮/吸顶语义时才建议 absolute、fixed 或 sticky。

• css_hint：面向实现的流式/Flex/Grid CSS 建议，普通元素不再默认包含坐标定位。

• measurement_hint：兼容旧消费者的设计坐标提示，保留原 position:absolute/left/top。

• layout_hint：容器的布局策略、方向、间距、置信度和局部绝对定位子元素。

• implementation_guidance：区域整体实现策略和顶层区块建议。

查询文件的 schema_version 当前为 4。工具参数和原有 bbox/style/source 字段保持兼容， 旧的绝对坐标 CSS 信息迁移到 measurement_hint。

lanhu_ui_assets

按页下载蓝湖“切图”面板中的真实切图（只取最外层导出图层，嵌套预览不会误算为独立切图）。 默认下载 PNG original；支持用 variant=svg 等选择可用变体及 force_refresh， MCP 不回传远程 URL 清单。

元素和切图是两个独立概念。蓝湖内部生成的 ddsImage 图层预览不会作为切图或资源返回。

推荐的 Agent 还原规则

1. 原图用于视觉比对，图层 JSON 中的数值用于实现。

2. 图层值优先于汇总 Token；Token 只用于发现复用关系。

3. 必须使用下载后的真实资源，不用 emoji、猜测图标或近似 CSS 图形替代。

4. 一次只读取当前实现区域，完成后再读取下一区域。

5. 实现后对照区域裁剪图做像素级检查。

开发验证

pip install -e ".[dev]"
pytest