Moonvy UI MCP

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

이 프로젝트는 lanhu-mcp의 도구 경계를 참고했지만, 데이터 읽기는 Moonvy에 맞춰져 있습니다. Moonvy의 디자인 데이터 파일(Genome)에서 정확한 파라미터를 추출하며, 스크린샷으로 색상, 글꼴 크기, 간격을 추측하지 않습니다.

할 수 있는 것

moonvy_get_node_style 및 moonvy_get_ui_spec는 다음을 제공합니다:

• 절대 위치 및 부모 노드 기준 relativeX / relativeY

• 부모 노드의 오른쪽, 아래쪽 가장자리까지의 거리

• 너비/높이, 가시성, 투명도, 클리핑 상태

• 단색, 그라데이션 및 이미지 채우기 참조

• 글꼴, 글꼴 크기, 글꼴 두께, 줄 높이, 자간, 텍스트 색상 및 정렬

• 모서리 반경, 테두리, 그림자

• 직접 참조할 수 있는 CSS 속성 객체

Related MCP server: Figma MCP

데이터 파이프라인

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)

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 링크에 대한 사용 순서

현재 링크:

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와의 대응 관계

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