exploria-ui-mcp-server 2.0.0 → 2.1.3

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 +93 -116
  2. package/dist/index.js +2257 -2004
  3. package/package.json +5 -1
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,58 +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` 路径替换为您实际的项目路径。
50
+ #### 具体 IDE 配置
62
51
 
63
- 3. 重启 Cursor，它会自动启动并连接到 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 |
64
57
 
65
- ### 2.3 Trae IDE 配置
58
+ ### 2.3 验证配置
66
59
 
67
- 1. 打开 Trae IDE MCP 配置文件：`.cursor/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": ["serve"],
78
- "cwd": "mcp-server",
79
- "env": {},
80
- "enabled": true
81
- }
82
- ]
83
- }
84
- ```
85
-
86
- **注意**：
87
-
88
- - `cwd` 路径为相对于项目根目录的路径
89
- - 确保 `enabled` 字段设置为 `true` 以启用该服务器
90
-
91
- 3. 重启 Trae IDE 或重新加载配置，它会自动启动并连接到 MCP Server
92
-
93
- ### 2.4 验证配置
94
-
95
- 配置完成后，在 AI IDE 中输入类似以下的查询，验证 MCP Server 是否正常工作：
60
+ 在 AI IDE 中输入查询验证服务是否正常：
96
61
 
97
62
  ```
98
63
  帮我查一下 button 组件的文档
@@ -102,38 +67,38 @@ pnpm install
102
67
 
103
68
  ### 3.1 工具（Tools）
104
69
 
105
- | 工具名称 | 描述 | 参数 | 返回值 |
106
- | ------------------------ | ------------------------- | --------------------------------- | -------------------------------------- |
107
- | `search_documents` | 搜索 Exploria UI 组件文档 | `query: string` | 匹配的组件列表 |
108
- | `get_component_list` | 获取所有组件列表 | 无 | 所有组件的基本信息 |
109
- | `get_component_details` | 获取指定组件的详细信息 | `componentName: string` | 组件的详细信息，包括属性、事件、插槽等 |
110
- | `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` | 匹配的组件列表（含详情） |
111
76
 
112
77
  ### 3.2 资源（Resources）
113
78
 
114
- | 资源 URI | 描述 | 返回值 |
115
- | ------------------------------- | -------------- | -------------------------------- |
116
- | `status://exploria-ui-server` | 服务器状态信息 | 服务器运行状态、版本、运行时间等 |
117
- | `docs://exploria-ui-api` | API 文档 | 完整的 API 文档 |
118
- | `components://exploria-ui-list` | 组件列表资源 | 所有组件的基本信息 |
79
+ | 资源 URI | 描述 | 返回值 |
80
+ |---------|------|--------|
81
+ | `status://exploria-ui-server` | 服务器状态 | 运行状态、版本、运行时间等 |
82
+ | `docs://exploria-ui-api` | API 文档 | 完整 API 文档 |
83
+ | `components://exploria-ui-list` | 组件列表 | 所有组件基本信息 |
119
84
 
120
85
  ### 3.3 提示（Prompts）
121
86
 
122
- | 提示名称 | 描述 | 参数 | 返回值 |
123
- | ------------------------- | ---------------- | -------------------------------------------- | ---------------- |
124
- | `component_documentation` | 生成组件文档模板 | `componentName: string` | 组件文档模板 |
125
- | `usage_example` | 生成组件使用示例 | `componentName: string`, `scenario?: string` | 组件使用示例代码 |
87
+ | 提示名称 | 描述 | 参数 | 返回值 |
88
+ |---------|------|------|--------|
89
+ | `component_documentation` | 生成组件文档模板 | `componentName: string` | 组件文档模板 |
90
+ | `usage_example` | 生成组件使用示例 | `componentName: string`, `scenario?: string` | 组件使用示例代码 |
126
91
 
127
92
  ## 4. 项目架构
128
93
 
129
94
  ### 4.1 核心模块
130
95
 
131
- | 模块 | 功能 |
132
- | ------------- | -------------------------------------- |
133
- | **Tools** | 可执行功能，如搜索文档、获取组件详情 |
134
- | **Resources** | 提供只读数据，如服务器状态、API 文档 |
135
- | **Prompts** | 预定义模板，用于生成组件文档和使用示例 |
136
- | **Utils** | 工具类，如文档解析器 |
96
+ | 模块 | 功能 |
97
+ |------|------|
98
+ | **Tools** | 可执行功能（搜索文档、获取组件详情等） |
99
+ | **Resources** | 提供只读数据（服务器状态、API 文档等） |
100
+ | **Prompts** | 预定义模板（生成文档、使用示例等） |
101
+ | **Utils** | 工具类（文档解析器等） |
137
102
 
138
103
  ### 4.2 项目结构
139
104
 
@@ -156,7 +121,7 @@ src/
156
121
  │ ├── componentDocumentation.ts # 生成组件文档模板
157
122
  │ └── usageExample.ts # 生成组件使用示例
158
123
  └── utils/ # 工具类
