Astryx Documentation MCP Server & AI Agent Skill

A comprehensive Model Context Protocol (MCP) server and AI Agent Skill for the Meta Astryx Design System. This project indexes scraped documentation, component specifications, StyleX guides, and CLI references, exposing structured tools and prompt guidelines for AI assistants and coding agents (Claude Desktop, Cursor, Project IDX, Gemini CLI, Antigravity, Windsurf).

🚀 Features & MCP Tools

The MCP server exposes four tools over stdio:

1. search_astryx_docs

   • Description: Full-text and keyword search across all Astryx documentation, guides, and component APIs.

   • Parameters: query: string (e.g., 'Button', 'defineTheme', 'StyleX', 'asChild').

2. get_astryx_component

   • Description: Retrieve usage guidelines, prop interfaces, imports, and code examples for a specific component.

   • Parameters: componentName: string (e.g., 'Button', 'AppShell', 'Table', 'Avatar', 'Dialog', 'Input').

3. get_theme_guide

   • Description: Retrieve information on the 6 built-in themes (Neutral, Butter, Stone, Gothic, Y2K, Matcha), CSS variable design tokens, and custom theme definitions with defineTheme.

   • Parameters: themeName?: string (e.g., 'butter', 'neutral', 'defineTheme').

4. get_cli_commands

   • Description: Documentation for @astryxdesign/cli and commands (init, doctor, template, manifest, theme build, swizzle).

   • Parameters: command?: string (e.g., 'init', 'doctor', 'template', 'manifest', 'theme build', 'swizzle').

🤖 Astryx Agent Skill (astryx-skill)

Located in astryx-skill/SKILL.md, this skill provides authoritative coding patterns and rules:

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

• Cascade Layers: Enforces @import '@astryxdesign/core/astryx.css'; under @layer astryx-base.

• StyleX Overrides: Uses StyleX via xstyle prop instead of arbitrary inline styles.

• Theme Provider: Standardized <Theme mode="system" theme={neutralTheme}> application structure.

🌐 Interactive Intro Website

An interactive presentation website is included in index.html, featuring:

• Live Theme Explorer: Test the 6 Astryx design themes (Neutral, Butter, Stone, Gothic, Y2K, Matcha).

• Component Playground: Interactive prop controls with real-time TSX code generation.

• MCP Server Stdio Simulator: Interactive search tool test runner.

• One-Click Publishing Matrix: Simple setup for GitHub Pages, Vercel, Netlify, and Cloudflare Pages.

🛠️ Getting Started

Prerequisites

• 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 & Run

# 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

🔌 Connecting to AI IDEs & Clients

1. Claude Desktop

Add the following to your 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

Add to your project's .cursor/mcp.json or mcp.json:

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

📂 Project Structure

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

📄 License

MIT