蓝湖 MCP 使用教程

适用对象：前端、后端、测试、产品，以及所有使用 Cursor、Codex、Claude Code 或其他 MCP 客户端的组员。项目地址：https://github.com/dsphper/lanhu-mcp

1. 它是什么

蓝湖 MCP Server 是一个本地运行的 MCP 服务。它把蓝湖里的需求文档、Axure 原型、UI 设计稿、切图资源和团队留言能力暴露给 AI 客户端。

配置完成后，组员可以在 Cursor、Codex、Claude Code 等工具里直接让 AI 读取蓝湖链接，而不是手动复制需求文本、截图、切图或设计参数。

典型用途：

需求评审：快速整理页面结构、业务流程、字段规则、异常场景和待确认问题。
前端开发：读取设计稿尺寸、颜色、字体、间距、切图资源，并辅助生成实现方案。
测试设计：根据蓝湖需求生成测试用例、边界值、字段校验表和回归范围。
团队协作：通过留言板沉淀需求分析结论、踩坑记录和交接信息。

2. 推荐部署方式

推荐每个组员在自己的电脑上本地部署一套蓝湖 MCP Server：

GitHub 仓库 -> 本地克隆 -> 配置自己的蓝湖 Cookie -> 启动本地 MCP -> AI 客户端连接 localhost

这样做的原因：

蓝湖 Cookie 属于个人登录凭证，不应该共享给别人。
localhost 只指向当前组员自己的电脑，权限边界清晰。
出问题时可以独立排查，不影响团队其他人。

不建议把某个人的蓝湖 Cookie 配成团队公共服务，除非团队已经明确设计了统一账号、权限、审计和运维方案。

3. 环境要求

基础要求：

Git
Python 3.10+
pip
能访问 GitHub、PyPI、Playwright 浏览器下载源
一个有目标项目权限的蓝湖账号

可选要求：

Docker / Docker Compose：如果希望容器化部署。
支持 MCP 的客户端：Cursor、Codex、Claude Code、Windsurf、VS Code Agent 等。

4. 安装方式一：源码运行

4.1 克隆项目

git clone https://github.com/dsphper/lanhu-mcp.git
cd lanhu-mcp

4.2 macOS / Linux 安装

推荐先使用项目自带脚本：

bash easy-install.sh

如果想手动安装：

python3 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m playwright install chromium
cp .env.example .env

然后编辑 .env，填入自己的蓝湖 Cookie。

4.3 Windows 安装

在 PowerShell 或 CMD 中执行：

git clone https://github.com/dsphper/lanhu-mcp.git
cd lanhu-mcp
py -3 -m venv venv
venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m playwright install chromium
copy .env.example .env

然后编辑 .env，填入自己的蓝湖 Cookie。

5. 安装方式二：Docker 部署

适合希望环境隔离的组员。

git clone https://github.com/dsphper/lanhu-mcp.git
cd lanhu-mcp
bash setup-env.sh
docker compose up -d

如果本机 Docker 命令是旧版，也可能需要：

docker-compose up -d

Docker 模式同样需要每个组员配置自己的蓝湖 Cookie。

.env 中最关键的是：

LANHU_COOKIE="这里填写你自己的蓝湖 Cookie"

获取 Cookie 的通用步骤：

浏览器打开蓝湖网页版并登录。
打开浏览器开发者工具。
进入 Network / 网络面板。
刷新蓝湖页面。
找到蓝湖请求，查看 Request Headers。
复制完整 Cookie 请求头的值。
粘贴到 .env 的 LANHU_COOKIE 中。

安全要求：

不要把 Cookie 发到群里。
不要把 Cookie 粘贴到 AI 聊天窗口。
不要把 .env 提交到 Git。
Cookie 失效后，重新登录蓝湖并复制新的 Cookie。

7. 启动 MCP Server

源码运行：

cd lanhu-mcp
source venv/bin/activate
SERVER_HOST=127.0.0.1 python lanhu_mcp_server.py

Windows：

cd lanhu-mcp
venv\Scripts\activate
$env:SERVER_HOST="127.0.0.1"
python lanhu_mcp_server.py

启动成功后会看到类似信息：

