Skip to main content
Glama
moonvy-ui-mcp

moonvy-ui-mcp

by Cc-Zzh1

Moonvy UI MCP

프론트엔드 개발을 위한 Moonvy(월유) 디자인 파일 읽기 MCP입니다. 프로젝트 페이지 또는 디자인 파일 URL을 입력하면 페이지 목록, 아트보드 크기, 레이어 트리, 노드 스타일, 디자인 토큰, 그리고 슬라이스/스냅샷/이미지 채우기 리소스를 얻을 수 있습니다.

이 프로젝트는 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

메타데이터, 토큰, 스타일이 포함된 레이어 트리를 한 번에 반환, 개발 시 우선 사용 권장

moonvy_download_asset

슬라이스, 스냅샷, 이미지 채우기 또는 최상위 파일 미리보기 다운로드

moonvy_clear_cache

디자인 파일 업데이트 후 메모리 캐시 정리

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 .env

Moonvy 로그인 토큰 설정

  1. 브라우저에서 Moonvy에 로그인하고, 읽어야 할 Moonvy 페이지를 엽니다.

  2. 개발자 도구의 Console을 엽니다.

  3. 다음을 실행합니다:

copy(window.app?.api?.$options?.token)
  1. 복사한 값을 이 프로젝트의 .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 링크에 대한 사용 순서

현재 링크:

https://moonvy.com/project/89f75621-a0e7-4122-b9ee-b6b703e1c826/cf67c54c-8e2b-4809-9e4d-fc6512d0e0be

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

현재 버전은 '디자인 파일 -> 프론트엔드 구현'에 집중하며, 란후(蓝湖) 프로젝트의 요구사항 문서 분석, 팀 게시판, 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 tools
moonvy_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

    A3.9/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables interaction with Figma files through intelligent API access, providing navigation, asset extraction, and design token retrieval with 95% token-optimized compact tree output format.
      15
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables developers to extract and organize Figma design files, including complete node data (tree structure and images) for AI understanding and code generation.
      23 PyPI
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Provides 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.
      9
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      Enables 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.
      23
      1
      MIT