moonvy-ui-mcp

Moonvy UI MCP

面向前端开发的 Moonvy（月维）设计稿读取 MCP。输入项目页或设计文件 URL，可获取页面列表、画框尺寸、图层树、节点样式、设计 Token，以及切图/快照/图片填充资源。

本项目参考了 lanhu-mcp 的工具边界，但数据读取针对 Moonvy：通过 Moonvy 的设计数据文件（Genome）提取精确参数，而不是用截图猜测颜色、字号和间距。

能做什么

MCP 工具	用途
moonvy_parse_url	解析项目、目录、设计文件 ID
moonvy_list_pages	从项目/目录列出设计文件；只有文件夹 URL 时先调用它
moonvy_get_design	获取标题、画框 ID、画框宽高、Genome 版本
moonvy_list_layers	扁平化图层索引，用于按名称查找节点 ID
moonvy_get_node_style	获取单个节点的尺寸、相对坐标、边距、填充、文字、圆角、描边、阴影和 CSS
moonvy_get_tree	获取带 UI 参数的嵌套图层树
moonvy_extract_tokens	提取颜色、渐变、字体、字号、字重、行高、圆角、阴影、推断间距
moonvy_get_ui_spec	一次返回元数据、Token 和带样式图层树，推荐开发时优先使用
moonvy_download_asset	下载切图、快照、图片填充或顶层文件预览
moonvy_clear_cache	设计稿更新后清理内存缓存

moonvy_get_node_style 和 moonvy_get_ui_spec 会给出：

• 绝对位置，以及相对父节点的 relativeX / relativeY
• 到父节点右边、底边的距离
• 宽高、可见性、透明度、裁剪状态
• 纯色、渐变和图片填充引用
• 字体、字号、字重、行高、字间距、文字颜色和对齐
• 圆角、描边、阴影
• 可直接参考的 CSS 属性对象

样式结果会同时返回源单位和 CSS 换算信息。Genome 的几何与效果数值保留为源 px，units 会明确给出 cssUnit、scale 和换算关系；移动端画板默认按 750rpx 基准生成整套 CSS。例如宽度为 375px 的画板使用 1px = 2rpx，阴影源值 0px 4px 5.8px 0px 会生成 0rpx 8rpx 11.6rpx 0rpx。可通过 MOONVY_CSS_UNIT=px|rpx|auto、MOONVY_RPX_BASE_WIDTH 和 MOONVY_RPX_SCALE 调整。

CSS 由本项目根据 Genome 生成，并非直接复制浏览器标注面板。线性渐变按 Moonvy 的归一化控制点计算方向和色标位置；径向渐变保留 from/to/aspect 对应的椭圆尺寸。fillDetails.gradient 保留原始控制点、角度和 onlyAngle，fillDetails.css 为转换结果。控制点缺失或退化时会回退到原始角度或默认径向尺寸，不保证这类数据与月维面板完全一致。

行高不是一律使用 px：typography.lineHeightUnit 区分 %、px 和 auto。例如 {value: 150, unit: "per"} 生成 150%，{value: 24, unit: "px"} 在 2 倍换算下生成 48rpx，自动行高生成 normal。Token 的 lineHeightDetails 返回 {value, unit, css}；旧的 lineHeights 数值列表仅保留用于兼容，不能将其中所有数值当作像素。内部描边会生成 box-sizing: border-box。

数据链路

Moonvy URL
  -> projectId / dirId / fileId
  -> POST https://global-api.moonvy.com/v2/anynode/get
  -> files.genome.url
  -> 下载并解压 Genome JSON
  -> 解析图层、样式、Token、资源
  -> MCP JSON 响应

项目/目录列表使用 POST /v2/anynode/list。这些是 Moonvy Web 当前使用的非公开接口，未来若 Moonvy 调整接口或 Genome 结构，需要同步更新适配层。

安装

要求 Node.js 20 或更高版本。

cd C:\path\to\moonvy-ui-mcp
npm install
Copy-Item .env.example .env

配置 Moonvy 登录令牌

1. 在浏览器登录 Moonvy，并打开需要读取的 Moonvy 页面。
2. 打开开发者工具的 Console。
3. 执行：

copy(window.app?.api?.$options?.token)

4. 把复制到的值写入本项目的 .env：

MOONVY_TOKEN=你的本机令牌

令牌只保存在本机，不要发到聊天、提交到 Git 或写入前端代码。服务响应会主动隐藏 JWT 和带查询参数的资源 URL。

自检

npm run check
npm test
npm start

npm start 是 stdio MCP 服务，正常情况下不会输出普通日志并会等待 MCP 客户端连接。

接入 Codex / ChatGPT 桌面应用

在设置中选择 MCP servers -> Add server，类型选择 STDIO：

