exploria-ui-mcp-server 2.1.1 → 2.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +109 -106
  2. package/dist/index.js +2840 -2700
  3. package/package.json +4 -7
package/README.md CHANGED
@@ -1,37 +1,28 @@
1
1
  # Exploria UI MCP Server
2
2
 
3
- Exploria UI MCP Server 是一个基于 MCP（Model Context Protocol）协议的服务，允许 AI 客户端（如 Cursor、Trae IDE）访问和查询 Exploria UI 组件库的文档和信息。
3
+ 基于 MCP（Model Context Protocol）协议的服务，允许 AI 客户端（如 Cursor、Trae IDE）访问和查询 Exploria UI 组件库的文档和信息。
4
4
 
5
5
  ## 1. MCP 协议简介
6
6
 
7
7
  ### 1.1 什么是 MCP？
8
8
 
9
- MCP（Model Context Protocol）是 AI 工具世界的「USB 标准」，它允许 AI 应用（如 Cursor、Trae IDE）通过统一的接口访问自定义数据和功能。
9
+ MCP 是 AI 工具世界的「USB 标准」，允许 AI 应用通过统一接口访问自定义数据和功能。
10
10
 
11
- ### 1.2 核心设计理念
11
+ ### 1.2 核心特性
12
12
 
13
- - **统一接口**：为所有 AI 工具提供统一的访问方式，避免为每个 AI 工具单独开发适配层
14
- - **轻量通信**：默认使用标准输入输出（stdio）进行通信，无需网络端口
15
- - **自动管理**：由 AI 客户端自动启动、管理和停止，无需手动干预
13
+ - **统一接口**：为所有 AI 工具提供统一访问方式
14
+ - **轻量通信**：使用标准输入输出（stdio）通信，无需网络端口
15
+ - **自动管理**：由 AI 客户端自动启动、管理和停止
16
16
  - **安全可靠**：通过管道通信，避免网络安全风险
17
17
 
18
- ### 1.3 通信原理
18
+ ### 1.3 通信流程
19
19
 
20
- MCP Server 与 AI IDE 的通信流程：
21
-
22
- 1. AI IDE（如 Cursor/Trae）启动时读取配置文件
23
- 2. 根据配置中的 `mcpServers` 自动启动 MCP Server 作为子进程
24
- 3. 通过标准输入输出（stdio）与 MCP Server 通信
20
+ 1. AI IDE 启动时读取配置文件
21
+ 2. 根据 `mcpServers` 配置自动启动 MCP Server 子进程
22
+ 3. 通过 stdio 与 MCP Server 通信
25
23
  4. 发送初始化指令，获取可用工具列表
26
- 5. 在需要时调用相应工具，获取结果
27
- 6. IDE 关闭时，自动终止 MCP Server 进程
28
-
29
- **关键特点**：
30
-
31
- - Cursor/Trae 是 MCP Server 的父进程
32
- - 通信方式：标准输入输出（stdio），不是网络通信
33
- - 无端口、无 TCP、无 HTTP
34
- - 所有消息通过 JSON 格式管道传输
24
+ 5. 按需调用工具，获取结果
25
+ 6. IDE 关闭时自动终止 MCP Server 进程
35
26
 
36
27
  ## 2. 快速开始
37
28
 
@@ -41,59 +32,32 @@ MCP Server 与 AI IDE 的通信流程：
41
32
  pnpm install
42
33
  ```
43
34
 
44
- ### 2.2 Cursor 配置
35
+ ### 2.2 AI IDE 配置
45
36
 
46
- 1. 打开 Cursor 配置文件：`%APPDATA%\Cursor\cursor_config.json`
47
- 2. 添加以下配置：
37
+ 所有 AI IDE 使用统一配置格式：
48
38
 
49
39
  ```json
