<div align="center">

# 蓝湖 MCP Server (Lanhu MCP)

**专为 [蓝湖 (Lanhu)](https://lanhuapp.com) 设计协作平台打造的 Model Context Protocol (MCP) 服务端。**

让 AI 编码助手（Claude、Cursor、Antigravity、Windsurf 等）能够直接读取蓝湖设计图的完整图层树、获取像素级精确的 CSS 标注样式，并自动下载切图图标——**全程无需消耗视觉 Vision Token**。

[简体中文](README.md) • [English](README_en.md)

<p align="center">
  <a href="https://github.com/xinayida/lanhu-mcp/releases"><img src="https://img.shields.io/github/v/release/xinayida/lanhu-mcp?style=flat-square&color=blue" alt="Release"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square" alt="Python 3.10+"></a>
  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-Protocol%202.0-orange?style=flat-square" alt="MCP"></a>
  <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/badge/uv-supported-purple?style=flat-square" alt="uv"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License"></a>
</p>

</div>

---

## 💡 为什么需要 Lanhu MCP？

在日常使用 AI 辅助编写前端或移动端界面（React、Vue、Flutter、SwiftUI 等）时，通常依赖向大模型发送设计图截图。然而这种方式存在明显痛点：
- **Token 消耗巨大**：高清截图会严重消耗模型的 Vision 上下文窗口；
- **尺寸与颜色靠猜**：模型对间距、边距、圆角与色值的识别存在幻觉和偏差；
- **切图与图标无法自动化**：模型无法直接将设计稿中的 SVG 图标或图片切图导出到本地工程。

**Lanhu MCP Server** 通过逆向解析蓝湖 Web 端数据协议，直接为大模型提供结构化的设计标注树：

- ⚡ **零视觉 Token 消耗**：纯 JSON 结构化数据传输，极大节省上下文空间与响应延迟。
- 📐 **像素级绝对精确**：图层绝对坐标与尺寸（`x`, `y`, `width`, `height`）、精准色值（HEX/RGBA、设计规范色板名称 `color_name`）、线性与径向渐变（`gradient`）、字体排版（字号、粗细、行高、字距、复合文字分段 `spans`）、四角独立圆角（`border_radii`）、边框、阴影以及开箱即用的标准 `css` 样式字典全部精确提取。
- 🎨 **切图自动提取与 WebP 转换**：自动识别导出切图并提供直链下载，位图切图默认自动转为现代高效的 **WebP** 格式，矢量图标支持原生 **SVG** 导出，免去手动切图和臃肿的 PNG。
- 🔄 **会话全自动化管理**：内置基于 Playwright 的无头 Cookie 自动续期脚本，告别频繁手动登录。

---

## ✨ 核心特性

- **团队与项目浏览**：获取当前账号所在的团队列表、工作台设计项目，支持关键词搜索。
- **画板/设计图检索**：获取项目下的所有画板（Screen）信息、缩略图与尺寸信息。
- **深度图层标注解析**：递归解析完整图层树，还原组件嵌套层级，提供现成 CSS 属性、渐变色与多段文本样式。
- **资源直下通道**：一键下载设计图中的 SVG 矢量图与位图切图至本地指定目录，位图自动转为 WebP 格式。
- **持久化认证续期**：集成浏览器会话持久化与自动续期机制，稳定无感运行。

---

## 📋 环境要求

- **Python**：`>= 3.10`
- **包管理器**：推荐使用 [uv](https://docs.astral.sh/uv/)（快速且免配置）
- **MCP 客户端**：Cursor、Claude Desktop、Claude Code、Antigravity、Windsurf、Cline、Codex、VS Code 等支持 MCP 协议的工具。

---

## 🚀 快速上手

### 方式一：使用 `uvx` 一键运行（推荐，免克隆）

无需手动下载仓库，直接通过 `uvx` 即开即用：

```bash
uvx --from git+https://github.com/xinayida/lanhu-mcp.git lanhu-mcp
```

### 方式二：从源码克隆运行

```bash
# 克隆仓库
git clone https://github.com/xinayida/lanhu-mcp.git
cd lanhu-mcp

# 同步安装虚拟环境与依赖
uv sync

# 启动 MCP 服务端（stdio 模式）
uv run lanhu-mcp
```

---

## 🔐 认证配置

Lanhu MCP 通过 Cookie 访问 `lanhuapp.com`。Cookie 默认安全存储于 `~/.lanhu/cookie`（文件权限 `0600`）。

### 方式一：自动化登录与续期（最省心推荐）

运行项目内置的 Playwright 自动化续期脚本：

```bash
uv run scripts/refresh_cookie.py
```

- **已登录状态**：在后台以无头模式静默访问蓝湖，刷新 Session 并自动更新 `~/.lanhu/cookie`。
- **登录态过期**：自动唤起 Chrome 窗口，等待用户进行一次登录（短信验证码或密码），登录成功后自动保存 Cookie 并关闭浏览器。

> **定时任务提示**：可通过 `--headless-only` 参数配置到系统的 Cron 定时任务中定期静默刷新：
> ```bash
> uv run scripts/refresh_cookie.py --headless-only
> ```

### 方式二：在对话中通过工具动态设置

在 AI 对话中直接调用 MCP 工具传入 Cookie：

```python
lanhu_set_cookie(cookie="session=...; user_token=...")
```

*手动获取 Cookie 方法*：
1. 在浏览器登录 [lanhuapp.com](https://lanhuapp.com)，按 `F12` 打开开发者工具。
2. 切换至 **Network (网络)** 面板，点击任意发往 `lanhuapp.com` 的请求。
3. 在 **Request Headers (请求标头)** 中复制包含 `session` 和 `user_token` 的完整 `Cookie` 内容。

### 方式三：通过环境变量配置

在项目根目录创建 `.env` 文件或配置环境变量 `LANHU_COOKIE`：

```bash
cp .env.example .env
# 编辑 .env 文件，填写 LANHU_COOKIE=session=...; user_token=...
```

---

## 🛠️ MCP 客户端配置指南

选择您常用的 AI 编辑器/客户端进行一键接入：

<details open>
<summary><b>Cursor</b></summary>

打开 **Cursor Settings** -> **MCP** -> **Add new MCP Server**：
- **Name**: `lanhu`
- **Type**: `command`
- **Command**:
  ```bash
  uvx --from git+https://github.com/xinayida/lanhu-mcp.git lanhu-mcp
  ```

或直接编辑配置文件 `~/.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]
    }
  }
}
```

</details>

<details>
<summary><b>Claude Desktop</b></summary>

编辑 `claude_desktop_config.json`（macOS 路径：`~/Library/Application Support/Claude/claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]
    }
  }
}
```

</details>

<details>
<summary><b>Claude Code</b></summary>

使用 Claude Code 命令行直接添加：

```bash
claude mcp add lanhu uvx --from git+https://github.com/xinayida/lanhu-mcp.git lanhu-mcp
```

</details>

<details>
<summary><b>Antigravity / Gemini CLI</b></summary>

在 Antigravity 插件配置或 `settings.json` 中添加：

```json
{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]
    }
  }
}
```

</details>

<details>
<summary><b>Windsurf</b></summary>

在 `~/.codeium/windsurf/mcp_config.json` 中添加：

```json
{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]
    }
  }
}
```

</details>

<details>
<summary><b>Cline / Roo Code</b></summary>

在 `cline_mcp_settings.json` 中配置：

```json
{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

</details>

<details>
<summary><b>Codex</b></summary>

使用 Codex CLI 命令添加：

```bash
codex mcp add lanhu uvx "--from" "git+https://github.com/xinayida/lanhu-mcp.git" "lanhu-mcp"
```

或在 `~/.codex/config.toml` 中配置：

```toml
[mcp_servers.lanhu]
command = "uvx"
args = ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]
```

</details>

<details>
<summary><b>VS Code / Copilot</b></summary>

在 VS Code 设置或 `.vscode/mcp.json` 中添加：

```json
{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]
    }
  }
}
```

</details>

---

## 🧰 工具清单与参数

| 工具名称 | 功能描述 | 核心参数 |
|:---|:---|:---|
| `lanhu_inspect_url` | **⚡ 极速统一入口**：智能解析任意蓝湖 URL，自动识别画板列表、单图详情、原型或分享链接 | `url`: 蓝湖页面链接 |
| `lanhu_set_cookie` | 设置认证 Cookie 并持久化保存到 `~/.lanhu/cookie` | `cookie`: 包含 `session` 和 `user_token` 的 Cookie 字符串 |
| `lanhu_get_teams` | 获取当前用户的团队列表（兼具认证连通性检测） | *(无)* |
| `lanhu_get_projects` | 获取指定团队下的所有设计项目 | `team_id`: 团队 ID |
| `lanhu_search_projects` | 按名称关键词搜索团队内的项目 | `team_id`: 团队 ID, `keyword`: 搜索关键词 |
| `lanhu_get_screens` | 获取指定项目下的画板列表（含尺寸和缩略图），支持直接传入 `url` | `project_id` / `url`, `team_id` (可选) |
| `lanhu_search_images` | 按名称关键词搜索画板/设计图 | `project_id`: 项目 ID, `team_id`: 团队 ID (可选), `keyword`: 搜索关键词 |
| `lanhu_get_annotations` | **⭐ 核心工具**：获取单张设计图的完整图层树与 CSS 标注数据，支持直接传入单图 `url` | `project_id` & `image_id` 或 `url`, `team_id` (可选) |
| `lanhu_get_assets` | 获取画板中所有可导出的切图/图标直链资源列表，支持直接传入 `url` | `project_id` & `image_id` 或 `url`, `team_id` (可选) |
| `lanhu_download_asset` | 下载切图到本地磁盘（位图自动转 WebP，矢量图保存为 SVG，具超大图安全防护） | `asset_id`, `asset_name`, `download_url`, `format`, `save_dir` |
| `lanhu_batch_export_assets` | 批量导出画板中所有切图资源，并在目标目录自动生成 `manifest.json` 清单 | `project_id` & `image_id` 或 `url`, `save_dir` (可选) |
| `lanhu_get_design_tokens` | **🎨 设计系统**：提取色板、字号、字重、圆角、阴影等全局规范 Token，支持导出 CSS/Tailwind/W3C 规范 | `project_id` / `url`, `image_id` (可选), `format` (`json`/`css`/`tailwind`/`w3c`) |
| `lanhu_get_layout_skeleton` | **📐 布局推断**：自动将绝对定位图层树转为现代 Flexbox 流式骨架树与 Tailwind 类名 | `project_id` & `image_id` 或 `url` |
| `lanhu_list_product_documents` | 获取项目下的所有产品文档/Axure 原型文档列表，支持直接传入 `url` | `project_id` 或 `url`, `team_id` (可选) |
| `lanhu_get_pages` | 获取 Axure 原型的完整页面目录树 (Sitemap) 与清单，支持直接传入 `url` | `project_id` & `doc_id` 或 `url`, `team_id` (可选) |
| `lanhu_get_page_content` | 提取 Axure 页面的需求说明文本、黄色便签 (annotations) 与备注 (notes) | `page_name`, `project_id` & `doc_id` 或 `url`, `team_id` (可选) |

---

## 🧭 典型 AI 编程工作流

### 方式一：直接提供蓝湖链接（最省心推荐 🚀）

直接将浏览器地址栏里的蓝湖链接发给 AI：

```text
用户：“请帮我根据这个蓝湖画板实现登录页面：https://lanhuapp.com/web/#/item/project/detailDetach?pid=xxx&image_id=yyy”
```

AI 助手将直接调用 `lanhu_inspect_url` 或 `lanhu_get_annotations(url=...)`，**一步完成图层树与样式提取**，无需多轮往返！

### 方式二：传统按项目逐步探索

```mermaid
graph LR
    A[1. lanhu_get_teams] --> B[2. lanhu_get_projects]
    B --> C[3. lanhu_get_screens]
    C --> D[4. lanhu_get_annotations]
    D --> E[5. 生成 CSS/HTML/React/Flutter 代码]
    D --> F[6. lanhu_download_asset 下载切图]
