AI导哈

设计稿解析服务器

蓝湖 MCP 服务器是一个用于与蓝湖设计平台集成的服务器，提供设计稿解析、切图下载、CSS 提取等功能，帮助开发者快速将设计稿转换为代码。

  • by meizai233
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 meizai233/lanhu-mcp

使用说明

蓝湖 MCP 服务器

蓝湖 MCP 服务器是一个 Model Context Protocol (MCP) 服务器，用于与蓝湖设计平台集成，提供设计稿解析、切图下载、CSS 提取等功能，帮助开发者快速将设计稿转换为代码。

功能特性

核心功能

  • 切图管理：
    • 获取设计图的所有切图信息和元数据（位置、尺寸、样式等）
    • 自动下载并保存 Sketch JSON 文件到本地
    • 批量下载所有切图图片到指定目录
    • 支持筛选特定切图并上传到 OSS 平台
  • CSS 提取：从蓝湖设计图中提取 CSS 代码，支持定位特定组件
  • 设计图列表：获取项目中的所有设计图列表
  • 设计图搜索：在蓝湖知识库中搜索设计图

与 AI 对话示例

以下是与 AI 协作完成设计稿到代码转换的典型对话流程：

1. 配置 Cursor MCP

首先，在 Cursor 的 MCP 配置文件中添加蓝湖 MCP 服务器配置。配置文件通常位于 ~/.cursor/mcp.json：

帮我在 Cursor 的 mcp.json 文件中配置蓝湖 MCP 服务器，填入以下信息：

配置示例（已脱敏）：

{
  "mcpServers": {
    "lanhu-mcp": {
      "command": "node",
      "args": [
        "/path/to/lanhu-mcp/dist/index.js"
      ],
      "cwd": "/path/to/lanhu-mcp",
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin",
        "LANHU_USER_TOKEN": "your_user_token_here",
        "LANHU_SESSION": "your_session_here",
        "TRANSFORM_MODE": "multiply",
        "TRANSFORM_MULTIPLIER": "2",
        "LANHU_TEAM_ID": "your_team_id_here",
        "LANHU_PID": "your_project_id_here",
        "OSS_UPLOAD_URL": "https://123-server.hellobike.cn/api/v1/oss/upload",
        "OSS_USER_ID": "your_user_id",
        "OSS_FILE_PATH": "公共/图标",
        "OSS_QUALITY": "0.8",
        "OSS_REPLACE": "false"
      }
    }
  }
}

配置说明：

  • command: 使用 node 运行 MCP 服务器
  • args: MCP 服务器入口文件的路径（编译后的 dist/index.js）
  • cwd: MCP 服务器项目的工作目录
  • env: 环境变量配置，包括蓝湖认证信息、转换配置和 OSS 配置

2. 下载 Sketch 设计图

指定蓝湖链接和预处理要求，让 AI 下载并预处理设计图：

把 https://lanhuapp.com/web/#/item/project/detailDetach?tid=xxx&pid=xxx&image_id=xxx 这个蓝湖链接的 sketch 设计图下载下来，并按照 2 倍像素进行预处理

或者指定固定宽度：

把 https://lanhuapp.com/web/#/item/project/detailDetach?tid=xxx&pid=xxx&image_id=xxx 这个蓝湖链接的 sketch 设计图下载下来，并按照宽度为 375px 进行预处理

指定保存路径（可选）：

AI 会在首次使用时询问您希望将文件保存到哪里，您可以直接指定：

把 https://... 这个蓝湖设计下载下来，保存到 /Users/xxx/my-project 目录

如果不指定，默认保存到当前工作目录。

3. 下载切图

让 AI 下载设计图的所有切图：

把该链接的切图下载下来

指定保存路径（可选）：

把切图下载到 /Users/xxx/my-project/assets 目录

如果不指定，默认保存到当前工作目录的 downloads/ 文件夹。

4. 上传切图到 OSS

根据需要上传所有切图、单个切图或筛选特定切图：

上传所有切图：

把刚才下载的所有切图上传到 OSS 平台

上传单个切图：

把切图名称为 "logo.png" 的切图上传到 OSS 平台

上传多个指定切图：

把切图名称包含 "icon" 的切图上传到 OSS 平台

5. 生成代码

根据场景选择不同的指令：

场景 A：新增页面

基于刚才下载的 sketch 设计图帮我写一个页面，并且按照项目规范来实现

场景 B：在已有页面新增 UI

在已有页面中，基于 sketch 设计图中名为 "按钮组件" 的组件，帮我新增一个组件

或者：

在已有页面中，基于 sketch 设计图中名为 "卡片视图" 的组件，帮我新增一个 view

完整对话示例

你：帮我配置 .env 文件，填入团队 ID 等环境变量信息

AI：已配置完成...

你：把 https://lanhuapp.com/web/#/item/project/detailDetach?tid=xxx&pid=xxx&image_id=xxx 这个蓝湖链接的 sketch 设计图下载下来，并按照 2 倍像素进行预处理

AI：已下载 Sketch JSON 文件到 sketch-json 文件夹...

你：把该链接的切图下载下来

AI：已下载 66 个切图到 downloads/小程序用车页_xxx/ 目录...

你：把刚才下载的所有切图上传到 OSS 平台

AI：已上传所有切图到 OSS，上传结果已保存...

你：基于刚才下载的 sketch 设计图帮我写一个页面，并且按照项目规范来实现

AI：正在分析 Sketch JSON 结构，生成页面代码...
注意：图片/icon 请使用刚才上传到 OSS 的 URL

最佳实践工作流

1. 从设计稿到组件的完整流程

