lanhu-context-mcp

简体中文 | English

✨ 把蓝湖设计稿整理成让 AI 生成代码还原页面的上下文。

Features

• 🎨 支持输出 HTML+CSS 或 HTML+Tailwind，可以按项目技术栈选择更合适的形态
• 🖼️ 返回切图资源映射和下载命令，减少手动逐个处理图片资源的步骤
• 🧱 补充 Design Tokens 和设计预览图，方便下游模型继续实现和视觉校验
• 🧭 附带面向下游 AI 的实现指引，明确优先级、适配方式和约束条件
• ⚙️ 支持通过 CLI 参数和环境变量配置 Tailwind 输出、跳过切图、单位缩放和提示语言
• 📦 提供 inline / files 两种产出模式：默认 inline 直接在 tool result 返回全部内容；files 把 HTML、切图映射、Design Tokens、Guide 打包成 context.md + preview.png 落盘并只回传 resource_link，规避大设计稿命中 MCP 客户端 tool 输出 token 上限（例如 Claude Code 默认 MAX_MCP_OUTPUT_TOKENS=25000）的截断问题

文档

完整文档请访问 lanhu.refineup.com。

快速开始

环境要求

• Node.js ^20.19.0 || >=22.12.0

设计稿转码

• 设计稿需要先开启转码功能，然后上传到蓝湖

Step 1. 准备环境变量

先创建一个 .env.local 文件。

你需要一个可用的蓝湖登录 Token，可参考 获取蓝湖 Token。

LANHU_TOKEN=your_lanhu_token_here

Step 2. 配置 MCP

把下面对应客户端的 MCP 配置写入对应文件；如果使用 Qoder，在 MCP 服务页点击“添加”后粘贴配置：

Claude Code（.mcp.json） / Cursor（.cursor/mcp.json）

{
  "mcpServers": {
    "lanhu-context-mcp": {
      "command": "npx",
      "args": ["-y", "lanhu-context-mcp"]
    }
  }
}

TRAE（.trae/mcp.json）

{
  "mcpServers": {
    "lanhu-context-mcp": {
      "command": "npx",
      "args": ["-y", "lanhu-context-mcp", "--cwd", "${workspaceFolder}"]
    }
  }
}

Codex（.codex/config.toml）

[mcp_servers.lanhu-context-mcp]
cwd = "/absolute/path/to/current-project"
command = "npx"
args = ["-y", "lanhu-context-mcp"]

Qoder（全局 MCP 服务）

{
  "mcpServers": {
    "lanhu-context-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "lanhu-context-mcp",
        "--cwd",
        "/absolute/path/to/current-project"
      ],
      "env": {
        "LANHU_TOKEN": "your_lanhu_token_here"
      }
    }
  }
}

TRAE 存在一个设计问题：MCP 子进程的工作目录不会指向当前项目，导致 .env.local 读不到、.lanhu-context-mcp.local/ 写入异常。所以 TRAE 配置里必须固定传入 --cwd 参数；值用编辑器内置变量 ${workspaceFolder} 即可自动指向项目根，无需写死绝对路径。

Codex 的 MCP 配置比较特殊，需要额外设置 cwd，并把它填写为当前项目的绝对路径。由于这个路径通常因人而异，通常不建议把 .codex/config.toml 提交到 Git，建议做好 Git 排除并由每位开发者在本地自行维护。

Qoder 目前只能在全局（用户级）配置 MCP，进程的工作目录通常是 /，会导致写入 .lanhu-context-mcp.local/ 时因为没有权限直接报错。所以 Qoder 配置里必须显式指定 --cwd（或 env.CWD）把工作目录切到项目根，同时通过 env 传入 LANHU_TOKEN（stdio 子进程不会继承 shell 环境变量）。

--cwd 不用写死成绝对路径。支持变量替换的编辑器（如 VSCode 系）可以直接用内置变量，配置就能在团队间复用、也不必每人手改路径："--cwd", "${workspaceFolder}"。

Windows

如果在 Windows 下直接使用上面的 npx 配置启动失败，可以改用下面的写法：

Claude Code（.mcp.json） / Cursor（.cursor/mcp.json）

{
  "mcpServers": {
    "lanhu-context-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "lanhu-context-mcp"]
    }
  }
}

TRAE（.trae/mcp.json）

{
  "mcpServers": {
    "lanhu-context-mcp": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "lanhu-context-mcp",
        "--cwd",
        "${workspaceFolder}"
      ]
    }
  }
}

Codex（WSL2）

[mcp_servers.lanhu-context-mcp]
cwd = "/absolute/path/to/current-project"
command = "npx"
args = ["-y", "lanhu-context-mcp"]

