Radix MCP Server

Radix UI MCP服务器

](https://badge.fury.io/js/@gianpieropuleo%2Fradix-mcp-server) 

一个轻量级的模型上下文协议（MCP）服务器，为AI助手提供全面的访问 Radix UI 库，包括主题、基本体和颜色。该服务器使Claude Desktop、Continue.dev、VS Code、Cursor和其他MCP兼容客户端等AI工具能够无缝检索和使用Radix UI组件。

🚀 主要特点

• 根主题：使用内置设计系统访问高级样式组件
• 原始根：获取无样式、可访问的组件实现
• 根的颜色：使用亮/暗模式支持检索语义色阶
• 组件源代码：获取最新的Radix UI组件TypeScript源代码
• 安装指南：所有软件包管理器的动态安装说明
• GitHub API集成：具有p-memoize和尊重速率限制的智能缓存
• 轻量级：采用现代Sindre Sorhus软件包（ky、p-limit、p-memoize）构建，以实现最小的捆绑包大小

📦 快速开始

⚡ 使用npx（推荐）

最快的入门方式-无需安装！

# Basic usage (rate limited to 60 requests/hour)
npx @gianpieropuleo/radix-mcp-server@latest

# With GitHub token for better rate limits (5000 requests/hour)
npx @gianpieropuleo/radix-mcp-server@latest --github-api-key ghp_your_token_here

# Short form
npx @gianpieropuleo/radix-mcp-server@latest -g ghp_your_token_here

# Using environment variable
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
npx @gianpieropuleo/radix-mcp-server@latest

# Select specific library
npx @gianpieropuleo/radix-mcp-server@latest --library themes
npx @gianpieropuleo/radix-mcp-server@latest --library primitives
npx @gianpieropuleo/radix-mcp-server@latest --library colors

# All libraries (default)
npx @gianpieropuleo/radix-mcp-server@latest --library all

# Using environment variable for library
export RADIX_LIBRARY=themes
npx @gianpieropuleo/radix-mcp-server@latest

🎯 现在试试：运行 npx @gianpieropuleo/radix-mcp-server@latest --help 查看所有选项！

🔧 命令行选项

radix-mcp-server [options]

Options:
  --library, -l 
         Radix library: 'themes', 'primitives', 'colors', or 'all' (default: all)
  --github-api-key, -g     GitHub Personal Access Token for API access
  --help, -h                      Show this help message
  --version, -v                   Show version information

Environment Variables:
  GITHUB_PERSONAL_ACCESS_TOKEN    Alternative way to provide GitHub token
  RADIX_LIBRARY                   Library to use: 'themes', 'primitives', 'colors', or 'all' (default: all)
  LOG_LEVEL                       Log level (debug, info, warn, error) - default: info

Examples:
  npx @gianpieropuleo/radix-mcp-server@latest
  npx @gianpieropuleo/radix-mcp-server@latest --library themes
  npx @gianpieropuleo/radix-mcp-server@latest --library primitives --github-api-key ghp_your_token_here
  npx @gianpieropuleo/radix-mcp-server@latest -l colors -g ghp_your_token_here
  npx @gianpieropuleo/radix-mcp-server@latest -l all

🎨 Radix UI库

🎭 根主题

具有内置设计系统的高级React组件。非常适合快速应用程序开发。

// Example: Get Button component from Themes
{
  "tool": "themes_get_component_source",
  "arguments": { "componentName": "button" }
}

🧩 原始根

低级、无样式、可访问的React组件。定制设计的最大灵活性。

// Example: Get Dialog primitive
{
  "tool": "primitives_get_component_source",
  "arguments": { "componentName": "dialog" }
}

🌈 根的颜色

具有语义含义和深色模式支持的美丽、可访问的色阶。

// Example: List all color scales
{
  "tool": "colors_list_scales",
  "arguments": {}
}

🔑 GitHub API令牌设置

你为什么需要代币？

• 无令牌：每小时限制为60个API请求
• 带令牌：每小时最多5000个请求
• 更高的可靠性和更快的响应速度

📝 获取代币（2分钟）

1. 转到GitHub设置:

- 访问 - 或者：GitHub个人资料→ 设置→ 开发人员设置→ 个人访问令牌

1. 生成新令牌:

- 点击“生成新令牌（经典）” - 添加注释：“Radix UI MCP服务器” - 过期：选择您的偏好（建议90天） - 范围: ✅ 不需要示波器！ （公共存储库访问权限就足够了）

1. 复制您的令牌:

- 复制生成的令牌（以开头 ghp_) - ⚠️ 安全保存 -你不会再看到它了！

🚀 使用您的令牌

方法1：命令行（快速测试）

npx @gianpieropuleo/radix-mcp-server@latest --github-api-key ghp_your_token_here

方法2：环境变量（推荐）

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here

# Then simply run:
npx @gianpieropuleo/radix-mcp-server@latest

🛠️ 编辑器集成

Claude桌面集成

添加到您的Claude Desktop配置(~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "radix-ui": {
      "command": "npx",
      "args": [
        "@gianpieropuleo/radix-mcp-server@latest",
        "--github-api-key",
        "ghp_your_token_here"
      ]
    },
    // Or for specific library only:
    "radix-themes": {
      "command": "npx",
      "args": [
        "@gianpieropuleo/radix-mcp-server@latest",
        "--library",
        "themes",
        "--github-api-key",
        "ghp_your_token_here"
      ]
    }
  }
}

