.github

React 设计系统

React Design Systems 是一个模型上下文协议（MCP）服务，提供有关为 React 创建的设计系统的全面信息。当前版本专注于 AWS Cloudscape Design System 组件，并支持代码生成。它使用 FastMCP 框架和 TypeScript 构建。

未来版本将扩展支持其他流行的 React 设计系统，包括 Material UI、Chakra UI、Ant Design、Blueprint 和 Mantine。

更新日志

请参阅 CHANGELOG.md

功能

组件信息与搜索

• 使用高级筛选选项搜索 Cloudscape 组件
• 获取组件的详细信息，包括属性、事件和函数
• 查看组件使用指南和最佳实践
• 按内容、章节或特定组件搜索组件使用指南
• 获取包含详细代码片段的组件示例
• 比较组件及其功能

代码生成

• 通过自定义选项生成组件代码
• 为常见 UI 模式和布局生成代码
• 生成多组件布局和组合
• 验证组件属性和配置

高级功能

• 使用指南：通过资源/工具混合方式全面访问组件使用指南
  • 通过 cloudscape://usage/{componentId} 资源 URI 直接访问
  • 跨所有使用指南内容进行高级搜索
  • 按章节筛选（功能、通用指南等）
  • 跨组件内容搜索
• 事件与函数：搜索并探索组件事件和函数 API
• 模式库：访问设计模式和架构指南
• 设置说明：获取前端代码模式的设置和配置指南

要求

• Node.js：24.0.1 或更高版本
• npm：10.x 或更高版本（随 Node.js 24.0.1 一同提供）

安装

作为依赖项使用

# Install from npm
npm install @agentience/react-design-systems-mcp

全局安装

# Install globally to use as a CLI tool
npm install -g @agentience/react-design-systems-mcp

# Then you can run it directly
react-design-systems-mcp

Claude Desktop 配置

要在 Claude Desktop 中使用 React Design Systems，可以将其配置为使用 npm 包的 MCP 服务。这样 Claude Desktop 就可以在需要时自动启动该服务。

配置文件

将以下配置添加到 Claude Desktop 的 MCP 设置文件中：

位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

配置：

{
  "mcpServers": {
    "react-design-systems": {
      "command": "npx",
      "args": [
        "@agentience/react-design-systems-mcp"
      ]
    }
  }
}

命令行参数

该服务支持以下命令行参数：

• --transport <type> 或 -t <type>：传输类型（stdio 或 sse）。默认值：stdio
• --port <number> 或 -p <number>：SSE 传输的端口。默认值：3001
• --bind <address> 或 -b <address>：SSE 传输的绑定地址。默认值：0.0.0.0

与 Claude 配合使用

要在 Claude 中使用此 MCP 服务并获得最佳效果，可以考虑使用专用的系统提示词。我们提供了一个示例系统提示词，可将 Claude 配置为精通 AWS Amplify Gen 2 的 Cloudscape 专家开发者。详情请参阅 Claude Cloudscape & Amplify Expert。

高级配置示例

使用自定义参数

{
  "mcpServers": {
    "react-design-systems": {
      "command": "npx",
      "args": [
        "@agentience/react-design-systems-mcp",
        "--transport",
        "stdio"
      ]
    }
  }
}

使用本地安装

如果已全局或本地安装该软件包：

{
  "mcpServers": {
    "react-design-systems": {
      "command": "react-design-systems-mcp"
    }
  }
}

开发配置

使用本地构建进行开发：

{
  "mcpServers": {
    "react-design-systems": {
      "command": "node",
      "args": [
        "/path/to/react-design-systems-mcp/dist/server.js"
      ],
      "cwd": "/path/to/react-design-systems-mcp"
    }
  }
}

验证

添加配置后：

1. 重启 Claude Desktop
2. 开始新的对话
3. React Design Systems MCP 服务应会自动可用
4. 可以使用 search_components 等工具验证连接

有关连接问题的故障排除，请参阅 MCP Protocol Guide。

Docker 部署

本项目可使用 Docker 部署。详细说明请参阅 Docker 部署指南。

使用 Docker 快速入门

# Pull the image from GitHub Container Registry
docker pull ghcr.io/agentience/react-design-systems-mcp:latest