Uvicorn running on http://127.0.0.1:8000

默认 MCP 地址：

http://localhost:8000/mcp

如果项目脚本默认显示 0.0.0.0:8000，代表服务监听所有网卡。团队成员本地使用时建议通过 SERVER_HOST=127.0.0.1 限制为本机访问，避免把带个人蓝湖 Cookie 权限的 MCP 服务暴露到局域网或公网。

注意：浏览器或普通 curl 访问 /mcp 可能返回 406 Not Acceptable，这不一定代表服务异常。MCP HTTP 端点需要 MCP 客户端按协议访问。

8. MCP 地址怎么写

每个组员本地启动后，客户端都连接自己的本机地址：

http://localhost:8000/mcp?role=Frontend&name=YourName

参数说明：

参数	示例	说明
`role`	`Frontend` / `Backend` / `Tester` / `Product` / `Developer`	表示当前使用者角色，影响协作追踪和部分分析视角
`name`	`zhangsan` / `alice`	用户名，用于留言和协作者记录

建议：

name 使用英文名或拼音，不要使用中文。
如果端口改成 8001，客户端 URL 也要同步改成 http://localhost:8001/mcp?...。

9. 通用 MCP 配置

大多数支持 HTTP MCP 的客户端，本质上都需要一个服务名和一个 URL。

通用 JSON 形态：

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

有些客户端不需要 type 字段，或把 HTTP 传输称为 streamable-http。如果客户端文档和上面不同，以客户端文档为准。

10. Cursor 配置

Cursor 支持项目级和全局级 MCP 配置：

项目级：项目根目录 .cursor/mcp.json
全局级：~/.cursor/mcp.json

推荐团队项目使用项目级配置，但不要把个人 name 固定进团队仓库。更稳妥的方式是让每个人维护自己的全局配置。

Cursor 配置示例：

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

验证方式：

cursor-agent mcp list
cursor-agent mcp list-tools lanhu

在 Cursor Chat 里使用时，切到 Agent 模式。Agent 会在相关时自动调用 Available Tools 里的 MCP 工具；如果没有自动调用，直接写“请使用 lanhu MCP”或点名工具名。

11. Codex 配置

Codex CLI 和 Codex IDE 扩展共享 ~/.codex/config.toml 配置。推荐用 CLI 添加：

codex mcp add lanhu --url "http://localhost:8000/mcp?role=Frontend&name=YourName"
codex mcp list

也可以手动编辑 ~/.codex/config.toml：

[mcp_servers.lanhu]
url = "http://localhost:8000/mcp?role=Frontend&name=YourName"

建议在项目的 AGENTS.md 中加入一句：

当我提供蓝湖链接并要求分析需求、设计稿或切图时，优先使用 lanhu MCP。

这样 Codex 更容易在相关任务里主动选择蓝湖 MCP。

12. Claude Code 配置

Claude Code 推荐用 claude mcp 命令添加 HTTP MCP 服务。

当前项目可用：

claude mcp add --transport http lanhu "http://localhost:8000/mcp?role=Frontend&name=YourName"
claude mcp list

所有项目可用：

claude mcp add --transport http --scope user lanhu "http://localhost:8000/mcp?role=Frontend&name=YourName"
claude mcp list

团队项目共享配置：

claude mcp add --transport http --scope project lanhu "http://localhost:8000/mcp?role=Frontend&name=YourName"

注意：项目级配置会写入项目 .mcp.json，是否提交到团队仓库要谨慎。通常只适合提交“服务名和通用 URL 规范”，不适合提交个人姓名、个人 Cookie 或个人私有配置。

在 Claude Code 内检查连接：

/mcp

13. 其他 MCP 客户端配置

如果客户端支持 mcpServers JSON，一般可以从下面开始：

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

如果客户端只支持 SSE 或 stdio，需要看客户端是否支持 Streamable HTTP，或是否需要额外代理。优先使用客户端官方推荐的 HTTP / Streamable HTTP 配置。

14. 在 AI 客户端里怎么用

最常用的方式不是手写工具参数，而是直接给蓝湖链接和目标产物。

通用原则：

