Astryx Documentation MCP Server & AI Agent Skill

Meta Astryx Design System을 위한 포괄적인 Model Context Protocol (MCP) 서버 및 AI 에이전트 스킬입니다. 이 프로젝트는 스크랩된 문서, 컴포넌트 사양, StyleX 가이드, CLI 참조 자료를 인덱싱하여 AI 어시스턴트와 코딩 에이전트(Claude Desktop, Cursor, Project IDX, Gemini CLI, Antigravity, Windsurf)를 위한 구조화된 도구와 프롬프트 지침을 제공합니다.

🚀 기능 및 MCP 도구

MCP 서버는 stdio를 통해 4가지 도구를 제공합니다:

1. search_astryx_docs

   • 설명: 모든 Astryx 문서, 가이드, 컴포넌트 API에 대한 전체 텍스트 및 키워드 검색입니다.

   • 매개변수: query: string (예: 'Button', 'defineTheme', 'StyleX', 'asChild').

2. get_astryx_component

   • 설명: 특정 컴포넌트의 사용 지침, prop 인터페이스, import, 코드 예제를 검색합니다.

   • 매개변수: componentName: string (예: 'Button', 'AppShell', 'Table', 'Avatar', 'Dialog', 'Input').

3. get_theme_guide

   • 설명: 6가지 기본 제공 테마(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 에이전트 스킬 (astryx-skill)

astryx-skill/SKILL.md에 위치한 이 스킬은 표준 코딩 패턴과 규칙을 제공합니다:

• 하위 경로 import: import { Button } from '@astryxdesign/core/Button';

• 캐스케이드 레이어: @layer astryx-base 아래에 @import '@astryxdesign/core/astryx.css';를 강제합니다.

• StyleX 오버라이드: 임의의 인라인 스타일 대신 xstyle prop을 통해 StyleX를 사용합니다.

• 테마 프로바이더: 표준화된 <Theme mode="system" theme={neutralTheme}> 애플리케이션 구조입니다.

🌐 인터랙티브 소개 웹사이트

index.html에 인터랙티브 프레젠테이션 웹사이트가 포함되어 있으며, 다음과 같은 기능을 제공합니다:

• 라이브 테마 탐색기: 6가지 Astryx 디자인 테마(Neutral, Butter, Stone, Gothic, Y2K, Matcha)를 테스트할 수 있습니다.

• 컴포넌트 플레이그라운드: 실시간 TSX 코드 생성을 지원하는 인터랙티브 prop 컨트롤입니다.

• MCP 서버 Stdio 시뮬레이터: 인터랙티브 검색 도구 테스트 러너입니다.

• 원클릭 게시 매트릭스: 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