# Run the container
docker run -d -p 3005:3005 --name react-design-systems-mcp ghcr.io/agentience/react-design-systems-mcp:latest

使用 Docker Compose

# Clone the repository
git clone https://github.com/agentience/react-design-systems-mcp.git
cd react-design-systems-mcp

# Start with Docker Compose
docker-compose up -d

有关如何构建 Docker 镜像并将其发布到 GitHub Container Registry 的信息，请参阅 Docker 发布指南。

FastMCP 实现

本项目使用 FastMCP 框架，以更结构化且类型安全的方式构建 MCP 服务。有关 FastMCP 实现和开发环境设置的详细信息，请参阅 DEVELOPMENT.md。

可用工具和资源

MCP 工具

组件信息

• search_components - 搜索组件并进行高级筛选
• get_component_details - 获取详细的组件信息
• get_component_properties - 获取组件属性及其规格说明
• get_component_events - 获取组件事件和事件处理信息
• get_component_functions - 获取组件函数和方法 API
• get_component_examples - 获取组件示例，可按示例 ID 筛选

使用指南

• get_component_usage - 获取特定组件的使用指南，可按章节筛选
• search_usage_guidelines - 根据查询内容、章节和组件筛选条件，搜索组件使用指南

代码生成

• generate_component_code - 生成组件代码并进行自定义
• generate_pattern_code - 为常见 UI 模式生成代码
• validate_component_props - 验证组件属性和配置

模式和搜索

• search_patterns - 搜索设计模式和架构指南
• search_properties - 搜索所有组件的属性
• search_events - 搜索组件事件并设置筛选条件
• search_functions - 搜索组件函数和方法

实用工具

• compare_components - 比较多个组件及其功能
• generate_layout_code - 生成多组件布局
• get_frontend_setup - 获取 frontend-code 模式的设置说明
• get_link_resource - 将 usage.md 文件中的内部链接解析为相应的后端资源

MCP 资源

组件使用指南

• cloudscape://usage/{componentId} - 以 Markdown 格式直接访问组件使用指南

使用示例

# Search for button-related components
search_components({"query": "button", "category": "actions"})

# Get detailed information about a specific component
get_component_details({"componentId": "button"})

# Access usage guidelines directly
Resource: cloudscape://usage/button

# Search across usage guidelines
search_usage_guidelines({"query": "primary button", "section": "Features"})

# Generate component code
generate_component_code({"componentId": "button", "variant": "primary"})

文档

• 架构
• 组件库
• FastMCP 实现
• 前端代码模式
• MCP 协议指南
• Roo 集成指南
• 使用指南
• Docker 部署指南
• Docker 发布指南

系统提示词

• Claude Cloudscape 与 Amplify 专家 - 使用 Claude 作为精通 AWS Amplify Gen 2 的 Cloudscape 开发专家的系统提示词示例

路线图

React Design Systems 目前支持 AWS Cloudscape Design System，但我们计划在未来扩展对其他热门 React 设计系统的支持：

• Material UI：全面支持 Google 为 React 实现的 Material Design
• Chakra UI：专注于组件，支持易于访问且可自定义的 Chakra UI 库
• Ant Design：面向 React 应用的企业级 UI 系统
• Blueprint：支持 Palantir 面向 Web 应用的 UI 工具包
• Mantine：提供现代 React 组件，并出色支持深色模式

如果你有兴趣为其他设计系统贡献支持，请查看我们的贡献指南。

作为依赖项使用

在项目中将此软件包用作依赖项时，可以按如下方式导入和使用：

// CommonJS
const { createReactDesignSystemsServer } = require('@agentience/react-design-systems-mcp');

// ES Modules
import { createReactDesignSystemsServer } from '@agentience/react-design-systems-mcp';

// Create and configure the server
const server = createReactDesignSystemsServer({
  // Configuration options
});

// Start the server
server.start();

贡献

欢迎贡献！欢迎提交 Pull Request。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 创建 Pull Request

许可证

MIT - 更多信息请参阅 LICENSE。## 可用文档

• React Design Systems 开发
• React Design Systems 的 Docker 部署
• React Design Systems v1.0.4