🎨 Lanhu MCP Server | 蓝湖MCP服务器

让所有 AI 助手共享团队知识，打破 AI IDE 孤岛

lanhumcp | 蓝湖mcp | lanhu-mcp | 蓝湖AI助手 | 蓝湖skills | Lanhu AI Integration

English | 简体中文

快速开始 • 功能特性 • 使用文档 • 贡献指南

🌟 项目亮点

一个面向蓝湖设计交付与需求阅读的 Model Context Protocol (MCP) 服务器。由 MCP 提供来源数据和资源，大模型结合画面理解并适配目标工程。

v1.8.6：需求页支持按文字、稳定块 ID、分块 ID 或坐标精确取局部图；长页分片保持横向完整。 版本说明 · 设计工作流 · 维护流程

🔥 核心创新：

• 📋 需求分析支持：提取 Axure 页面、文字与注释，提供开发、测试、探索视角；业务结论由 AI 与使用者核对。
• 💬 团队知识库：打破 AI IDE 孤岛，让所有 AI 助手共享知识库和上下文
• 🎨 UI设计支持：自动下载设计稿，智能提取切图，语义化命名；设计图分析可获取尺寸/间距/颜色/字体等精确参数，并得到转换后的 HTML+CSS 代码参考
• ⚡ 性能优化：基于版本号的智能缓存，增量更新，并发处理

🎯 适用场景：

• ✅ Cursor + 蓝湖：让 Cursor AI 直接读取蓝湖需求文档和设计稿
• ✅ Windsurf + 蓝湖：Windsurf Cascade AI 直接读取蓝湖需求文档和设计稿
• ✅ Claude Code + 蓝湖：Claude AI 直接读取蓝湖需求文档和设计稿
• ✅ OpenClaw + 蓝湖：OpenClaw 原生支持读取蓝湖需求文档和设计稿
• ✅ ClawBot + 蓝湖：ClawBot 智能助手深度集成蓝湖协作
• ✅ Trae + 蓝湖：Trae AI 直接读取蓝湖需求文档和设计稿
• ✅ 通义灵码 + 蓝湖：通义灵码 AI 直接读取蓝湖需求文档和设计稿
• ✅ Cline + 蓝湖：Cline AI 直接读取蓝湖需求文档和设计稿
• ✅ 任何支持 MCP 协议的 AI 开发工具

🎯 解决痛点：

• ❌ 旧世界：每个开发者的 AI 独立工作，重复分析需求，无法共享经验
• ✅ 新世界：所有 AI 连接同一知识中枢，需求分析一次、全员复用，踩坑经验永久保存

📑 目录

• 核心特性
• 快速开始
• 团队留言板：突破 AI 协作的最后一公里
• 使用指南
• 可用工具列表
• 系统架构
• 项目结构
• 高级配置
• 性能指标
• 常见问题
• 安全说明
• 贡献指南
• 许可证
• 致谢
• 联系方式
• 路线图

✨ 核心特性

📋 需求文档分析

• 文档提取：下载和解析 Axure 页面、资源及已支持的注释字段；交互语义的覆盖取决于源数据。
• 三种分析模式：
• 🔧 开发视角：详细字段规则、业务逻辑、全局流程图
• 🧪 测试视角：测试场景、用例、边界值、校验规则
• 🚀 快速探索：核心功能概览、模块依赖、评审要点
• 四阶段工作流：全局扫描 → 分组分析 → 反向验证 → 生成交付物
• 长页视觉证据：完整截图保持原画质与兼容性；超长或超大页面额外返回带重叠区域的原清晰度分块，并标注页名和源坐标。
• 核对流程：通过目录和来源信息帮助检查遗漏，不把流程提示当成准确率保证。

🎨 UI设计支持

• 按画面和图层ID读取（新增）：固定设计版本，返回设计总览、带编号的局部裁图、原始样式与素材ID；不依赖统一的图层命名。
• 原始切图自动交付（新增）：实际下载并校验图片尺寸/哈希，提供可通过 MCP 传输的资源包和客户端安装器。详见 设计上下文与资源交付。
• 设计稿查看：批量下载和展示 UI 设计图
• 设计图分析：返回设计图预览、源参数以及 Schema 派生的 HTML+CSS 参考；生成代码仍需结合原始标注和实际渲染核验。
• 切图提取：自动识别和导出设计切图、图标资源
• 稳定资源映射：图层和素材按ID关联；业务命名由大模型结合视觉和工程约定决定。

💬 团队协作留言板 - 打破 AI IDE 孤岛

🌟 核心创新：让每个开发者的 AI 助手都能共享团队知识和上下文

问题背景：

• 每个开发者的 AI IDE（Cursor、Windsurf）是独立的，无法共享上下文
• A 开发遇到的坑，B 开发的 AI 不知道
• 需求分析结果无法传递给测试同学的 AI
• 团队知识碎片化在各个聊天窗口，无法沉淀

创新解决方案：