```

### 代码调用示例

```python
# 极速单入口方式：
result = lanhu_inspect_url(url="https://lanhuapp.com/web/#/item/project/detailDetach?pid=xxx&image_id=yyy")

# 或传统分步方式：
# 1. 验证认证并获取团队
teams = lanhu_get_teams()
team_id = teams[0]["id"]

# 2. 获取项目列表
projects = lanhu_get_projects(team_id=team_id)
project_id = projects[0]["id"]

# 3. 获取画板列表
screens = lanhu_get_screens(project_id=project_id, team_id=team_id)
image_id = screens[0]["id"]

# 4. 获取核心图层标注与样式数据
annotations = lanhu_get_annotations(
    project_id=project_id,
    image_id=image_id,
    team_id=team_id
)

# 5. 下载页面切图/图标（位图默认保存为 webp，矢量图保存为 svg）
assets = lanhu_get_assets(project_id=project_id, image_id=image_id, team_id=team_id)
lanhu_download_asset(
    asset_id=assets[0]["id"],
    asset_name=assets[0]["name"],
    download_url=assets[0]["download_url"],
    format="webp" # 亦可指定 "svg"
)
```

---

## 📦 标注数据结构示例

调用 `lanhu_get_annotations` 返回的完整结构化 JSON：

```json
{
  "id": "651234567890abcdef",
  "name": "收银台",
  "width": 375.0,
  "height": 812.0,
  "thumbnail_url": "https://...",
  "layers": [
    {
      "id": "layer_01",
      "name": "提交按钮",
      "type": "rect",
      "bounds": { "x": 16.0, "y": 740.0, "width": 343.0, "height": 48.0 },
      "border_radius": 12.0,
      "opacity": 1.0,
      "visible": true,
      "fills": [
        {
          "type": "gradient",
          "gradient": {
            "type": "linear",
            "angle": 180.0,
            "css": "linear-gradient(180deg, rgba(69,140,255,1) 0%, rgba(40,40,55,1) 100%)",
            "stops": [
              { "position": 0.0, "color": "#458CFF", "color_rgba": "rgba(69,140,255,1)" },
              { "position": 1.0, "color": "#282837", "color_rgba": "rgba(40,40,55,1)" }
            ]
          }
        }
      ],
      "borders": [
        {
          "width": 1.0,
          "style": "solid",
          "position": "center",
          "color": "#00C18C",
          "color_rgba": "rgba(0,193,140,1)",
          "color_name": "Brand/Primary",
          "css": "1.0px solid rgba(0,193,140,1)"
        }
      ],
      "css": {
        "width": "343px",
        "height": "48px",
        "background": "linear-gradient(180deg, rgba(69,140,255,1) 0%, rgba(40,40,55,1) 100%)",
        "border": "1.0px solid rgba(0,193,140,1)",
        "border-radius": "12px"
      },
      "children": [
        {
          "id": "layer_02",
          "name": "PriceText",
          "type": "text",
          "text": "7.2km",
          "bounds": { "x": 130.0, "y": 754.0, "width": 61.0, "height": 40.0 },
          "font": {
            "size": 32.0,
            "weight": "700",
            "family": "DINAlternate-Bold",
            "line_height": 40.0,
            "color": "#E9E6F8",
            "color_rgba": "rgba(233,230,248,1)",
            "spans": [
              { "text": "7.2", "size": 32.0, "weight": "700", "family": "DINAlternate-Bold", "color": "#E9E6F8" },
              { "text": "km", "size": 16.0, "weight": "700", "family": "DINAlternate-Bold", "color": "#E9E6F8" }
            ]
          },
          "css": {
            "width": "61px",
            "height": "40px",
            "font-family": "DINAlternate-Bold",
            "font-size": "32px",
            "font-weight": "700",
            "line-height": "40px",
            "color": "#E9E6F8"
          }
        }
      ]
    }
  ],
  "assets": [
    {
      "id": "asset_01:svg",
      "name": "icon_alipay",
      "format": "svg",
      "download_url": "https://..."
    },
    {
      "id": "asset_02:webp",
      "name": "banner_bg",
      "format": "webp",
      "download_url": "https://..."
    }
  ]
}
```

### 方式三：Axure 原型与 PRD 需求文档分析

除了 UI 标注外，蓝湖托管的 Axure 原型和产品文档（PRD）也是 AI 理解业务逻辑与交互需求的关键信息源。本工具采用**纯轻量 API 逆向提取**（无需任何浏览器进程），秒级提取原型目录结构与业务说明：

```mermaid
graph LR
    A[1. lanhu_list_product_documents] --> B[2. lanhu_get_pages]
    B --> C[3. lanhu_get_page_content]
    C --> D[4. AI 生成业务逻辑 / 交互状态 / 单元测试]
