lanhu-mcp

一位产品经理的苦恼，和他最终找到的答案

凌晨两点，产品经理小张还在对着 Axure 原型文档一条条敲需求。他需要在明天的评审会上，向五个开发团队讲清楚"会员积分模块"的字段规则、边界条件、异常流程。这是他第三遍改需求文档了——前两遍，开发同学都说"需求太模糊，看不懂"。

同样的场景，正在无数中国互联网公司里上演。产品经理用 Axure 画好原型，上传到蓝湖，设计稿交给开发团队。但在 AI 编程时代，传统的"截图+口述"模式遇到了新问题：AI 助手看不懂蓝湖设计稿，无法直接理解设计师的意图，更无法帮你写代码。

直到 lanhu-mcp 出现。

背景：AI 编程时代的协作断层

2024 年以来，以 Cursor、Windsurf、Claude Code 为代表的 AI 代码编辑器迅速崛起。这些工具的核心逻辑是：AI 不仅能写代码，还能理解项目上下文、读取外部知识、自动完成复杂任务。但有一个关键瓶颈始终存在——AI 不知道团队的私有知识在哪里。

蓝湖（Lanhu）是国内最流行的设计协作平台，数百万设计师和产品经理在这里管理 Axure 原型、UI 设计稿、产品文档。当开发同学想在 AI 助手里引用蓝湖内容时，传统路径是：打开蓝湖 → 截图 → 粘贴到 AI 对话框 → 等待 AI 理解。这个过程低效、信息损耗严重。

lanhu-mcp 的作者 dsphper 敏锐地发现了这个痛点。作为一名长期使用 Cursor 和 Claude 的开发者，他在 CSDN 博客中写道：这个工具能让"所有 AI 助手共享团队知识，打破 AI IDE 孤岛"。这是该项目的核心价值主张。

类比解释：把蓝湖变成 AI 的"技能包"

可以把 lanhu-mcp 理解为一个翻译官 + 知识搬运工。它基于 Model Context Protocol（MCP）——这是 Anthropic 在 2024 年提出的开放协议，旨在让 AI 助手能调用外部工具和数据源。

打个比方：MCP 就像是 USB-C 接口标准，而 lanhu-mcp 就是一款通过 USB-C 接入电脑的蓝湖数据线。无论你用的是 Cursor、Windsurf 还是 Claude Code，只要 AI 工具支持 MCP，就能通过这根"数据线"直接读取蓝湖里的内容。

这种架构的优势在于一次配置，永久生效。不需要每次都手动截图，不需要复制粘贴，AI 工具可以自主调用 lanhu-mcp 的工具，按需获取蓝湖设计稿、Axure 文档、团队留言板信息。

核心功能：从设计稿到代码的全链路支持

lanhu-mcp 目前暴露了 5 个 MCP 工具，覆盖了从产品需求文档到 UI 设计稿的完整链路：

1. lanhu_list_product_documents — 列出蓝湖项目文档

这个工具可以列出团队在蓝湖中创建的所有 Axure 原型文档，包括文档名称、ID、更新时间等元信息。它直接调用蓝湖的 /api/project/product_documents 接口，返回结构化的文档列表。开发者只需传入 team_id 和 project_id，就能获取该项目的所有原型文档。

2. lanhu_get_pages — 获取 Axure 页面结构

单个 Axure 文档往往包含数十甚至数百个页面，手动翻找极为低效。lanhu_get_pages 通过 Playwright 自动化浏览器，完整抓取 Axure 文档的页面树状结构，包含页面标题、嵌套关系、页面 ID 等。抓取结果会缓存到 ./data/{doc_id}/pages.json，避免重复请求。

3. lanhu_get_ai_analyze_page_result — AI 需求分析（核心亮点）

这是项目最具创新性的功能。它会自动抓取 Axure 页面的完整标注信息（包括文字标注、交互说明、字段规则），并基于这些数据生成结构化的需求分析文档。支持三种分析视角：

