Astryx Documentation MCP Server & AI Agent Skill

Полнофункциональный сервер Model Context Protocol (MCP) и навык AI-агента для Meta Astryx Design System. Этот проект индексирует собранную документацию, спецификации компонентов, руководства по StyleX и справочники CLI, предоставляя структурированные инструменты и рекомендации по промптам для AI-ассистентов и агентов разработки (Claude Desktop, Cursor, Project IDX, Gemini CLI, Antigravity, Windsurf).

🚀 Возможности и инструменты MCP

MCP-сервер предоставляет четыре инструмента через stdio:

1. search_astryx_docs

   • Описание: Полнотекстовый поиск и поиск по ключевым словам по всей документации Astryx, руководствам и API компонентов.

   • Параметры: query: string (например, 'Button', 'defineTheme', 'StyleX', 'asChild').

2. get_astryx_component

   • Описание: Получение руководств по применению, работа с интерфейсами пропсов, данными импортов и примерами кода для конкретного компонента.

   • Параметры: componentName: string (например, 'Button', 'AppShell', 'Table', 'Avatar', 'Dialog', 'Input').

3. get_theme_guide

   • Описание: Получение информации о шести встроенных темах (Neutral, Butter, Stone, Gothic, Y2K, Matcha), дизайн-токенах CSS-переменных и пользовательских определениях тем с помощью defineTheme.

   • Параметры: themeName?: string (например, 'butter', 'neutral', 'defineTheme').

4. get_cli_commands

   • Описание: Документация для @astryxdesign/cli и команд (init, doctor, template, manifest, theme build, swizzle).

   • Параметры: command?: string (например, 'init', 'doctor', 'template', 'manifest', 'theme build', 'swizzle').

🤖 Astryx Agent Skill (astryx-skill)

Находится в astryx-skill/SKILL.md и предоставляет эталонные паттерны и правила кодирования:

• Подпутевые импорты: import { Button } from '@astryxdesign/core/Button';

• Каскадные слои: Предписывает @import '@astryxdesign/core/astryx.css'; внутри @layer astryx-base.

• Переопределение стиле́й через StyleX: Используйте StyleX через проп xstyle вместо произвольных инлайн-стилей.

• Провайдер темы: Стандартизированная структура приложения <Theme mode="system" theme={neutralTheme}>.

🌐 Интерактивный вводный веб-сайт

В index.html включён интерактивный презентационный сайт, предлагающий пользователю:

• Живой обзор тем: Проверьте 6 тем дизайна Astryx (Neutral, Butter, Stone, Gothic, Y2K, Matcha).

• Площадка компонентов: Интерактивное управление пропами с генерацией TSX-кода в реальном времени.

• Симулятор stdio для MCP-сервера: Интерактивный тестовый запуск инструментов поиска.

• Матрица публикации в один клик: Простая настройка для GitHub Pages, Vercel, Netlify и Cloudflare Pages.

🛠️ Начало работы

Необходимые условия

• Node.js >= 18.0.0

• npm / pnpm / yarn

Установка

git clone https://github.com/georgemathunjaga/astryx-mcp-and-skill.git
cd astryx-mcp-and-skill
npm install

Сборка и запуск

# Build TypeScript and bundle crawl data to dist/
npm run build

# Start the MCP server using node (stdio)
npm start

# Run in development mode with live TypeScript compilation
npm run dev

# Run automated integration tests
npm test

🔌 Подключение к AI-IDE и клиентам

1. Claude Desktop

Добавьте следующее содержимое в claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "astryx-docs": {
      "command": "node",
      "args": ["E:/workspace/public-repos/astryx-mcp/dist/index.js"]
    }
  }
}

2. Google Project IDX / Gemini CLI / Cursor

Добавьте в .cursor/mcp.json вашего проекта или в mcp.json:

{
  "mcpServers": {
    "astryx-docs": {
      "command": "node",
      "args": ["E:/workspace/public-repos/astryx-mcp/dist/index.js"]
    }
  }
}

📂 Структура проекта

astryx-mcp/
├── astryx-skill/             # Astryx Agent Skill instructions
│   ├── SKILL.md
│   └── astryx-skill.md
├── index.html                # Interactive Intro Website
├── styles.css                # Master CSS Design System
├── app.js                    # Interactive Website Logic & MCP Simulator
├── dist/                     # Compiled JavaScript output & assets
│   ├── index.js
│   └── data/
│       └── astryx_crawl.json
├── src/
│   ├── data/
│   │   └── astryx_crawl.json # Crawled Astryx documentation dataset
│   └── index.ts              # MCP Server definition and tool handlers
├── test/
│   └── mcp-test.js           # MCP Stdio verification suite
├── package.json
├── tsconfig.json
└── README.md

📄 Лицензия

MIT