exploria-ui-mcp-server 2.1.4 → 2.2.6

package/README.md

@@ -1,40 +1,97 @@
 # Exploria UI MCP Server
 
-基于 MCP（Model Context Protocol）协议的服务，允许 AI 客户端（如 Cursor、Trae IDE）访问和查询 Exploria UI 组件库的文档和信息。
+## 1. 项目概述
 
-## 1. MCP 协议简介
+### 1.1 项目定位
 
-### 1.1 什么是 MCP？
+Exploria UI MCP Server 是基于 MCP（Model Context Protocol）协议的服务，作为 AI IDE（如 Cursor、Trae IDE）与 Exploria UI 组件库之间的关键桥梁，允许 AI 客户端无缝访问和查询 Exploria UI 组件库的文档和信息。
 
-MCP 是 AI 工具世界的「USB 标准」，允许 AI 应用通过统一接口访问自定义数据和功能。
+### 1.2 核心价值
 
-### 1.2 核心特性
+- **连接 AI 工作流与组件库**：为 AI IDE 提供直接访问 Exploria UI 组件库文档的能力
+- **提升开发效率**：AI 可以直接获取组件详细信息，生成代码示例和文档
+- **统一访问接口**：基于 MCP 协议，为所有 AI IDE 提供标准化的访问方式
+- **增强 AI 能力**：为 AI 模型提供准确的组件信息，生成更优质的代码和解决方案
 
-- **统一接口**：为所有 AI 工具提供统一访问方式
-- **轻量通信**：使用标准输入输出（stdio）通信，无需网络端口
-- **自动管理**：由 AI 客户端自动启动、管理和停止
-- **安全可靠**：通过管道通信，避免网络安全风险
+## 2. Exploria UI 组件库
 
-### 1.3 通信流程
+### 2.1 设计理念
 
-1. AI IDE 启动时读取配置文件
-2. 根据 `mcpServers` 配置自动启动 MCP Server 子进程
-3. 通过 stdio 与 MCP Server 通信
-4. 发送初始化指令，获取可用工具列表
-5. 按需调用工具，获取结果
-6. IDE 关闭时自动终止 MCP Server 进程
+Exploria UI 是一套现代化、高性能的 UI 组件库，专注于提供优雅的设计和出色的用户体验。其设计理念包括：
 
-## 2. 快速开始
+- **模块化设计**：组件高度模块化，便于组合和扩展
+- **响应式布局**：适配各种屏幕尺寸，提供一致的用户体验
+- **可定制性**：支持主题定制和样式覆盖
+- **高性能**：优化渲染性能，确保流畅的交互体验
 
-### 2.1 安装依赖
+### 2.2 核心组件类别
 
-```bash
-pnpm install
-```
+Exploria UI 组件库包含丰富的组件，按功能分为以下几类：
+
+| 类别         | 描述                     | 示例组件                 |
+| ------------ | ------------------------ | ------------------------ |
+| 基础组件     | 构建 UI 的基础元素       | Button, Input, Icon      |
+| 布局组件     | 用于页面布局的组件       | Layout, Grid, Space      |
+| 表单组件     | 用于数据收集和验证的组件 | Form, Select, DatePicker |
+| 数据展示组件 | 用于展示数据的组件       | Table, List, Card        |
+| 反馈组件     | 用于用户反馈的组件       | Modal, Message, Loading  |
+| 导航组件     | 用于页面导航的组件       | Menu, Tabs, Breadcrumb   |
+| 高级组件     | 复杂功能的组合组件       | Pagination, Upload, Tree |
+| AI 相关组件  | 集成 AI 功能的组件       | AI Assistant, Chatbot    |
+
+### 2.3 文档体系
+
+Exploria UI 拥有完整的文档体系，包括：
+
+- **组件文档**：详细的组件使用说明、属性列表、事件和插槽
+- **API 文档**：完整的 API 参考
+- **使用示例**：丰富的代码示例和最佳实践
+- **设计指南**：设计原则和样式规范
+
+## 3. MCP Server 核心架构
+
+### 3.1 架构定位
+
+MCP Server 在项目架构中扮演着核心角色，作为 AI IDE 与 Exploria UI 组件库文档之间的中间层，负责：
+
+1. **协议转换**：将 AI IDE 的 MCP 请求转换为对 Exploria UI 文档的查询
+2. **文档检索**：高效搜索和检索组件文档
+3. **响应生成**：将文档信息转换为 AI 可理解的格式
+4. **服务管理**：处理服务的启动、运行和关闭
+
+### 3.2 核心组件
+
+| 组件名称                 | 功能描述                                                                |
+| ------------------------ | ----------------------------------------------------------------------- |
+| **ExploriaUIMCPServer**  | 主服务器类，负责协调所有组件，处理服务生命周期管理                      |
+| **McpServer**            | 来自 @modelcontextprotocol/sdk 的核心 MCP 服务器实例，处理 MCP 协议通信 |
+| **StdioServerTransport** | 标准输入输出传输层，用于与 AI IDE 通信                                  |
+| **DocumentParser**       | 文档解析器，负责解析和处理 Exploria UI 文档                             |
+
+### 3.3 注册模块
 