• 开发视角：输出详细的字段规则、业务逻辑、全局流程图，适合后端开发参考
• 测试视角：输出测试场景、用例、边界值、校验规则，适合 QA 同学
• 快速探索：输出核心功能概览、模块依赖、评审要点，适合快速过一遍需求

项目文档声称需求分析准确率超过 95%，背后依赖的是四阶段工作流：全局扫描 → 分组分析 → 反向验证 → 生成交付物。整个过程基于 TODO 驱动，确保不遗漏任何标注。

4. lanhu_get_designs — 获取设计稿信息

设计稿功能支持两种模式：基础模式和高级模式。基础模式返回设计图预览和基本信息；高级模式（analysis_type: 'detailed'）则返回详细的设计参数——组件尺寸、间距、颜色值（RGB/HEX）、字体大小等。更重要的是，它能将这些设计参数自动转换为 HTML+CSS 代码参考，转换效果与蓝湖原生导出一致。

5. lanhu_resolve_invite_link — 解析蓝湖邀请链接

简化团队接入流程，支持直接解析蓝湖邀请链接获取团队和项目信息。

团队留言板：打破 AI IDE 孤岛

除了上述设计相关功能，lanhu-mcp 还实现了一个独特的团队留言板（MessageStore）系统。

这个功能的灵感来源于一个真实痛点：在传统工作流中，每个开发者的 AI 助手是"孤岛"。你用 Cursor 分析过的需求，用 Windsurf 的 AI 助手完全不知道；你在本地积累的调试经验，也无法同步给团队其他成员。

MessageStore 基于 JSON 文件存储（./data/{project_id}/messages.json），提供了完整的 CRUD 接口：记录留言、获取历史、按角色筛选、@提及通知等。所有连接同一 MCP 服务器的 AI 助手，都能看到这个共享知识库。这是一种轻量级的团队知识中枢实现，不需要额外数据库，部署和使用都极为简单。

技术架构：FastMCP + Playwright 的深度结合

从代码层面看，lanhu-mcp 是一个典型的单文件 Python 应用，主文件 lanhu_mcp_server.py 约 2900 行代码，核心依赖为：

依赖	用途
fastmcp>=2.0.0	MCP 协议实现，快速构建 MCP 服务器
httpx>=0.27.0	异步 HTTP 客户端，调用蓝湖 API
beautifulsoup4>=4.12.0	HTML/XML 解析，提取 Axure 标注
playwright>=1.48.0	浏览器自动化，渲染动态页面、抓取截图
lxml>=5.0.0	高性能 XML 处理

代码架构设计

项目包含三个核心类：

MessageStore（约 520 行）：团队留言板的数据存储层。实现了 JSON 文件的增删改查，支持按角色（后端/前端/产品经理等）过滤消息，支持 @提及通知逻辑。存储路径为 ./data/{project_id}/messages.json，每次写入前会加载完整文件（MessageStore._load()），更新后立即持久化（MessageStore._save()）。

LanhuExtractor（约 1300 行）：蓝湖数据提取的核心引擎。包含两大核心能力：

• Axure 文档提取：通过 Playwright 自动化浏览器加载 Axure 页面，抓取页面树状结构、页面标注、资源文件（图片、JS）。提取逻辑包含智能缓存机制——基于版本号判断是否需要重新下载（_should_update_cache()），避免重复请求。

• 设计稿分析：调用蓝湖的 DDS（Design Schema）API，获取设计稿的 JSON Schema，包含组件树、样式数据、颜色值等。然后通过 _extract_design_tokens()、_generate_html() 等函数，将结构化数据转换为人类可读的 CSS 代码参考。

HTML/CSS 生成引擎

项目实现了一套从蓝湖设计 Schema 到 HTML+CSS 的转换器（_generate_html、_generate_css、_generate_css_var 等函数，约 200 行）。转换逻辑将蓝湖组件树映射为 Kebab Case 类名的语义化 HTML 结构，并生成对应的 CSS 变量和样式规则。特别处理了 Flex 布局（_should_use_flex）、阴影（_simplify_shadow）、圆角（_extract_border_radius）等复杂样式。这套转换器的输出可以直接作为 AI 理解设计稿的中间表示。