明确写“使用 lanhu MCP”。
明确你要的视角：前端、后端、测试、产品。
明确输出格式：需求清单、测试用例、组件拆分、切图清单、待确认问题。
先让 AI 读取页面列表，再分批深入分析核心页面。

15. 需求文档分析提示词

前端视角：

请使用 lanhu MCP 分析这个蓝湖需求文档，按前端开发视角输出：

页面列表和模块结构
每个页面的核心业务流程
字段规则、校验规则、默认值、异常提示
页面跳转、弹窗、按钮状态和权限判断
前端组件拆分建议
API 对接字段清单和待确认点
可能影响排期的风险点

链接：https://lanhuapp.com/...

测试视角：

请使用 lanhu MCP 分析这个蓝湖需求文档，按测试视角输出：

功能点清单
正向用例、异常用例和边界值
字段校验表
状态流转和权限场景
需要产品确认的问题
回归测试重点

链接：https://lanhuapp.com/...

快速评审：

请使用 lanhu MCP 快速浏览这个蓝湖需求文档，先不要展开所有细节，只输出：

项目大意
页面/模块清单
主要流程
前端最需要关注的 10 个点
需要继续深挖的页面

链接：https://lanhuapp.com/...

16. UI 设计稿分析提示词

设计还原视角：

请使用 lanhu MCP 查看这个蓝湖设计稿，按前端还原视角输出：

设计稿页面列表
每个页面的布局结构
关键尺寸、间距、颜色、字体
可复用组件拆分建议
React/Vue/小程序实现注意点
移动端适配风险
与设计稿不明确的地方

链接：https://lanhuapp.com/...

指定页面实现：

请使用 lanhu MCP 分析这个设计稿中的“首页”，输出前端实现方案：

页面 DOM 结构建议
组件拆分
CSS 布局方案
设计 token：颜色、字体、间距、圆角、阴影
图片和图标资源清单
响应式和小程序适配注意点

链接：https://lanhuapp.com/...

17. 切图和资源下载提示词

请使用 lanhu MCP 获取这个蓝湖项目中“首页设计”的切图信息，并输出：

可下载资源清单
建议文件名
建议放置目录
哪些资源适合作为 icon，哪些适合作为 image
前端引用方式

链接：https://lanhuapp.com/...

React 项目：

请使用 lanhu MCP 获取“首页设计”的切图，并按 React 项目结构给出资源落地建议：

- 图标放到 `src/assets/icons/`
- 图片放到 `src/assets/images/`
- 文件名使用 kebab-case
- 输出每个资源的用途和引用示例

链接：https://lanhuapp.com/...

Vue 3 项目：

请使用 lanhu MCP 获取“首页设计”的切图，并按 Vue 3 项目结构给出资源落地建议：

- 图标放到 `src/assets/icons/`
- 图片放到 `src/assets/images/`
- 文件名使用 kebab-case
- 输出每个资源的用途和引用示例

链接：https://lanhuapp.com/...

18. 团队留言板用法

团队留言板适合沉淀结论，不适合保存密钥、Cookie、真实用户数据、内部接口 Token 或私有日志。

发布留言：

请使用 lanhu MCP 发布一条团队留言：

类型：知识库
摘要：登录页前端实现注意点
内容：
1. 密码字段需要确认是否允许特殊字符
2. 验证码失败后是否刷新图片未明确
3. 登录失败提示文案需要产品确认

请 @Tester 和 @Product。

查看 @我的消息：

请使用 lanhu MCP 查看所有 @我的留言，并按优先级排序。

查历史知识：

请使用 lanhu MCP 查询所有和“登录”“验证码”“权限”相关的知识库留言，整理成前端开发注意事项。

19. 工具清单

蓝湖 MCP 当前主要工具如下：

