内容
# Radix UI MCP 服务器
[](https://badge.fury.io/js/@gianpieropuleo%2Fradix-mcp-server)
[](https://opensource.org/licenses/MIT)
一个轻量级的模型上下文协议（MCP）服务器，为 AI 助手提供对 [Radix UI](https://www.radix-ui.com/) 库的全面访问，包括主题、基元和颜色。该服务器使 Claude Desktop、Continue.dev、VS Code、Cursor 等 AI 工具以及其他 MCP 兼容客户端能够无缝地检索和处理 Radix UI 组件。
> **建立在 [shadcn-ui-mcp-server](https://github.com/Jpisnice/shadcn-ui-mcp-server) 的优秀基础上，由 [@Jpisnice](https://github.com/Jpisnice) 构建。** 该项目改编了该工作，以专注于 Radix UI 生态系统，同时保持相同的强大 MCP 集成能力。
## 🚀 主要功能
- **Radix 主题**：访问具有内置设计系统的高级样式组件
- **Radix 基元**：获取未样式化、可访问的组件实现
- **Radix 颜色**：检索具有浅色/深色模式支持的语义颜色刻度
- **组件源代码**：获取最新的 Radix UI 组件 TypeScript 源代码
- **安装指南**：适用于所有包管理器的动态安装说明
- **GitHub API 集成**：使用 p-memoize 和尊重的速率限制进行智能缓存
- **轻量级**：使用现代 Sindre Sorhus 包（ky、p-limit、p-memoize）构建，以最小化捆绑包大小
## 📦 快速入门
### ⚡ 使用 npx（推荐）
最快的入门方式 - 无需安装！
```bash
# 基本用法（限速 60 请求/小时）
npx @gianpieropuleo/radix-mcp-server@latest
# 使用 GitHub 令牌获得更好的速率限制（5000 请求/小时）
npx @gianpieropuleo/radix-mcp-server@latest --github-api-key ghp_your_token_here
# 简写
npx @gianpieropuleo/radix-mcp-server@latest -g ghp_your_token_here
# 使用环境变量
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
npx @gianpieropuleo/radix-mcp-server@latest
# 选择特定库
npx @gianpieropuleo/radix-mcp-server@latest --library themes
npx @gianpieropuleo/radix-mcp-server@latest --library primitives
npx @gianpieropuleo/radix-mcp-server@latest --library colors
# 所有库（默认）
npx @gianpieropuleo/radix-mcp-server@latest --library all
# 使用环境变量指定库
export RADIX_LIBRARY=themes
npx @gianpieropuleo/radix-mcp-server@latest
```
**🎯 立即试用**：运行 `npx @gianpieropuleo/radix-mcp-server@latest --help` 查看所有选项！
### 🔧 命令行选项
```bash
radix-mcp-server [选项]
选项：
--library, -l <library> Radix 库：'themes'、'primitives'、'colors' 或 'all'（默认：all）
--github-api-key, -g <token> GitHub 个人访问令牌，用于 API 访问
--help, -h 显示帮助信息
--version, -v 显示版本信息
环境变量：
GITHUB_PERSONAL_ACCESS_TOKEN 提供 GitHub 令牌的替代方式
RADIX_LIBRARY 要使用的库：'themes'、'primitives'、'colors' 或 'all'（默认：all）
LOG_LEVEL 日志级别（debug、info、warn、error）- 默认：info
示例：
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 库
### 🎭 Radix 主题
具有内置设计系统的高级 React 组件。适用于快速应用程序开发。
```typescript
// 示例：从主题获取 Button 组件
{
"tool": "themes_get_component_source",
"arguments": { "componentName": "button" }
}
```
### 🧩 Radix 基元
低级、无样式、可访问的 React 组件。最大化自定义设计灵活性。
```typescript
// 示例：获取 Dialog 基元
{
"tool": "primitives_get_component_source",
"arguments": { "componentName": "dialog" }
}
```
### 🌈 Radix 颜色
具有语义含义和深色模式支持的美丽、可访问的颜色刻度。
```typescript
// 示例：列出所有颜色刻度
{
"tool": "colors_list_scales",
"arguments": {}
}
```
## 🔑 GitHub API 令牌设置
**为什么需要令牌？**
- 无令牌：限制为每小时 60 个 API 请求
- 有令牌：最多 5000 请求/小时
- 更高的可靠性，更快的响应
### 📝 获取您的令牌（2 分钟）
1. **前往 GitHub 设置**：
- 访问 [GitHub 设置 → 开发者设置 → 个人访问令牌 → 令牌（经典）](https://github.com/settings/tokens)
- 或：GitHub 个人资料 → 设置 → 开发者设置 → 个人访问令牌
2. **生成新令牌**：
- 点击“生成新令牌（经典）”
- 添加备注：“Radix UI MCP 服务器”
- **过期时间**：选择您的偏好（推荐 90 天）
- **作用域**：✅ **不需要作用域！** （公共仓库访问足够）
3. **复制您的令牌**：
- 复制生成的令牌（以 `ghp_` 开头）
- ⚠️ **安全保存** - 您将看不到它再次！
### 🚀 使用您的令牌
**方法 1：命令行（快速测试）**
```bash
npx @gianpieropuleo/radix-mcp-server@latest --github-api-key ghp_your_token_here
```
**方法 2：环境变量（推荐）**
```bash
# 添加到您的 shell 配置文件（~/.bashrc，~/.zshrc 等）
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
# 然后简单运行：
npx @gianpieropuleo/radix-mcp-server@latest
```
## 🛠️ 编辑器集成
### Claude Desktop 集成
将以下内容添加到您的 Claude Desktop 配置文件（`~/.config/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"radix-ui": {
"command": "npx",
"args": [
"@gianpieropuleo/radix-mcp-server@latest",
"--github-api-key",
"ghp_your_token_here"
]
}
}
}
```
或使用环境变量：
```json
{
"mcpServers": {
"radix-ui": {
"command": "npx",
"args": ["@gianpieropuleo/radix-mcp-server@latest"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
}
}
}
}
```
### VS Code 集成
#### 方法 1：使用 Continue 扩展
```json
{
"continue.server": {
"mcpServers": {
"radix-ui": {
"command": "npx",
"args": [
"@gianpieropuleo/radix-mcp-server@latest",
"--github-api-key",
"ghp_your_token_here"
]
}
}
}
}
```
#### 方法 2：使用 Claude 扩展
```json
{
"claude.mcpServers": {
"radix-ui": {
"command": "npx",
"args": ["@gianpieropuleo/radix-mcp-server@latest"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
}
}
}
}
```
### Cursor 集成
在项目根目录创建 `.cursorrules` 文件：
```json
{
"mcpServers": {
"radix-ui": {
"command": "npx",
"args": ["@gianpieropuleo/radix-mcp-server@latest"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
}
}
}
}
```
## 🎯 使用示例
### 获取 Radix 主题组件
询问您的 AI 助手：
```
"显示 Radix 主题 Button 组件的源代码"
"列出所有可用的 Radix 主题组件"
"如何安装和设置 Radix 主题？"
```
### 使用 Radix 基元
询问您的 AI 助手：
```
"获取 Radix UI 的 Dialog 基元"
"显示如何使用 Accordion 基元"
"列出所有可用的 Radix 基元"
```
### 使用 Radix 颜色
询问您的 AI 助手：
```
"显示 Radix 颜色中的蓝色刻度"
"如何使用 CSS 变量设置 Radix 颜色？"
"列出所有可用的颜色刻度"
```
### 构建完整 UI
询问您的 AI 助手：
```
"使用 Radix 主题组件创建仪表板"
"使用 Radix 基元构建模态对话框"
"使用 Radix 颜色设置设计系统"
```
## 🛠️ 可用工具
MCP 服务器为 AI 助手提供以下工具：
### Radix 主题工具
- **`themes_list_components`** - 列出所有可用的 Radix 主题组件
- **`themes_get_component_source`** - 获取 Radix 主题组件源代码
- **`themes_get_component_documentation`** - 获取 Radix 主题组件文档
- **`themes_get_getting_started`** - 获取 Radix 主题安装说明
### Radix 基元工具
- **`primitives_list_components`** - 列出所有可用的 Radix 基元
- **`primitives_get_component_source`** - 获取 Radix 基元组件源代码
- **`primitives_get_component_documentation`** - 获取 Radix 基元组件文档
- **`primitives_get_getting_started`** - 获取 Radix 基元安装说明
### Radix 颜色工具
- **`colors_list_scales`** - 列出所有可用的颜色刻度
- **`colors_get_scale`** - 获取特定的颜色刻度定义
- **`colors_get_scale_documentation`** - 获取 Radix 颜色文档
- **`colors_get_getting_started`** - 获取 Radix 颜色安装说明
### 示例工具用法
```typescript
// 获取 Radix 主题 Button 组件
{
"tool": "themes_get_component_source",
"arguments": { "componentName": "button" }
}
// 列出所有 Radix 基元
{
"tool": "primitives_list_components",
"arguments": {}
}
// 获取蓝色颜色刻度
{
"tool": "colors_get_scale",
"arguments": { "scaleName": "blue" }
}
// 获取 Radix 颜色安装指南
{
"tool": "colors_get_getting_started",
"arguments": {}
}
```
## ⚡ 架构和性能
### 现代、轻量级堆栈
该 MCP 服务器使用精心挑选的现代、轻量级包构建：
- **[ky](https://github.com/sindresorhus/ky)** - 优雅的 HTTP 客户端（取代较重的替代品）
- **[p-limit](https://github.com/sindresorhus/p-limit)** - API 使用的并发控制
- **[p-memoize](https://github.com/sindresorhus/p-memoize)** - 智能函数记忆与 TTL
- **[expiry-map](https://github.com/sindresorhus/expiry-map)** - TTL 缓存支持自动过期
- **[pino](https://github.com/pinojs/pino)** - 快速、结构化日志记录
- **[zod](https://github.com/colinhacks/zod)** - 运行时类型验证
### 智能缓存策略
- **24 小时 TTL**：所有 GitHub API 响应缓存 24 小时
- **函数级记忆化**：每个 API 函数都单独记忆化
- **自动过期**：缓存条目自动过期，防止数据过时
- **内存高效**：只有活动数据保留在内存中
### 速率限制和 API 尊重
- **并发控制**：GitHub API 最大并发请求数为 1
- **智能批处理**：相关请求在可能的情况下进行批处理
- **优雅降级**：在达到速率限制时回退到缓存数据
- **令牌支持**：GitHub 令牌将限制从 60 增加到 5000 请求/小时
## 🐛 故障排除
### 常见问题
**"速率限制超过" 错误：**
```bash
# 解决方案：添加 GitHub API 令牌
npx @gianpieropuleo/radix-mcp-server --github-api-key ghp_your_token_here
```
**"命令未找到" 错误：
```bash
# 解决方案：安装 Node.js 18+ 并确保 npx 可用
node --version # 应为 18+
npx --version # 应正常工作
```
**组件未找到：
```bash
# 首先检查可用组件
npx @gianpieropuleo/radix-mcp-server --library themes
# 然后通过您的 MCP 客户端调用相应的列表工具
```
**库选择问题：
```bash
# 验证库参数
npx @gianpieropuleo/radix-mcp-server --library themes # ✅ 有效
npx @gianpieropuleo/radix-mcp-server --library invalid # ❌ 无效
```
### 调试模式
启用详细日志记录：
```bash
# 设置调试环境变量
LOG_LEVEL=debug npx @gianpieropuleo/radix-mcp-server --github-api-key ghp_your_token
```
## 📄 许可证
该项目在 MIT 许可证下许可 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
## 🤝 贡献
1. 分叉仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交您的更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开拉取请求
## 📞 支持
- 🐛 [报告问题](https://github.com/gianpieropuleo/radix-mcp-server/issues)
- 💬 [讨论](https://github.com/gianpieropuleo/radix-mcp-server/discussions)
- 📖 [文档](https://github.com/gianpieropuleo/radix-mcp-server#readme)
- 📦 [npm 包](https://www.npmjs.com/package/@gianpieropuleo/radix-mcp-server)
## 🔗 相关项目
- [Radix UI 主题](https://www.radix-ui.com/themes) - 高级 React 组件
- [Radix UI 基元](https://www.radix-ui.com/primitives) - 低级 React 组件
- [Radix UI 颜色](https://www.radix-ui.com/colors) - 美丽的颜色系统
- [模型上下文协议](https://modelcontextprotocol.io/) - 协议规范
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - 官方 MCP SDK
## ⭐ 致谢
- [Radix UI 团队](https://github.com/radix-ui) - 优秀的组件库
- [Anthropic](https://anthropic.com) - 模型上下文协议规范
- 开源社区提供灵感和贡献
---
**由 [Gianpiero Puleo](https://github.com/gianpieropuleo) 和 [Claude Code](https://www.anthropic.com/claude-code) **构建**
**建立在 [shadcn-ui-mcp-server](https://github.com/Jpisnice/shadcn-ui-mcp-server) 的优秀工作基础上，由 [@Jpisnice](https://github.com/Jpisnice) **构建**
**如果您觉得此项目有帮助，请 ⭐ 星标此仓库！另外，请考虑为 [原始项目](https://github.com/Jpisnice/shadcn-ui-mcp-server) 加 ⭐标，以便使其成为可能。**
MCP 市场