缓存策略

项目实现了两层缓存：

1. 版本号缓存：_metadata_cache 字典缓存 Axure 文档的版本号和页面树。每次请求时先查缓存，只有版本号变化才重新抓取。
2. 文件级缓存：LanhuExtractor 将页面结构（pages.json）、设计稿元信息（schema.json）、Sketch 数据（sketch.json）分别存储在 ./data/{doc_id}/ 目录，文件名包含版本号后缀，支持增量更新。

Dockerfile 分析

项目提供的 Dockerfile 值得关注：它基于 python:3.10-slim，安装了完整的 Playwright 浏览器依赖（包括 GTK、ALSA 等 Linux 桌面库），以及 Chromium 浏览器。这说明 MCP 服务器不仅提供 API 接口，还会在运行时启动无头浏览器来渲染 Axure 页面和抓取设计稿。

上手门槛：配置 Cookie 是唯一难点

从部署角度看，lanhu-mcp 的门槛并不高。项目提供了三种安装方式：

1. Docker 一键部署（推荐）：复制 config.example.env 为 .env，填入 LANHU_COOKIE，运行 docker-compose up -d。整个过程不超过 10 分钟。

2. Shell 脚本半自动安装：运行 easy-install.sh，脚本会自动检测 Python 环境、安装依赖、配置环境变量。

3. 手动安装：创建虚拟环境、pip install -r requirements.txt、安装 Playwright 浏览器。

唯一需要手动操作的是获取蓝湖 Cookie。项目在 setup-env.sh 中提供了交互式引导，会弹出浏览器窗口，手把手教你从浏览器开发者工具中提取 Cookie 值。但需要注意的是，Cookie 有时效性（通常几天到几周），过期后需要重新获取。

隐私与安全：Cookie 管理的风险

作为一个需要蓝湖账号 Cookie 的工具，lanhu-mcp 在安全方面需要格外注意：

• Cookie 存储在 .env 文件中，项目已将 .env 加入 .gitignore，防止意外提交
• Dockerfile 末尾清理了 HTTP_PROXY 和 HTTPS_PROXY 环境变量，防止代理泄露
• 提供飞书 Webhook 通知功能，可将关键操作推送到飞书群

潜在风险：Cookie 方案本质上是模拟登录，权限等同于你的蓝湖账号。如果 Cookie 被窃取，攻击者可以访问你所有有权限的蓝湖项目文档和设计稿。建议定期更换 Cookie、避免在不受信任的网络环境下使用、考虑使用专门的蓝湖子账号限制权限范围。

行业意义：MCP 生态的中国实践

lanhu-mcp 在 GitHub 上获得了 1949 Stars（截至 2026 年 7 月），在 MCP Servers 生态中属于头部项目。它的成功折射出一个趋势：MCP 协议正在成为 AI 时代连接私有数据的标准方式。

从竞争格局看，蓝湖官方并未提供 MCP 服务，lanhu-mcp 是社区自发实现的对接方案。类似地，市场上还有 MrDgbot 的 mcp-lanhu（Node.js 版本）等多个实现。这些项目共同推动了 MCP 生态的繁荣。

从技术演进看，lanhu-mcp 的 Axure → HTML+CSS 转换能力，代表了"设计稿 → 代码"自动化的一条新路径。虽然目前只是生成参考代码（而非直接可用的生产代码），但随着 AI 生成能力的提升，这条路径的价值会越来越大。

总结

lanhu-mcp 是一款精准切入痛点的 MCP 工具。它的核心价值不是"替代蓝湖"，而是"让 AI 助手理解蓝湖"。通过将蓝湖的设计协作数据转化为 AI 可消费的上下文，它解决了 AI 编程时代"最后一公里"的协作断层问题。

如果你所在团队使用蓝湖管理设计稿和 Axure 文档，同时希望让开发团队的 AI 助手（Cursor、Windsurf、Claude Code）能够直接读取和理解这些内容，lanhu-mcp 值得一试。唯一需要注意的是 Cookie 管理带来的安全考量，建议在隔离环境中测试后再推广到团队使用。