Lanhu UI MCP

面向 UI 还原 Agent 的蓝湖 MCP，只暴露两个工具：

• lanhu_ui_region：读取准确元素、文本样式、布局提示和参考裁剪。

• lanhu_ui_assets：下载蓝湖切图并返回独立图层实例、组合顺序和覆盖率。

两个工具都接收包含 pid 与 image_id（或 docId）的蓝湖详情 URL。

安装

需要 Python 3.10 或更高版本。

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
Copy-Item .env.example .env

将登录蓝湖后的完整 Cookie 写入 .env：

LANHU_COOKIE=你的完整Cookie

启动：

python -m lanhu_ui_mcp

Related MCP server: Lanhu MCP Server

工具

lanhu_ui_assets

切图输出支持按需选择显示倍率和格式：

• density=auto|1x|2x|3x|source，默认 auto；未明确指定时，所有满足条件的位图统一输出 2x。

• format=source|png|webp，默认 source。

• 每个实例返回 source_pixel_ratio、available_densities、recommended_density 和实际 pixel_ratio；完整选择原因保存在页面 manifest。

• 可选倍率仍通过 available_densities 完整提供；显式传入倍率时按指定倍率输出。

• 源文件始终保留，派生图按参数缓存；源图不足目标倍率时不放大，而是保留源图并写入 density_policy.fallbacks。SVG 始终按矢量源文件返回。

下载蓝湖切图模式中的真实切图。默认返回最多 20 个切图实例；数量更多时使用 cursor 继续分页。

每个实例包含：

• instance_id

• layer_id

• parent_id

• bbox

• z_index

• path

• role

• render_order

• discovery_source

• discovery_confidence

相同远程图片只保存一份本地文件，但每个图层实例都会独立返回，不会按 URL 合并。 存在蓝湖导出标记时 discovery_source=lanhu_export_metadata；缺少导出标记时才使用 embedded_asset_fallback，并明确返回降级警告。

响应中的 composition.backgrounds 标明背景切图必须叠加的子切图， composition.render_sequence 给出完整渲染顺序。

可通过 used_assets 传入页面实际使用的 layer_id 或本地路径，返回：

• pending_instance_count：仍未分页下载的实例数量，不代表下载失败。

• download_failures：当前页真实下载失败的资源摘要。

• implementation_usage：传入 used_assets 后才计算的实现使用覆盖率。

lanhu_ui_region

返回元素参数和实现建议。常用参数：

• profile=compact|implementation|raw

• collapse_slices=true

• visible_only=true

• crop_image=true

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

• query=关键词

• cursor / limit

首次查询完整画布时，响应包含 region_overview：

• top_level_regions：顶级区域摘要及可继续查询的 region_id。

• text_summary：重要文本样本和坐标。

• risk_warnings：分页遗漏、背景叠加和定位风险。

详细图层通过 region_id、cursor 和 limit 分页查询。

bbox 是设计测量数据，不表示必须绝对定位。实现页面时优先使用正常文档流、 Flexbox 或 Grid；只有 layout_hint 明确建议时才使用 absolute、fixed 或 sticky。 表单、列表和纵向区块会附带 padding、gap、margin、对齐方式与 child_order。

切图内部图层默认折叠，避免重复实现。覆盖数据分为：

• asset_coverage：当前区域切图实例的检索情况。

• retrieval_coverage：切图、普通文本、形状和覆盖层的查询情况。

• implementation_coverage：只有下游提供实际实现证据后才能计算；区域读取默认 返回 checked: false。

完整遗漏列表只写入查询 JSON。MCP 响应仅返回数量和最多 5 个样例，避免分页后 又通过覆盖率字段把全部图层塞回上下文。

背景或大切图通过 required_non_asset_layers 标明仍需单独实现的文本、形状和覆盖层。

文本图层在 implementation/raw profile 中返回 text_spec：

• 可实现的段落与换行。

• 字体、字号、字重、行高、字间距、颜色和对齐方式。

• 文本容器宽高、换行和空白处理建议。

PNG/WebP 等栅格切图返回像素坐标 alpha_bbox 和设计坐标 visual_bbox； SVG 返回基于 viewBox 的 visual_bbox，用于区分透明边缘、阴影和设计图层 bbox。

通用语义与布局推断

• 不使用页面文案或行业词汇推断表单、列表、背景、fixed 或 sticky。

• 优先读取 role、semanticRole、layoutRole、componentType、 controlType、position 等图层元数据。

• 元数据缺失时，仅根据包含、重叠、对齐、间距和重复尺寸等几何结构推断。

• fixed/sticky 必须有显式元数据；无法确认时保守返回普通流式布局或 unknown。

• form 由显式角色或通用控件组合识别，list 由显式角色或重复结构识别， 与中文、英文及具体业务内容无关。

• 普通兄弟元素的几何重叠不会直接触发 absolute，而是写入 ignored_overlaps，包含双方 layer ID、重叠率、交集 bbox 和 z-index。

• 有序兄弟重叠继续使用 Flow/Flex；child_margins.overlap_before 给出重叠量， 下游仅在视觉还原需要时使用负 margin 或 transform。

• 只有显式 absolute/fixed/sticky、装饰覆盖层或越界装饰元素才输出定位建议； 实际定位元素通过 overlap_with 和 overlap_evidence 标明关联对象。

参考裁剪

区域截图统一标记为：

{
  "role": "reference_crop",
  "formal_page_resource": false,
  "usage": "visual comparison only"
}

reference_crop 仅用于视觉对比，禁止作为正式页面图片。兼容字段 paths.crop 暂时保留，并与 paths.reference_crop 指向同一文件。

数据与兼容性

当前 schema_version 为 8。

• JSON 使用严格 UTF-8 编码，不转义中文。

• 非有限浮点数会转换为 null，确保 JSON 合法。

• 读取时兼容 UTF-8 BOM。

• lanhu_ui_region 写入前执行 UTF-8、严格 JSON round-trip 和结构 Schema 校验， 并在 validation 中返回结果。

• 两个工具名称和调用参数继续可用。

• v7 调整了覆盖率响应：visible_content_coverage 改为 retrieval_coverage，implemented/unimplemented 改为 returned/missing；消费方应检查 schema_version。

• 旧缓存会因 Schema 版本变化自动重新生成。

• measurement_hint 保留旧版绝对坐标，css_hint 面向实际布局实现。

内部按职责拆分：

• schema_adapter.py：将蓝湖/Sketch Schema 转为统一图层记录。

• region_pipeline.py：区域过滤、布局分析和检索覆盖率。

• asset_pipeline.py：切图分页、下载、去重、可见边界和使用校验。

• contracts.py：Schema v7、UTF-8、JSON、bbox、ID 和渲染顺序校验。

• projections.py：限制 MCP 响应体积；完整数据保留在本地 JSON。

缓存目录结构：

.lanhu-cache/<project>/designs/<design>/
├── raw-schema.json
├── original.png
├── overview.json
├── regions.json
├── design-tokens.json
├── assets.json
├── queries/
└── downloaded-slices/

验证

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check lanhu_ui_mcp tests
.\.venv\Scripts\python.exe -m mypy lanhu_ui_mcp
.\.venv\Scripts\python.exe -m compileall -q lanhu_ui_mcp tests