# 蓝湖 Design Schema MCP

这是一个非官方、只读的 [Model Context Protocol](https://modelcontextprotocol.io/) 服务，用于读取和分析蓝湖设计项目。

它读取蓝湖缓存的 Figma 原始导出，并转换成精简、带版本号的 Design IR。输出会保留组件身份、几何信息、文本、样式和可导出资源，但不会猜测应用布局或业务逻辑。

> 本项目与蓝湖或 Figma 不存在隶属、合作或官方认可关系。项目依赖蓝湖未公开的接口，这些接口可能随时发生变化。

## 工具

| 工具 | 用途 |
| --- | --- |
| `lanhu_get_designs` | 获取项目中的设计图清单及封面元数据 |
| `lanhu_get_design_preview` | 返回设计图封面，用于视觉核对 |
| `lanhu_search_design_nodes` | 按 id、名称、路径、文案或组件身份检索原始节点树 |
| `lanhu_get_design_schema` | 以 `summary`、`full` 或 `exact` 模式返回精简的 Design IR |
| `lanhu_get_design_slices` | 获取 PNG/SVG 资源及可直接放置的视觉位置和尺寸 |

所有工具均标记为只读。Schema、节点检索和切图调用共享一份进程内、感知设计版本的 LRU 缓存。

## 数据流架构

![蓝湖 Design IR MCP 数据流架构](docs/assets/data-flow-architecture.svg)

## 使用要求

- Node.js 20 或更高版本
- 一个有权访问目标项目的蓝湖账号
- 有效的蓝湖浏览器会话 Cookie

## 安全与隐私

蓝湖 Cookie 是完整登录凭证，应按密码级别保护。

- 将 Cookie 保存到本地文件，并通过 `LANHU_COOKIE_FILE` 指向该文件。
- 将文件权限限制为仅当前用户可读（`chmod 600`）。
- 不要把 Cookie 提交到仓库、粘贴到 Issue 或写入日志。
- 条件允许时，使用权限最小化的专用蓝湖账号。
- 删除 Cookie 文件并在蓝湖退出登录，可以撤销当前会话。
- 预览图和原始导出只允许通过 HTTPS 从公网地址下载；本机、内网、保留地址及不安全重定向会被拒绝。
- 预览图只接受经过文件签名校验的 PNG、JPEG、GIF 或 WebP，SVG 和伪造图片响应会被拒绝。
- 校验以文件签名为准，不轻信响应头：CDN 把图片错标为 `application/octet-stream` 时仍按签名识别，但未知二进制一律拒绝。

本服务会把项目名称、设计文案、预览图、组件元数据和资源 URL 返回给 MCP 客户端。根据客户端配置，这些数据可能被发送给 AI 服务提供商。处理私有设计或受监管数据前，请先确认服务商的数据处理政策。

在 macOS 上创建 Cookie 文件：

```bash
umask 077
pbpaste > ~/.lanhu-cookie
chmod 600 ~/.lanhu-cookie
```

获取 Cookie：登录 `lanhuapp.com`，打开浏览器开发者工具，在 Network 面板选择任意蓝湖 API 请求，复制完整的 `Cookie` 请求头值。

## 从源码安装

```bash
git clone https://github.com/andyjin5/lanhu-schema-mcp.git
cd lanhu-schema-mcp
npm ci
npm run build
npm test
```

本项目目前尚未发布到 npm，请从源码构建后使用。

## 配置 MCP 客户端

### Claude Code

```bash
claude mcp add lanhu-schema --scope user \
  --env LANHU_COOKIE_FILE=$HOME/.lanhu-cookie \
  -- node /absolute/path/to/lanhu-schema-mcp/dist/stdio.js
```

检查进程是否成功启动：

```bash
claude mcp list
```

### Codex

将以下内容加入 `~/.codex/config.toml`，并把两个路径替换为当前机器上的绝对路径：

```toml
[mcp_servers.lanhu-schema]
command = "node"
args = ["/absolute/path/to/lanhu-schema-mcp/dist/stdio.js"]
startup_timeout_sec = 30
tool_timeout_sec = 120

[mcp_servers.lanhu-schema.env]
LANHU_COOKIE_FILE = "/absolute/path/to/.lanhu-cookie"
```

修改配置后重启 Codex。

也可以直接设置 `LANHU_COOKIE`，但这会将凭证明文保存在客户端配置中，不推荐长期使用。

## 使用真实项目验证

进程成功启动不代表 Cookie 一定有效。请向 MCP 客户端提供一个包含 `pid` 的蓝湖项目地址，并让它调用 `lanhu_get_designs`。

设计图清单成功返回后，选择一张设计图并调用 `lanhu_get_design_schema` 和 `lanhu_get_design_slices`。

常见错误：

- `未配置蓝湖 Cookie`：检查 `LANHU_COOKIE_FILE` 是否为绝对路径、文件是否可读且非空。
- `HTTP 401`、`403` 或 `418`：Cookie 权限不足或已过期；重新登录蓝湖并覆盖 Cookie 文件。
- 缺少 `json_url`：当前设计图没有暴露本服务需要的 Figma 原始导出。
- 启动失败：确认 Node.js 版本不低于 20，执行 `npm ci`，然后重新运行 `npm run build`。

## Design IR

当前契约版本为 `schema_version: 3`。完整字段说明见 [docs/design-schema.md](docs/design-schema.md)。

- `summary` 返回层级、几何、文案和轻量资源引用。
- `full` 增加标准化文本样式、填充、边框、阴影、模糊和组件身份。
- `exact` 必须配合 `node_ids`，并返回选中节点的 transform、origin、矢量路径和变量绑定等原始字段。

过大的 `full` 响应会自动降级为 `summary`。如果 summary 仍然过大，服务会截断响应并返回 warning；此时先使用 `lanhu_search_design_nodes` 定位节点，再通过 `node_ids` 分区读取较小的子树。

IR 使用平台无关的 1x 设计逻辑单位。Web、原生客户端和游戏客户端需要自行处理单位换算、布局推断、运行时数据绑定和资源落地。

关于旋转与视觉几何：

- `frame` 和 `rel` 是旋转前的逻辑几何；旋转或变换后的轴对齐视觉包围盒按需输出为 `visualFrame`，仅在与 `frame` 不同时出现。
- 切图的 `position` 和 `logical_size` 直接采用视觉矩形，与已经应用旋转的 PNG/SVG 对齐。资源本身已含旋转，不能再按节点 `rotation` 二次旋转。
- `offCanvas` 和切图的 `off_canvas` 均以视觉矩形判断。

原始导出缺少合法 `sliceScale` 时，`slice_scale` 返回 `null` 并产生 `slice_scale_missing` warning；服务不会猜默认倍率，也不会伪造 `stored_size`。

## 已知限制

- 服务依赖蓝湖未公开的接口字段，蓝湖修改接口后可能无法继续工作。
- 只有包含可用 Figma 原始导出的设计图才能得到完整支持。
- 封面尺寸不是设计画布尺寸；画布尺寸应使用 Design IR 的 `meta.canvas`。
- 服务不会推断 flex 布局、循环、响应式行为或生产组件映射。
- 资源和封面 URL 由蓝湖接口提供，并由本地 MCP 进程下载。

## 配套 Skill

仓库提供中文的 [`lanhu-design-to-code`](skills/lanhu-design-to-code/SKILL.md) Skill，用于指导 Agent 读取蓝湖设计证据、按照目标仓库规范实现 UI，并对渲染结果进行验收。

安装到 Codex：

```bash
mkdir -p ~/.codex/skills
cp -R skills/lanhu-design-to-code ~/.codex/skills/
```

或者安装到 Claude Code：

```bash
mkdir -p ~/.claude/skills
cp -R skills/lanhu-design-to-code ~/.claude/skills/
```

使用 Skill 前需要先配置本 MCP。之后可以显式调用 `$lanhu-design-to-code`，也可以直接提供蓝湖地址并要求 Agent 按设计实现页面。

## 开发

```bash
npm ci
npm test
```

`npm test` 会编译 TypeScript、执行 IR、客户端和配套 Skill 测试，完成真实 MCP stdio 握手，并验证 npm 发布包内容。仓库中的测试数据全部为合成数据，不包含生产设计或真实资源 URL。

## 许可证

[MIT](LICENSE)