component-genie-mcp/README.md

A simplified Model Context Protocol server for querying React components with complete content access

# ComponentGenie MCP 服务器

[![npm version](https://badge.fury.io/js/component-genie-mcp.svg)](https://badge.fury.io/js/component-genie-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

## 功能特性

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

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

## 快速开始

### 全局安装
```bash
npm install -g component-genie-mcp
```

### 或者本地安装
```bash
npm install component-genie-mcp
```

### 环境要求
- Node.js 18+
- npm 或 yarn

### 启动服务器

#### 方式1：全局安装后使用
```bash
# 使用当前目录作为项目根目录
component-genie-mcp

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

#### 方式2：本地安装后使用
```bash
# 使用当前目录作为项目根目录
npx component-genie-mcp

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

#### 方式3：使用环境变量
```bash
PROJECT_ROOT=/path/to/your/project component-genie-mcp
```

### 在 Claude Desktop 中配置

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

**全局安装后的配置：**
```json
{
  "mcpServers": {
    "component-genie": {
      "command": "component-genie-mcp",
      "args": ["/path/to/your/project"]
    }
  }
}
```

**本地安装后的配置：**
```json
{
  "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` 文件，包含组件的详细信息：

```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` 等

## 开发和测试

### 运行测试
```bash
# 测试组件列表功能
node quick-test.js

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

### 开发模式
```bash
npm run dev
```

## 技术栈

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

## 错误处理

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

## 注意事项

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

## 许可证

MIT License