或者使用环境变量：

{
  "mcpServers": {
    "radix-ui": {
      "command": "npx",
      "args": ["@gianpieropuleo/radix-mcp-server@latest"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

VS代码集成

方法1：使用Continue扩展

{
  "continue.server": {
    "mcpServers": {
      "radix-ui": {
        "command": "npx",
        "args": [
          "@gianpieropuleo/radix-mcp-server@latest",
          "--github-api-key",
          "ghp_your_token_here"
        ]
      }
    }
  }
}

方法2：使用Claude扩展

{
  "claude.mcpServers": {
    "radix-ui": {
      "command": "npx",
      "args": ["@gianpieropuleo/radix-mcp-server@latest"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

光标集成

创建一个 .cursorrules 项目根目录中的文件：

{
  "mcpServers": {
    "radix-ui": {
      "command": "npx",
      "args": ["@gianpieropuleo/radix-mcp-server@latest"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

🎯 使用示例

获取Radix主题组件

问你的AI助手：

"Show me the source code for the Radix Themes Button component"
"List all available Radix Themes components"
"How do I install and set up Radix Themes?"

使用原始根

问你的AI助手：

"Get the Dialog primitive from Radix UI"
"Show me how to use the Accordion primitive"
"List all available Radix Primitives"

使用根颜色

问你的AI助手：

"Show me the blue color scale from Radix Colors"
"How do I set up Radix Colors with CSS variables?"
"List all available color scales"

构建完整的用户界面

问你的AI助手：

"Create a dashboard using Radix Themes components"
"Build a modal dialog using Radix Primitives"
"Set up a design system with Radix Colors"

🛠️ 可用工具

MCP服务器为AI助手提供以下工具：

Radix主题工具

• themes_list_components -列出所有可用的Radix主题组件
• themes_get_component_source -获取Radix Themes组件源代码
• themes_get_component_documentation -获取Radix主题组件文档
• themes_get_getting_started -获取Radix主题的安装说明

Radix原始工具

• primitives_list_components -列出所有可用的Radix原语
• primitives_get_component_source -获取Radix Primitive组件源代码
• primitives_get_component_documentation -获取Radix Primitive组件文档
• primitives_get_getting_started -获取Radix Primitives的安装说明

根颜色工具

• colors_list_scales -列出所有可用的色阶
• colors_get_scale -获取特定的色阶定义
• colors_get_scale_documentation -获取Radix Colors文档
• colors_get_getting_started -获取Radix Colors的安装说明

工具使用示例

// Get Radix Themes Button component
{
  "tool": "themes_get_component_source",
  "arguments": { "componentName": "button" }
}

// List all Radix Primitives
{
  "tool": "primitives_list_components",
  "arguments": {}
}

// Get blue color scale
{
  "tool": "colors_get_scale",
  "arguments": { "scaleName": "blue" }
}

// Get installation guide for Radix Colors
{
  "tool": "colors_get_getting_started",
  "arguments": {}
}

⚡ 架构与性能

现代、轻便的堆栈

此MCP服务器采用一组精心策划的现代轻量级软件包构建：

• ky公司 -优雅的HTTP客户端（取代了更重的替代品）
• p极限 -尊重API使用的并发控制
• p记忆 -TTL智能功能记忆
• 到期图 -TTL缓存支持自动过期
• 皮诺 -快速、结构化的日志记录
• 动物圈 -运行时类型验证

智能缓存策略

• 24小时TTL：所有GitHub API响应缓存24小时
• 功能级记忆：每个API函数都单独存储
• 自动过期：缓存条目会自动过期，防止过时数据
• 内存效率高：只有活动数据保存在内存中

利率限制和API方面

• 并发控制：对GitHub API的最大1个并发请求
• 智能配料：相关请求尽可能分批处理
• 优雅降级：当达到速率限制时，回退到缓存数据
• 代币支持GitHub代币将请求数限制从每小时60个增加到5000个

🐛 故障排除

常见问题

“超出速率限制”错误：

# Solution: Add GitHub API token
npx @gianpieropuleo/radix-mcp-server --github-api-key ghp_your_token_here

“找不到命令”错误：

# Solution: Install Node.js 18+ and ensure npx is available
node --version  # Should be 18+
npx --version   # Should work

未找到组件：

# Check available components first
npx @gianpieropuleo/radix-mcp-server --library themes
# Then call appropriate list tool via your MCP client

图书馆选择问题：

# Verify library parameter
npx @gianpieropuleo/radix-mcp-server --library themes  # ✅ Valid
npx @gianpieropuleo/radix-mcp-server --library invalid # ❌ Invalid

调试模式

启用详细日志记录：

# Set debug environment variable
LOG_LEVEL=debug npx @gianpieropuleo/radix-mcp-server --github-api-key ghp_your_token

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🤝 贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

📞 支持

• 🐛 报告问题
• 💬 讨论
• 📖 文档
• 📦

🔗 相关项目

• Radix UI主题 -高级React组件
• Radix UI图元 -底层React组件
• 根UI颜色 -美丽的色彩系统
• 模型上下文协议 -协议规范
• MCP TypeScript SDK -官方MCP SDK

⭐ 致谢

• Radix UI团队 令人惊叹的组件库
• Anthropic 用于模型上下文协议规范
• 开源社区的灵感和贡献

______________________________________________________________________

星⭐ 如果你觉得这个仓库有用的话！还可以考虑主演 原始项目 这使得这成为可能。