# 蓝湖 MCP

![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg) ![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg) ![MCP](https://img.shields.io/badge/MCP-stdio-8A2BE2.svg)

**让 AI 直接读蓝湖设计稿、还原成代码。**

把蓝湖的图层结构、每层 CSS、切图和走查评论交给 AI，自动生成 React / Vue / 小程序 / 原生代码——不用肉眼量间距、手抄色值、逐个下载切图。

> 第三方开源项目，与蓝湖（lanhuapp.com）官方无任何隶属、授权或背书关系；「蓝湖」仅为数据来源指称。读取蓝湖时使用你的**个人登录态**。

## 定位

不做「大而全」，只把**「读设计稿 → 还原 UI」**这一段做到最顺手。对标 [Figma 官方 MCP](https://developers.figma.com/docs/figma-mcp-server/) 的能力面（链接解析 → 设计上下文 → 截图 → 切图），做成蓝湖版：

| 你需要 | lanhu-mcp 对应 |
|---|---|
| 解析设计稿链接 | `lanhu_resolve_link` |
| 读设计上下文（图层 + 样式） | `lanhu_get_design` |
| 看设计稿截图 | `lanhu_get_screenshot` |
| 下载切图 | `lanhu_get_slices` / `lanhu_download_slices` |

## 为什么选它

社区已有多款蓝湖 MCP（更早、star 更多、功能面更全），我们拼的不是功能数量，而是这条主链路上的**精度与体验**：

- 🎯 **更准**：用蓝湖官方结构化数据（`json_url` Sketch 源 + DDS `props.style` 补 CSS），而非解析 Sketch 文件的间接方案；每层输出**框架无关的纯 CSS 对象**。
- 💬 **社区唯一走查评论**：读设计稿批注（含回复、坐标、版本），把设计师的意见直接喂给 AI——这是「设计 → 代码」闭环里被所有人忽略的一环。
- 🪶 **零浏览器、依赖最小**：仅 `mcp` + `httpx`，一条命令装完，任何 CI / 容器 / 远程环境都能跑（对比 dsphper 需 Playwright + Chromium）。
- 🔒 **安全更严谨**：session 只发蓝湖域名、跨域重定向自动剥 Cookie；多数社区实现下载 CDN 切图时会把 Cookie 带出。

## 快速开始

**最快：让 AI 帮你装。** 把下面这段发给 Claude Code / Cursor：

```text
帮我在当前目录安装并接入「蓝湖 MCP」：
1. python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
2. 把 .mcp.json 里的 lanhu 服务注册进你的 MCP 配置（或 claude mcp add lanhu -- .venv/bin/python src/server.py）
3. 运行 .venv/bin/python tests/test_transform.py 验证；然后让我提供一条蓝湖链接做真实读取
```

**手动三步：**

```bash
# ① 安装（需 Python 3.10+）
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt

# ② 认证（从蓝湖 Cookie 复制 session，详见「认证」）
export LANHU_SESSION='<你的 session>'

# ③ 接入
claude mcp add lanhu -- .venv/bin/python src/server.py
```

## 工具一览

7 个只读工具，覆盖「解析链接 → 列设计稿 → 读图层 → 截图对照 → 下切图 → 读走查」全链路：

| 工具 | 输入 | 返回 |
|---|---|---|
| `lanhu_resolve_link` | 任意蓝湖链接（正式 / `detailDetach` 单图 / 分享·邀请·短链） | `team_id` / `project_id` / `image_id` / `version_id` 等 + 链接类型 |
| `lanhu_list_designs` | 蓝湖链接 | 项目设计稿列表（名称 / 尺寸 / 更新时间 / `dds_ready`） |
| `lanhu_get_design` | 链接 + 设计稿名（可空） | 图层树 + 每层完整 CSS + 文本 + 摘要 |
| `lanhu_get_screenshot` | 链接 + 设计稿名（可空） | 设计稿预览图（图片 + 文本两个内容块） |
| `lanhu_get_slices` | 链接 + 设计稿名（可空） | 切图下载地址列表 |
| `lanhu_download_slices` | 链接 + 设计稿名 + 目录 | 切图下载到本地，返回绝对路径 |
| `lanhu_get_comments` | 链接 + 设计稿名（可空） | 走查 / 评论（回复、坐标、版本） |

> `design_name` 可传名称 / id / 序号，留空取第一个。URL 参数别名全覆盖（`tid`/`teamId`/`team_id`、`pid`/`project_id`/`projectId`、`image_id`/`imageId`/`img_id`/`imgId` 等）。

## 怎么用

### 例 1：还原一个页面

```
你：用蓝湖 MCP 还原这个设计稿成 React 组件：https://lanhuapp.com/web/#/item/project/stage?tid=…&pid=…
```

AI 会自己走完 `resolve_link → list_designs → get_design → get_screenshot → get_comments`，然后产出对齐设计稿的组件代码。

### 例 2：按走查意见改样式

```
你：这个稿子有哪些走查意见？把主按钮改成评论里提到的那个色值。
```

AI 调 `lanhu_get_comments` 读到「主按钮改 #2563EB」，再定位对应节点改 `css`。

### 例 3：下载切图

```
你：把这个稿子的切图下载到 ./assets。
```

AI 调 `lanhu_download_slices`，图标 / 素材落到本地工程。

## 输出长什么样

`lanhu_get_design` 返回结构化、框架无关的图层树（每层 kebab-case CSS），AI 直接拼代码：

```json
{
  "name": "购物车",
  "size": [375, 812],
  "schema_source": "sketch+dds",
  "layer_tree": [
    {
      "name": "结算栏",
      "type": "container",
      "css": { "left": 0, "top": 748, "width": 375, "height": 64 },
      "children": [
        {
          "name": "加入购物车",
          "type": "shape",
          "css": { "left": 16, "top": 758, "width": 343, "height": 44,
                   "background": "rgb(37,99,235)", "border-radius": 8 },
          "children": [
            { "name": "加入购物车", "type": "text",
              "css": { "font-size": 16, "font-weight": 600, "color": "rgb(255,255,255)" },
              "text": "加入购物车" }
          ]
        }
      ]
    }
  ]
}
```

## 详细使用

### 安装

- Python ≥ 3.10（macOS 自带版本可能过旧，可 `brew install python@3.12`）
- 依赖仅 `mcp`（2.x）、`httpx`（≥ 0.27）

```bash
git clone https://github.com/yuanhuizang-cloud/lanhu-mcp.git lanhu-mcp
cd lanhu-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```

### 认证（读真实设计稿，必需）

1. 浏览器登录 [lanhuapp.com](https://lanhuapp.com)，打开任意设计稿。
2. `F12` → **Application（应用）** → **Cookies** → 点 `lanhuapp.com` → 复制名为 `session` 的 **Value**。
3. 存到本地（不回显、不写进配置、不进 Git）：

```bash
echo '粘贴你的 session 值' > ~/.lanhu_session
chmod 600 ~/.lanhu_session
```

优先级：`LANHU_SESSION` 环境变量 > `~/.lanhu_session` 文件。**session 会过期**，报「登录态失效」时重复上面 3 步即可。

### 接入 AI 工具

- **Claude Code**：`.mcp.json`（或 `claude mcp add lanhu -- .venv/bin/python src/server.py`）
- **Cursor**：`.cursor/mcp.json`
- **Codex**：`codex.config.example.toml` 合并进 `~/.codex/config.toml`
- **Cline**：`command` + `args` 填入 MCP 配置

通用配置（命令均为相对路径，在项目目录启动）：

```json
{
  "mcpServers": {
    "lanhu": {
      "command": ".venv/bin/python",
      "args": ["src/server.py"]
    }
  }
}
```

## 架构与数据流

```mermaid
flowchart LR
    A[蓝湖链接] --> B[resolve_link 链接解析]
    B --> C[list_designs 设计稿列表]
    C --> D[get_design 读设计稿]
    D --> E[json_url Sketch 主树]
    D --> F[DDS store_schema_revise props.style 补 CSS]
    E --> G[transform.py 统一节点 + 每层 CSS]
    F --> G
    G --> H[AI 生成代码]
    D -.-> I[get_screenshot 截图]
    D -.-> J[get_slices / download_slices 切图]
    D -.-> K[get_comments 走查评论]
```

三级降级，任何情况不崩溃、不误导：

1. `Sketch 源 + DDS CSS`（最高精度）
2. 仅 `Sketch 源`
3. 纯位图稿 → 返回明确 `note` 提示

## 安全

- **凭据不外泄**：session 只从 `LANHU_SESSION` 或 `~/.lanhu_session`（chmod 600）读取，不写进代码 / 配置 / 提交物；仓库不含任何真实凭据。
- **会话域限制**：session 只发 `*.lanhuapp.com`；切图等第三方域名（OSS / CDN）不带 Cookie，跨域重定向自动剥 Cookie。
- **隐私脱敏**：评论只返回昵称 / 内容 / 时间 / 坐标 / 版本，不含手机号 / 邮箱 / open_id。
- **只读不改**：7 个工具均为只读，不写蓝湖；唯一写操作是 `download_slices` 保存到本地目录。
- **最小依赖**：仅 `mcp` + `httpx`，无浏览器 / 数据库。

## 与社区方案对比

| 维度 | lanhu-mcp | [MrDgbot/lanhu-mcp](https://github.com/MrDgbot/lanhu-mcp) | [dsphper/lanhu-mcp](https://github.com/dsphper/lanhu-mcp) |
|---|---|---|---|
| 定位 | 聚焦「读设计稿 → 还原 UI」 | 设计稿 / PRD / Axure → HTML+CSS+Tokens | 团队协作 + 需求分析 + 设计交付 |
| 语言 / 运行时 | Python；仅 mcp + httpx | TS（Node ≥ 20） | Python；FastMCP + Playwright |
| 输出 | **每层纯 CSS 对象**（框架无关） | HTML+CSS 字符串 + Tokens | 预览图 + 源参数 + 切图 |
| 走查评论 | ✅（社区唯一） | ❌ | ❌ |
| 分享链接解析 | ✅ 真实接口 + 多级兜底 | ✅ 仅正则 JS 跳转 | ✅ Playwright |
| 安装成本 | venv，极轻 | npx 即用 | Docker / Playwright，较重 |

## 已支持 / 边界

**✅ 已支持**：7 个工具、URL 别名兼容、`detailDetach` 单图、分享 / 邀请 / 短链解析、三级降级、评论脱敏。

**⬜ 明确不做**（聚焦主链路）：设计 tokens 独立输出、评论写回、蓝湖 D2C 代码直出、组件映射、PRD / Axure 文档、团队协作 / 留言板。

## Docker 部署

```bash
cd lanhu-mcp
docker build -t lanhu-mcp .
docker run -i --rm -e LANHU_SESSION='你的 session 值' lanhu-mcp
```

接入 AI 工具用 `docker.mcp.json`（`args` 保留 `-i`）。镜像内以非 root 用户 `mcp`（uid 1000）运行，读不到宿主机 `~/.lanhu_session`，用 `-e LANHU_SESSION` 传 session。

## 常见问题

- **跑不起来 / 找不到 `.venv/bin/python`**：确认在项目目录运行；工具要求绝对路径时用 `pwd` 拼出 `<项目路径>/.venv/bin/python` 与 `<项目路径>/src/server.py`。
- **读不到图层树**：该稿 `json_url` 无图层数据（纯位图稿），返回 `note` 提示而非报错。
- **报「未配置 session」**：按「认证」配置后重启 AI 工具。
- **报「登录态失效」**：session 过期，重新复制 Cookie 更新。
- **分享 / 邀请链接解析失败**：确认账号已被邀请加入项目；或浏览器打开链接、登录后复制带 `tid=…&pid=…` 的正式链接。
- **Docker 读不到 session**：镜像读不到宿主机 `~/.lanhu_session`，用 `-e LANHU_SESSION=...` 传入。

## 免责与许可证

- **第三方性质**：独立开发者 / 开源社区维护；「蓝湖」仅为数据来源指称，读取时用你的个人登录态。
- **本地运行、不上传**：所有读取与切图下载都在本机完成，不收集 / 不上传 / 不共享你的 session、设计稿数据或生成结果。
- **仅供学习与合法授权使用**：只在你有权访问的账号 / 项目范围内使用。
- **许可证**：[MIT](./LICENSE)。