# Exploria UI MCP Server

Exploria UI MCP Server 是一个基于 MCP（Model Context Protocol）协议的服务，允许 AI 客户端（如 Cursor、Trae IDE）访问和查询 Exploria UI 组件库的文档和信息。

## 1. MCP 协议简介

### 1.1 什么是 MCP？

MCP（Model Context Protocol）是 AI 工具世界的「USB 标准」，它允许 AI 应用（如 Cursor、Trae IDE）通过统一的接口访问自定义数据和功能。

### 1.2 核心设计理念

- **统一接口**：为所有 AI 工具提供统一的访问方式，避免为每个 AI 工具单独开发适配层
- **轻量通信**：默认使用标准输入输出（stdio）进行通信，无需网络端口
- **自动管理**：由 AI 客户端自动启动、管理和停止，无需手动干预
- **安全可靠**：通过管道通信，避免网络安全风险

### 1.3 通信原理

MCP Server 与 AI IDE 的通信流程：

1. AI IDE（如 Cursor/Trae）启动时读取配置文件
2. 根据配置中的 `mcpServers` 自动启动 MCP Server 作为子进程
3. 通过标准输入输出（stdio）与 MCP Server 通信
4. 发送初始化指令，获取可用工具列表
5. 在需要时调用相应工具，获取结果
6. IDE 关闭时，自动终止 MCP Server 进程

**关键特点**：

- Cursor/Trae 是 MCP Server 的父进程
- 通信方式：标准输入输出（stdio），不是网络通信
- 无端口、无 TCP、无 HTTP
- 所有消息通过 JSON 格式管道传输

## 2. 快速开始

### 2.1 安装依赖

```bash
pnpm install
```

### 2.2 Cursor 配置

1. 打开 Cursor 配置文件：`%APPDATA%\Cursor\cursor_config.json`
2. 添加以下配置：

```json
{
    "mcpServers": {
        "exploria-ui-mcp": {
            "command": "pnpm",
            "args": ["serve"],
            "cwd": "C:\\Users\\YYWD4\\Desktop\\exploria-ui-document\\mcp-server"
        }
    }
}
```

**注意**：请将 `cwd` 路径替换为您实际的项目路径。

3. 重启 Cursor，它会自动启动并连接到 MCP Server

### 2.3 Trae IDE 配置

1. 打开 Trae IDE MCP 配置文件：`.cursor/mcp.json`（位于项目根目录）
2. 添加以下配置：

```json
{
    "servers": [
        {
            "id": "exploria-ui-mcp",
            "name": "Exploria UI MCP Server",
            "command": "pnpm",
            "args": ["serve"],
            "cwd": "mcp-server",
            "env": {},
            "enabled": true
        }
    ]
}
```

**注意**：

- `cwd` 路径为相对于项目根目录的路径
- 确保 `enabled` 字段设置为 `true` 以启用该服务器

3. 重启 Trae IDE 或重新加载配置，它会自动启动并连接到 MCP Server

### 2.4 验证配置

配置完成后，在 AI IDE 中输入类似以下的查询，验证 MCP Server 是否正常工作：

```
帮我查一下 button 组件的文档
```

## 3. 核心功能

### 3.1 工具（Tools）

| 工具名称                 | 描述                      | 参数                              | 返回值                                 |
| ------------------------ | ------------------------- | --------------------------------- | -------------------------------------- |
| `search_documents`       | 搜索 Exploria UI 组件文档 | `query: string`                   | 匹配的组件列表                         |
| `get_component_list`     | 获取所有组件列表          | 无                                | 所有组件的基本信息                     |
| `get_component_details`  | 获取指定组件的详细信息    | `componentName: string`           | 组件的详细信息，包括属性、事件、插槽等 |
| `search_and_get_details` | 搜索并获取组件详情        | `query: string`, `limit?: number` | 匹配的组件列表，包含详细信息           |

### 3.2 资源（Resources）

| 资源 URI                        | 描述           | 返回值                           |
| ------------------------------- | -------------- | -------------------------------- |
| `status://exploria-ui-server`   | 服务器状态信息 | 服务器运行状态、版本、运行时间等 |
| `docs://exploria-ui-api`        | API 文档       | 完整的 API 文档                  |
| `components://exploria-ui-list` | 组件列表资源   | 所有组件的基本信息               |