• Command：node
• Arguments：C:\path\to\moonvy-ui-mcp\src\server.js
• Working directory：C:\path\to\moonvy-ui-mcp

也可以把以下内容加入 ~/.codex/config.toml 或可信项目内的 .codex/config.toml：

[mcp_servers.moonvy]
command = "node"
args = ["C:/path/to/moonvy-ui-mcp/src/server.js"]
cwd = "C:/path/to/moonvy-ui-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 180

服务默认从 cwd 下的 .env 读取 MOONVY_TOKEN。如希望从本机环境变量转发，也可添加：

env_vars = ["MOONVY_TOKEN"]

保存后重启 Codex/桌面应用，在输入框使用 /mcp 检查连接。

接入 Cursor / Windsurf / Claude Code

使用标准 stdio MCP 配置：

{
  "mcpServers": {
    "moonvy": {
      "command": "node",
      "args": ["C:/path/to/moonvy-ui-mcp/src/server.js"],
      "cwd": "C:/path/to/moonvy-ui-mcp"
    }
  }
}

Moonvy 链接的使用顺序

示例链接（请将占位符替换为你有权限访问的项目和目录 ID）：

https://moonvy.com/project/<projectId>/<dirId>

它包含 projectId + dirId，指向文件夹而不是具体设计文件，因此建议：

1. 调用 moonvy_list_pages 获取文件列表。
2. 选定返回结果里的具体设计 URL。
3. 调用 moonvy_get_design 查看画框列表。
4. 对目标画框调用 moonvy_get_ui_spec，先使用 maxDepth=4、maxNodes=500。
5. 若需要精确查看某个元素，先用 moonvy_list_layers 找节点 ID，再调用 moonvy_get_node_style。
6. 图标、背景图或页面快照用 moonvy_download_asset 下载到实际前端项目的资源目录。

示例提示词：

使用 Moonvy MCP 列出这个项目目录里的设计文件。找到“新增学生”页面后，
读取它的 UI spec，保留原始颜色、字号、间距和圆角，并把需要的切图下载到
C:/work/school-web/src/assets/moonvy。

与 lanhu-mcp 的对应关系

lanhu-mcp 思路	本项目实现
获取设计列表	moonvy_list_pages
分析设计图参数	moonvy_get_ui_spec / moonvy_get_node_style
获取切图	moonvy_download_asset
通过 Cookie/JWT 复用登录权限	MOONVY_TOKEN 环境变量
缓存设计数据	进程内 Genome TTL 缓存
控制模型上下文	frameId、maxDepth、maxNodes

当前版本专注“设计稿 -> 前端实现”，没有复制蓝湖项目里的需求文档分析、团队留言板和飞书协作功能。

安全与限制

• 仅使用你本来就有权限访问的 Moonvy 项目。
• .env 已加入 .gitignore；仍需避免手动提交令牌。
• moonvy_download_asset 要求绝对输出目录，防止资源被意外写入不明确位置。
• Moonvy 令牌过期后需要重新获取。
• 本项目不绕过登录、项目权限或 Moonvy 服务端访问控制。
• Genome 中不同设计工具版本的字段可能不完全一致；解析器保留了常见兼容字段，但仍建议用实际团队设计稿做一次端到端验收。
• 当前文字样式以首个文本段为准；富文本分段的下划线、链接和其他覆盖样式尚未完整输出。

开发与测试

单元测试使用合成 Genome，不需要 Moonvy 凭据：

npm test

真实项目端到端测试需要有效的 MOONVY_TOKEN：

1. moonvy_list_pages(文件夹 URL)
2. moonvy_get_design(设计文件 URL)
3. moonvy_get_ui_spec(设计文件 URL)
4. moonvy_get_node_style(设计文件 URL, 节点 ID)

仓库另提供一次可复跑的多画板回归验证：

# 默认从当前目录 .env 加载；已有其他配置文件时可指定其绝对路径。
$env:DOTENV_CONFIG_PATH = 'C:/path/to/moonvy-ui-mcp/.env'
node scripts/verify-live.mjs

该命令会启动当前源码的独立 stdio MCP 进程，只读验证 test/fixtures/css-panel-baselines.json 中 4 张画板、10 个图层的 CSS，并核对 get_ui_spec、get_tree、extract_tokens 与 get_node_style 的一致性。基准来自 2026-09-14 浏览器实际标注（颜色等价归一化为 hex，零扩展阴影显式保留 0rpx）；图层坐标累加父级后与画板坐标对照。验证固定使用 1px = 2rpx，不下载素材、不修改在线设计、不输出令牌，也不会随 npm test 自动运行。设计更新后应先在浏览器核对，再更新基准，不能直接把当前解析结果当成正确答案。