heroui-v2-mcp

MCP (Model Context Protocol) сервер для документации компонентов HeroUI v2 (https://v2.heroui.com), исходного кода, стилей и токенов темы.

В отличие от официального @heroui/react-mcp, который ориентирован на HeroUI v3 и требует развернутого Cloudflare Worker + R2 bucket + проекта PostHog, это автономный локальный сервер: он загружает все данные по запросу напрямую из heroui-inc/heroui@main (ветка, соответствующая v2.x) и raw.githubusercontent.com, кэшируя результаты в памяти на время работы процесса. Не требуется ни облачная учетная запись, ни развертывание API, ни конвейер извлечения данных.

Зачем отдельный проект

HeroUI v3 (ветка v3, сайт heroui.com) и v2 (ветка main, сайт v2.heroui.com) — это разные, несовместимые модели компонентов: разная структура пакетов, отсутствие llms.txt на сайте v2, другая структура папок документации (/docs/components/* против /docs/react/*), другой подход к стилизации (файлы tailwind-variants в packages/core/theme/src/components против того, что использует v3). Официальный MCP явно отказывается обслуживать документацию v2, поэтому этот проект повторяет его интерфейс инструментов, но указывает на источники данных v2.

Related MCP server: UI Toolkit MCP Server

Инструменты

Установка и запуск

Пакет опубликован в npm как heroui-v2-mcp, поэтому для его использования не требуется клонирование или сборка.

Использование с Claude Code / Claude Desktop / Cursor

Добавьте в конфигурацию MCP — npx загрузит и запустит его по запросу:

{
  "mcpServers": {
    "heroui-v2": {
      "command": "npx",
      "args": ["-y", "heroui-v2-mcp"]
    }
  }
}

Или установите глобально и укажите путь к бинарному файлу напрямую:

npm install -g heroui-v2-mcp

{
  "mcpServers": {
    "heroui-v2": {
      "command": "heroui-v2-mcp"
    }
  }
}

Локальная разработка (из исходного кода)

npm install
npm run dev         # tsx --watch, runs src/server.ts directly (no build step)
npm run inspect      # launches @modelcontextprotocol/inspector against src/server.ts
npm run build        # emits dist/server.js

Ограничения GitHub по количеству запросов

Списки каталогов проходят через REST API GitHub, который имеет ограничение 60 запросов/час без аутентификации. Содержимое файлов (raw.githubusercontent.com) не подпадает под это ограничение. Если вы получаете ошибки 403 при просмотре многих компонентов, установите токен:

export GITHUB_TOKEN=ghp_xxx   # no scopes needed, just raises the rate limit to 5000/hr

Как разрешаются данные

• Список компонентов = файлы в apps/docs/content/docs/components/*.mdx в ветке main.

• Большинство слаг-идентификаторов документации сопоставляются 1:1 с пакетом packages/components/<slug>. Некоторые страницы документации описывают подкомпоненты, входящие в состав другого пакета (например, textarea поставляется внутри @heroui/input, checkbox-group внутри @heroui/checkbox) — см. COMPONENT_PACKAGE_ALIASES в src/constants.ts.

• Таблицы свойств/API извлекаются из литерала JSX <APITable data={[...]} />, встроенного в каждую страницу документации .mdx (этот массив вычисляется как литерал JS — это статические данные из официального репозитория, а не произвольный/недоверенный ввод).

• Токены темы берутся из packages/core/theme/src/colors/{semantic,common}.ts и default-layout.ts.

Кэширование

Каждый ответ GitHub (содержимое файла или список каталогов) кэшируется в памяти на 30 минут (CACHE_TTL_MS в src/constants.ts). Перезапустите процесс, чтобы принудительно обновить кэш раньше.