Astryx-Dokumentations-MCP-Server & KI-Agenten-Skill

Ein umfassender Model Context Protocol (MCP)-Server und eine KI-Agenten-Fähigkeit für das Meta Astryx Design System. Dieses Projekt indexiert gescrapte Dokumentationen, Komponentenspezifikationen, StyleX-Anleitungen und CLI-Referenzen und stellt strukturierte Tools und Prompt-Richtlinien für KI-Assistenten und Codierungsagenten (Claude Desktop, Cursor, Project IDX, Gemini CLI, Antigravity, Windsurf) bereit.

🚀 Funktionen & MCP-Tools

Der MCP-Server stellt vier Tools über stdio bereit:

1. search_astryx_docs

   • Beschreibung: Volltext- und Stichwortsuche in der gesamten Astryx-Dokumentation, den Anleitungen und den Komponenten-APIs.

   • Parameter: query: string (z. B. 'Button', 'defineTheme', 'StyleX', 'asChild').

2. get_astryx_component

   • Beschreibung: Ruft Nutzungsrichtlinien, Prop-Schnittstellen, Importe und Codebeispiele für eine bestimmte Komponente ab.

   • Parameter: componentName: string (z. B. 'Button', 'AppShell', 'Table', 'Avatar', 'Dialog', 'Input').

3. get_theme_guide

   • Beschreibung: Ruft Informationen zu den 6 integrierten Themes (Neutral, Butter, Stone, Gothic, Y2K, Matcha), CSS-Variablen-Design-Tokens und benutzerdefinierten Theme-Definitionen mit defineTheme ab.

   • Parameter: themeName?: string (z. B. 'butter', 'neutral', 'defineTheme').

4. get_cli_commands

   • Beschreibung: Dokumentation für @astryxdesign/cli und Befehle (init, doctor, template, manifest, theme build, swizzle).

   • Parameter: command?: string (z. B. 'init', 'doctor', 'template', 'manifest', 'theme build', 'swizzle').

🤖 Astryx-Agenten-Skill (astryx-skill)

Dieser Skill befindet sich in astryx-skill/SKILL.md und bietet maßgebliche Codierungsmuster und Regeln:

• Subpath-Importe: import { Button } from '@astryxdesign/core/Button';

• Cascade-Layer: Erzwingt @import '@astryxdesign/core/astryx.css'; unter @layer astryx-base.

• StyleX-Überschreibungen: Verwendet StyleX über die xstyle-Prop anstelle von beliebigen Inline-Stilen.

• Theme-Provider: Standardisierte <Theme mode="system" theme={neutralTheme}>-Anwendungsstruktur.

🌐 Interaktive Intro-Website

Eine interaktive Präsentationswebsite ist in index.html enthalten und bietet:

• Live-Theme-Explorer: Testen Sie die 6 Astryx-Design-Themes (Neutral, Butter, Stone, Gothic, Y2K, Matcha).

• Komponenten-Playground: Interaktive Prop-Steuerung mit Echtzeit-TSX-Codegenerierung.

• MCP-Server-Stdio-Simulator: Interaktiver Test-Runner für Suchtools.

• One-Click-Publishing-Matrix: Einfache Einrichtung für GitHub Pages, Vercel, Netlify und Cloudflare Pages.

🛠️ Erste Schritte

Voraussetzungen

• Node.js >= 18.0.0

• npm / pnpm / yarn

Installation

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

Build & Ausführen

# 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

🔌 Verbindung zu KI-IDEs und Clients

1. Claude Desktop

Fügen Sie Folgendes zu Ihrer claude_desktop_config.json hinzu:

• 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

Fügen Sie zur .cursor/mcp.json oder mcp.json Ihres Projekts hinzu:

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

📂 Projektstruktur

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

📄 Lizenz

MIT