工具名	作用	常见触发方式
`lanhu_resolve_invite_link`	解析蓝湖邀请链接	“这个分享链接帮我解析一下”
`lanhu_get_pages`	获取原型页面列表	“看看这个需求文档有哪些页面”
`lanhu_get_ai_analyze_page_result`	分析原型页面内容	“分析这个页面的字段规则和流程”
`lanhu_get_designs`	获取 UI 设计图列表	“看看这个设计稿有哪些页面”
`lanhu_get_ai_analyze_design_result`	分析 UI 设计图	“分析首页设计稿尺寸、颜色、字体”
`lanhu_get_design_slices`	获取切图信息	“下载首页所有切图”
`lanhu_say`	发布团队留言	“把这个结论发到团队留言板”
`lanhu_say_list`	查看留言列表	“查看所有 @我的消息”
`lanhu_say_detail`	查看留言详情	“查看第 3 条留言详情”
`lanhu_say_edit`	编辑留言	“修改第 3 条留言”
`lanhu_say_delete`	删除留言	“删除第 3 条留言”
`lanhu_get_members`	查看协作者	“查看谁访问过这个项目”

20. 推荐团队工作流

20.1 前端接需求

本地启动蓝湖 MCP Server。
在当前业务项目中打开 AI 客户端。
发蓝湖需求链接，让 AI 用 lanhu MCP 获取页面列表。
让 AI 分析核心页面，输出字段规则、流程和待确认问题。
把待确认问题同步给产品。
产品确认后，再让 AI 结合当前代码结构给实现方案。

20.2 前端还原设计稿

发蓝湖设计稿链接，让 AI 获取设计稿列表。
指定目标页面，让 AI 分析布局、颜色、字体、间距。
让 AI 对照当前项目组件库和样式体系生成实现方案。
需要资源时，再调用切图工具。
实现后让 AI 对照设计稿检查偏差。

20.3 测试接入

测试同学用 role=Tester 配置 MCP。
让 AI 按测试视角分析同一个需求链接。
输出测试用例、边界值、字段校验表。
查询开发同学沉淀的留言，减少重复分析。

21. 常见问题

21.1 客户端显示 MCP 未连接

检查顺序：

蓝湖 MCP Server 是否正在运行。
客户端 URL 是否是 http://localhost:8000/mcp?...。
当前客户端是否支持 HTTP / Streamable HTTP MCP。
配置文件 JSON / TOML 是否合法。
修改配置后是否重启客户端。

21.2 AI 不主动调用蓝湖 MCP

处理方式：

确认当前模式支持 Agent 工具调用。
提示词里明确写“请使用 lanhu MCP”。
点名工具，例如 lanhu_get_pages 或 lanhu_get_designs。
检查工具列表里蓝湖 MCP 是否被禁用。
工具调用审批弹窗出现时点击允许。

现象通常是蓝湖接口返回未登录、无权限或读取失败。

处理方式：

浏览器重新登录蓝湖。
从浏览器请求头重新复制 Cookie。
更新本地 lanhu-mcp/.env 中的 LANHU_COOKIE。
重启 MCP Server。

21.4 设计稿分析不完整

可能原因：

蓝湖设计稿没有开启或生成设计转代码信息。
设计师上传的插件版本过旧。
当前账号没有目标设计稿权限。
页面太大，AI 一次分析上下文不够。

处理方式：

让设计师确认蓝湖插件版本和上传方式。
先获取设计稿列表，再指定单个页面分析。
让 AI 分批分析，不要一次要求所有页面。

21.5 端口 8000 被占用

可以换端口启动：

cd lanhu-mcp
source venv/bin/activate
SERVER_HOST=127.0.0.1 SERVER_PORT=8001 python lanhu_mcp_server.py

Windows PowerShell：

cd lanhu-mcp
venv\Scripts\activate
$env:SERVER_HOST="127.0.0.1"
$env:SERVER_PORT="8001"
python lanhu_mcp_server.py

然后客户端 URL 改成：

http://localhost:8001/mcp?role=Frontend&name=YourName

22. 安全边界

必须遵守：

不把 LANHU_COOKIE 发到 AI 聊天窗口。
不把 .env 提交到 Git。
不把 AppID、AppSecret、Token、密码写进团队留言。
不在公开文档里粘贴真实用户数据、内部接口日志、生产错误堆栈。
对 AI 输出的需求结论做人工复核，特别是金额、权限、状态流转、风控、合规相关逻辑。

前端开发时还要注意：

用户输入仍然不可信，小程序端也要校验。
H5 / Web 不要用未净化的 v-html 或 dangerouslySetInnerHTML 渲染蓝湖或用户输入内容。
切图资源进入项目后，按项目资源规范命名和压缩。

