Servidor MCP de Documentación de Astryx y Skill de Agente de IA

Un servidor completo de Model Context Protocol (MCP) y Skill de Agente de IA para el Meta Astryx Design System. Este proyecto indexa documentación recopilada, especificaciones de componentes, guías de StyleX y referencias de CLI, exponiendo herramientas estructuradas y pautas de prompt para asistentes de IA y agentes de codificación (Claude Desktop, Cursor, Project IDX, Gemini CLI, Antigravity, Windsurf).

🚀 Características y herramientas MCP

El servidor MCP expone cuatro herramientas a través de stdio:

1. search_astryx_docs

   • Descripción: Búsqueda de texto completo y por palabras clave en toda la documentación de Astryx, guías y APIs de componentes.

   • Parámetros: query: string (p. ej., 'Button', 'defineTheme', 'StyleX', 'asChild').

2. get_astryx_component

   • Descripción: Obtener pautas de uso, interfaces de props, importaciones y ejemplos de código para un componente específico.

   • Parámetros: componentName: string (p. ej., 'Button', 'AppShell', 'Table', 'Avatar', 'Dialog', 'Input').

3. get_theme_guide

   • Descripción: Obtener información sobre los 6 temas integrados (Neutral, Butter, Stone, Gothic, Y2K, Matcha), tokens de diseño de variables CSS y definiciones de temas personalizados con defineTheme.

   • Parámetros: themeName?: string (p. ej., 'butter', 'neutral', 'defineTheme').

4. get_cli_commands

   • Descripción: Documentación para @astryxdesign/cli y sus comandos (init, doctor, template, manifest, theme build, swizzle).

   • Parámetros: command?: string (p. ej., 'init', 'doctor', 'template', 'manifest', 'theme build', 'swizzle').

🤖 Skill de Agente de Astryx (astryx-skill)

Ubicado en astryx-skill/SKILL.md, este skill proporciona patrones y reglas de codificación de referencia:

• Importaciones de subruta: import { Button } from '@astryxdesign/core/Button';

• Capas en cascada: Aplica @import '@astryxdesign/core/astryx.css'; bajo @layer astryx-base.

• Anulaciones de StyleX: Usa StyleX mediante la prop xstyle en lugar de estilos en línea arbitrarios.

• Proveedor de tema: Estructura de aplicación estandarizada <Theme mode="system" theme={neutralTheme}>.

🌐 Sitio web interactivo de introducción

Se incluye un sitio web de presentación interactivo en index.html, que ofrece:

• Explorador de temas en vivo: Prueba los 6 temas de diseño de Astryx (Neutral, Butter, Stone, Gothic, Y2K, Matcha).

• Campo de pruebas de componentes: Controles interactivos de props con generación de código TSX en tiempo real.

• Simulador de stdio del servidor MCP: Ejecutor de pruebas interactivo para la herramienta de búsqueda.

• Matriz de publicación con un clic: Configuración sencilla para GitHub Pages, Vercel, Netlify y Cloudflare Pages.

🛠️ Primeros pasos

Requisitos previos

• Node.js >= 18.0.0

• npm / pnpm / yarn

Instalación

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

Compilar y ejecutar

# 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

🔌 Conexión con IDEs y clientes de IA

1. Claude Desktop

Añade lo siguiente a tu 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

Añade lo siguiente a .cursor/mcp.json o mcp.json de tu proyecto:

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

📂 Estructura del proyecto

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

📄 Licencia

MIT