-### 2.2 AI IDE 配置
+MCP Server 启动时会注册三类核心模块：
 
-所有 AI IDE 使用统一配置格式：
+1. **工具模块 (Tools)**
+    - 提供 AI IDE 可调用的各种工具函数
+    - 包括文档搜索、组件列表获取、组件详情查询等功能
+    - 注册入口：`./tools/index.js`
+
+2. **资源模块 (Resources)**
+    - 提供项目相关的资源支持
+    - 包括服务器状态、API 文档、组件清单等
+    - 注册入口：`./resources/index.js`
+
+3. **提示模块 (Prompts)**
+    - 提供指导 AI 模型生成更准确响应的提示模板
+    - 包括组件文档模板生成、使用示例生成等
+    - 注册入口：`./prompts/index.js`
+
+## 4. 快速开始
+
+### 4.1 AI IDE 配置
+
+所有 AI IDE 使用统一配置格式，在配置文件中添加以下内容：
 
 ```json
 {
@@ -47,15 +104,7 @@ pnpm install
 }
 ```
 
-#### 具体 IDE 配置
-
-| IDE                 | 配置文件位置                          | 操作步骤                                               |
-| ------------------- | ------------------------------------- | ------------------------------------------------------ |
-| Cursor              | `%APPDATA%\Cursor\cursor_config.json` | 1. 打开配置文件<br>2. 添加上述配置<br>3. 重启 Cursor   |
-| Trae IDE            | `.trae/mcp.json`（项目根目录）        | 1. 打开配置文件<br>2. 添加上述配置<br>3. 重启 Trae IDE |
-| 其他支持 MCP 的 IDE | 参考官方文档                          | 1. 找到 MCP 配置文件<br>2. 添加上述配置<br>3. 重启 IDE |
-
-### 2.3 验证配置
+### 4.2 验证配置
 
 在 AI IDE 中输入查询验证服务是否正常：
 
@@ -63,9 +112,9 @@ pnpm install
 帮我查一下 button 组件的文档
 ```
 
-## 3. 核心功能
+## 5. 核心功能详解
 
-### 3.1 工具（Tools）
+### 5.1 工具 (Tools)
 
 | 工具名称                 | 描述               | 参数                              | 返回值                             |
 | ------------------------ | ------------------ | --------------------------------- | ---------------------------------- |
@@ -74,7 +123,7 @@ pnpm install
 | `get_component_details`  | 获取组件详情       | `componentName: string`           | 组件详细信息（属性、事件、插槽等） |
 | `search_and_get_details` | 搜索并获取组件详情 | `query: string`, `limit?: number` | 匹配的组件列表（含详情）           |
 
-### 3.2 资源（Resources）
+### 5.2 资源 (Resources)
 
 | 资源 URI                        | 描述       | 返回值                     |
 | ------------------------------- | ---------- | -------------------------- |
@@ -82,25 +131,39 @@ pnpm install
 | `docs://exploria-ui-api`        | API 文档   | 完整 API 文档              |
 | `components://exploria-ui-list` | 组件列表   | 所有组件基本信息           |
 
-### 3.3 提示（Prompts）
+### 5.3 提示 (Prompts)
 
 | 提示名称                  | 描述             | 参数                                         | 返回值           |
 | ------------------------- | ---------------- | -------------------------------------------- | ---------------- |
 | `component_documentation` | 生成组件文档模板 | `componentName: string`                      | 组件文档模板     |
 | `usage_example`           | 生成组件使用示例 | `componentName: string`, `scenario?: string` | 组件使用示例代码 |
 