• 🔗 统一知识库：所有 AI 助手连接同一个 MCP 服务器，共享留言板数据
• 🧠 上下文传递：开发 AI 分析的需求，测试 AI 可以直接查询使用
• 💡 知识沉淀：坑点、经验、最佳实践以"知识库"类型永久保存
• 📋 任务协作：通过"任务"类型留言，让 AI 帮忙查询代码、数据库
• 📨 @提醒机制：支持飞书通知，打通 AI 协作与人工沟通
• 👥 协作追踪：自动记录谁的 AI 访问过哪些文档，团队透明

⚡ 性能优化

• 智能缓存：基于文档版本号的永久缓存机制
• 增量更新：只下载变更的资源
• 并发处理：支持批量页面截图和资源下载

🚀 快速开始

⚠️ 重要提示：必须使用支持视觉功能的AI模型！ 本项目需要AI模型具备图像识别和分析能力，推荐使用以下2026年主流视觉模型： - 🤖 Claude (Anthropic) - 🌟 GPT (OpenAI) - 💎 Gemini (Google) - 🚀 Kimi (月之暗面) - 🎯 Qwen (阿里巴巴) - 🧠 DeepSeek (深度求索) 不支持纯文本模型（如 GPT-3.5、Claude Instant 等）

💡 小白用户？ 直接对 AI 说 "帮我克隆并安装 https://github.com/dsphper/lanhu-mcp 项目"，AI 会引导你完成所有步骤！

方式一：让 AI 帮你安装（推荐！！！）

直接在对 AI 说：

"帮我克隆并安装 https://github.com/dsphper/lanhu-mcp 项目"

AI 会自动完成：克隆项目 → 安装依赖 → 引导获取 Cookie → 配置并启动服务

📖 参考文档：AI 安装指南 • Cookie 获取教程

方式二：手动安装

2.1 Docker 部署（推荐）

优点：环境隔离、一键部署、易于管理

# 1. 克隆项目
git clone https://github.com/dsphper/lanhu-mcp.git
cd lanhu-mcp

# 2. 创建配置并填写 Cookie
cp .env.example .env
# 编辑 .env，将 LANHU_COOKIE 改为你自己的 Cookie

# 3. 构建并启动服务
docker compose up -d --build

Windows 用户可用 copy .env.example .env 创建配置文件。旧版 Docker Compose 可将 docker compose 替换为 docker-compose。

已有单文件部署升级： lanhu_mcp_server.py 已内嵌项目自带的 lanhu_design 实现。在依赖已安装的环境中，只替换这一个文件即可获得完整需求文档与设计稿工具；不再需要额外复制 lanhu_design/ 目录。正式安装仍推荐使用完整仓库、wheel 或 Docker，以便同步依赖。

📖 详细文档：Docker 部署指南

2.2 源码运行

前置要求：Python 3.10+。macOS 自带的 Python 3.9 不满足要求，请先运行 python3 --version 确认版本。

# 1. 克隆项目
git clone https://github.com/dsphper/lanhu-mcp.git
cd lanhu-mcp

# 2. 一键安装（推荐，会引导你配置 Cookie）
bash easy-install.sh        # Linux/Mac
# 或
easy-install.bat           # Windows

💡 easy-install.sh 会自动安装依赖、引导获取 Cookie 并配置环境。国内用户默认优先使用阿里云 PyPI，并自动回退到清华和官方 PyPI；Chromium 使用 npmmirror 的 Chrome for Testing 专用镜像，兼容旧版路径并以 Playwright 官方 CDN 兜底；可通过 PIP_INDEX_URL、PLAYWRIGHT_DOWNLOAD_HOST、PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST 覆盖。

Linux / macOS：

python3 -m venv venv
./venv/bin/python -m pip install -e .
./venv/bin/python -m playwright install chromium
cp .env.example .env
# 编辑 .env，将 LANHU_COOKIE 改为你自己的 Cookie

Windows：

python -m venv venv
venv\Scripts\python.exe -m pip install -e .
venv\Scripts\python.exe -m playwright install chromium
copy .env.example .env

配置（源码运行需要）

1. 设置蓝湖 Cookie（必需）

export LANHU_COOKIE="your_lanhu_cookie_here"

💡 获取 Cookie：登录蓝湖网页版，打开浏览器开发者工具，从请求头中复制 Cookie

1. 配置飞书机器人（可选）

方式一：环境变量（推荐，支持 Docker）

export FEISHU_WEBHOOK_URL="https://open.feishu.cn/open-apis/bot/v2/hook/your-webhook-url"

方式二：修改代码 在 lanhu_mcp_server.py 中修改：

DEFAULT_FEISHU_WEBHOOK = "https://open.feishu.cn/open-apis/bot/v2/hook/your-webhook-url"

1. 配置用户信息映射（可选）

更新 FEISHU_USER_ID_MAP 字典以支持 @提醒功能。

1. 其他环境变量（可选）

# 服务器配置
export SERVER_HOST="0.0.0.0"       # 服务器监听地址
export SERVER_PORT=8000            # 服务器端口

