Skip to main content
Glama
andyjin5

蓝湖 Design Schema MCP

by andyjin5

蓝湖 Design Schema MCP

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

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

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

工具

工具

用途

lanhu_get_designs

获取项目中的设计图清单及封面元数据

lanhu_get_design_preview

返回设计图封面,用于视觉核对

lanhu_search_design_nodes

按 id、名称、路径、文案或组件身份检索原始节点树

lanhu_get_design_schema

summaryfullexact 模式返回精简的 Design IR

lanhu_get_design_slices

获取 PNG/SVG 资源及可直接放置的视觉位置和尺寸

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

Related MCP server: codesign-mcp

数据流架构

蓝湖 Design IR 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_schemalanhu_get_design_slices

常见错误:

  • 未配置蓝湖 Cookie:检查 LANHU_COOKIE_FILE 是否为绝对路径、文件是否可读且非空。

  • HTTP 401403418: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、原生客户端和游戏客户端需要自行处理单位换算、布局推断、运行时数据绑定和资源落地。

关于旋转与视觉几何:

  • framerel 是旋转前的逻辑几何;旋转或变换后的轴对齐视觉包围盒按需输出为 visualFrame,仅在与 frame 不同时出现。

  • 切图的 positionlogical_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

Available Tools

5 tools
lanhu_get_design_previewA
Read-only

获取单张设计图的预览图片,用于确认整体视觉、图层是否烧录文字等。预览图不是几何权威来源;尺寸、坐标、颜色仍以 lanhu_get_design_schema 和 slices 为准。

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes蓝湖 URL,pid 必需。支持 detailDetach(含 image_id)、stage/product 等格式,例:https://lanhuapp.com/web/#/item/project/detailDetach?tid=xxx&pid=xxx&image_id=xxx
designNo目标设计图:index 数字(lanhu_get_designs 返回的 index 字段)、设计图 id(uuid)或完整名称。URL 里已带 image_id 时可省略。

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only and open-world hints; description adds that preview is not authoritative for dimensions/colors, complementing annotations without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, no filler, front-loaded with purpose and key limitation. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given simple tool with 2 params and no output schema, description sufficiently covers purpose, limitations, and sibling relationships; no gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters with descriptions; description adds context beyond schema, e.g., that 'design' can be omitted if image_id in URL, enhancing semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a preview image to confirm visuals and text burning, distinguishing it from schema and slices tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use this tool (visual confirmation) and when not to (rely on schema/slices for authoritative geometry), providing clear guidance vs alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lanhu_get_designsA
Read-only

[第一步] 获取蓝湖项目的 UI 设计图清单(index/id/名称/封面 URL/封面尺寸)。preview_size 是封面尺寸,不是设计画布;画布尺寸必须读取 Design IR meta.canvas。后续用返回的 index 或 id 调 lanhu_get_design_schema / lanhu_get_design_slices。

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes蓝湖 URL,pid 必需。支持 detailDetach(含 image_id)、stage/product 等格式,例:https://lanhuapp.com/web/#/item/project/detailDetach?tid=xxx&pid=xxx&image_id=xxx

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context beyond annotations: it clarifies that preview_size refers to cover dimensions, not canvas size, and directs that canvas size must be read from Design IR meta.canvas. This helps avoid misuse.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise—two sentences—with no extraneous information. It front-loads the purpose and immediately follows with critical behavioral and workflow details. Every sentence contributes meaningfully.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list tool with one parameter and no output schema, the description provides adequate context: purpose, output fields, a behavioral caveat, and follow-up use. It is complete enough for an agent to use correctly in the workflow, though it does not mention potential pagination or other limits.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% as the single parameter 'url' has a description. The tool description does not add new information about the parameter beyond what the schema provides, so it meets the baseline without adding extra semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves a list of UI designs from a Lanhu project, specifying the fields (index, id, name, cover URL, cover size). It distinguishes itself from sibling tools by explicitly positioning itself as the first step and directing subsequent calls to lanhu_get_design_schema or lanhu_get_design_slices using the returned index or id.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly marks itself as '[第一步]' (step 1) and instructs the user to use the returned values to call other tools. This provides clear usage context and workflow guidance, though it does not explicitly state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lanhu_get_design_schemaA
Read-only

[主要设计信息源] 获取单张设计图的 Design IR:节点层级、绝对/相对坐标、文字内容与字体、颜色/渐变/圆角/阴影、设计系统组件身份(component 字段,含选中/未选中等状态语义)。坐标是平台中立的 1x 设计逻辑单位,不包含目标端生产布局语义。full 响应过大会自动降级 summary;需要 transform/vector/token 等原始字段时,先用 lanhu_search_design_nodes 定位节点,再用 detail=exact + node_ids 分区读取。exact 会保留命中子树中的隐藏和零尺寸状态节点。

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes蓝湖 URL,pid 必需。支持 detailDetach(含 image_id)、stage/product 等格式,例:https://lanhuapp.com/web/#/item/project/detailDetach?tid=xxx&pid=xxx&image_id=xxx
designNo目标设计图:index 数字(lanhu_get_designs 返回的 index 字段)、设计图 id(uuid)或完整名称。URL 里已带 image_id 时可省略。
detailNofull=标准平台中立 IR;summary=层级/几何/文案;exact=在 full 基础上附带原始节点字段,必须配合 node_idsfull
node_idsNo只返回这些节点的子树(配合 summary 定位后分区读取)

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide readOnlyHint and openWorldHint. The description adds key behavioral context: auto-degradation for large responses, platform-neutral coordinates, and retention of hidden/zero-size nodes in exact mode. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured and front-loaded with the core purpose. It is slightly verbose but every sentence adds necessary detail for correct usage. Some repetition could be trimmed, but overall efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description explains what the tool returns (IR including nodes, coordinates, etc.), limitations (auto-degradation, platform-neutral), and how to use different detail modes with node_ids. It also relates to sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. The description adds value by explaining detail level purposes, partitioning strategy, and providing URL format examples. It clarifies the design parameter's specification methods (index, uuid, name).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description precisely states the tool retrieves Design IR, listing specific data types (node hierarchy, coordinates, text, fonts, colors, shadows, etc.). It distinguishes itself as the primary design info source and references sibling tools for other tasks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is given for when to use summary vs full vs exact detail levels, including auto-degradation of full responses. It advises using lanhu_search_design_nodes first for node location, then partitioned reading with exact mode and node_ids.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lanhu_get_design_slicesA
Read-only

