lanhu-design-mcp 0.1.1

Android-first MCP server for reading Lanhu design specs and exporting UI restoration context

蓝湖设计 MCP

v0.1.1 是面向 macOS 的蓝湖设计读取与细粒度 UI 资源导出 MCP 服务器。

功能

• 读取蓝湖设计项目 URL，列出所有设计图
• 分析指定设计稿并返回平台调整后的 UI 结构（Android dp / iOS pt / Web px / 微信 rpx）
• 返回完整设计图与细粒度 Sketch、Figma、Photoshop 切图资源及 Web、iOS、Android 多倍率地址
• 导出包含资产和分析的完整 Agent UI 还原上下文
• 托管 Chrome Profile 自动登录，无需手动复制 Cookie

系统要求

• macOS
• Google Chrome（已安装）
• Python 3.10 及以上

安装

pip install lanhu-design-mcp

首次登录

lanhu-design-mcp auth login
lanhu-design-mcp auth status

登录使用独立的本地 Chrome Profile，首次交互式登录后，后续 MCP 进程自动重用会话。正常设计工具调用不会打开可见浏览器。凭证过期时返回 auth_required 指引，需重新调用 lanhu_auth_login。

lanhu-design-mcp auth logout --confirm

MCP 配置

{
  "mcpServers": {
    "lanhu-design": {
      "command": "lanhu-design-mcp"
    }
  }
}

MCP 工具

工具	参数	说明
lanhu_health_check	无	返回本地配置状态，不访问网络且不暴露 Cookie 值
lanhu_get_designs	url	获取项目的所有设计图列表
lanhu_analyze_design	url, design_name_or_index (可选), target_platform (可选，默认 android)	分析指定设计稿并返回平台调整后的 UI 结构
lanhu_get_design_assets	url, design_name_or_index (可选), target_platform (可选，默认 android)	返回完整设计图与细粒度可下载切图资源
lanhu_export_ui_context	url, design_name_or_index (可选), target_platform (可选，默认 android)	返回包含资产和分析的完整 Agent UI 还原上下文
lanhu_auth_login	无	打开专属 Chrome Profile 进行交互式 Lanhu 登录
lanhu_auth_status	session_id (可选)	报告托管认证状态，不含凭据
lanhu_auth_logout	confirm (可选，默认 false)	登出并删除托管 Profile，需要 confirm=true

细粒度切图

lanhu_get_design_assets 返回整张设计图和设计师声明的细粒度切图。整图始终是 assets 的第一项；其余 kind: "slice" 项可包含：

• remote_url：蓝湖存储的原始 PNG 或 SVG 地址
• svg_url：同时存在 PNG 和 SVG 时的矢量地址
• scale_urls：Web、iOS 和 Android 多倍率 PNG 地址
• logical_size、position_px：逻辑尺寸和画布坐标
• layer_path：源设计中的图层路径
• suggested_local_path：建议的本地保存路径

该工具只返回下载映射，不会向调用方项目写入文件。

{
  "slice_scale": 2,
  "total_assets": 2,
  "total_slices": 1,
  "assets": [
    {"kind": "design_image", "remote_url": "https://..."},
    {
      "kind": "slice",
      "name": "切换",
      "format": "png",
      "remote_url": "https://...",
      "svg_url": "https://...",
      "scale_urls": {"1x": "https://...", "2x": "https://...", "android_xhdpi": "https://..."},
      "logical_size": {"width": 22, "height": 22},
      "position_px": {"x": 1241, "y": 66},
      "layer_path": "切换",
      "suggested_local_path": "assets/lanhu/design-id/切换.png"
    }
  ]
}

平台单位

• Web: px - 蓝湖原始标注单位
• Android: dp = px / 2 - 基于验证的蓝湖规则（1920x1080px → 960x540dp）
• iOS: pt = px / 2 - 默认逻辑点转换
• 微信小程序: rpx = px * 750 / 设计稿宽度 - 基于设计稿宽度的 rpx 转换

托管认证与安全

• 认证信息仅存在于本机托管 Chrome Profile 中，绝不通过 MCP 响应或日志输出
• 启动和健康检查不访问网络，不触发浏览器
• auth_required 错误为结构化响应，不含凭据
• 登出仅删除托管 Profile，不触碰系统 Chrome 默认 Profile

故障排查

状态	说明	处理
auth_required	凭据无效或过期	运行 lanhu-design-mcp auth login
unsupported_platform	仅在 macOS 上支持	使用 macOS 设备
dependency_missing	Playwright Python 库或 Chrome 不可用	pip install --upgrade lanhu-design-mcp 并确认 Chrome 已安装
profile_locked	托管 Profile 被其他进程占用	等待其他进程完成后重试
cancelled	登录窗口在认证完成前关闭	重新运行 lanhu-design-mcp auth login
timed_out	登录窗口 5 分钟内未完成认证	重新运行 lanhu-design-mcp auth login

开发与测试

git clone https://github.com/blantian/lanhu-design-mcp
cd lanhu-design-mcp
uv sync --dev
uv run pytest

v0.1.1 兼容性说明

• 仅支持 macOS；不再支持通过环境变量文件或浏览器默认数据库配置凭据
• MCP 传输固定为 stdio
• Playwright Python 库为必要依赖，但不会自动下载 Chromium

许可证

MIT