exploria-ui-mcp-server 2.0.0

package/LICENSE

@@ -0,0 +1,194 @@
+木兰宽松许可证，第2版
+
+木兰宽松许可证，第2版
+
+2020年1月 http://license.coscl.org.cn/MulanPSL2
+
+您对“软件”的复制、使用、修改及分发受木兰宽松许可证，第2版（“本许可证”）的如下条款的约束：
+
+0.   定义
+
+“软件” 是指由“贡献”构成的许可在“本许可证”下的程序和相关文档的集合。
+
+“贡献” 是指由任一“贡献者”许可在“本许可证”下的受版权法保护的作品。
+
+“贡献者” 是指将受版权法保护的作品许可在“本许可证”下的自然人或“法人实体”。
+
+“法人实体” 是指提交贡献的机构及其“关联实体”。
+
+“关联实体” 是指，对“本许可证”下的行为方而言，控制、受控制或与其共同受控制的机构，此处的控制是
+指有受控方或共同受控方至少50%直接或间接的投票权、资金或其他有价证券。
+
+1.   授予版权许可
+
+每个“贡献者”根据“本许可证”授予您永久性的、全球性的、免费的、非独占的、不可撤销的版权许可，您可
+以复制、使用、修改、分发其“贡献”，不论修改与否。
+
+2.   授予专利许可
+
+每个“贡献者”根据“本许可证”授予您永久性的、全球性的、免费的、非独占的、不可撤销的（根据本条规定
+撤销除外）专利许可，供您制造、委托制造、使用、许诺销售、销售、进口其“贡献”或以其他方式转移其“贡
+献”。前述专利许可仅限于“贡献者”现在或将来拥有或控制的其“贡献”本身或其“贡献”与许可“贡献”时的“软
+件”结合而将必然会侵犯的专利权利要求，不包括对“贡献”的修改或包含“贡献”的其他结合。如果您或您的“
+关联实体”直接或间接地，就“软件”或其中的“贡献”对任何人发起专利侵权诉讼（包括反诉或交叉诉讼）或
+其他专利维权行动，指控其侵犯专利权，则“本许可证”授予您对“软件”的专利许可自您提起诉讼或发起维权
+行动之日终止。
+
+3.   无商标许可
+
+“本许可证”不提供对“贡献者”的商品名称、商标、服务标志或产品名称的商标许可，但您为满足第4条规定
+的声明义务而必须使用除外。
+
+4.   分发限制
+
+您可以在任何媒介中将“软件”以源程序形式或可执行形式重新分发，不论修改与否，但您必须向接收者提供“
+本许可证”的副本，并保留“软件”中的版权、商标、专利及免责声明。
+
+5.   免责声明与责任限制
+
+“软件”及其中的“贡献”在提供时不带任何明示或默示的担保。在任何情况下，“贡献者”或版权所有者不对
+任何人因使用“软件”或其中的“贡献”而引发的任何直接或间接损失承担责任，不论因何种原因导致或者基于
+何种法律理论，即使其曾被建议有此种损失的可能性。
+
+6.   语言
+
+“本许可证”以中英文双语表述，中英文版本具有同等法律效力。如果中英文版本存在任何冲突不一致，以中文
+版为准。
+
+条款结束
+
+如何将木兰宽松许可证，第2版，应用到您的软件
+
+如果您希望将木兰宽松许可证，第2版，应用到您的新软件，为了方便接收者查阅，建议您完成如下三步：
+
+1， 请您补充如下声明中的空白，包括软件名、软件的首次发表年份以及您作为版权人的名字；
+
+2， 请您在软件包的一级目录下创建以“LICENSE”为名的文件，将整个许可证文本放入该文件中；
+
+3， 请将如下声明文本放入每个源文件的头部注释中。
+
+Copyright (c) [Year] [name of copyright holder]
+[Software Name] is licensed under Mulan PSL v2.
+You can use this software according to the terms and conditions of the Mulan
+PSL v2.
+You may obtain a copy of Mulan PSL v2 at:
+         http://license.coscl.org.cn/MulanPSL2
+THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY
+KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+NON-INFRINGEMENT, MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
+See the Mulan PSL v2 for more details.
+
+Mulan Permissive Software License，Version 2
+
+Mulan Permissive Software License，Version 2 (Mulan PSL v2)
+
+January 2020 http://license.coscl.org.cn/MulanPSL2
+
+Your reproduction, use, modification and distribution of the Software shall
+be subject to Mulan PSL v2 (this License) with the following terms and
+conditions:
+
+0. Definition
+
+Software means the program and related documents which are licensed under
+this License and comprise all Contribution(s).
+
+Contribution means the copyrightable work licensed by a particular
+Contributor under this License.
+
+Contributor means the Individual or Legal Entity who licenses its
+copyrightable work under this License.
+
+Legal Entity means the entity making a Contribution and all its
+Affiliates.
+
+Affiliates means entities that control, are controlled by, or are under
+common control with the acting entity under this License, ‘control’ means
+direct or indirect ownership of at least fifty percent (50%) of the voting
+power, capital or other securities of controlled or commonly controlled
+entity.
+
+1. Grant of Copyright License
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to you a perpetual, worldwide, royalty-free, non-exclusive,
+irrevocable copyright license to reproduce, use, modify, or distribute its
+Contribution, with modification or not.
+
+2. Grant of Patent License
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to you a perpetual, worldwide, royalty-free, non-exclusive,
+irrevocable (except for revocation under this Section) patent license to
+make, have made, use, offer for sale, sell, import or otherwise transfer its
+Contribution, where such patent license is only limited to the patent claims
+owned or controlled by such Contributor now or in future which will be
+necessarily infringed by its Contribution alone, or by combination of the
+Contribution with the Software to which the Contribution was contributed.
+The patent license shall not apply to any modification of the Contribution,
+and any other combination which includes the Contribution. If you or your
+Affiliates directly or indirectly institute patent litigation (including a
+cross claim or counterclaim in a litigation) or other patent enforcement
+activities against any individual or entity by alleging that the Software or
+any Contribution in it infringes patents, then any patent license granted to
+you under this License for the Software shall terminate as of the date such
+litigation or activity is filed or taken.
+
+3. No Trademark License
+
+No trademark license is granted to use the trade names, trademarks, service
+marks, or product names of Contributor, except as required to fulfill notice
+requirements in section 4.
+
+4. Distribution Restriction
+
+You may distribute the Software in any medium with or without modification,
+whether in source or executable forms, provided that you provide recipients
+with a copy of this License and retain copyright, patent, trademark and
+disclaimer statements in the Software.
+
+5. Disclaimer of Warranty and Limitation of Liability
+
+THE SOFTWARE AND CONTRIBUTION IN IT ARE PROVIDED WITHOUT WARRANTIES OF ANY
+KIND, EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL ANY CONTRIBUTOR OR
+COPYRIGHT HOLDER BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING, BUT NOT
+LIMITED TO ANY DIRECT, OR INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING
+FROM YOUR USE OR INABILITY TO USE THE SOFTWARE OR THE CONTRIBUTION IN IT, NO
+MATTER HOW IT’S CAUSED OR BASED ON WHICH LEGAL THEORY, EVEN IF ADVISED OF
+THE POSSIBILITY OF SUCH DAMAGES.
+
+6. Language
+
+THIS LICENSE IS WRITTEN IN BOTH CHINESE AND ENGLISH, AND THE CHINESE VERSION
+AND ENGLISH VERSION SHALL HAVE THE SAME LEGAL EFFECT. IN THE CASE OF
+DIVERGENCE BETWEEN THE CHINESE AND ENGLISH VERSIONS, THE CHINESE VERSION
+SHALL PREVAIL.
+
+END OF THE TERMS AND CONDITIONS
+
+How to Apply the Mulan Permissive Software License，Version 2
+(Mulan PSL v2) to Your Software
+
+To apply the Mulan PSL v2 to your work, for easy identification by
+recipients, you are suggested to complete following three steps:
+
+i. Fill in the blanks in following statement, including insert your software
+name, the year of the first publication of your software, and your name
+identified as the copyright owner;
+
+ii. Create a file named "LICENSE" which contains the whole context of this
+License in the first directory of your software package;
+
+iii. Attach the statement to the appropriate annotated syntax at the
+beginning of each source file.
+
+Copyright (c) [Year] [name of copyright holder]
+[Software Name] is licensed under Mulan PSL v2.
+You can use this software according to the terms and conditions of the Mulan
+PSL v2.
+You may obtain a copy of Mulan PSL v2 at:
+         http://license.coscl.org.cn/MulanPSL2
+THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY
+KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+NON-INFRINGEMENT, MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
+See the Mulan PSL v2 for more details.

package/README.md

@@ -0,0 +1,242 @@
+# 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