-## 4. 项目架构
+## 6. 技术实现
 
-### 4.1 核心模块
+### 6.1 构建流程
 
-| 模块          | 功能                                   |
-| ------------- | -------------------------------------- |
-| **Tools**     | 可执行功能（搜索文档、获取组件详情等） |
-| **Resources** | 提供只读数据（服务器状态、API 文档等） |
-| **Prompts**   | 预定义模板（生成文档、使用示例等）     |
-| **Utils**     | 工具类（文档解析器等）                 |
+1. 项目基于 Vite 构建工具进行打包
+2. 打包过程结束后，通过自定义 Vite 插件自动执行文件复制操作
+3. 插件将 `../src/views/document/pages` 目录下的所有文件复制到 `mcp-server/dist/knowledge` 目录
+4. 同时将项目根目录的 README.md 复制到 `mcp-server/dist/public/README.md`
+5. 最终构建产物包含完整的 MCP Server 实现和所需的知识文件
 
-### 4.2 项目结构
+### 6.2 NPM 包结构
+
+当项目打包完成并上传至 NPM 仓库后，生成的 NPM 包包含以下目录和文件结构：
+
+```
+mcp-server/
+├── dist/
+│   ├── index.js
+│   └── knowledge/          # 来自  ../src/views/document/pages
+│          ├── ...
+│          └── README.md
+├── package.json
+└── README.md
+```
+
+### 6.3 项目结构
 
 ```
 src/
@@ -124,47 +187,61 @@ src/
     └── documentParser.ts # 文档解析器
 ```
 
-## 5. 开发与调试
+### 6.4 技术栈
 
-### 5.1 构建项目
+| 技术                        | 用途                     |
+| --------------------------- | ------------------------ |
+| `@modelcontextprotocol/sdk` | 官方 MCP TypeScript SDK  |
+| `zod`                       | 工具参数运行时类型校验   |
+| `tsx`                       | 直接运行 TypeScript 代码 |
+| `typescript`                | 类型安全                 |
+| `pnpm`                      | 包管理                   |
 
-```bash
-pnpm build
-```
+## 7. MCP 协议详解
 
-### 5.2 本地运行
+### 7.1 传输协议
 
-#### 在 mcp-server 目录下运行（推荐）：
+MCP Server 与 AI IDE 之间支持三种传输协议：
 
-```bash
-# 构建 MCP Server
-pnpm run build
+1. **标准输入输出 (stdio)**
+    - 轻量级通信方式，无需网络端口
+    - 通过管道传输数据，安全可靠
+    - 由 AI 客户端自动启动、管理和停止
+    - 本项目采用此协议作为主要通信方式
 
-# 运行构建后的服务
-pnpm run start
-```
+2. **Server-Sent Events (SSE)**
+    - 基于 HTTP 的单向实时通信协议
+    - 适合服务器向客户端推送数据的场景
+    - 支持事件驱动的通信模式
 
-#### 或在项目根目录执行：
+3. **流式 HTTP (Streaming HTTP)**
+    - 基于 HTTP 长连接的双向通信
+    - 支持服务器和客户端之间的连续数据传输
+    - 适合需要持续交互的场景
 
-```bash
-# 开发模式
-pnpm mcp:dev
+### 7.2 服务启动机制
 
-# 构建 MCP Server
-pnpm mcp:build
+1. AI 相关 IDE 通过 MCP 协议连接并请求启动 MCP Server
+2. IDE 实际调用的是 NPM 包中 package.json 定义的可执行命令
+3. 可执行命令指向 `dist/index.js` 文件，该文件会实例化并启动 ExploriaUIMCPServer 类
+4. ExploriaUIMCPServer 类初始化流程：
+    - 加载 package.json 获取配置信息
+    - 设置事件处理器（错误处理、信号处理等）
+    - 初始化 McpServer 实例
+    - 注册所有工具、资源和提示模块
+    - 创建并连接 StdioServerTransport
+5. 连接建立后，服务器通过 MCP 协议与 IDE 进行通信，提供各项功能
 
-# 运行构建后的服务
-pnpm mcp:start
-```
+## 8. 调试
 
