React 设计系统

React 设计系统是一个模型上下文协议（MCP）服务器，提供关于为 React 创建的设计系统的全面信息。当前版本专注于 AWS Cloudscape 设计系统组件以及代码生成能力。它使用 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 提供）

安装

作为依赖项安装

# 从 npm 安装
npm install @agentience/react-design-systems-mcp

全局安装

# 全局安装以用作 CLI 工具
npm install -g @agentience/react-design-systems-mcp

# 然后可以直接运行
react-design-systems-mcp

Claude Desktop 配置

要使用 React 设计系统与 Claude Desktop，可以使用 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 <类型> 或 -t <类型>：传输类型（stdio 或 sse）。默认值：stdio
• --port <数字> 或 -p <数字>：SSE 传输端口。默认值：3001
• --bind <地址> 或 -b <地址>：SSE 传输绑定地址。默认值：0.0.0.0

与 Claude 的使用

当使用此 MCP 服务器与 Claude 时，考虑使用专门的系统提示以获得最佳效果。我们提供了一个示例系统提示，该提示将 Claude 配置为具有 AWS Amplify Gen 2 知识的 Cloudscape 开发专家。详情请参阅 Claude Cloudscape & Amplify 专家。

高级配置示例

带有自定义参数

{
  "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 设计系统 MCP 服务器应自动可用
4. 您可以使用如 search_components 等工具来验证连接

有关连接问题的故障排除，请参阅 MCP 协议指南。

Docker 部署

该项目可以通过 Docker 进行部署。详细说明请参阅 Docker 部署指南。

使用 Docker 快速开始

# 从 GitHub 容器注册表拉取镜像
docker pull ghcr.io/agentience/react-design-systems-mcp:latest

# 运行容器
docker run -d -p 3005:3005 --name react-design-systems-mcp ghcr.io/agentience/react-design-systems-mcp:latest

使用 Docker Compose

# 克隆仓库
git clone https://github.com/agentience/react-design-systems-mcp.git
cd react-design-systems-mcp

# 使用 Docker Compose 启动
docker-compose up -d

有关如何构建并发布 Docker 镜像到 GitHub 容器注册表的信息，请参阅 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 - 获取前端代码模式的设置说明
• get_link_resource - 解析来自 usage.md 文件的内部链接到适当的后端资源

MCP 资源

组件使用指南

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

示例用法

# 搜索与按钮相关的组件
search_components({"query": "button", "category": "actions"})

# 获取特定组件的详细信息
get_component_details({"componentId": "button"})

# 直接访问使用指南
资源：cloudscape://usage/button

# 跨使用指南搜索
search_usage_guidelines({"query": "主要按钮", "section": "特性"})

# 生成组件代码
generate_component_code({"componentId": "button", "variant": "主要"})

文档

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

系统提示

• Claude Cloudscape & Amplify 专家 - 将 Claude 配置为具有 AWS Amplify Gen 2 知识的 Cloudscape 开发专家的示例系统提示

发展路线图

React 设计系统目前支持 AWS Cloudscape 设计系统，但未来计划扩展支持其他流行的 React 设计系统：

• Material UI：对 Google 的 Material Design 在 React 中的实现进行全面支持
• 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';

// 创建并配置服务器
const server = createReactDesignSystemsServer({
  // 配置选项
});

// 启动服务器
server.start();

贡献

欢迎贡献！请随时提交 Pull Request。

1. 分叉仓库
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m '添加一些精彩的功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开 Pull Request

许可证

MIT - 详情请参阅 LICENSE。