159
- └── documentParser.ts # 文档解析器，处理组件文档
124
+ └── documentParser.ts # 文档解析器
160
125
  ```
161
126
 
162
127
  ## 5. 开发与调试
@@ -169,74 +134,86 @@ pnpm build
169
134
 
170
135
  ### 5.2 本地运行（仅开发阶段）
171
136
 
172
- **注意**：在生产环境中，MCP Server 由 AI IDE 自动启动和管理，无需手动运行。以下命令仅用于开发和调试阶段。
173
-
174
- ```bash
175
- # 使用 tsx 直接运行 TypeScript 代码（开发模式）
176
- pnpm serve
177
-
178
- # 运行构建后的代码（生产模式测试）
179
- pnpm start
180
- ```
181
-
182
- ### 5.3 使用 MCP Dev 工具
183
-
184
- 安装 MCP Dev 工具进行调试：
137
+ 在项目根目录执行：
185
138
 
186
139
  ```bash
187
- npm install -g @modelcontextprotocol/dev
188
- ```
140
+ # 开发模式
141
+ pnpm mcp:dev
189
142
 
190
- 然后在项目目录中运行：
143
+ # 构建 MCP Server
144
+ pnpm mcp:build
191
145
 
192
- ```bash
193
- mcp dev src/index.ts
146
+ # 运行构建后的服务
147
+ pnpm mcp:start
194
148
  ```
195
149
 
196
- 这会模拟 AI IDE 启动和调用流程，便于调试。
197
-
198
150
  ## 6. 扩展指南
199
151
 
200
152
  ### 6.1 添加新工具
201
153
 
202
- 1. 在 `src/tools/` 目录下创建新的工具文件，如 `newTool.ts`
154
+ 1. 在 `src/tools/` 目录下创建新工具文件（如 `newTool.ts`）
203
155
  2. 实现工具函数并注册到 MCP Server
204
156
  3. 在 `src/tools/index.ts` 中导入并注册新工具
205
157
 
206
158
  ### 6.2 添加新资源
207
159
 
208
- 1. 在 `src/resources/` 目录下创建新的资源文件，如 `newResource.ts`
160
+ 1. 在 `src/resources/` 目录下创建新资源文件
209
161
  2. 实现资源函数并注册到 MCP Server
210
162
  3. 在 `src/resources/index.ts` 中导入并注册新资源
211
163
 
212
164
  ### 6.3 添加新提示
213
165
 
214
- 1. 在 `src/prompts/` 目录下创建新的提示文件，如 `newPrompt.ts`
166
+ 1. 在 `src/prompts/` 目录下创建新提示文件
215
167
  2. 实现提示函数并注册到 MCP Server
216
168
  3. 在 `src/prompts/index.ts` 中导入并注册新提示
217
169
 
218
170
  ## 7. 技术栈
219
171
 
220
- | 技术 | 用途 |
221
- | --------------------------- | ---------------------------- |
222
- | `@modelcontextprotocol/sdk` | 官方 MCP TypeScript SDK |
223
- | `zod` | 用于工具参数的运行时类型校验 |
224
- | `tsx` | 直接运行 TypeScript 代码 |
225
- | `typescript` | 类型安全 |
226
- | `pnpm` | 包管理 |
172
+ | 技术 | 用途 |
173
+ |-----|------|
174
+ | `@modelcontextprotocol/sdk` | 官方 MCP TypeScript SDK |
175
+ | `zod` | 工具参数运行时类型校验 |
176
+ | `tsx` | 直接运行 TypeScript 代码 |
177
+ | `typescript` | 类型安全 |
178
+ | `pnpm` | 包管理 |
227
179
 
228
180
  ## 8. 协议兼容性
229
181
 
230
182
  - 支持 MCP 协议 v1.0+
231
- - 兼容 Cursor、Trae IDE、Claude Desktop 等支持 MCP 的 AI 客户端
232
- - 使用标准输入输出（stdio）通信，无需网络端口
183
+ - 兼容 Cursor、Trae IDE、Claude Desktop 等
184
+ - 使用 stdio 通信，无需网络端口
233
185
 
234
186
  ## 9. 安全特性
235
187
 
236
188
  - 无网络通信，所有数据通过管道传输
237
189
  - 由 AI 客户端自动管理，无需手动暴露服务
238
- - 支持工具级别的权限控制（通过 MCP SDK 实现）
190
+ - 支持工具级别的权限控制
191
+
192
+ ## 10. 知识库
193
+
194
+ ### 10.1 知识库位置
195
+
196
+ 位于 `mcp-server/public` 文件夹下，包含所有组件、指令、工具函数的详细文档和使用示例。
197
+
198
+ ### 10.2 知识库结构
199
+
200
+ ```
201
+ public/
202
+ ├── components/ # 组件文档（按类别分类）
203
+ │ ├── advanced/ # 高级组件
204
+ │ ├── ai/ # AI 相关组件
205
+ │ ├── basic/ # 基础组件
206
+ │ ├── data/ # 数据展示组件
207
+ │ ├── feedback/ # 反馈组件
208
+ │ ├── form/ # 表单组件
209
+ │ ├── geometry/ # 几何相关组件
210
+ │ ├── layout/ # 布局组件
211
+ │ └── navigation/ # 导航组件
212
+ ├── directives/ # 指令文档
213
+ ├── other/ # 其他功能文档
214
+ └── utils/ # 工具函数文档
215
+ ```
239
216
 
240
- ## 10. 许可证
217
+ ## 11. 许可证
241
218
 
242
219
  MIT