Astryx 文档 MCP 服务器与 AI 代理技能

一个全面的 Model Context Protocol (MCP) 服务器和 AI 代理技能，用于 Meta Astryx Design System。该项目索引了抓取的文档、组件规范、StyleX 指南和 CLI 参考，为 AI 助手和编码代理（Claude Desktop、Cursor、Project IDX、Gemini CLI、Antigravity、Windsurf）提供结构化工具和提示指南。

🚀 功能与 MCP 工具

MCP 服务器通过 stdio 暴露四个工具：

1. search_astryx_docs

   • 描述：跨所有 Astryx 文档、指南和组件 API 进行全文和关键字搜索。

   • 参数：query: string（例如，'Button'、'defineTheme'、'StyleX'、'asChild'）。

2. get_astryx_component

   • 描述：检索特定组件的使用指南、属性接口、导入和代码示例。

   • 参数：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 { Button } from '@astryxdesign/core/Button';

• 级联层：强制在 @layer astryx-base 下使用 @import '@astryxdesign/core/astryx.css';。

• StyleX 覆盖：通过 xstyle 属性使用 StyleX，而不是任意内联样式。

• 主题提供者：标准化的 <Theme mode="system" theme={neutralTheme}> 应用结构。

🌐 交互式介绍网站

包含在 index.html 中的交互式演示网站，具有以下特点：

• 实时主题浏览器：测试 6 个 Astryx 设计主题（Neutral、Butter、Stone、Gothic、Y2K、Matcha）。

• 组件游乐场：交互式属性控制，实时生成 TSX 代码。

• 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