获取单张设计图的切图清单:PNG/SVG 下载地址、logical_size(1x 逻辑尺寸)、position(画布坐标,量间距用)、stored_size(实际存储倍率尺寸)。off_canvas=true 仅表示切图与目标画布不相交;是否使用以及资源如何落地由目标端决定。

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes蓝湖 URL,pid 必需。支持 detailDetach(含 image_id)、stage/product 等格式,例:https://lanhuapp.com/web/#/item/project/detailDetach?tid=xxx&pid=xxx&image_id=xxx
designNo目标设计图:index 数字(lanhu_get_designs 返回的 index 字段)、设计图 id(uuid)或完整名称。URL 里已带 image_id 时可省略。

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnly and openWorld hints. The description adds value by detailing the returned data (download addresses, sizes, coordinates) and clarifying off_canvas semantics. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with essential information. Every word carries weight; no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description sufficiently explains what the tool returns. Parameter descriptions are complete, and the tool's behavior (including edge case 'off_canvas') is covered. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%. Both parameters are well-documented in the schema. The description adds no new parameter-level detail beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves '切图清单' (slices list) for a single design, listing specific data fields (PNG/SVG URLs, logical_size, position, stored_size). This distinguishes it from siblings like get_design_preview or get_design_schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the meaning of 'off_canvas=true' and its practical implication ('是否使用以及资源如何落地由目标端决定'). It provides context for interpreting results but does not explicitly contrast with alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lanhu_search_design_nodesA
Read-only

分页检索单张设计图的轻量节点目录,返回 id/路径/几何/文案/DS 身份/visible。包含 full/summary 默认裁剪的隐藏节点;大型稿或需要定位 node_ids 时优先使用。

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes蓝湖 URL,pid 必需。支持 detailDetach(含 image_id)、stage/product 等格式,例:https://lanhuapp.com/web/#/item/project/detailDetach?tid=xxx&pid=xxx&image_id=xxx
limitNo每页数量,默认和最大均为 100
queryNo按 id、图层名、路径、文案或 component 模糊搜索
designNo目标设计图:index 数字(lanhu_get_designs 返回的 index 字段)、设计图 id(uuid)或完整名称。URL 里已带 image_id 时可省略。
offsetNo分页偏移,默认 0

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint. The description adds context about pagination, return fields, and inclusion of hidden nodes, which is valuable beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a concise two-sentence paragraph that front-loads the purpose and includes key details without redundancy. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers what the tool returns, when to use it, and mentions pagination. Without an output schema, it provides a good overview. Could mention support for fuzzy search via query parameter, but overall complete for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters are fully documented. The description does not add per-parameter details but provides overall context that the tool is paginated and returns specific fields, which is baseline sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool searches a paginated node directory for a single design, returning specific fields (id, path, geometry, copy, DS identity, visible). This distinguishes it from sibling tools like preview, designs, schema, and slices.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to prioritize this tool for large designs or when locating node_ids. It implies alternatives but does not explicitly list when not to use or name other tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.3.0
    • First observedlanhu_get_design_preview
    • First observedlanhu_get_design_schema
    • First observedlanhu_get_design_slices
    • First observedlanhu_get_designs
    • First observedlanhu_search_design_nodes

TDQS

A4.4/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: list designs, preview image, full design IR, slices, and node search. Descriptions clarify when to use each, especially the relationship between schema and search_nodes.

Naming Consistency4/5

Naming follows a consistent 'lanhu_verb_noun' pattern in snake_case. The verb 'search' in one tool deviates from the 'get' prefix used by the other four, but remains clear and predictable.

Tool Count5/5

Five tools is well-scoped for a read-only design schema server. Each tool has a specific role without unnecessary overlap, covering listing, preview, schema, slices, and node search.

Completeness5/5

The tool surface covers all essential read operations for design retrieval: listing designs, preview image, full Design IR, export slices, and lightweight node search. No obvious gaps for the stated purpose.

Maintenance

ActivityStale
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    B
    maintenance
    Local MCP server for Tencent CoDesign sharing links, exposing artboards, layer specs, preview images, and exported slices to support design-to-code workflows.
    8
    136 npm
    14
    MIT
  • A
    license
    A
    quality
    A
    maintenance
    MCP server for macOS that reads Lanhu designs, analyzes UI structures, and exports fine-grained design assets for multiple platforms.
    8
    5
    MIT