23. 高质量提示词模板

23.1 前端实现方案模板

请使用 lanhu MCP 分析下面蓝湖链接，并结合当前项目代码结构，输出前端实现方案。

要求：
1. 先列页面和模块
2. 再列接口字段、状态、校验和异常分支
3. 给出组件拆分和文件建议
4. 标明 React/Vue/小程序实现差异
5. 列出必须找产品确认的问题
6. 不要直接改代码，先给方案

链接：https://lanhuapp.com/...

23.2 设计还原检查模板

请使用 lanhu MCP 分析这个设计稿，并对照当前页面实现做设计还原检查。

重点检查：
布局结构
字体大小和字重
颜色 token
间距和圆角
图片和图标资源
移动端适配
可访问性和点击区域

链接：https://lanhuapp.com/...

23.3 测试用例模板

请使用 lanhu MCP 按测试视角分析这个需求，输出测试用例。

输出格式：
功能点
前置条件
操作步骤
预期结果
边界值
异常场景
回归范围

链接：https://lanhuapp.com/...

24. 参考资料

lanhu-mcp GitHub 仓库：https://github.com/dsphper/lanhu-mcp
Cursor MCP 官方文档：https://docs.cursor.com/en/context/mcp
Cursor Agent MCP CLI 文档：https://docs.cursor.com/cli/mcp
OpenAI Docs MCP 文档中的 Codex MCP 配置示例：https://developers.openai.com/learn/docs-mcp
Claude Code MCP 官方文档：https://code.claude.com/docs/en/mcp
MCP Streamable HTTP 传输规范：https://modelcontextprotocol.io/specification/2025-06-18/basic/transports

1. 它是什么​

2. 推荐部署方式​

3. 环境要求​

4. 安装方式一：源码运行​

4.1 克隆项目​

4.2 macOS / Linux 安装​

4.3 Windows 安装​

5. 安装方式二：Docker 部署​

6. 配置蓝湖 Cookie​

7. 启动 MCP Server​

8. MCP 地址怎么写​

9. 通用 MCP 配置​

10. Cursor 配置​

11. Codex 配置​

12. Claude Code 配置​

13. 其他 MCP 客户端配置​

14. 在 AI 客户端里怎么用​

15. 需求文档分析提示词​

16. UI 设计稿分析提示词​

17. 切图和资源下载提示词​

18. 团队留言板用法​

19. 工具清单​

20. 推荐团队工作流​

20.1 前端接需求​

20.2 前端还原设计稿​

20.3 测试接入​

21. 常见问题​

21.1 客户端显示 MCP 未连接​

21.2 AI 不主动调用蓝湖 MCP​

21.3 Cookie 失效​

21.4 设计稿分析不完整​

21.5 端口 8000 被占用​

22. 安全边界​

23. 高质量提示词模板​

23.1 前端实现方案模板​

23.2 设计还原检查模板​

23.3 测试用例模板​

24. 参考资料​

1. 它是什么

2. 推荐部署方式

3. 环境要求

4. 安装方式一：源码运行

4.1 克隆项目

4.2 macOS / Linux 安装

4.3 Windows 安装

5. 安装方式二：Docker 部署

6. 配置蓝湖 Cookie

7. 启动 MCP Server

8. MCP 地址怎么写

9. 通用 MCP 配置

10. Cursor 配置

11. Codex 配置

12. Claude Code 配置

13. 其他 MCP 客户端配置

14. 在 AI 客户端里怎么用

15. 需求文档分析提示词

16. UI 设计稿分析提示词

17. 切图和资源下载提示词

18. 团队留言板用法

19. 工具清单

20. 推荐团队工作流

20.1 前端接需求

20.2 前端还原设计稿

20.3 测试接入

21. 常见问题

21.1 客户端显示 MCP 未连接

21.2 AI 不主动调用蓝湖 MCP

21.3 Cookie 失效

21.4 设计稿分析不完整

21.5 端口 8000 被占用

22. 安全边界

23. 高质量提示词模板

23.1 前端实现方案模板

23.2 设计还原检查模板

23.3 测试用例模板

24. 参考资料