蓝湖 Design Schema MCP

这是一个非官方、只读的 Model Context Protocol 服务，用于读取和分析蓝湖设计项目。

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

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

工具

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

Related MCP server: codesign-mcp

数据流架构

使用要求

• 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 文件：

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

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

从源码安装

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

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

检查进程是否成功启动：

claude mcp list

Codex

将以下内容加入 ~/.codex/config.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。

• 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 Skill，用于指导 Agent 读取蓝湖设计证据、按照目标仓库规范实现 UI，并对渲染结果进行验收。

安装到 Codex：

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

或者安装到 Claude Code：

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

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

开发

npm ci
npm test

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

许可证

MIT