蓝湖设计 URL → 获取设计信息 → 下载切图和 Sketch JSON → 还原组件

步骤 1：获取设计信息和切图

使用 get_design_slices_info 工具获取设计图的完整信息：

  • 自动下载 Sketch JSON 文件到 sketch-json 文件夹
  • 获取所有切图的元数据（位置、尺寸、样式、下载链接等）
  • 支持尺寸转换配置

步骤 2：下载切图到本地

使用 download_design_slices 工具批量下载所有切图：

  • 自动创建下载目录（格式：downloads/{设计名称}_{设计ID}）
  • 下载所有切图图片文件
  • 返回下载结果统计

步骤 3：上传切图到 OSS（可选）

如果需要将切图上传到 OSS 平台：

  • 使用 upload_all_slices_to_oss 批量上传所有切图
  • 或使用 upload_filtered_slices_to_oss 筛选特定切图上传
  • 自动保存上传结果和 URL 映射到 JSON 文件

步骤 4：提取 CSS 代码

使用 get_lanhu_css 工具提取设计图的 CSS：

  • 获取整个设计图的 CSS
  • 或定位特定组件并获取其 CSS 和间距信息

步骤 5：还原组件

使用下载的 Sketch JSON 和切图：

  • Sketch JSON 包含完整的设计结构信息（图层、位置、样式等）
  • 切图图片用于组件中的图片资源
  • CSS 代码作为样式参考

文件保存位置

输出目录结构

蓝湖 MCP 会在调用者项目的根目录下创建以下文件夹：

your-project/              # 您的项目根目录
├── sketch-json/           # Sketch JSON 文件
│   └── sketch-{id}-{version}.json
├── downloads/             # 下载的切图
│   └── {设计名称}_{设计ID}/
│       ├── image1.png
│       └── image2.png
└── oss-urls/             # OSS 上传 URL 映射
    └── {设计名称}_{设计ID}_urls.json

说明：

  • 所有文件都保存在调用 MCP 的项目根目录，而不是 MCP 服务器自己的目录
  • process.cwd() 会自动获取当前工作目录
  • 可以通过工具参数自定义下载目录

配置说明

环境变量配置

在项目根目录创建 .env 文件，配置以下变量：

蓝湖 API 认证（必需）

LANHU_USER_TOKEN=your_user_token_here
LANHU_SESSION=your_session_here

蓝湖团队 ID（可选）

LANHU_TEAM_ID=your_team_id_here

如果配置了 LANHU_TEAM_ID，在调用 get_design_slices_info 工具时会优先使用环境变量中的 teamId，而不是从 URL 中解析。如果未配置，则从 URL 中解析 teamId。

设计数据转换配置（可选）

用于将设计稿的真实尺寸转换为代码生成所需的尺寸。如果不配置，则不会进行自动转换（但仍可通过 MCP 工具参数手动指定）。

像素倍数模式（适用于 2x、3x 等倍率转换）：

TRANSFORM_MODE=multiply
TRANSFORM_MULTIPLIER=2  # 所有尺寸乘以 2

固定宽度模式（适用于响应式设计，按比例缩放到指定宽度）：

TRANSFORM_MODE=fixedWidth
TRANSFORM_TARGET_WIDTH=1080  # 目标宽度 1080px

CSS REM 模式（适用于基于 REM 的响应式网页）：

TRANSFORM_MODE=rem
TRANSFORM_REM_BASE=12  # 12px = 1rem（可选，默认值为 12）

配置说明

  • 转换配置是项目级别的，一般不需要频繁更改
  • 如果在 .env 中配置了转换模式，所有 API 调用都会自动应用该转换
  • 仍可通过 MCP 工具的 transform 参数覆盖默认配置

OSS 上传配置（必需，用于上传切图到 OSS）

用于将设计稿的切图上传到 OSS 平台。以下配置项均为必需：

# OSS 上传 API 地址
OSS_UPLOAD_URL=https://123-server.hellobike.cn/api/v1/oss/upload

# 用户 ID
OSS_USER_ID=your_user_id

# 文件路径（如 "公共/图标"）
OSS_FILE_PATH=公共/图标

# 图片质量（0-1，默认 0.8）
OSS_QUALITY=0.8

# 是否替换已存在文件（默认 false）
OSS_REPLACE=false

配置说明：

  • OSS_UPLOAD_URL: OSS 上传 API 的完整地址
  • OSS_USER_ID: 用于标识上传用户的 ID
  • OSS_FILE_PATH: 文件在 OSS 中的存储路径
  • OSS_QUALITY: 图片压缩质量，范围 0-1，默认 0.8
  • OSS_REPLACE: 如果文件已存在是否替换，默认 false

测试和调试

MCP Client 测试工具

项目包含一个 MCP Client 用于手动测试和调试 MCP 服务器。

使用方法

交互式模式（默认）：

pnpm client
# 或
pnpm client:interactive

命令行模式：

# 列出所有可用工具
pnpm client list-tools

# 解析蓝湖 URL
pnpm client parse-url "https://lanhuapp.com/web/#/item/project/detailDetach?tid=..."

# 获取 CSS
pnpm client get-css "https://lanhuapp.com/web/#/item/project/detailDetach?tid=..."

# 获取指定组件的 CSS
pnpm client get-css "https://lanhuapp.com/web/#/item/project/detailDetach?tid=..." "ComponentName"

交互式命令

在交互式模式下，可以使用以下命令：

  • list-tools - 列出所有可用工具
  • parse-url <url> - 解析蓝湖 URL
  • get-css <url> [componentName] - 获取 CSS
  • help - 显示帮助信息
  • exit - 退出交互式模式

相关 MCP