# Astryx Documentation MCP Server & AI Agent Skill

A comprehensive [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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`](file:///e:/workspace/public-repos/astryx-mcp/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
```bash
git clone https://github.com/georgemathunjaga/astryx-mcp-and-skill.git
cd astryx-mcp-and-skill
npm install
```

### Build & Run
```bash
# 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`

```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`:

```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