ComponentGenie MCP 服务器

ComponentGenie 是一个基于 Model Context Protocol (MCP) 的服务器，为 AI 模型（如 Claude）提供项目内 React 组件的智能查询和详情获取功能。

功能特性

🔍 组件列表查询 (get_component_list)

• 获取项目内所有可用的组件列表
• 支持按关键词搜索组件名称或使用场景
• 支持限制返回结果数量
• 提供组件的基本信息（名称和使用场景）

📋 组件详情获取 (get_component_details) - 简化版

• 根据组件名称获取详细信息（批量查询支持）
• 总是返回所有可用内容（类型定义、实现代码、文档、Demo）
• 不限制内容长度和Demo数量
• 简化的API，只需要组件名称参数
• 支持多种文件类型：.tsx, .ts, .jsx, .js
• 内置组件数据，无需搜索项目目录

快速开始

全局安装

npm install -g component-genie-mcp

或者本地安装

npm install component-genie-mcp

环境要求

• Node.js 18+
• npm 或 yarn

启动服务器

方式1：全局安装后使用

# 使用当前目录作为项目根目录
component-genie-mcp

# 或指定项目根目录
component-genie-mcp /path/to/your/project

方式2：本地安装后使用

# 使用当前目录作为项目根目录
npx component-genie-mcp

# 或指定项目根目录
npx component-genie-mcp /path/to/your/project

方式3：使用环境变量

PROJECT_ROOT=/path/to/your/project component-genie-mcp

在 Claude Desktop 中配置

在 Claude Desktop 的配置文件中添加以下配置：

全局安装后的配置：

{
  "mcpServers": {
    "component-genie": {
      "command": "component-genie-mcp",
      "args": ["/path/to/your/project"]
    }
  }
}

本地安装后的配置：

{
  "mcpServers": {
    "component-genie": {
      "command": "npx",
      "args": ["component-genie-mcp", "/path/to/your/project"]
    }
  }
}

MCP 工具说明

1. get_component_list

获取项目内所有可用的组件列表。

参数：

• search (可选): 搜索关键词，可以匹配组件名称或使用场景
• limit (可选): 返回结果的最大数量，默认为50

返回：

• 组件列表和基本信息
• 匹配的组件数量
• 搜索关键词（如果有）

示例：

工具：get_component_list
参数：{"search": "table", "limit": 5}

2. get_component_details (简化版)

根据组件名称获取组件的详细信息。简化后总是返回所有内容，无需额外参数控制。

参数：

• componentName (必需): 要获取详情的组件名称数组，支持批量查询

返回：

• 组件的详细使用场景说明
• 组件类型定义（完整内容，不限制长度）
• 组件实现代码（如果存在）
• 组件文档（完整内容，不限制长度）
• 所有Demo示例（完整内容，不限制数量）

特性：

• ✅ 总是包含所有可用内容
• ✅ 不限制内容长度
• ✅ 不限制Demo数量
• ✅ 支持批量查询多个组件

示例：

工具：get_component_details
参数：{"componentName": ["DPHeader"]}

# 批量查询示例
工具：get_component_details  
参数：{"componentName": ["AutoTable", "DPHeader", "ActionGroup"]}

项目结构要求

组件信息文件

服务器需要 src/resources/components-detail.json 文件，包含组件的详细信息：

{
  "timestamp": "2025-07-04T07:48:06.884Z",
  "totalCount": 82,
  "components": [
    {
      "name": "ComponentName",
      "whenToUse": "组件的使用场景描述"
    }
  ]
}

组件文件查找

服务器会在以下目录中查找组件实现文件：

• src/components/
• components/
• src/
• lib/components/
• packages/

支持的文件格式：

• 直接文件：ComponentName.tsx, ComponentName.ts, ComponentName.jsx, ComponentName.js
• 目录结构：ComponentName/index.tsx, ComponentName/ComponentName.tsx 等

开发和测试

运行测试

# 测试组件列表功能
node quick-test.js

# 测试组件详情功能
node test-component-details.js

开发模式

npm run dev

技术栈

• MCP SDK: @modelcontextprotocol/sdk
• Schema验证: Zod
• Transport: STDIO (标准输入输出)
• 文件系统: Node.js fs/promises

错误处理

• 自动处理文件路径问题，支持多种部署环境
• 提供详细的错误信息和建议
• 当组件不存在时提供可用组件的提示

注意事项

1. 项目根目录设置: 确保正确设置项目根目录，这影响组件文件的查找
2. 文件权限: 确保服务器有权限读取项目目录中的文件
3. 组件信息同步: 保持 components-detail.json 文件与实际组件的同步

许可证

MIT License