50
40
  {
51
41
  "mcpServers": {
52
- "exploria-ui-mcp": {
53
- "command": "pnpm",
54
- "args": ["serve"],
55
- "cwd": "C:\\Users\\YYWD4\\Desktop\\exploria-ui-document\\mcp-server"
42
+ "exploria-ui-mcp-server": {
43
+ "command": "npx",
44
+ "args": ["exploria-ui-mcp-server"]
56
45
  }
57
46
  }
58
47
  }
59
48
  ```
60
49
 
61
- **注意**：请将 `cwd` 路径替换为您实际的项目路径。
62
-
63
- 3. 重启 Cursor，它会自动启动并连接到 MCP Server
64
-
65
- ### 2.3 Trae IDE 配置
66
-
67
- 1. 打开 Trae IDE MCP 配置文件：`.trae/mcp.json`（位于项目根目录）
68
- 2. 添加以下配置：
69
-
70
- ```json
71
- {
72
- "servers": [
73
- {
74
- "id": "exploria-ui-mcp",
75
- "name": "Exploria UI MCP Server",
76
- "command": "pnpm",
77
- "args": ["mcp:dev"],
78
- "cwd": ".",
79
- "env": {},
80
- "enabled": true
81
- }
82
- ]
83
- }
84
- ```
85
-
86
- **注意**：
87
-
88
- - `cwd` 路径为项目根目录
89
- - 使用根项目的 `mcp:dev` 脚本启动服务
90
- - 确保 `enabled` 字段设置为 `true` 以启用该服务器
50
+ #### 具体 IDE 配置
91
51
 
92
- 3. 重启 Trae IDE 或重新加载配置，它会自动启动并连接到 MCP Server
52
+ | IDE | 配置文件位置 | 操作步骤 |
53
+ | ------------------- | ------------------------------------- | ------------------------------------------------------ |
54
+ | Cursor | `%APPDATA%\Cursor\cursor_config.json` | 1. 打开配置文件<br>2. 添加上述配置<br>3. 重启 Cursor |
55
+ | Trae IDE | `.trae/mcp.json`（项目根目录） | 1. 打开配置文件<br>2. 添加上述配置<br>3. 重启 Trae IDE |
56
+ | 其他支持 MCP 的 IDE | 参考官方文档 | 1. 找到 MCP 配置文件<br>2. 添加上述配置<br>3. 重启 IDE |
93
57
 
94
- ### 2.4 验证配置
58
+ ### 2.3 验证配置
95
59
 
96
- 配置完成后，在 AI IDE 中输入类似以下的查询，验证 MCP Server 是否正常工作：
60
+ 在 AI IDE 中输入查询验证服务是否正常：
97
61
 
98
62
  ```
99
63
  帮我查一下 button 组件的文档
@@ -103,20 +67,20 @@ pnpm install
103
67
 
104
68
  ### 3.1 工具（Tools）
105
69
 
106
- | 工具名称 | 描述 | 参数 | 返回值 |
107
- | ------------------------ | ------------------------- | --------------------------------- | -------------------------------------- |
108
- | `search_documents` | 搜索 Exploria UI 组件文档 | `query: string` | 匹配的组件列表 |
109
- | `get_component_list` | 获取所有组件列表 | 无 | 所有组件的基本信息 |
110
- | `get_component_details` | 获取指定组件的详细信息 | `componentName: string` | 组件的详细信息，包括属性、事件、插槽等 |
111
- | `search_and_get_details` | 搜索并获取组件详情 | `query: string`, `limit?: number` | 匹配的组件列表，包含详细信息 |
70
+ | 工具名称 | 描述 | 参数 | 返回值 |
71
+ | ------------------------ | ------------------ | --------------------------------- | ---------------------------------- |
72
+ | `search_documents` | 搜索组件文档 | `query: string` | 匹配的组件列表 |
73
+ | `get_component_list` | 获取所有组件列表 | 无 | 所有组件基本信息 |
74
+ | `get_component_details` | 获取组件详情 | `componentName: string` | 组件详细信息（属性、事件、插槽等） |
75
+ | `search_and_get_details` | 搜索并获取组件详情 | `query: string`, `limit?: number` | 匹配的组件列表（含详情） |
112
76
 
113
77
  ### 3.2 资源（Resources）
114
78
 
115
- | 资源 URI | 描述 | 返回值 |
116
- | ------------------------------- | -------------- | -------------------------------- |
117
- | `status://exploria-ui-server` | 服务器状态信息 | 服务器运行状态、版本、运行时间等 |
118
- | `docs://exploria-ui-api` | API 文档 | 完整的 API 文档 |
119
- | `components://exploria-ui-list` | 组件列表资源 | 所有组件的基本信息 |
79
+ | 资源 URI | 描述 | 返回值 |
80
+ | ------------------------------- | ---------- | -------------------------- |
81
+ | `status://exploria-ui-server` | 服务器状态 | 运行状态、版本、运行时间等 |
82
+ | `docs://exploria-ui-api` | API 文档 | 完整 API 文档 |
83
+ | `components://exploria-ui-list` | 组件列表 | 所有组件基本信息 |
120
84
 
121
85
  ### 3.3 提示（Prompts）
122
86
 
@@ -131,10 +95,10 @@ pnpm install
131
95
 
132
96
  | 模块 | 功能 |
133
97
  | ------------- | -------------------------------------- |
134
- | **Tools** | 可执行功能，如搜索文档、获取组件详情 |
135
- | **Resources** | 提供只读数据，如服务器状态、API 文档 |
136
- | **Prompts** | 预定义模板，用于生成组件文档和使用示例 |
137
- | **Utils** | 工具类，如文档解析器 |
98
+ | **Tools** | 可执行功能（搜索文档、获取组件详情等） |
99
+ | **Resources** | 提供只读数据（服务器状态、API 文档等） |
100
+ | **Prompts** | 预定义模板（生成文档、使用示例等） |
101
+ | **Utils** | 工具类（文档解析器等） |
138
102
 
139
103
  ### 4.2 项目结构
140
104
 
@@ -157,7 +121,7 @@ src/
157
121
  │ ├── componentDocumentation.ts # 生成组件文档模板
158
122
  │ └── usageExample.ts # 生成组件使用示例
159
123
  └── utils/ # 工具类
160
- └── documentParser.ts # 文档解析器，处理组件文档
124
+ └── documentParser.ts # 文档解析器
161
125
  ```
162
126
 
163
127
  ## 5. 开发与调试
@@ -168,81 +132,120 @@ src/
168
132
  pnpm build
169
133
  ```
170
134
 
171
- ### 5.2 本地运行（仅开发阶段）
135
+ ### 5.2 本地运行
136
+
137
+ #### 在 mcp-server 目录下运行（推荐）：
138
+
139
+ ```bash
140
+ # 构建 MCP Server
141
+ pnpm run build
142
+
143
+ # 运行构建后的服务
144
+ pnpm run start
145
+ ```
172
146
 
173
- **注意**：在生产环境中，MCP Server 由 AI IDE 自动启动和管理，无需手动运行。以下命令仅用于开发和调试阶段。
147
+ #### 或在项目根目录执行：
174
148
 
175
149
  ```bash
176
- # 从根项目启动 MCP Server 开发模式
150
+ # 开发模式
177
151
  pnpm mcp:dev
178
152
 
179
153
  # 构建 MCP Server
180
154
  pnpm mcp:build
181
155
 
182
- # 运行构建后的 MCP Server
156
+ # 运行构建后的服务
183
157
  pnpm mcp:start
184
158
  ```
185
159
 
186
- **注意**：这些命令需要在项目根目录下执行，而不是 mcp-server 子目录。
187
-
188
- ### 5.3 使用 MCP Dev 工具
189
-
190
- 安装 MCP Dev 工具进行调试：
160
+ ### 5.3 使用 MCP Inspector 调试
191
161
 
192
162
  ```bash
193
- npm install -g @modelcontextprotocol/dev
163
+ # 使用 MCP Inspector 启动服务，方便调试
164
+ npx -y @modelcontextprotocol/inspector node dist/index.js
194
165
  ```
195
166
 
196
- 然后在项目目录中运行：
167
+ ### 5.4 故障排除
197
168
 
198
- ```bash
199
- mcp dev src/index.ts
200
- ```
169
+ 1. **连接失败或 "Command not found" 错误**：
170
+ - 确保已正确构建项目：`pnpm run build`
171
+ - 检查当前工作目录，确保在正确的位置运行命令
172
+ - 查看控制台输出的错误信息，针对性解决
201
173
 
202
- 这会模拟 AI IDE 启动和调用流程，便于调试。
174
+ 2. **JSON 解析错误**：
175
+ - 确保所有日志输出已重定向到 stderr（本项目已自动处理）
176
+ - 检查是否有其他进程占用了 stdio
177
+
178
+ 3. **文档未找到**：
179
+ - 确保文档已正确复制到 `public` 目录
180
+ - 检查 `docsRoot` 配置是否正确
203
181
 
204
182
  ## 6. 扩展指南
205
183
 
206
184
  ### 6.1 添加新工具
207
185
 
208
- 1. 在 `src/tools/` 目录下创建新的工具文件，如 `newTool.ts`
186
+ 1. 在 `src/tools/` 目录下创建新工具文件（如 `newTool.ts`）
209
187
  2. 实现工具函数并注册到 MCP Server
210
188
  3. 在 `src/tools/index.ts` 中导入并注册新工具
211
189
 
212
190
  ### 6.2 添加新资源
213
191
 
214
- 1. 在 `src/resources/` 目录下创建新的资源文件，如 `newResource.ts`
192
+ 1. 在 `src/resources/` 目录下创建新资源文件
215
193
  2. 实现资源函数并注册到 MCP Server
216
194
  3. 在 `src/resources/index.ts` 中导入并注册新资源
217
195
 
218
196
  ### 6.3 添加新提示
219
197
 
220
- 1. 在 `src/prompts/` 目录下创建新的提示文件，如 `newPrompt.ts`
198
+ 1. 在 `src/prompts/` 目录下创建新提示文件
221
199
  2. 实现提示函数并注册到 MCP Server
222
200
  3. 在 `src/prompts/index.ts` 中导入并注册新提示
223
201
 
224
202
  ## 7. 技术栈
225
203
 
226
- | 技术 | 用途 |
227
- | --------------------------- | ---------------------------- |
228
- | `@modelcontextprotocol/sdk` | 官方 MCP TypeScript SDK |
229
- | `zod` | 用于工具参数的运行时类型校验 |
230
- | `tsx` | 直接运行 TypeScript 代码 |
231
- | `typescript` | 类型安全 |
232
- | `pnpm` | 包管理 |
204
+ | 技术 | 用途 |
205
+ | --------------------------- | ------------------------ |
206
+ | `@modelcontextprotocol/sdk` | 官方 MCP TypeScript SDK |
207
+ | `zod` | 工具参数运行时类型校验 |
208
+ | `tsx` | 直接运行 TypeScript 代码 |
209
+ | `typescript` | 类型安全 |
210
+ | `pnpm` | 包管理 |
233
211
 
234
212
  ## 8. 协议兼容性
235
213
 
236
214
  - 支持 MCP 协议 v1.0+
237
- - 兼容 Cursor、Trae IDE、Claude Desktop 等支持 MCP 的 AI 客户端
238
- - 使用标准输入输出（stdio）通信，无需网络端口
215
+ - 兼容 Cursor、Trae IDE、Claude Desktop 等
216
+ - 使用 stdio 通信，无需网络端口
239
217
 
240
218
  ## 9. 安全特性
241
219
 
242
220
  - 无网络通信，所有数据通过管道传输
243
221
  - 由 AI 客户端自动管理，无需手动暴露服务
244
- - 支持工具级别的权限控制（通过 MCP SDK 实现）
222
+ - 支持工具级别的权限控制
223
+
224
+ ## 10. 知识库
225
+
226
+ ### 10.1 知识库位置
227
+
228
+ 位于 `mcp-server/public` 文件夹下，包含所有组件、指令、工具函数的详细文档和使用示例。
229
+
230
+ ### 10.2 知识库结构
231
+
232
+ ```
233
+ public/
234
+ ├── components/ # 组件文档（按类别分类）
235
+ │ ├── advanced/ # 高级组件
236
+ │ ├── ai/ # AI 相关组件
237
+ │ ├── basic/ # 基础组件
238
+ │ ├── data/ # 数据展示组件
239
+ │ ├── feedback/ # 反馈组件
240
+ │ ├── form/ # 表单组件
241
+ │ ├── geometry/ # 几何相关组件
242
+ │ ├── layout/ # 布局组件
243
+ │ └── navigation/ # 导航组件
244
+ ├── directives/ # 指令文档
245
+ ├── other/ # 其他功能文档
246
+ └── utils/ # 工具函数文档
247
+ ```
245
248
 
246
- ## 10. 许可证
249
+ ## 11. 许可证
247
250
 
248
251
  MIT