```

#### 原型分析调用示例

```python
# 1. 快捷单入口：直接查看原型文档概览（自动拉取页面目录）
result = lanhu_inspect_url("https://lanhuapp.com/web/#/item/project/productDoc?pid=xxx&doc_id=yyy")

# 2. 或手动提取单页面需求文本与交互便签
page = lanhu_get_page_content(
    url="https://lanhuapp.com/web/#/item/project/productDoc?pid=xxx&doc_id=yyy",
    page_name="登录页"
)
print(page["text_content"])   # 提取页面所有 DOM 文本与业务规则
print(page["annotations"])    # 提取黄色交互便签与备注
```

#### 原型页面数据返回示例 (`LanhuAxurePage`)

```json
{
  "id": "u0",
  "name": "登录页",
  "filename": "登录页.html",
  "type": "Wireframe",
  "folder": "用户中心",
  "path": "用户中心/登录页",
  "text_content": [
    "登录即代表同意用户协议与隐私条款",
    "用户名规则：支持手机号/邮箱，4-20位字符",
    "密码规则：6-20位字母数字组合"
  ],
  "annotations": [
    {
      "label": "登录按钮",
      "note": "未勾选协议时置灰禁用，勾选后变为高亮；点击后提交并展示 loading",
      "owner_id": "u12"
    }
  ],
  "notes": {
    "页面状态": "提供验证码登录与密码登录两种切换形态"
  }
}
```

### 方式四：设计系统 Tokens 与智能响应式布局骨架生成

无需人工从大量绝对坐标图层中寻找规律，通过内置的算法引擎一键完成**规范提取**与**代码骨架转换**：

```mermaid
graph LR
    A[蓝湖画板图层] --> B[lanhu_get_design_tokens]
    A --> C[lanhu_get_layout_skeleton]
    B --> D[CSS 变量 / Tailwind 配置 / W3C Tokens]
    C --> E[Flexbox 流式结构 + Tailwind 响应式代码]
