moonvy-ui-mcp
Moonvy UI MCP
프론트엔드 개발을 위한 Moonvy(월유) 디자인 파일 읽기 MCP입니다. 프로젝트 페이지 또는 디자인 파일 URL을 입력하면 페이지 목록, 아트보드 크기, 레이어 트리, 노드 스타일, 디자인 토큰, 그리고 슬라이스/스냅샷/이미지 채우기 리소스를 얻을 수 있습니다.
이 프로젝트는 lanhu-mcp의 도구 경계를 참고했지만, 데이터 읽기는 Moonvy에 맞춰져 있습니다. Moonvy의 디자인 데이터 파일(Genome)에서 정확한 파라미터를 추출하며, 스크린샷으로 색상, 글꼴 크기, 간격을 추측하지 않습니다.
할 수 있는 것
MCP 도구 | 용도 |
| 프로젝트, 디렉터리, 디자인 파일 ID 파싱 |
| 프로젝트/디렉터리에서 디자인 파일 나열, 폴더 URL만 있을 때 먼저 호출 |
| 제목, 아트보드 ID, 아트보드 너비/높이, Genome 버전 가져오기 |
| 이름으로 노드 ID를 찾기 위한 평면화된 레이어 인덱스 |
| 단일 노드의 크기, 상대 좌표, 여백, 채우기, 텍스트, 모서리 반경, 테두리, 그림자 및 CSS 가져오기 |
| UI 파라미터가 포함된 중첩 레이어 트리 가져오기 |
| 색상, 그라데이션, 글꼴, 글꼴 크기, 글꼴 두께, 줄 높이, 모서리 반경, 그림자, 추론된 간격 추출 |
| 메타데이터, 토큰, 스타일이 포함된 레이어 트리를 한 번에 반환, 개발 시 우선 사용 권장 |
| 슬라이스, 스냅샷, 이미지 채우기 또는 최상위 파일 미리보기 다운로드 |
| 디자인 파일 업데이트 후 메모리 캐시 정리 |
moonvy_get_node_style 및 moonvy_get_ui_spec는 다음을 제공합니다:
절대 위치 및 부모 노드 기준
relativeX/relativeY부모 노드의 오른쪽, 아래쪽 가장자리까지의 거리
너비/높이, 가시성, 투명도, 클리핑 상태
단색, 그라데이션 및 이미지 채우기 참조
글꼴, 글꼴 크기, 글꼴 두께, 줄 높이, 자간, 텍스트 색상 및 정렬
모서리 반경, 테두리, 그림자
직접 참조할 수 있는 CSS 속성 객체
Related MCP server: figma-mcp-server
데이터 파이프라인
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이 현재 사용하는 비공개 API로, 향후 Moonvy가 API 또는 Genome 구조를 변경하면 어댑터 레이어도 함께 업데이트해야 합니다.
설치
Node.js 20 이상이 필요합니다.
cd C:\path\to\moonvy-ui-mcp
npm install
Copy-Item .env.example .envMoonvy 로그인 토큰 설정
브라우저에서 Moonvy에 로그인하고, 읽어야 할 Moonvy 페이지를 엽니다.
개발자 도구의 Console을 엽니다.
다음을 실행합니다:
copy(window.app?.api?.$options?.token)복사한 값을 이 프로젝트의
.env에 작성합니다:
MOONVY_TOKEN=你的本机令牌토큰은 로컬에만 저장되며, 채팅에 보내거나 Git에 커밋하거나 프론트엔드 코드에 작성하지 마세요. 서비스 응답은 JWT와 쿼리 파라미터가 포함된 리소스 URL을 자동으로 숨깁니다.
자체 점검
npm run check
npm test
npm startnpm start는 stdio MCP 서비스로, 정상적으로는 일반 로그를 출력하지 않고 MCP 클라이언트 연결을 대기합니다.
Codex / ChatGPT 데스크톱 앱 연동
설정에서 MCP servers -> Add server를 선택하고, 유형은 STDIO를 선택합니다:
Command:
nodeArguments:
C:\path\to\moonvy-ui-mcp\src\server.jsWorking 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 링크에 대한 사용 순서
현재 링크:
https://moonvy.com/project/89f75621-a0e7-4122-b9ee-b6b703e1c826/cf67c54c-8e2b-4809-9e4d-fc6512d0e0beprojectId + dirId를 포함하며, 특정 디자인 파일이 아닌 폴더를 가리키므로 다음을 권장합니다:
moonvy_list_pages를 호출하여 파일 목록을 가져옵니다.반환 결과에서 특정 디자인 URL을 선택합니다.
moonvy_get_design을 호출하여 아트보드 목록을 확인합니다.대상 아트보드에 대해
moonvy_get_ui_spec을 호출하고, 먼저maxDepth=4,maxNodes=500을 사용합니다.특정 요소를 정확히 확인해야 한다면, 먼저
moonvy_list_layers로 노드 ID를 찾은 후moonvy_get_node_style을 호출합니다.아이콘, 배경 이미지 또는 페이지 스냅샷은
moonvy_download_asset으로 실제 프론트엔드 프로젝트의 리소스 디렉터리에 다운로드합니다.
예시 프롬프트:
使用 Moonvy MCP 列出这个项目目录里的设计文件。找到“新增学生”页面后,
读取它的 UI spec,保留原始颜色、字号、间距和圆角,并把需要的切图下载到
C:/work/school-web/src/assets/moonvy。lanhu-mcp와의 대응 관계
lanhu-mcp 접근 방식 | 이 프로젝트 구현 |
디자인 목록 가져오기 |
|
디자인 파라미터 분석 |
|
슬라이스 가져오기 |
|
Cookie/JWT로 로그인 권한 재사용 |
|
디자인 데이터 캐시 | 프로세스 내 Genome TTL 캐시 |
모델 컨텍스트 제어 |
|
현재 버전은 '디자인 파일 -> 프론트엔드 구현'에 집중하며, 란후(蓝湖) 프로젝트의 요구사항 문서 분석, 팀 게시판, Feishu 협업 기능은 복제하지 않았습니다.
보안 및 제한 사항
원래 접근 권한이 있는 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)Available Tools
10 toolsmoonvy_clear_cacheClear Moonvy genome cacheA
Clear the in-memory genome cache after a design has changed and must be fetched again.
Inputs: no named parameters.
moonvy_download_assetDownload Moonvy assetA
Download a design slice, snapshot, image fill, or top-level file/preview into an absolute local output directory.
Inputs: url (required), nodeId (required), outputDir (required), type, +2 more.
moonvy_extract_tokensExtract Moonvy design tokensB
Extract reusable colors, gradients, fonts, text metrics, radii, inferred padding/gaps, and shadows from a design.
Inputs: url (required).
moonvy_get_designGet Moonvy design metadataA
Return the design title, genome version, frame IDs, frame dimensions, and child counts for a Moonvy design URL.
Inputs: url (required).
moonvy_get_node_styleGet exact Moonvy node styleA
Return one node’s size, coordinates, distances to parent edges, fills, typography, borders, radius, effects, opacity, visibility, and directly usable CSS declarations.
Inputs: url (required), nodeId (required).
moonvy_get_treeGet Moonvy layer treeA
Return the nested design layer tree. Styles include exact UI values and CSS. Limit depth and node count to keep model context compact.
Inputs: url (required), frameId, maxDepth, maxNodes, +2 more.
moonvy_get_ui_specGet frontend-ready Moonvy UI specA
Recommended development tool: return design metadata, inferred design tokens, and a styled component tree in one response. Use frameId/maxDepth/maxNodes to control context size.
Inputs: url (required), frameId, maxDepth, maxNodes, +1 more.
moonvy_list_layersList Moonvy layersA
Return a flat layer index with node IDs, names, types, depth, absolute bounds, and parent-relative positions. Use it to find a node ID before requesting exact style.
Inputs: url (required), frameId, maxNodes, includeHidden.
moonvy_list_pagesList Moonvy project pagesA
List folders and design files below a Moonvy project or directory URL. Call this first when only a project URL is known.
Inputs: url (required), limit, maxApiPages.
moonvy_parse_urlParse Moonvy URLA
Validate a Moonvy URL and return project, directory, and file IDs. Does not require authentication.
Inputs: url (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a distinct responsibility: URL parsing, listing pages, fetching design metadata, layer indexing, node style extraction, tree traversal, token extraction, full spec generation, asset download, and cache management. No two tools overlap in purpose, making misselection unlikely.
All tools follow a consistent 'moonvy_verb_noun' pattern using snake_case (e.g., moonvy_list_pages, moonvy_get_node_style). The prefix uniformly identifies the server, and verbs are action-oriented with descriptive nouns, creating a predictable and readable API surface.
With 10 tools, the server covers the core workflow of navigating Moonvy designs, extracting styles, tokens, specs, and assets without excess. The count is well-scoped for its purpose—neither too sparse nor bloated.
The tool surface covers the full design-to-code pipeline: parse URLs, navigate hierarchy, retrieve detailed node styles, extract tokens, generate UI specs, and download assets. A minor gap is the lack of tools for editing or creating designs, but given the read-focused nature of this server, the existing set is comprehensive and leaves no dead ends for typical usage.
Related MCP Connectors
Access and maintain design system docs, tokens, components, skills, and contexts across any project.
Turn any live website into brand colors, fonts, design tokens, SVGs, Lottie and paste-ready code.
Visual builder for React Native and Expo apps. Read and update project design tokens.
Search 700+ design layers and fetch the build prompt for HTML, Next.js, React, Vue and more.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables interaction with Figma files through intelligent API access, providing navigation, asset extraction, and design token retrieval with 95% token-optimized compact tree output format.151MIT
- AlicenseNot gradedqualityDmaintenanceEnables developers to extract and organize Figma design files, including complete node data (tree structure and images) for AI understanding and code generation.23 PyPIMIT
- AlicenseAqualityCmaintenanceProvides AI coding agents with structured access to Lanhu design data, enabling direct inspection of artboards, extraction of pixel-perfect layer styles and CSS attributes, and downloading of design assets without vision token overhead.9MIT
- AlicenseCqualityBmaintenanceEnables AI clients to read design pages, screenshots, original assets, styles, and workflows from Lanhu, Figma, and Mockplus, inspect elements, download resources, and build local page-flow maps.231MIT