<div align="center">

# 🎨 蓝湖 MCP Server

**让 AI 编程助手直接读取蓝湖设计稿、提取代码、解析需求文档、下载切图**

[![MIT License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)

</div>

---

## 这是什么

`mcp-lanhu` 是蓝湖的 [MCP](https://modelcontextprotocol.io/) 服务器，装上之后 **Cursor、Windsurf、Claude Desktop、Claude Code** 都能直接连接蓝湖。AI 可以读取设计稿、提取 HTML/CSS、解析 PRD、下载切图，全程不用离开编辑器。

### 核心能力

- **设计稿 → 代码**：生成像素级 HTML + CSS，含完整 Design Tokens（颜色、字体、阴影、渐变）
- **结构化 Design Tokens**：提取所有颜色、字体族/字号/字重、阴影、边框、圆角，按使用频率排序
- **PRD 驱动开发**：将 PRD 或 Axure 原型交给 AI，需求感知编码
- **自动切图**：提取并下载设计师标记的切图到本地，可生成 `manifest.json` 溯源
- **并发 + 重试**：多设计稿并行分析，网络异常自动重试
- **MCP Resources & Prompts**：内置前端开发和设计走查 Prompt 模板

---

## 安装

### 手动配置

**Cursor / Windsurf** — 编辑 `.cursor/mcp.json`（或 `.windsurf/mcp.json`）：

```json
{
  "mcpServers": {
    "lanhu": {
      "command": "npx",
      "args": ["-y", "mcp-lanhu"],
      "env": { "LANHU_COOKIE": "your_cookie_here" }
    }
  }
}
```

**Claude Desktop** — 编辑 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "lanhu": {
      "command": "npx",
      "args": ["-y", "mcp-lanhu"],
      "env": { "LANHU_COOKIE": "your_cookie_here" }
    }
  }
}
```

**Claude Code**：

```bash
claude mcp add lanhu -- npx -y mcp-lanhu
```

然后设置环境变量 `LANHU_COOKIE`。

### 获取 Cookie

1. 登录 [蓝湖](https://lanhuapp.com)
2. F12 打开开发者工具 → Network 标签
3. 复制任意请求的 `Cookie` 请求头

配置完成后重启客户端，粘贴蓝湖链接即可使用。

---

## 工具

### `lanhu_design` — 设计稿

通过 `mode` 参数切换功能：

| Mode | 说明 |
|------|------|
| `list` | 列出项目所有设计图 |
| `analyze` | 设计图 → HTML+CSS + Design Tokens（默认） |
| `tokens` | 仅提取 Design Tokens（字体、颜色、阴影等） |
| `slices` | 提取设计师标记的可导出切图信息 |
| `download` | 下载切图到本地目录，可写 `manifest.json` |

`analyze` 模式支持 `include` 参数按需选择输出：`html`、`image`、`tokens`、`layout`、`layers`、`slices`，默认 `["html", "tokens", "layers", "image"]`。请求 `layers` 时可用 `layer_depth` 控制嵌套深度：默认 `4`，`0` 仅返回顶层，`"all"` 返回完整图层树。

`download` 模式相关参数：

- `download_dir`：切图保存目录（必填，绝对或相对路径）
- `write_manifest`：设为 `true` 时额外生成 `manifest.json`，记录「本地文件 ↔ 原图层名 ↔ 语义名 ↔ 蓝湖 CDN URL」的映射

**Design Tokens 输出示例：**

```
=== Design Tokens ===

Colors (12 unique):
  rgba(140,140,140,1) x48
  rgba(255,255,255,1) x28
  rgba(51,51,51,1) x12
  ...

Fonts (7 unique):
  Source Han Sans CN / Regular / 14px x25
  PingFang SC / Bold / 10px x3
  ...

Shadows (3 unique):
  rgba(0,81,187,0.03) 0px 0px 0px 1px x3
  ...
```

### `lanhu_page` — PRD / 原型

| Mode | 说明 |
|------|------|
| `list` | 列出 PRD 所有页面 |
| `analyze` | PRD/原型 → 结构化分析（默认） |

`analyze` 模式支持 `analysis_mode` 切换分析视角：`developer`（开发，默认）、`tester`（测试）、`explorer`（探索）。

### `lanhu_resolve_invite` — 解析邀请链接

将蓝湖分享链接解析为可用的项目 URL。

---

## MCP Resources & Prompts

| 类型 | 名称 | 说明 |
|------|------|------|
| Resource | `project-designs` | 项目设计稿列表（`lanhu://project/{pid}/designs?tid={tid}`） |
| Prompt | `frontend-dev` | 根据设计稿生成像素级前端代码 |
| Prompt | `design-review` | 审查设计一致性和可实现性 |

---

## 使用场景

- **前端开发**：粘贴蓝湖链接 → AI 生成与设计稿匹配的组件代码
- **设计走查**：对比实现与 Design Tokens（间距、颜色、字体）
- **需求实现**：将 PRD 交给 AI，需求驱动的功能开发
- **资源导出**：批量提取并下载图标和图片

---

## 兼容性

| 客户端 | 支持 | 传输 |
|--------|------|------|
| Cursor | ✅ | stdio |
| Windsurf | ✅ | stdio |
| Claude Desktop | ✅ | stdio |
| Claude Code | ✅ | stdio |
| 其他 MCP 兼容 IDE | ✅ | stdio |

---

## 开发

```bash
git clone https://github.com/Shaolih0603/lanhu-mcp.git
cd lanhu-mcp
npm install
cp config.example.env .env   # 填入 LANHU_COOKIE
npm run dev     # 开发模式
npm run build   # 构建
npm test        # 测试
```

---

## FAQ

**Q: 什么是 MCP？**
A: [Model Context Protocol](https://modelcontextprotocol.io/)，让 AI 助手安全连接外部工具的开放标准。

**Q: 支持哪些蓝湖套餐？**
A: 任何可网页访问的蓝湖账号，通过浏览器 Cookie 认证。

**Q: `analyze` 返回太大怎么办？**
A: 用 `include` 参数，如 `["tokens"]` 只返回 Design Tokens；不需要 base64 图片时请不要包含 `image`。

**Q: 不用 Cursor 也能用？**
A: 能。支持所有 MCP 客户端。

---

## License

[MIT](LICENSE)

本项目基于 [MrDgbot/lanhu-mcp](https://github.com/MrDgbot/lanhu-mcp) 二次开发，遵循 MIT 协议。