-### 5.3 使用 MCP Inspector 调试
+### 8.1 使用 MCP Inspector 调试
 
 ```bash
 # 使用 MCP Inspector 启动服务，方便调试
 npx -y @modelcontextprotocol/inspector node dist/index.js
 ```
 
-### 5.4 故障排除
+### 8.2 故障排除
 
 1. **连接失败或 "Command not found" 错误**：
     - 确保已正确构建项目：`pnpm run build`
@@ -179,73 +256,56 @@ npx -y @modelcontextprotocol/inspector node dist/index.js
     - 确保文档已正确复制到 `public` 目录
     - 检查 `docsRoot` 配置是否正确
 
-## 6. 扩展指南
+## 9. 扩展指南
 
-### 6.1 添加新工具
+### 9.1 添加新工具
 
 1. 在 `src/tools/` 目录下创建新工具文件（如 `newTool.ts`）
 2. 实现工具函数并注册到 MCP Server
 3. 在 `src/tools/index.ts` 中导入并注册新工具
 
-### 6.2 添加新资源
+### 9.2 添加新资源
 
 1. 在 `src/resources/` 目录下创建新资源文件
 2. 实现资源函数并注册到 MCP Server
 3. 在 `src/resources/index.ts` 中导入并注册新资源
 
-### 6.3 添加新提示
+### 9.3 添加新提示
 
 1. 在 `src/prompts/` 目录下创建新提示文件
 2. 实现提示函数并注册到 MCP Server
 3. 在 `src/prompts/index.ts` 中导入并注册新提示
 
-## 7. 技术栈
-
-| 技术                        | 用途                     |
-| --------------------------- | ------------------------ |
-| `@modelcontextprotocol/sdk` | 官方 MCP TypeScript SDK  |
-| `zod`                       | 工具参数运行时类型校验   |
-| `tsx`                       | 直接运行 TypeScript 代码 |
-| `typescript`                | 类型安全                 |
-| `pnpm`                      | 包管理                   |
+## 10. 安全与兼容性
 
-## 8. 协议兼容性
+### 10.1 安全特性
 
-- 支持 MCP 协议 v1.0+
-- 兼容 Cursor、Trae IDE、Claude Desktop 等
-- 使用 stdio 通信，无需网络端口
-
-## 9. 安全特性
-
-- 无网络通信，所有数据通过管道传输
+- 无网络通信，所有数据通过管道传输，避免网络安全风险
 - 由 AI 客户端自动管理，无需手动暴露服务
 - 支持工具级别的权限控制
+- 数据传输过程中不涉及敏感信息
+
+### 10.2 协议兼容性
+
+- 支持 MCP 协议 v1.0+
+- 兼容 Cursor、Trae IDE、Claude Desktop 等主流 AI IDE
+- 使用 stdio 通信，无需网络端口，减少配置复杂度
 
-## 10. 知识库
+## 11. 知识库
 
-### 10.1 知识库位置
+### 11.1 知识库位置
 
-位于 `mcp-server/public` 文件夹下，包含所有组件、指令、工具函数的详细文档和使用示例。
+位于 `dist/knowledge` 文件夹下，包含所有组件、指令、工具函数的详细文档和使用示例。这些文件是在构建过程中从 `../src/views/document/pages` 目录复制而来的。
 
-### 10.2 知识库结构
+### 11.2 知识库结构
 
 ```
-public/
-├── components/        # 组件文档（按类别分类）
-│   ├── advanced/      # 高级组件
-│   ├── ai/            # AI 相关组件
-│   ├── basic/         # 基础组件
-│   ├── data/          # 数据展示组件
-│   ├── feedback/      # 反馈组件
-│   ├── form/          # 表单组件
-│   ├── geometry/      # 几何相关组件
-│   ├── layout/        # 布局组件
-│   └── navigation/    # 导航组件
-├── directives/        # 指令文档
-├── other/             # 其他功能文档
-└── utils/             # 工具函数文档
+dist/
+└── knowledge/          # 来自 ../src/views/document/pages
+    ├── ...            # 多个 Markdown 知识文件
+    └── README.md       # 项目说明文档
 ```
 
-## 11. 许可证
+## 12. 许可证
 
 MIT