Metadata-Version: 2.4
Name: lanhu-design-mcp
Version: 0.1.1
Summary: Android-first MCP server for reading Lanhu design specs and exporting UI restoration context
Author: lantian
License: MIT
Project-URL: Homepage, https://github.com/blantian/lanhu-design-mcp
Project-URL: Repository, https://github.com/blantian/lanhu-design-mcp
Project-URL: Issues, https://github.com/blantian/lanhu-design-mcp/issues
Keywords: lanhu,design,ui,android,mcp,design-to-code
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: MacOS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: playwright>=1.50.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Dynamic: license-file

<!-- mcp-name: io.github.blantian/lanhu-design-mcp -->

# 蓝湖设计 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 及以上

## 安装

```bash
pip install lanhu-design-mcp
```

## 首次登录

```bash
lanhu-design-mcp auth login
lanhu-design-mcp auth status
```

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

```bash
lanhu-design-mcp auth logout --confirm
```

## MCP 配置

```json
{
  "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`：建议的本地保存路径

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

```json
{
  "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` |

## 开发与测试

```bash
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
