lanhu-design-mcp 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +68 -69
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,40 +1,30 @@
1
1
  # lanhu-design-mcp
2
2
 
3
- 零依赖 stdio MCP server，让任意支持 MCP 的 coding Agent（Claude Code / Cursor / Trae /
4
- opencode）直接读蓝湖设计稿做开发：
3
+ 零依赖 stdio MCP server，让任意支持 MCP 的 coding Agent 直接读蓝湖设计稿做开发：
5
4
 
6
- - **结构化图层树**：官方 API（Cookie 直调）取 x/y/宽高/色值/字号/圆角（含逐角）/描边/阴影/文本，精确数值来自结构化数据，**不靠视觉模型 OCR 截图小字**；
7
- - **团队目录导航**：团队 → 项目 → 分组（需求）→ 设计稿完整层级，一次拉取、按需下钻；
8
- - **切图下载**：单稿或分组批量，三层去重 + 字节级验真，直接落盘本地 assets；
9
- - **视觉理解**：配置视觉模型后自动理解设计稿封面图语义（`visionAnalysis`）。
5
+ - **结构化图层树**：官方 API（Cookie 直调）取 x/y/宽高/色值/字号/圆角/描边/阴影/文本——精确数值来自结构化数据，不靠视觉模型 OCR 截图小字
6
+ - **团队目录导航**：团队 → 项目 → 分组（需求）→ 设计稿，一次拉取、按需下钻
7
+ - **切图下载**：单稿或分组批量，三层去重 + 字节级验真
8
+ - **视觉理解**：配置视觉模型后自动理解设计稿封面语义
10
9
 
11
- TypeScript + 官方 MCP SDK。你的 coding Agent 就是流水线里的"代码生成引擎"——本 MCP 只负责"读设计"；
12
- 实现完成后的验证（截图、比对、缺陷检查）由 Agent 用自己的浏览器与多模态能力完成，不经 MCP 中转。
13
-
14
- ## 环境要求
15
-
16
- - Node.js >= 18
17
-
18
- ## 安装 & 构建
10
+ ## 安装
19
11
 
20
12
  ```bash
21
13
  npm install && npm run build # esbuild 打包为单文件 dist/index.js
14
+ npx playwright install chromium # 仅登录脚本需要
22
15
  ```
23
16
 
24
- ## 快速开始
25
-
26
- ### 1. 蓝湖 Cookie
17
+ ## 准备蓝湖 Cookie
27
18
 
28
- - **推荐**：Windows 双击 `lanhu-login.bat`（或 `npm run login`），浏览器登录后回终端按 Enter，cookie 自动写入 `.mcp-local/lanhu.cookie`（已 gitignore）；
29
- - **手动**：F12 → Network → 任意请求复制 `Cookie` 头整串，写入同一文件；
30
- - 过期后重跑一次登录脚本即可，AI 检测到 401 时会提示你。
19
+ - **推荐**：F12 → Network → 复制任意请求的 `Cookie` 头整串，写入同一文件
20
+ - **备用**：双击 `lanhu-login.bat`（或 `npm run login`），浏览器登录后回终端按 Enter，cookie 自动写入 `.mcp-local/lanhu.cookie`（已 gitignore）
21
+ - 过期后重新拿Cookie即可；工具遇 401 会先区分「过期」与「该资源无权限」
31
22
 
32
- ### 2. 视觉模型（analyze 需要）
23
+ ## 接入 Agent（MCP 配置）
33
24
 
34
- 配置 `VLM_API_KEY`，可选 `VLM_BASE_URL` / `VLM_MODEL`（任何 OpenAI 兼容端点均可，默认 DeepSeek）。
35
- 配好后 `lanhu_fetch_design` **默认自动返回视觉理解**；想跳过传 `analyze:false`，或设 `LANHU_AUTO_ANALYZE=0` 全局关闭。
25
+ ### Claude Code
36
26
 
37
- ### 3. 接入 Agent（项目根 `.mcp.json`）
27
+ 项目根 `.mcp.json`：
38
28
 
39
29
  ```json
40
30
  {
@@ -44,7 +34,6 @@ npm install && npm run build # esbuild 打包为单文件 dist/index.js
44
34
  "args": ["-y", "lanhu-design-mcp"],
45
35
  "env": {
46
36
  "VLM_API_KEY": "your-api-key",
47
- "VLM_BASE_URL": "https://api.deepseek.com",
48
37
  "LANHU_COOKIE_FILE": "./.mcp-local/lanhu.cookie"
49
38
  }
50
39
  }
@@ -52,53 +41,63 @@ npm install && npm run build # esbuild 打包为单文件 dist/index.js
52
41
  }
53
42
  ```