Codex（原生）

[mcp_servers.lanhu-context-mcp]
cwd = "C:\\absolute\\path\\to\\current-project"
command = "C:\\Program Files\\nodejs\\npx.cmd"
args = ["-y", "lanhu-context-mcp"]

[mcp_servers.lanhu-context-mcp.env]
APPDATA = "C:\\Users\\{your-name}\\AppData\\Roaming"
LOCALAPPDATA = "C:\\Users\\{your-name}\\AppData\\Local"
USERPROFILE = "C:\\Users\\{your-name}"
HOME = "C:\\Users\\{your-name}"
SYSTEMROOT = "C:\\Windows"
COMSPEC = "C:\\Windows\\System32\\cmd.exe"

Qoder（全局 MCP 服务）

{
  "mcpServers": {
    "lanhu-context-mcp": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "lanhu-context-mcp",
        "--cwd",
        "C:\\absolute\\path\\to\\current-project"
      ],
      "env": {
        "LANHU_TOKEN": "your_lanhu_token_here"
      }
    }
  }
}

Codex 原生 fallback 参考： openai/codex#2555

Step 3. 安装 Lanhu Helper 谷歌浏览器插件

安装 Lanhu Helper 后，可以直接从蓝湖右键复制选中图层链接或示例提示词。

Step 4. 将蓝湖链接和提示词发给 AI

请根据这个蓝湖设计稿实现
@https://lanhuapp.com/web/#/item/project/detailDetach?tid={tid}&pid={pid}&project_id={project_id}&image_id={image_id}

https://lanhuapp.com/web/#/item/project/detailDetach?tid={tid}&pid={pid}&project_id={project_id}&image_id={image_id}

提示词可以按你的想法来写，但蓝湖 URL 必须确保完整且正确，否则无法正常调用 Tool。

查看更丰富的文档

生态

Lanhu Helper — 配套的蓝湖 Chrome 浏览器扩展，可以从蓝湖右键复制选中图层链接和示例提示词

参与开发

欢迎提交 PR 或 issue。下面是把开发环境跑起来的流程。

1. 安装依赖

仓库使用 pnpm workspace（含 playground 子包），在根目录执行：

pnpm install

2. 准备 .env.local

复制示例文件，再去掉 .example 后缀填入凭据：

cp .env.local.example .env.local

字段说明：

| 字段 | 必填 | 用途 | | ---------------- | -------------- | ------------------------------------------------------------------------------------------ | | LANHU_TOKEN | 是 | 调用蓝湖 API 的 Token，获取方式见 这里 | | LANHU_TEST_URL | 跑集成测试时填 | 一条真实可访问的蓝湖设计稿详情链接，集成测试会向它发请求 |

3. 三层验证矩阵

不同改动建议跑不同层级的验证：

| 层级 | 命令 | 何时跑 | 依赖 | | -------------- | ------------------------------------------------ | --------------------------------------- | ----------------------------------------- | | 单元测试 | pnpm test / pnpm test:coverage | 任何 PR 必过；目标覆盖率 100% | 无 | | 集成测试 | pnpm test:integration 及其 :http/:stdio 变体 | 改服务、工具、transport、协议层时建议跑 | LANHU_TOKEN + LANHU_TEST_URL | | 端到端验证场地 | 见下方 playground 一节 | 改输出格式、提示词、文件落盘逻辑时手测 | LANHU_TOKEN + 任何接入 MCP 的 AI 客户端 |

集成测试更细的子集（仅 files 模式、仅 stdio 等）在 package.json 的 test:integration:* 脚本里。

4. playground — 端到端验证场地（E2E verification harness）

playground/ 是一个 Vue 3 + Vite + Tailwind 工程，专门用来在真实 MCP 客户端（Claude Code / Cursor / Codex / Qoder）里跑实际蓝湖 API、把生成的页面落到 src/pages/、并通过 dev server 实时预览——验证 get_design_context 整条链路的真实行为，是单元/集成测试覆盖不到的层面。

常用命令：

# 启动 playground dev server
pnpm play

# 清理上一轮产物（src/pages 内页面 + src/assets 内切图 + .lanhu-context-mcp.local 目录）
pnpm play:clean

详细工作流和客户端配置看 playground/README.md。

5. 提 PR 前的检查清单

• [ ] pnpm typecheck 通过
• [ ] pnpm test 通过且覆盖率不下降（运行 pnpm test:coverage 确认）
• [ ] pnpm lint 通过
• [ ] 涉及对外行为或产出格式的改动，至少跑一次 pnpm test:integration:files 或在 playground 里实际验收

License

MIT

Copyright (c) 2026-present, REFINIST