# 蓝湖 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 直接读懂蓝湖。**

## 快速开始

### 方式一：让 AI 帮你装（推荐）

把这句话发给你的 AI 助手（Claude Code / Cursor / 任何支持 MCP 协议的 AI）：

```text
帮我通过 git clone 克隆仓库并安装蓝湖 MCP：https://github.com/yuanhuizang-cloud/lanhu-mcp
```

### 方式二：手动安装

前置：Git、Python ≥ 3.10。macOS / Linux 在终端运行：

```bash
git clone https://github.com/yuanhuizang-cloud/lanhu-mcp.git
cd lanhu-mcp
bash easy-install.sh
```

脚本自动安装依赖、引导填写 session、执行离线自检，再按选择接入客户端：

- **Claude Code / Cursor**：自动更新项目的 `.mcp.json` / `.cursor/mcp.json`，保留其他 MCP 服务。
- **Codex**：检测到 CLI 时自动注册；否则生成 `codex-config.toml`，供合并到用户目录的 `.codex/config.toml`。
- **其他客户端**：使用生成的 `mcp-config.json`，不含登录凭据。

安装后重新打开 AI 客户端，提供蓝湖链接验证真实读取。离线自检只验证代码、配置读取和工具发现，不验证登录态是否有效。

<details>
<summary>Windows 一键安装</summary>

在 PowerShell 中运行：

```powershell
git clone https://github.com/yuanhuizang-cloud/lanhu-mcp.git
cd lanhu-mcp
.\easy-install.bat
```

无需激活虚拟环境或修改执行策略。需要重新填写 session 时运行：

```powershell
.\easy-install.bat --configure --skip-deps
```

</details>