54
43
 
55
- 源码开发时改为 `node` + `dist/index.js` 绝对路径。Cursor（`.cursor/mcp.json`）/ Trae / opencode 配置字段一致。
44
+ ### Codex CLI
45
+
46
+ 编辑 `~/.codex/config.toml`（TOML 格式，键名是 `mcp_servers` 下划线）：
47
+
48
+ ```toml
49
+ [mcp_servers.lanhu-design-mcp]
50
+ command = "npx"
51
+ args = ["-y", "lanhu-design-mcp"]
52
+ env = { VLM_API_KEY = "your-api-key", LANHU_COOKIE_FILE = "./.mcp-local/lanhu.cookie" }
53
+ ```
56
54
 
57
- ## 工具一览
55
+ ### OpenCode
56
+
57
+ 项目根 `opencode.json`（注意差异：`mcp`、`command` 是数组、env 键名是 `environment`）：
58
+
59
+ ```json
60
+ {
61
+ "mcp": {
62
+ "lanhu-design-mcp": {
63
+ "type": "local",
64
+ "command": ["npx", "-y", "lanhu-design-mcp"],
65
+ "environment": {
66
+ "VLM_API_KEY": "your-api-key",
67
+ "LANHU_COOKIE_FILE": "./.mcp-local/lanhu.cookie"
68
+ },
69
+ "enabled": true
70
+ }
71
+ }
72
+ }
73
+ ```
74
+
75
+ ### 注意事项
76
+
77
+ - TRAE / Cursor / Cline 等其他宿主用 Claude Code 的通用 `mcpServers` JSON 格式即可
78
+ - cookie 优先级：工具入参 `cookie` > 环境变量 `LANHU_COOKIE` > 文件。⚠️ 设过 `LANHU_COOKIE` 环境变量会压制文件内容——登录脚本续期后仍 401 就是这个原因，需删除/更新该环境变量
79
+ - `VLM_API_KEY`（任意 OpenAI 兼容端点，默认 DeepSeek）配好后 `lanhu_fetch_design` 自动返回视觉理解；不配则跳过
80
+ - 源码开发把 `command`/`args` 改为 `node` + `/path/to/lanhu-design-mcp/dist/index.js`（Windows 写 `C:/path/to/...`，正斜杠免转义）；npm 包已发布，可 `npx -y lanhu-design-mcp` 免构建
81
+
82
+ ## 工具
58
83
 
59
84
  | 工具 | 用途 |
60
85
  |---|---|
61
- | `lanhu_check_auth` | 探活 cookie，区分"已过期"与"该资源无权限" |
62
- | `lanhu_list_teams` | 列账号加入的全部团队（多团队发现） |
63
- | `lanhu_list_directory` | 一次拉团队目录（项目 → 分组，无需链接） |
64
- | `lanhu_read_sector` | 按分组列稿目录（稿名/尺寸/层数，不含图层树） |
65
- | `lanhu_fetch_design` | 读单稿结构化图层树 + 视觉语义理解 |
86
+ | `lanhu_check_auth` | 探活 cookie，区分「已过期」与「无权限」 |
87
+ | `lanhu_list_teams` | 列出账号加入的全部团队 |
88
+ | `lanhu_list_directory` | 一次拉团队目录（项目 → 分组） |
89
+ | `lanhu_read_sector` | 按分组列设计稿目录（稿名/尺寸/层数） |
90
+ | `lanhu_fetch_design` ⭐ | 读单稿结构化图层树 + 视觉语义理解 |
66
91
  | `lanhu_download_slices` | 切图下载到本地 assets（单稿 / 分组批量） |
67
92
 