```

#### 1. 提取全局设计系统 Tokens
```python
# 导出为原生 CSS 变量样式表
css_tokens = lanhu_get_design_tokens(url="https://lanhuapp.com/web/#/item/project/stage?tid=xxx&pid=yyy", format="css")

# 导出为 Tailwind 扩展配置
tailwind_config = lanhu_get_design_tokens(url="https://lanhuapp.com/web/#/item/project/stage?tid=xxx&pid=yyy", format="tailwind")
```

#### 2. 智能推断 Flexbox 响应式布局骨架
```python
# 自动将绝对坐标推断为语义化 HTML 标签 (header/button/h1/div) 与 Flex 流向 (flex-row / flex-col / gap / padding)
skeleton = lanhu_get_layout_skeleton(url="https://lanhuapp.com/web/#/item/project/detailDetach?pid=xxx&image_id=yyy")
```

#### 3. 批量导出画板切图与生成清单
```python
# 一键下载所有切图资源，并生成前端工程可直接引入的 manifest.json (含 import 语句)
res = lanhu_batch_export_assets(url="https://lanhuapp.com/web/#/item/project/detailDetach?pid=xxx&image_id=yyy", save_dir="src/assets")
```

---

## ⚙️ 环境变量配置说明

| 环境变量 | 默认值 | 说明 |
|:---|:---|:---|
| `LANHU_COOKIE` | *(空)* | 蓝湖 Cookie 兜底配置（格式 `session=...; user_token=...`） |
| `LANHU_DOWNLOAD_DIR` | `~/Downloads/lanhu_assets` | 切图资源下载保存的目标目录 |
| `LANHU_TIMEOUT` | `30` | API 网络请求超时时间（秒） |
| `LANHU_LOG_LEVEL` | `INFO` | 日志输出级别（`DEBUG`, `INFO`, `WARNING`, `ERROR`） |

---

## ⚠️ 免责声明

本项目仅供个人学习、技术研究与 AI 辅助开发效率探索之目的，通过逆向分析 Web 接口实现。请在使用过程中严格遵守蓝湖服务条款。因使用本开源工具产生的任何风险与责任由使用者自行承担。

---

## 📄 开源许可

本项目基于 [MIT License](LICENSE) 协议开源。