{"id":50791409,"url":"https://github.com/cinob/moonvy-design-mcp","last_synced_at":"2026-06-12T11:30:26.733Z","repository":{"id":362878831,"uuid":"1251371520","full_name":"cinob/moonvy-design-mcp","owner":"cinob","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-06T09:57:14.000Z","size":61,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T11:21:24.606Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cinob.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-27T14:08:40.000Z","updated_at":"2026-06-06T09:57:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cinob/moonvy-design-mcp","commit_stats":null,"previous_names":["cinob/moonvy-design-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/cinob/moonvy-design-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cinob%2Fmoonvy-design-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cinob%2Fmoonvy-design-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cinob%2Fmoonvy-design-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cinob%2Fmoonvy-design-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cinob","download_url":"https://codeload.github.com/cinob/moonvy-design-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cinob%2Fmoonvy-design-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34243051,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-12T11:30:21.153Z","updated_at":"2026-06-12T11:30:22.395Z","avatar_url":"https://github.com/cinob.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Moonvy Design MCP\n\n从 Moonvy 设计页面提取前端样式信息的本地工具链，基于 [OpenCLI](https://github.com/jackwener/opencli) 适配器实现。\n\n## 功能\n\n```bash\n# 设计稿元数据（标题、画框尺寸）\nopencli moonvy design \u003curl\u003e -f json\n\n# 项目页面/文件列表\nopencli moonvy pages \u003curl\u003e -f json\n\n# 图层列表（ID、名称、类型、位置）\nopencli moonvy layers \u003curl\u003e --limit 20 -f json\n\n# 单个节点的样式（背景色、字号、圆角等）\nopencli moonvy style \u003curl\u003e --node \"4:1224\" -f json\n\n# 完整图层树（可附带每个节点的样式）\nopencli moonvy tree \u003curl\u003e --with-style -f json\n\n# 提取设计 Token（颜色、字号、圆角、间距）\nopencli moonvy tokens \u003curl\u003e -f json\n\n# 下载节点切图、快照或关联图片\nopencli moonvy asset \u003curl\u003e --node \"4:1224\" [--type slice|snapshot|image] [--slice-format format] [--name name] [--out dir]\n```\n\n## 安装\n\n下载本项目：\n\n```bash\nnpx degit cinob/moonvy-design-mcp moonvy-design-mcp\ncd moonvy-design-mcp\n```\n\n安装依赖并链接 Moonvy OpenCLI 适配器：\n\n```bash\nnpm install     # postinstall 会自动创建符号链接到 ~/.opencli/clis/moonvy/\nnpm run status  # 查看链接状态\n```\n\n也可以使用 `pnpm install` 或 `bun install`，安装后同样会执行 `postinstall`。\n\n需要已登录 Moonvy 的浏览器会话（复用本地登录状态）。\n\n## 工作原理\n\n```\nMoonvy 页面 (需要登录)\n    ↓\nOpenCLI 浏览器自动化 (获取 JWT Token)\n    ↓\nMoonvy API: POST /v2/anynode/get (获取 genome 文件 URL)\n    ↓\n下载并解压 genome.json (gzip)\n    ↓\n解析图层树、样式、设计 Token → JSON 输出\n```\n\n## 项目结构\n\n```\nmoonvy-design-mcp/\n├── package.json\n├── server.js                 # MCP stdio server，薄封装 opencli moonvy 命令\n├── sync-adapters.sh          # link/unlink 符号链接\n├── adapters/moonvy/          # 适配器源码\n│   ├── shared.js             # API 客户端、genome 解析\n│   ├── design.js\n│   ├── pages.js\n│   ├── layers.js\n│   ├── style.js\n│   ├── tree.js\n│   └── tokens.js\n└── site/                     # API 发现记录 \u0026 验证 fixtures\n    ├── notes.md\n    ├── endpoints.json\n    └── verify/\n```\n\n适配器通过符号链接映射到 `~/.opencli/clis/moonvy/`，修改源码立即生效。\n\n## 脚本\n\n```bash\n./sync-adapters.sh link      # 创建符号链接\n./sync-adapters.sh unlink    # 移除符号链接\n./sync-adapters.sh status    # 查看当前状态\n\nnpm run link\nnpm run unlink\nnpm run status\nnpm run check                # 检查 MCP server 语法\nnpm run mcp                  # 以 stdio 方式启动 MCP server\n```\n\n## 在 Claude Code 中安装 MCP\n\n当前 MCP server 是 OpenCLI 的薄封装，内部仍然调用 `opencli moonvy ... -f json`。\n\n```bash\nclaude mcp add -s project moonvy -- node ./server.js\n```\n\n查看或移除：\n\n```bash\nclaude mcp list\nclaude mcp get moonvy\nclaude mcp remove moonvy\n```\n\n暴露的 MCP 工具：\n\n- `moonvy_get_design`\n- `moonvy_list_pages`\n- `moonvy_list_layers`\n- `moonvy_get_node_style`\n- `moonvy_get_tree`\n- `moonvy_extract_tokens`\n- `moonvy_sync_project`\n- `moonvy_search_designs`\n- `moonvy_get_tree_by_name`\n- `moonvy_download_asset`\n\n## Claude Code 推荐工作流\n\n`moonvy-design-mcp` 是工具项目，`.moonvy-mcp/` 应创建在真实前端项目根目录中。项目索引类工具都要求传入绝对路径 `workspaceDir`，避免误写到工具项目自身。\n\n推荐在真实前端项目中安装 MCP 时使用工具项目的绝对路径：\n\n```bash\nclaude mcp add -s project moonvy -- node /path/to/moonvy-design-mcp/server.js\n```\n\n首次使用时同步 Moonvy 项目索引：\n\n```text\n调用 moonvy_sync_project：\n- projectUrl: Moonvy 项目链接\n- workspaceDir: 真实前端项目根目录绝对路径\n```\n\n同步会创建：\n\n```text\n\u003cworkspaceDir\u003e/.moonvy-mcp/catalog.json\n\u003cworkspaceDir\u003e/.moonvy-mcp/aliases.json  # 如果不存在则创建空对象\n```\n\n`catalog.json` 默认只保存 `type: \"design\"` 的设计图条目；如需收录其它资源类型，可在 `moonvy_sync_project` 传 `types`。保存字段是白名单：设计图 ID、名称、类型、脱敏后的链接、项目 ID、父级 ID、别名、标签和同步时间。同步不会保存 cookie、JWT、API 原始响应或完整设计树，也不会覆盖用户已维护的 `.moonvy-mcp/aliases.json`。\n\n后续开发时可以让 Claude Code 先查索引：\n\n```text\n请读取当前项目的 .moonvy-mcp，找到“首页”设计稿，并根据它还原 pages/index/index.vue。\n```\n\n推荐流程：\n\n1. `moonvy_search_designs` 根据页面名、组件名、文件路径或别名查找设计图。\n2. `moonvy_get_tree_by_name` 通过设计图名称获取完整 tree/style。\n3. Claude Code 结合现有代码实现 UI。\n4. 启动真实项目验证页面效果。\n\n业务项目建议维护：\n\n```text\n.moonvy-mcp/\n├── catalog.json      # 工具同步生成，可按需提交\n├── aliases.json      # 用户维护的代码文件到设计图映射\n└── cache/            # 后续缓存目录，默认不需要提交\n```\n\n业务项目 `.gitignore` 建议包含：\n\n```gitignore\n.moonvy-mcp/cache/\n.moonvy-mcp/*.local.json\n```\n\n如果设计图名称或链接也属于敏感信息，则不要提交整个 `.moonvy-mcp/`。\n\n## 切图与静态资源下载\n\n除了样式解析，工具还支持导出和下载设计稿中节点相关的切图（Slices）、画布快照（Snapshots）以及节点图片填充（Image Fills）：\n\n```bash\n# 下载指定图层的切图（默认导出 SVG 格式，可指定为 png/max 等高倍率格式）\nopencli moonvy asset \u003curl\u003e --node \"120:4603\" --slice-format max --out ./assets\n\n# 下载指定图层所处位置的快照图片\nopencli moonvy asset \u003curl\u003e --node \"58:4363\" --type snapshot --name \"welcome_preview\"\n\n# 下载节点的图片填充背景图\nopencli moonvy asset \u003curl\u003e --node \"59:4441\" --type image\n```\n\n支持的资源类型 (`--type`)：\n- `slice`: 图层配置的切图输出（通常为设计师手动标记导出的图标等）。\n- `snapshot`: 节点自身的画布预览（支持自动向上级画板回溯定位快照）。\n- `image`: 节点 `fills` 属性中填充的原始图片。\n\n`--slice-format` 支持指定切图尺寸与比例：例如 `svg`、`base` (1x)、`max` (最高倍率，通常为 4x/2x)。\n\n---\n\n## Node ID 格式\n\nMoonvy 使用 Figma 风格的节点 ID：`4:1221`、`I4:1222;4:1005;4:69`\n\n可通过 `opencli moonvy layers \u003curl\u003e` 获取设计稿中的所有节点 ID。\n\n## HTML 还原推荐流程\n\n```bash\n# 1. 获取 frame 尺寸\nopencli moonvy design \u003curl\u003e -f json\n\n# 2. 获取完整树和样式，作为生成 HTML 的主要输入\nopencli moonvy tree \u003curl\u003e --with-style -f json\n\n# 3. 如需快速定位节点，可限制深度\nopencli moonvy tree \u003curl\u003e --with-style --max-depth 2 -f json\n```\n\n还原时不要只看组件父节点。按钮、表单、图标的真实颜色和圆角经常在子节点 `bg`、`text`、`Path` 上。\n\n## 限制\n\n- 需要已登录的浏览器会话\n- 仅支持读取，不支持修改设计\n- 设计数据来源为 Moonvy 的 genome 文件格式\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcinob%2Fmoonvy-design-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcinob%2Fmoonvy-design-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcinob%2Fmoonvy-design-mcp/lists"}