没有 Git 时，也可以在 [GitHub 仓库](https://github.com/yuanhuizang-cloud/lanhu-mcp)选择 **Code → Download ZIP**，解压后进入项目目录运行对应安装脚本。

项目级 `.mcp.json` / `.cursor/mcp.json` 生成在克隆目录中。若要从其他前端工程使用，请按客户端的配置作用域，将生成的 `mcp-config.json` 中的服务条目合并到目标工程或全局配置。

### 配置

脚本根据 [config.example.json](./config.example.json) 创建项目目录的 `config.json`。通常只需填写 session，其他项保持默认：

```json
{
  "session": "粘贴你的 session 值",
  "request_timeout_seconds": 30,
  "max_redirects": 8,
  "download_max_mb": 64,
  "download_dir": "slices"
}
```

获取 session：浏览器登录 [蓝湖](https://lanhuapp.com) 并打开设计稿 → Chrome 开发者工具（`F12`，macOS 为 `⌥⌘I`）→ **Application → Cookies → lanhuapp.com → session** → 复制 **Value**，不带 `session=`。安装向导输入不回显；`config.json` 不提交到 Git，也不打进 Docker 镜像。

**session 会过期**。报「登录态失效」时，重新登录蓝湖并修改 `config.json` 的 `session` 后重试；每次工具调用重新读配置，本地无需重启客户端。也可以运行向导更新：

```bash
bash easy-install.sh --configure --skip-deps
```

<details>
<summary>手动启动与自检（排查问题时使用）</summary>

MCP 使用 stdio，通常由客户端按需启动。手动排查入口：

```bash
bash run-stdio.sh
```

按 `Ctrl+C` 停止，再执行同一命令重启。离线协议自检：

```bash
.venv/bin/python scripts/check_mcp.py --check-config
```

<details>
<summary>Windows 启动与自检</summary>

```powershell
.\run-stdio.bat
```

按 `Ctrl+C` 停止，再执行同一命令重启。离线自检：

```powershell
.\.venv\Scripts\python.exe scripts/check_mcp.py --check-config
```

</details>

自动化安装可用 `bash easy-install.sh --non-interactive --client project`，使用前自行填写 `config.json`。依赖已就绪的离线重装可加 `--skip-deps`。

</details>

<details>
<summary>Docker 部署（可选）</summary>

先复制 `config.example.json` 为 `config.json` 并填写 session（已运行安装脚本则无需重复）。安装并启动 Docker，在项目目录运行：

```bash
mkdir -p slices
LOCAL_UID="$(id -u)" LOCAL_GID="$(id -g)" docker compose run --build --rm lanhu-mcp
```

<details>
<summary>Windows Docker 部署</summary>

```powershell
New-Item -ItemType Directory -Force slices | Out-Null
docker compose run --build --rm lanhu-mcp
```

</details>
</details>


## 工具与功能

| 工具 | 功能与返回内容 |
|---|---|
| `lanhu_resolve_link` | 提取项目、团队、设计稿等链接参数；分享 / 邀请 / 短链尝试通过 HTTP 跳转、蓝湖短链解析接口及 HTML 中的 JS 跳转解析 |
| `lanhu_list_designs` | 列出设计稿 ID、名称、尺寸、更新时间、评论标志、最新版本 ID 和 DDS 就绪状态 |
| `lanhu_get_design` | 读取源图层 JSON，按图层 ID 合并 DDS 样式，返回图层树、文本、CSS 对象、图片引用及顶层摘要 |
| `lanhu_get_screenshot` | 下载蓝湖已有设计预览图并返回 MCP 图片内容，供 AI 进行视觉对照；不启动浏览器实时截图 |
| `lanhu_get_comments` | 合并标注页和画布页的原生评论，返回昵称、正文、时间、坐标、回复及可用的版本信息 |
| `lanhu_get_slices` | 列出切图 URL、图层位置与路径，以及可用的格式、资源变体和样式元数据 |
| `lanhu_download_slices` | 将切图下载到指定目录下的设计稿子目录，返回已保存路径与失败清单 |


## 使用示例

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

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


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

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

### 例 3：下载切图

```
你：把这个稿子的切图下载到我的前端工程 /绝对路径/my-app/assets 下。
```

## 能力对比与选型

核对日期：**2026-10-21**。以下按代码实现比较：本项目为当前实现；[MrDgbot/lanhu-mcp](https://github.com/MrDgbot/lanhu-mcp/tree/1c675360ee9330b70056b875da38a250af49fed4) 固定到 `1c67536`（包版本 2.0.2），[dsphper/lanhu-mcp](https://github.com/dsphper/lanhu-mcp/tree/6ded5bd906992b0acdd504ce9358e0608a750de1) 固定到 `6ded5bd`（1.8.7）。社区后续版本可能变化。

[//]: # (对比没有进行三者同环境的真实项目精度、启动耗时、内存或吞吐基准测试，因此不作精度或性能排名。表中“未提供”指本次核对版本未发现对应的公开能力。)

| 维度 | 本项目 | MrDgbot | dsphper |
|---|---|---|---|
| 设计属性 / 标注 | 图层树、文本、CSS 对象、图片引用 | 图层、CSS 标注、布局摘要和设计 Tokens | 原始属性、文本规格、字体要求；旧链路也提供设计标注 |
| 蓝湖原生评论 / 回复 | 标注页与画布页评论，含坐标和可用版本信息 | 未提供正文读取工具；有评论存在标志 | 未提供原生评论正文读取工具；有独立留言板 |
| HTML / CSS 参考 | 返回 CSS 对象，由调用方生成页面 | HTML / CSS、资源路径映射及 Sketch 降级参考 | 旧链路生成 HTML / CSS；新链路提供源数据和视觉证据 |
| PRD / Axure | 未提供 | 页面列表与静态内容提取，不依赖浏览器渲染 | 产品文档列表、浏览器渲染、分块及区域检查 |
| 版本选择与一致性 | 主要读取最新版本；不支持指定历史版本或固定快照 | 设计读取主要使用当前版本，未提供同等的固定快照链路 | 可指定设计版本，以固定快照衔接区域检查与资源导出 |
| 大稿按需读取 | 单稿整棵图层树，无分页 | 输出项筛选、图层深度控制 | 节点分页、区域和节点 ID 查询 |
| 视觉核对 | 整张预览图 | 设计预览图 | 整图、局部裁剪、稳定节点编号和几何间距 |
| 资源交付 | URL 清单与服务所在机器直接落盘 | 切图信息、URL 与本地路径映射；原型工具另有资源下载 | 新链路按资源 ID 选择格式变体，交付 ZIP 与 manifest，并提供客户端安装工具 |
| 资源校验 | 下载完成后的大小检查；扩展名 / MIME 判断 | 切图提取与资源映射，未见同等的像素 / 哈希校验链路 | 新链路校验格式、像素、哈希及目标倍率 |
| 批量与缓存 | 单稿工具，由 Agent 组织多次调用；切图顺序下载 | 多稿分析、有限并发与部分重试；原型资源有缓存 | 部分工具支持多稿 / 多页，另有版本快照、资源及原型缓存 |
| 链接解析 | HTTP 跳转、短链解析接口、dayu 与 HTML 中 JS 跳转兜底 | `fetch` 跟随 HTTP 重定向，再提取 HTML 中的 JS 跳转 | 邀请 / 分享链接通过 Playwright 执行前端跳转 |
| 部署与运行时 | Python ≥ 3.10，stdio，本地或 Docker | Node ≥ 20，stdio，`npx` 包入口 | Python ≥ 3.10，stdio 或 HTTP，本地或 Docker |
| 直接运行依赖 | 2 项：`mcp`、`httpx` | 2 项：MCP SDK、`zod` | 9 项，包含 FastMCP、Playwright、Pillow 等 |
| 浏览器使用 | 无浏览器依赖 | 无浏览器依赖 | 邀请解析和原型渲染等路径需要 Chromium，新设计链路通过 HTTP 与 Pillow 处理 |
| 会话与下载边界 | 蓝湖域 Cookie 限制、跨域剥离；下载仅初始 URL 白名单及完成后大小检查 | 读取链路有超时与错误处理；未见同等的域名白名单和流式大小限制 | 新设计链路逐跳校验 HTTPS / 域名 / 端口、按来源发送 Cookie、流式限制大小；旧链路需分别评估 |
| 自建协作 | 未提供；通过读取原生评论衔接设计讨论 | 未提供留言板 | 留言增删改查、协作者记录和可选飞书通知；独立于蓝湖原生评论 |
| MCP 接口形态 | 7 个拆分工具 | 3 个聚合工具，另有 Resource 和 Prompt | 17 个工具，另有设计预览与资源包 Resource |

### 强项、限制与适合的用户

| 项目 | 强项 | 限制或使用成本 | 适合的目标用户 |
|---|---|---|---|
| 本项目 | 原生评论直接进入 AI 上下文；工具职责清楚；切图可直接落盘；本地配置热更新 | 无 PRD、Tokens、区域查询与固定版本快照；大稿全量返回；存在下方列出的实现边界 | 在已有本地工程中实现页面、按走查意见改样式、下载素材的前端 / 全栈研发 |
| MrDgbot | npm 接入方便；HTML / CSS、Tokens、布局与图层输出丰富；支持输出项、深度控制和批量分析 | 无原生评论正文读取；原型分析以静态提取为主；会话与资源下载边界需要结合实际环境评估 | 使用 Node 工具链，希望集中获取设计分析、代码参考和原型内容的研发 |
| dsphper | PRD / Axure 覆盖广；固定版本、局部视觉检查和资源校验较完整；支持 HTTP 共享服务与独立留言协作 | 依赖及维护成本较高；浏览器路径需要 Chromium；新旧链路行为不同；共享 HTTP 部署需自行评估接入认证，设计服务当前为单配置账号 | 需要一起查看需求、原型、设计与资源，或需要按区域检查复杂设计稿的团队 |

## 当前能力边界

- **版本与选稿**：没有历史版本列表或版本差异比较工具；URL 中的 `versionId` 虽会被解析，但不用于选择设计数据版本。带 `tid` 的单图链接应显式传入 `design_name`（建议用 ID），避免落到默认稿。多次工具调用之间也没有固定版本快照保证。
- **源数据与降级**：图层依赖 `json_url`；DDS 仅作为补充，不会独立构建图层树。DDS 正常返回无资源时可只用图层源；DDS 请求抛错时仍会中断，尚不能保证自动降级。正常完成读取但无可用图层时返回空树与 `note`，不能仅据此认定为纯位图稿。
- **字段覆盖**：已支持部分 Sketch / Figma / Photoshop 格式的根结构及基础样式映射，不保证所有源字段完整转换。例如 `font.content` 文本，以及没有 `frame / bounds`、只在图层顶层给出的几何字段，目前可能丢失。复杂效果与推断层级需要结合原始预览图核对。
- **输出范围**：`lanhu_get_design` 中的 `design_tokens` 当前为 `{}`，`annotations` 为 `[]`；评论需单独调用 `lanhu_get_comments`。没有直接生成组件工程、PRD / Axure 分析、自建留言发布或通知工具。
- **评论完整性**：两路评论有分页上限；部分接口失败仍可能汇总为 `status: "ok"`，空列表也不能完全证明没有评论。画布评论的版本字段可能为空。
- **资源交付**：列出变体不等于支持选择倍率 / 格式；当前下载使用默认 URL，不提供像素、哈希或目标倍率校验，也不提供远程客户端资源包交付。重复下载可能覆盖目标目录中已有的同名文件。
- **规模与耗时**：图层无分页或区域筛选，切图顺序下载；较大设计稿可能返回较多内容。性能及设计还原精度需在目标项目上验证。

## 安全

- **凭据存储**：session 仅保存在本地 `config.json`；安装脚本在 macOS / Linux 上设置权限为 `600`，并排除 Git 和 Docker 构建。不要提交或分享含真实凭据的配置。
- **会话域限制**：请求头按蓝湖主域及子域判断是否携带 session；第三方 OSS / CDN 不带 Cookie，跳转到非蓝湖域名时剥离会话头。
- **下载边界**：切图 / 预览图的初始 URL 校验 HTTPS、域名白名单与端口，默认大小上限为 64 MiB。当前未对每一跳重定向重复校验下载白名单，大小也在响应读取后检查，不能当作流式内存限制或完整的任意 URL 防护。
- **身份字段裁剪**：评论输出只选取昵称、正文、时间、坐标、版本、回复与来源，不返回用户对象的手机号 / 邮箱 / open_id 等字段；不扫描或清除正文、昵称中可能出现的个人信息。
- **远端只读**：七个工具不修改蓝湖设计与评论；`lanhu_download_slices` 会写本地文件，安装脚本会写本地配置。部分读取接口使用 POST，请求方法不代表修改远端数据。
- **运行依赖**：两项直接运行依赖 `mcp` 和 `httpx`，无浏览器 / 数据库；安装时还会安装它们的传递依赖。

## 常见问题

- **跑不起来 / 找不到 Python**：确认 Python ≥ 3.10 已安装，使用克隆方式时还需 Git；重新运行安装脚本，项目移动后也需重跑脚本更新绝对路径。
- **读不到图层树**：检查返回的 `note` 和工具错误，可能涉及位图稿、权限、源数据格式或 DDS 请求失败；可先读取预览图核对，不保证所有异常都会返回空树。
- **报「未配置 session」**：填写 `config.json` 的 `session` 字段，或运行一键安装向导。
- **报「登录态失效」**：重新登录蓝湖并更新 `config.json` 的 `session` 后重试；本地无需重启，Docker 请重新创建容器。
- **分享 / 邀请链接解析失败**：确认账号已被邀请加入项目；或浏览器打开链接、登录后复制带 `tid=…&pid=…` 的正式链接。
- **Docker 读不到 session**：确认宿主机 `config.json` 已存在、只读挂载到 `/app/config.json`，并使用有读取权限的 UID/GID。

## 免责与许可证

- **第三方性质**：独立开发者 / 开源社区维护；「蓝湖」仅为数据来源指称，读取时用你的个人登录态。
- **运行与数据流**：服务在你部署的机器上请求蓝湖及资源存储，并将设计数据、预览图、评论和资源地址返回你配置的 MCP 客户端；后续是否发送给云端模型取决于客户端和模型配置。本项目没有另设数据采集服务，不代表返回给客户端的数据始终留在本机。
- **仅供学习与合法授权使用**：只在你有权访问的账号 / 项目范围内使用。
- **许可证**：[MIT](./LICENSE)。