68
- 工具入参 schema 自描述，Agent 在工具列表里即可看到完整入参说明。
69
-
70
- ## 环境变量
71
-
72
- | 变量 | 必填 | 默认 | 说明 |
73
- |---|---|---|---|
74
- | `VLM_API_KEY` | analyze 时必填 | — | 视觉模型 Key（须为对应平台签发，如 api.deepseek.com 需 DeepSeek key） |
75
- | `VLM_BASE_URL` | 否 | `https://api.deepseek.com` | 任意 OpenAI 兼容端点 |
76
- | `VLM_MODEL` | 否 | `deepseek-v4-flash-vision-exp` | 视觉模型名 |
77
- | `LANHU_VISION_MAX_TOKENS` | 否 | `8192` | 输出上限（GLM 系模型因 thinking 计入预算，分支内默认 `16384`；设太小 JSON 会被半截截断） |
78
- | `LANHU_VISION_TIMEOUT_MS` | 否 | `120000` | 单次视觉请求超时（毫秒） |
79
- | `LANHU_VISION_CACHE` | 否 | `1` | 设 `0` 关闭视觉结果缓存（`LANHU_VISION_CACHE_DIR` 可改目录） |
80
- | `LANHU_AUTO_ANALYZE` | 否 | — | 设 `0` 关闭 fetch_design 自动视觉分析（视觉模型配齐时默认自动开） |
81
- | `VISION_USE_V1` | 否 | — | 设 `0` 切到端点原生 `/chat/completions` |
82
- | `LANHU_COOKIE` | api 模式必填（与 `LANHU_COOKIE_FILE` 二选一） | — | 蓝湖 Cookie 串（F12 复制） |
83
- | `LANHU_COOKIE_FILE` | 同上 | — | cookie 文件路径；`lanhu-login.bat` 续期时自动写入 |
84
- | `LANHU_MOCK` | 否 | — | 设 `1` 时 fetch_design 返回内置示例（无需联网） |
85
- | `LANHU_SLICE_CONCURRENCY` | 否 | `6` | 切图下载并发数 |
86
- | `LANHU_ALLOWED_ASSET_HOSTS` | 否 | — | 切图主机白名单追加项（逗号分隔），默认仅放行蓝湖/阿里云系 |
87
- | `LANHU_MIN_VISIBLE_FRACTION` | 否 | `0.25` | 出画窄条剔除阈值，设 `0` 关闭 |
88
- | `LANHU_PRUNE_OCCLUDED` | 否 | `1` | 设 `0` 关闭遮挡剔除 |
89
- | `LANHU_PRUNE_FRAGMENTS` | 否 | `1` | 设 `0` 关闭碎片装饰带剔除 |
90
-
91
- > cookie 解析优先级：**工具入参 `cookie` > 环境变量 `LANHU_COOKIE` > 文件 `LANHU_COOKIE_FILE`**。
92
- > ⚠️ 若设过 `LANHU_COOKIE` 环境变量，它会压制文件内容——登录脚本续期后新 cookie 写入了文件，但旧环境变量仍生效，会持续 401；需删除/更新该环境变量。
93
-
94
- ## 部署
95
-
96
- - **拷贝即用**：整个目录发给对方，`npm install && npm run build` 后指向 `dist/index.js`；
97
- - **npm**：`npm i -g lanhu-design-mcp`，或一次性 `npx -y lanhu-design-mcp`；
98
- - **Docker**：`node:18-alpine` 内 build，运行时 `-e` 注入密钥。
99
-
100
- ## 红线（务必遵守）
101
-
102
- - **蓝湖小字（色值、字号、间距）只从 `lanhu_fetch_design` 结构化数据取，绝不靠视觉模型 OCR 截图**——图片压缩后 10px 小字/密集文本必读错；
103
- - 视觉模型结论只当线索；**钱 / 权限 / 用户数据相关流程必须人审**;
104
- - 没调 `lanhu_check_auth` 探活前不断定 cookie 过期——单资源 401 多半是权限问题，重新登录无效。
93
+ 工具入参 schema 自描述，Agent 在工具列表里即可看到完整入参说明；其余调优环境变量（并发/超时/缓存/剔除阈值）见 `src/` 内定义。
94
+
95
+ ## 红线
96
+
97
+ - 蓝湖小字（色值、字号、间距）**只从 `lanhu_fetch_design` 结构化数据取**，绝不靠视觉模型 OCR 截图——图片压缩后小字必读错
98
+ - 视觉模型结论只当线索；钱 / 权限 / 用户数据相关流程必须人审
99
+ - 没调 `lanhu_check_auth` 探活前不断定 cookie 过期——单资源 401 多半是权限问题，重新登录无效
100
+
101
+ ## License
102
+
103
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lanhu-design-mcp",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
4
  "description": "蓝湖设计稿 MCP Server — 官方 API 读稿 + 分组枚举 + 视觉理解",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",