### 3.3 提示（Prompts）

| 提示名称                  | 描述             | 参数                                         | 返回值           |
| ------------------------- | ---------------- | -------------------------------------------- | ---------------- |
| `component_documentation` | 生成组件文档模板 | `componentName: string`                      | 组件文档模板     |
| `usage_example`           | 生成组件使用示例 | `componentName: string`, `scenario?: string` | 组件使用示例代码 |

## 4. 项目架构

### 4.1 核心模块

| 模块          | 功能                                   |
| ------------- | -------------------------------------- |
| **Tools**     | 可执行功能，如搜索文档、获取组件详情   |
| **Resources** | 提供只读数据，如服务器状态、API 文档   |
| **Prompts**   | 预定义模板，用于生成组件文档和使用示例 |
| **Utils**     | 工具类，如文档解析器                   |

### 4.2 项目结构

```
src/
├── index.ts              # 入口文件，启动 MCP Server
├── tools/                # 工具模块
│   ├── index.ts          # 工具注册入口
│   ├── searchDocuments.ts       # 搜索文档工具
│   ├── getComponentList.ts      # 获取组件列表工具
│   ├── getComponentDetails.ts   # 获取组件详情工具
│   └── searchAndGetDetails.ts   # 搜索并获取组件详情工具
├── resources/            # 资源模块
│   ├── index.ts          # 资源注册入口
│   ├── serverStatus.ts   # 服务器状态资源
│   ├── apiDocs.ts        # API 文档资源
│   └── componentList.ts  # 组件列表资源
├── prompts/              # 提示模块
│   ├── index.ts          # 提示注册入口
│   ├── componentDocumentation.ts  # 生成组件文档模板
│   └── usageExample.ts            # 生成组件使用示例
└── utils/                # 工具类
    └── documentParser.ts # 文档解析器，处理组件文档
```

## 5. 开发与调试

### 5.1 构建项目

```bash
pnpm build
```

### 5.2 本地运行（仅开发阶段）

**注意**：在生产环境中，MCP Server 由 AI IDE 自动启动和管理，无需手动运行。以下命令仅用于开发和调试阶段。

```bash
# 使用 tsx 直接运行 TypeScript 代码（开发模式）
pnpm serve

# 运行构建后的代码（生产模式测试）
pnpm start
```

### 5.3 使用 MCP Dev 工具

安装 MCP Dev 工具进行调试：

```bash
npm install -g @modelcontextprotocol/dev
```

然后在项目目录中运行：

```bash
mcp dev src/index.ts
```

这会模拟 AI IDE 启动和调用流程，便于调试。

## 6. 扩展指南

### 6.1 添加新工具

1. 在 `src/tools/` 目录下创建新的工具文件，如 `newTool.ts`
2. 实现工具函数并注册到 MCP Server
3. 在 `src/tools/index.ts` 中导入并注册新工具

### 6.2 添加新资源

1. 在 `src/resources/` 目录下创建新的资源文件，如 `newResource.ts`
2. 实现资源函数并注册到 MCP Server
3. 在 `src/resources/index.ts` 中导入并注册新资源

### 6.3 添加新提示

1. 在 `src/prompts/` 目录下创建新的提示文件，如 `newPrompt.ts`
2. 实现提示函数并注册到 MCP Server
3. 在 `src/prompts/index.ts` 中导入并注册新提示

## 7. 技术栈

| 技术                        | 用途                         |
| --------------------------- | ---------------------------- |
| `@modelcontextprotocol/sdk` | 官方 MCP TypeScript SDK      |
| `zod`                       | 用于工具参数的运行时类型校验 |
| `tsx`                       | 直接运行 TypeScript 代码     |
| `typescript`                | 类型安全                     |
| `pnpm`                      | 包管理                       |

## 8. 协议兼容性

- 支持 MCP 协议 v1.0+
- 兼容 Cursor、Trae IDE、Claude Desktop 等支持 MCP 的 AI 客户端
- 使用标准输入输出（stdio）通信，无需网络端口

## 9. 安全特性

- 无网络通信，所有数据通过管道传输
- 由 AI 客户端自动管理，无需手动暴露服务
- 支持工具级别的权限控制（通过 MCP SDK 实现）

## 10. 许可证

MIT
