Moonvy UI MCP

MCP для чтения дизайн-файлов Moonvy (月维), ориентированный на фронтенд-разработку. Введите 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. Если 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 ресурсов с query-параметрами.

Самопроверка

npm run check
npm test
npm start

npm start — это stdio MCP-сервис; в обычном режиме он не выводит обычных логов и ожидает подключения MCP-клиента.

Подключение к Codex / ChatGPT Desktop

В настройках выберите 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

Сервис по умолчанию читает MOONVY_TOKEN из .env в cwd. Если хотите пробрасывать из переменных окружения машины, добавьте также:

env_vars = ["MOONVY_TOKEN"]

После сохранения перезапустите Codex/Desktop-приложение и проверьте подключение через /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. Если нужно точно рассмотреть какой-то элемент, сначала найдите ID узла через moonvy_list_layers, затем вызовите moonvy_get_node_style.

6. Иконки, фоновые изображения или снимки страниц скачивайте через moonvy_download_asset в каталог ресурсов реального фронтенд-проекта.

Пример промпта:

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

Соответствие lanhu-mcp

Текущая версия сфокусирована на пути «дизайн-файл -> фронтенд-реализация» и не копирует из проекта Lanhu анализ требований, командную доску и интеграцию с 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)