# 数据存储
export DATA_DIR="./data"           # 数据存储目录

# 性能调优
export HTTP_TIMEOUT=30             # HTTP请求超时时间（秒）
export VIEWPORT_WIDTH=1920         # 浏览器视口宽度
export VIEWPORT_HEIGHT=1080        # 浏览器视口高度

# 调试选项
export DEBUG="false"               # 调试模式（true/false）

📝 完整环境变量说明请参考 config.example.env 文件

运行服务

源码运行：

./venv/bin/lanhu-mcp --transport http       # Linux/macOS
venv\Scripts\lanhu-mcp.exe --transport http  # Windows

按需启动（stdio，本地 MCP 客户端推荐）：

./run-stdio.sh # Linux/Mac
./run-stdio.bat # Windows

run-stdio.sh 会自动进入项目目录、读取 .env，并以 stdio 方式启动 MCP 服务。适合 Cursor、Claude Code 等支持 command / args 配置的客户端按需拉起服务，无需手动常驻启动 HTTP 服务。

Docker 运行：

docker-compose up -d              # 启动
docker-compose logs -f            # 查看日志
docker-compose down              # 停止

服务器将在 http://localhost:8000/mcp 启动

连接到 AI 客户端

在支持 MCP 的 AI 客户端（如 Claude Code、Cursor、Windsurf）中配置：

Claude Code 配置示例：

{
  "mcpServers": {
    "lanhu": {
      "type": "http",
      "url": "http://localhost:8000/mcp?role=Developer&name=YourName"
    }
  }
}

Cursor / Windsurf 等其他客户端配置示例：

{
  "mcpServers": {
    "lanhu": {
      "url": "http://localhost:8000/mcp?role=Developer&name=YourName"
    }
  }
}

按需启动配置示例（无需提前启动服务）：

Linux/Mac

{
  "mcpServers": {
    "lanhu": {
      "command": "/bin/bash",
      "args": [
        "<ABSOLUTE_PATH_TO_LANHU_MCP>/run-stdio.sh"
      ],
      "env": {
        "LANHU_USER_NAME": "YourName",
        "LANHU_USER_ROLE": "Developer"
      }
    }
  }
}

Windows

{
  "mcpServers": {
    "lanhu": {
      "command": "<ABSOLUTE_PATH_TO_LANHU_MCP>/run-stdio.bat",
      "env": {
        "LANHU_USER_NAME": "YourName",
        "LANHU_USER_ROLE": "Developer"
      }
    }
  }
}

请将 <ABSOLUTE_PATH_TO_LANHU_MCP> 替换为本机 lanhu-mcp 项目的绝对路径；macOS/Linux 下可在项目目录执行 pwd 获取。

📌 URL 参数说明： - role: 用户角色（Developer/Frontend/Backend/Tester/Product 等） - name: 用户姓名（用于协作追踪和 @提醒） - ⚠️ 注意：部分 AI 开发工具不支持 URL 中使用中文参数值，建议使用英文

📌 stdio 环境变量说明： - LANHU_USER_ROLE: 用户角色（Developer/Frontend/Backend/Tester/Product 等） - LANHU_USER_NAME: 用户姓名（用于协作追踪和 @提醒）

🎯 提升 UI 还原度

开启蓝湖的设计稿转代码功能可以显著提升 UI 还原度。如果遇到提示无法转换的问题，需要让 UI 设计师升级蓝湖插件版本后重新上传设计稿。

✨保持关注

给我们点个 Star，你将能第一时间从 GitHub 收到所有新版本的发布通知！

📖 使用指南

需求文档分析工作流

1. 获取页面列表

请帮我用mcp看看这个需求文档：
https://lanhuapp.com/web/#/item/project/product?tid=xxx&pid=xxx&docId=xxx

2. AI 自动执行四阶段分析

• ✅ STAGE 1: 全局文本扫描，建立整体认知
• ✅ STAGE 2: 分组详细分析（根据选择的模式）
• ✅ STAGE 3: 反向验证，确保零遗漏
• ✅ STAGE 4: 生成交付文档（需求文档/测试计划/评审PPT）

3. 获取交付物

• 开发视角：详细需求文档 + 全局业务流程图
• 测试视角：测试计划 + 测试用例清单 + 字段校验表
• 快速探索：评审文档 + 模块依赖图 + 讨论要点

full 模式遇到长页时会保留原完整截图，并默认附加前 4 张细节分块。若返回信息提示仍有后续分块，再使用 tile_offset 继续读取；tile_limit 每页最多为 12。普通页面和 text_only 模式不增加截图。

UI 设计稿查看

请帮我用mcp看看这个设计稿：
https://lanhuapp.com/web/#/item/project/stage?tid=xxx&pid=xxx

分析结果包含设计图预览、详细参数（尺寸/间距/颜色/字体等）以及转换后的 HTML+CSS 代码，便于还原实现。

切图下载

帮我用mcp下载"首页设计"的所有切图

AI 会自动：