phinix 0.2.2 → 0.2.4

package/.qoder/repowiki/zh/content//345/274/200/345/217/221/344/270/216/346/265/213/350/257/225.md

@@ -0,0 +1,332 @@
+# 开发与测试
+
+<cite>
+**本文引用的文件**
+- [package.json](file://package.json)
+- [README.md](file://README.md)
+- [test-mcp.sh](file://test-mcp.sh)
+- [quick-test.js](file://quick-test.js)
+- [debug-client.js](file://debug-client.js)
+- [src/index.js](file://src/index.js)
+- [src/server.js](file://src/server.js)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南聚焦于本仓库的开发与测试流程，围绕以下目标展开：
+- 解释如何使用 npm run dev 进入开发模式，以便在代码变更时自动重启服务。
+- 详解三类测试脚本：test-mcp.sh（通过 STDIO 直连 MCP 服务器进行协议层测试）、quick-test.js（快速验证核心工具链路与返回结构）、debug-client.js（功能更全面的调试客户端，可列出工具、调用多个工具进行端到端验证）。
+- 说明各脚本的预期输出与行为，帮助开发者快速定位问题。
+
+## 项目结构
+该仓库采用“入口文件 -> 服务器实现 -> 工具注册”的分层结构：
+- 入口文件负责启动服务器模块。
+- 服务器模块完成 MCP 服务初始化、能力声明、工具注册、插件扫描与连接 STDIO 传输。
+- 测试脚本通过 STDIO 与服务器交互，模拟 MCP 客户端行为。
+
+```mermaid
+graph TB
+A["src/index.js<br/>入口"] --> B["src/server.js<br/>MCP 服务器实现"]
+B --> C["STDIO 传输<br/>StdioServerTransport"]
+B --> D["工具注册<br/>get_project_knowledge / get_component_* / get_api_definition"]
+B --> E["插件扫描<br/>src/plugins/*"]
+```
+
+图表来源
+- [src/index.js](file://src/index.js#L1-L5)
+- [src/server.js](file://src/server.js#L1-L139)
+
+章节来源
+- [src/index.js](file://src/index.js#L1-L5)
+- [src/server.js](file://src/server.js#L1-L139)
+
+## 核心组件
+- 开发模式脚本
+  - npm run dev：使用 tsx --watch 监听 src/index.js 并在文件变化时自动重启，便于本地开发调试。
+- MCP 服务器
+  - 通过 STDIO 传输与外部客户端通信，注册一组工具（项目知识、组件列表、组件定义、源码、README、示例、API 定义），并在启动时预加载项目知识。
+- 测试客户端
+  - quick-test.js：以 MCP 客户端方式连接服务器，调用 get_component_list、get_component_details、get_api_definition 等工具，校验返回结构与边界条件。
+  - debug-client.js：列出可用工具、调用组件列表与搜索，输出结构化响应，便于端到端验证。
+  - test-mcp.sh：通过 STDIO 直接发送 JSON-RPC 请求，验证 tools/list 与 tools/call 的协议层行为。
+
+章节来源
+- [package.json](file://package.json#L10-L16)
+- [src/server.js](file://src/server.js#L1-L139)
+- [quick-test.js](file://quick-test.js#L1-L142)
+- [debug-client.js](file://debug-client.js#L1-L56)
+- [test-mcp.sh](file://test-mcp.sh#L1-L13)
+
+## 架构总览
+下图展示了从测试脚本到 MCP 服务器的交互路径，以及服务器内部的工具注册与插件扫描流程。
+
+```mermaid
+sequenceDiagram
+participant Dev as "开发者终端"
+participant Script as "测试脚本<br/>quick-test.js / debug-client.js / test-mcp.sh"
+participant Server as "MCP 服务器<br/>src/server.js"
+participant Tools as "工具实现<br/>get_* 工具"
+participant Plugins as "插件扫描<br/>src/plugins/*"
+Dev->>Script : 运行测试脚本
+Script->>Server : 通过 STDIO 发送请求
+Server->>Plugins : 启动时扫描并注册插件
+Server->>Tools : 注册工具项目知识、组件系列、API
+Script->>Server : 调用工具如 get_component_list
+Server->>Tools : 分发调用
+Tools-->>Server : 返回结构化结果
+Server-->>Script : 返回 JSON-RPC 响应
+Script-->>Dev : 输出日志与断言结果
+```
+
+图表来源
+- [src/server.js](file://src/server.js#L1-L139)
+- [quick-test.js](file://quick-test.js#L1-L142)
+- [debug-client.js](file://debug-client.js#L1-L56)
+- [test-mcp.sh](file://test-mcp.sh#L1-L13)
+
+## 详细组件分析
+
+### 开发模式：npm run dev
+- 目标：在本地开发时，监视源码变更并自动重启服务器，提升迭代效率。
+- 行为要点：
+  - 使用 tsx --watch 监听 src/index.js。
+  - 当文件变化时，自动重启进程，保持服务持续可用。
+- 使用建议：
+  - 在修改服务器逻辑、工具实现或插件后，观察控制台输出确认热重载生效。
+  - 若出现异常退出，检查控制台错误堆栈并修复后再继续。
+
+章节来源
+- [package.json](file://package.json#L10-L16)
+
+### 测试脚本：test-mcp.sh（协议层测试）
+- 目的：通过 STDIO 直接向服务器发送 JSON-RPC 请求，验证 MCP 协议与工具调用的基本通路。
+- 关键步骤：
+  - 列出可用工具：tools/list
+  - 调用 get_component_list（limit=5）
+  - 调用 get_component_list（search="table", limit=3）
+- 预期输出特征：
+  - 成功时返回 JSON 结构，包含工具列表与工具调用结果。
+  - 失败时返回错误对象（如方法名无效、参数不合法等）。
+- 常见问题：
+  - 服务器未启动或 STDIO 未就绪：脚本会立即报错。
+  - 工具名拼写错误：返回方法不存在的错误。
+  - 参数缺失或类型不符：返回参数校验错误。
+
+章节来源
+- [test-mcp.sh](file://test-mcp.sh#L1-L13)
+
+### 测试脚本：quick-test.js（核心功能快速验证）
+- 目的：以 MCP 客户端方式连接服务器，快速验证核心工具链路与返回结构，覆盖边界条件。
+- 覆盖场景：
+  - 调用 get_component_list（limit=3）
+  - 调用 get_component_list（search="table", limit=2）
+  - 调用 get_component_details（不存在的组件）：验证“未找到”语义
+  - 调用 get_component_details（存在的组件，概览与完整信息）：验证文件状态、实现/定义/README/示例字段长度
+  - 调用 get_api_definition（存在与不存在的 API）：验证成功与失败分支
+- 预期输出特征：
+  - 成功时返回 data 字段，包含组件列表、文件状态、内容长度等。
+  - 失败时返回错误信息或“未找到”提示。
+- 断言建议：
+  - 组件列表长度与 limit/search 一致。
+  - 文件状态字段存在且合理。
+  - 实现/定义/README/示例内容长度为数值。
+  - API 查询返回结构与错误提示符合预期。
+
+```mermaid
+sequenceDiagram
+participant QT as "quick-test.js"
+participant S as "MCP 服务器"
+participant T as "工具实现"
+QT->>S : connect()
+QT->>S : callTool(get_component_list, {limit : 3})
+S->>T : get_component_list({limit : 3})
+T-->>S : {componentList}
+S-->>QT : {data}
+QT->>S : callTool(get_component_list, {search : "table", limit : 2})
+S->>T : get_component_list({search : "table", limit : 2})
+T-->>S : {componentList}
+S-->>QT : {data}
+QT->>S : callTool(get_component_details, {componentName : "NonExistentComponent"})
+S->>T : get_component_details(...)
+T-->>S : {found : false,...}
+S-->>QT : {data}
+QT->>S : callTool(get_component_details, {componentName : "DPHeader", includeImplementation : false})
+S->>T : get_component_details(...)
+T-->>S : {found : true,fileStatus,...}
+S-->>QT : {data}
+QT->>S : callTool(get_component_details, {componentName : "DPHeader", includeImplementation : true})
+S->>T : get_component_details(...)
+T-->>S : {found : true,projectRoot,fileStatus,files,...}
+S-->>QT : {data}
+QT->>S : callTool(get_api_definition, {url : "/api/..."})
+S->>T : get_use_api(...)
+T-->>S : {data}
+S-->>QT : {data}
+```
+
+图表来源
+- [quick-test.js](file://quick-test.js#L1-L142)
+- [src/server.js](file://src/server.js#L1-L139)
+
+章节来源
+- [quick-test.js](file://quick-test.js#L1-L142)
+
+### 测试脚本：debug-client.js（端到端调试）
+- 目的：列出可用工具、调用组件列表与搜索，输出结构化响应，便于端到端验证。
+- 关键步骤：
+  - 连接服务器
+  - listTools 获取工具清单
+  - 调用 get_component_list（limit=5）
+  - 调用 get_component_list（search="table"）
+- 预期输出特征：
+  - listTools 返回工具数组。
+  - 工具调用返回 data 字段，包含组件列表与计数。
+- 使用建议：
+  - 将输出复制到编辑器中查看缩进，便于核对字段完整性。
+  - 如遇连接失败，检查服务器是否已启动且无异常退出。
+
+```mermaid
+sequenceDiagram
+participant DC as "debug-client.js"
+participant S as "MCP 服务器"
+DC->>S : connect()
+DC->>S : listTools()
+S-->>DC : {tools}
+DC->>S : callTool(get_component_list, {limit : 5})
+S-->>DC : {data}
+DC->>S : callTool(get_component_list, {search : "table", limit : 3})
+S-->>DC : {data}
+```
+
+图表来源
+- [debug-client.js](file://debug-client.js#L1-L56)
+- [src/server.js](file://src/server.js#L1-L139)
+
+章节来源
+- [debug-client.js](file://debug-client.js#L1-L56)
+
+### MCP 服务器：启动与工具注册
+- 启动流程：
+  - 初始化 MCP 服务器实例，声明能力与描述。
+  - 包装埋点统计（analytics），随后注册工具与插件。
+  - 通过 STDIO 传输建立连接，打印可用工具列表与资源文件位置。
+  - 预加载项目知识，提升首次使用响应速度。
+- 工具注册：
+  - 注册 get_project_knowledge、get_component_list、get_component_define、get_component_source、get_component_readme、get_component_demos、get_api_definition。
+- 插件扫描：
+  - 启动时扫描 src/plugins/* 目录，动态导入每个插件的 registerPlugin 并执行注册。
+
+```mermaid
+flowchart TD
+Start(["启动服务器"]) --> Init["初始化 MCP 服务器"]
+Init --> Wrap["包装埋点统计"]
+Wrap --> RegisterTools["注册内置工具"]
+RegisterTools --> ScanPlugins["扫描插件目录"]
+ScanPlugins --> ImportPlugin["导入插件入口"]
+ImportPlugin --> CallRegister["调用 registerPlugin(server)"]
+CallRegister --> Connect["建立 STDIO 连接"]
+Connect --> Preload["预加载项目知识"]
+Preload --> Ready(["服务就绪"])
+```
+
+图表来源
+- [src/server.js](file://src/server.js#L1-L139)
+
+章节来源
+- [src/server.js](file://src/server.js#L1-L139)
+
+## 依赖关系分析
+- 开发与运行时依赖
+  - @modelcontextprotocol/sdk：提供 MCP 客户端与服务器、STDIO 传输、工具注册与调用能力。
+  - tsx：开发模式下监听并运行 TypeScript/JS 文件。
+  - zod：用于工具参数的 Schema 校验。
+- 测试脚本与服务器的耦合点
+  - quick-test.js 与 debug-client.js 通过 STDIO 与服务器交互，依赖服务器工具注册与 STDIO 传输。
+  - test-mcp.sh 直接向服务器发送 JSON-RPC 请求，依赖服务器对 tools/list 与 tools/call 的实现。
+
+```mermaid
+graph LR
+Pkg["package.json<br/>scripts & deps"] --> Dev["npm run dev"]
+Dev --> TSX["tsx --watch"]
+TSX --> Entry["src/index.js"]
+Entry --> Server["src/server.js"]
+QT["quick-test.js"] --> Server
+DC["debug-client.js"] --> Server
+SH["test-mcp.sh"] --> Server
+SDK["@modelcontextprotocol/sdk"] --> Server
+Zod["zod"] --> Server
+```
+
+图表来源
+- [package.json](file://package.json#L10-L16)
+- [src/index.js](file://src/index.js#L1-L5)
+- [src/server.js](file://src/server.js#L1-L139)
+- [quick-test.js](file://quick-test.js#L1-L142)
+- [debug-client.js](file://debug-client.js#L1-L56)
+- [test-mcp.sh](file://test-mcp.sh#L1-L13)
+
+章节来源
+- [package.json](file://package.json#L10-L16)
+- [src/server.js](file://src/server.js#L1-L139)
+
+## 性能考虑
+- 热重载与开发效率
+  - 使用 npm run dev 时，tsx --watch 会在文件变更后重启进程。建议在大型改动后进行全量测试，避免频繁小改导致的多次重启。
+- 服务器预加载
+  - 服务器启动时预加载项目知识，有助于减少首次调用延迟；若项目知识文件较大，可关注启动时间。
+- 工具调用的返回大小
+  - 某些工具（如源码、README、示例）可能返回较长文本，建议在测试中使用合理的 maxContentLength/limit 参数，避免输出过大影响可读性。
+
+## 故障排查指南
+- 服务器未启动或无法连接
+  - 现象：测试脚本立即报错或无响应。
+  - 排查：确认 npm run dev 已启动，控制台显示“MCP Server started on stdio”与“Available tools”等日志。
+- 工具名错误
+  - 现象：返回“方法不存在”或“工具未找到”。
+  - 排查：核对工具名与 README 中的工具清单一致。
+- 参数不合法
+  - 现象：返回参数校验错误或空数据。
+  - 排查：对照 README 中的参数说明，确保必填项与类型正确。
+- 项目知识或组件信息缺失
+  - 现象：get_project_knowledge 或组件相关工具返回异常。
+  - 排查：确认 src/resources/project-knowledge.md 与 src/resources/components-info.json 存在且内容完整。
+- 插件未生效
+  - 现象：期望的工具未出现在工具列表。
+  - 排查：确认插件目录结构与 registerPlugin 导出正确，服务器启动日志中应显示“注册插件: ...”。
+
+章节来源
+- [README.md](file://README.md#L297-L343)
+- [src/server.js](file://src/server.js#L1-L139)
+
+## 结论
+- 开发阶段优先使用 npm run dev，结合 quick-test.js 与 debug-client.js 进行快速验证。
+- 协议层测试可使用 test-mcp.sh，确保 STDIO 与 JSON-RPC 的基本通路正常。
+- 服务器启动时会预加载项目知识并注册工具与插件，确保首次调用的稳定性。
+- 遇到问题时，依据脚本输出与服务器日志进行逐项排查，优先确认服务器状态与工具清单。
+
+## 附录
+- 常用命令
+  - 开发模式：npm run dev
+  - 快速测试：node quick-test.js
+  - 端到端调试：node debug-client.js
+  - 协议层测试：./test-mcp.sh
+- 参考文档
+  - README 中的“开发和测试”、“MCP 工具说明”、“项目结构要求”等章节提供了工具参数与预期行为的详细说明。
+
+章节来源
+- [README.md](file://README.md#L297-L343)
+- [package.json](file://package.json#L10-L16)
+- [test-mcp.sh](file://test-mcp.sh#L1-L13)
+- [quick-test.js](file://quick-test.js#L1-L142)
+- [debug-client.js](file://debug-client.js#L1-L56)

package/.qoder/repowiki/zh/content//345/277/253/351/200/237/345/274/200/345/247/213.md

@@ -0,0 +1,329 @@
+# 快速开始
+
+<cite>
+**本文引用的文件**
+- [README.md](file://README.md)
+- [package.json](file://package.json)
+- [src/index.js](file://src/index.js)
+- [src/server.js](file://src/server.js)
+- [src/config.js](file://src/config.js)
+- [src/tools/index.js](file://src/tools/index.js)
+- [src/tools/componentList.js](file://src/tools/componentList.js)
+- [src/resources/components-info.json](file://src/resources/components-info.json)
+- [mcp-config.json](file://mcp-config.json)
+- [debug-client.js](file://debug-client.js)
+- [quick-test.js](file://quick-test.js)
+- [test-mcp.sh](file://test-mcp.sh)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南面向首次使用者，帮助你在本地快速搭建并运行 phinpilot MCP 服务器，完成以下目标：
+- 明确环境要求（Node.js 18+）
+- 安装依赖并启动服务器（两种方式）
+- 在 Cursor IDE 中配置 MCP 服务器（提供 JSON 示例）
+- 解释 mcp-config.json 的结构
+- 使用 debug-client.js 验证服务器是否正常工作，并调用核心工具（如 get_component_list）
+
+## 项目结构
+phinpilot 是一个基于 Model Context Protocol (MCP) 的服务器，通过 STDIO 传输与客户端通信。其核心入口、配置、工具注册与资源文件分布如下：
+- 入口文件：src/index.js
+- 服务器主程序：src/server.js
+- 配置解析：src/config.js（解析项目根目录、埋点配置）
+- 工具注册：src/tools/index.js（导出各工具的 Schema 与实现）
+- 资源文件：src/resources/components-info.json（组件清单）、src/resources/project-knowledge.md（项目知识）
+- MCP 配置：mcp-config.json（Cursor/MCP 客户端配置）
+- 调试与测试：debug-client.js、quick-test.js、test-mcp.sh
+
+```mermaid
+graph TB
+A["src/index.js<br/>入口"] --> B["src/server.js<br/>服务器主程序"]
+B --> C["src/config.js<br/>配置解析"]
+B --> D["src/tools/index.js<br/>工具注册"]
+D --> E["src/tools/componentList.js<br/>组件列表工具"]
+B --> F["src/resources/components-info.json<br/>组件清单"]
+G["mcp-config.json<br/>MCP 客户端配置"] --> B
+H["debug-client.js<br/>调试客户端"] --> B
+I["quick-test.js<br/>快速测试"] --> B
+J["test-mcp.sh<br/>STDIO 测试脚本"] --> B
+```
+
+图表来源
+- [src/index.js](file://src/index.js#L1-L5)
+- [src/server.js](file://src/server.js#L1-L139)
+- [src/config.js](file://src/config.js#L1-L54)
+- [src/tools/index.js](file://src/tools/index.js#L1-L47)
+- [src/tools/componentList.js](file://src/tools/componentList.js#L1-L89)
+- [src/resources/components-info.json](file://src/resources/components-info.json#L1-L200)
+- [mcp-config.json](file://mcp-config.json#L1-L10)
+- [debug-client.js](file://debug-client.js#L1-L56)
+- [quick-test.js](file://quick-test.js#L1-L142)
+- [test-mcp.sh](file://test-mcp.sh#L1-L13)
+
+章节来源
+- [README.md](file://README.md#L45-L71)
+- [package.json](file://package.json#L1-L47)
+- [src/index.js](file://src/index.js#L1-L5)
+- [src/server.js](file://src/server.js#L1-L139)
+- [src/config.js](file://src/config.js#L1-L54)
+- [src/tools/index.js](file://src/tools/index.js#L1-L47)
+- [src/resources/components-info.json](file://src/resources/components-info.json#L1-L200)
+- [mcp-config.json](file://mcp-config.json#L1-L10)
+- [debug-client.js](file://debug-client.js#L1-L56)
+- [quick-test.js](file://quick-test.js#L1-L142)
+- [test-mcp.sh](file://test-mcp.sh#L1-L13)
+
+## 核心组件
+- 入口与启动
+  - 入口文件：src/index.js 导入并启动服务器主程序。
+  - 启动方式一：npm start（使用 tsx 直接运行 src/index.js）
+  - 启动方式二：通过命令行参数或环境变量指定项目根目录
+- 服务器主程序
+  - 创建 MCP 服务器实例，注册埋点统计中间件，再注册各类工具（如 get_component_list、get_project_knowledge 等）。
+  - 启动 STDIO 传输，打印可用工具列表与资源文件位置。
+- 配置解析
+  - 优先级：命令行参数 > 环境变量 > 当前工作目录
+  - 埋点配置支持开关、上报地址、批量大小、重试次数等
+- 工具注册
+  - 通过 src/tools/index.js 统一导出各工具的 Schema 与实现，服务器逐一注册
+- 资源文件
+  - 组件清单：src/resources/components-info.json（包含组件名称与使用场景）
+  - 项目知识：src/resources/project-knowledge.md（项目背景知识与开发规范）
+
+章节来源
+- [src/index.js](file://src/index.js#L1-L5)
+- [src/server.js](file://src/server.js#L1-L139)
+- [src/config.js](file://src/config.js#L1-L54)
+- [src/tools/index.js](file://src/tools/index.js#L1-L47)
+- [src/resources/components-info.json](file://src/resources/components-info.json#L1-L200)
+
+## 架构总览
+下面的序列图展示了从启动到工具调用的关键流程，包括 STDIO 传输、工具注册、资源加载与调试客户端验证。
+
+```mermaid
+sequenceDiagram
+participant CLI as "终端"
+participant NPM as "npm 脚本"
+participant Entry as "src/index.js"
+participant Server as "src/server.js"
+participant Config as "src/config.js"
+participant Tools as "src/tools/index.js"
+participant Res as "src/resources/components-info.json"
+participant Debug as "debug-client.js"
+CLI->>NPM : 运行 npm start
+NPM->>Entry : 启动入口
+Entry->>Server : 导入服务器主程序
+Server->>Config : 解析项目根目录
+Server->>Tools : 注册埋点与工具
+Server->>Res : 加载组件清单
+Server-->>CLI : 输出可用工具与资源路径
+CLI->>Debug : 运行调试客户端
+Debug->>Server : STDIO 连接
+Debug->>Server : 列出工具
+Debug->>Server : 调用 get_component_list
+Server-->>Debug : 返回组件列表
+```
+
+图表来源
+- [src/index.js](file://src/index.js#L1-L5)
+- [src/server.js](file://src/server.js#L1-L139)
+- [src/config.js](file://src/config.js#L1-L54)
+- [src/tools/index.js](file://src/tools/index.js#L1-L47)
+- [src/resources/components-info.json](file://src/resources/components-info.json#L1-L200)
+- [debug-client.js](file://debug-client.js#L1-L56)
+
+## 详细组件分析
+
+### 启动与运行
+- 环境要求
+  - Node.js 18+（引擎声明）
+- 安装依赖
+  - 使用 npm install 安装项目依赖
+- 启动服务器
+  - 方式一：直接启动（使用当前目录作为项目根目录）
+    - npm start（脚本指向 tsx src/index.js）
+  - 方式二：指定项目根目录
+    - 通过环境变量 PROJECT_ROOT 指定
+    - 或通过命令行参数（支持 --project-root=路径 或位置参数）
+- 资源文件要求
+  - 组件清单文件：src/resources/components-info.json
+  - 项目知识文件：src/resources/project-knowledge.md（服务器会预加载）
+
+章节来源
+- [README.md](file://README.md#L45-L71)
+- [package.json](file://package.json#L1-L47)
+- [src/config.js](file://src/config.js#L1-L54)
+- [src/server.js](file://src/server.js#L1-L139)
+- [src/resources/components-info.json](file://src/resources/components-info.json#L1-L200)
+
+### Cursor IDE 中配置 MCP 服务器
+- 在 Cursor 的配置文件中添加 mcpServers，键名为 phinix
+- command 指向 node，args 指向 src/index.js
+- cwd 设置为项目根目录
+- env 可配置埋点相关参数（可选）
+- mcp-config.json 提供了一个最小化示例，可据此在 Cursor 中调整
+
+章节来源
+- [README.md](file://README.md#L72-L94)
+- [mcp-config.json](file://mcp-config.json#L1-L10)
+
+### mcp-config.json 结构说明
+- mcpServers：MCP 服务器集合
+  - 键名：服务器标识（如 phinix）
+  - command：执行命令（如 node）
+  - args：命令参数（如 ["src/index.js"]）
+  - cwd：工作目录（项目根目录）
+  - env：环境变量（可选）
+
+章节来源
+- [mcp-config.json](file://mcp-config.json#L1-L10)
+
+### 使用 debug-client.js 验证服务器
+- debug-client.js 通过 STDIO 连接 MCP 服务器，执行以下步骤：
+  - 连接服务器
+  - 列出工具
+  - 调用 get_component_list（限制返回数量）
+  - 调用 get_component_list（带搜索关键词）
+- 你可以直接运行该脚本验证服务器是否正常工作
+
+章节来源
+- [debug-client.js](file://debug-client.js#L1-L56)
+- [README.md](file://README.md#L299-L309)
+
+### 核心工具调用流程（以 get_component_list 为例）
+- 服务器在启动时注册工具，组件列表工具负责读取组件清单文件并返回组件列表
+- 调用链路：客户端 -> STDIO -> 服务器 -> 工具实现 -> 返回结果
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant STDIO as "STDIO 传输"
+participant Server as "服务器"
+participant Tool as "组件列表工具"
+participant Res as "组件清单文件"
+Client->>STDIO : 调用 get_component_list
+STDIO->>Server : 转发工具调用
+Server->>Tool : 执行 getComponentList
+Tool->>Res : 读取组件清单
+Res-->>Tool : 返回清单数据
+Tool-->>Server : 组装响应
+Server-->>Client : 返回组件列表
+```
+
+图表来源
+- [src/server.js](file://src/server.js#L1-L139)
+- [src/tools/index.js](file://src/tools/index.js#L1-L47)
+- [src/tools/componentList.js](file://src/tools/componentList.js#L1-L89)
+- [src/resources/components-info.json](file://src/resources/components-info.json#L1-L200)
+
+## 依赖关系分析
+- 入口依赖
+  - src/index.js 仅导入 src/server.js
+- 服务器依赖
+  - src/server.js 依赖 src/config.js（解析项目根目录与埋点配置）、src/tools/index.js（工具注册）、STDIO 传输
+- 工具依赖
+  - src/tools/index.js 统一导出各工具的 Schema 与实现
+  - 组件列表工具依赖 src/resources/components-info.json
+- 配置依赖
+  - src/config.js 从命令行参数、环境变量与当前工作目录解析项目根目录
+- MCP 客户端依赖
+  - debug-client.js、quick-test.js、test-mcp.sh 通过 STDIO 与服务器交互
+
+```mermaid
+graph LR
+Entry["src/index.js"] --> Server["src/server.js"]
+Server --> Config["src/config.js"]
+Server --> Tools["src/tools/index.js"]
+Tools --> CompList["src/tools/componentList.js"]
+CompList --> Res["src/resources/components-info.json"]
+Debug["debug-client.js"] --> Server
+Quick["quick-test.js"] --> Server
+Sh["test-mcp.sh"] --> Server
+```
+
+图表来源
+- [src/index.js](file://src/index.js#L1-L5)
+- [src/server.js](file://src/server.js#L1-L139)
+- [src/config.js](file://src/config.js#L1-L54)
+- [src/tools/index.js](file://src/tools/index.js#L1-L47)
+- [src/tools/componentList.js](file://src/tools/componentList.js#L1-L89)
+- [src/resources/components-info.json](file://src/resources/components-info.json#L1-L200)
+- [debug-client.js](file://debug-client.js#L1-L56)
+- [quick-test.js](file://quick-test.js#L1-L142)
+- [test-mcp.sh](file://test-mcp.sh#L1-L13)
+
+章节来源
+- [src/index.js](file://src/index.js#L1-L5)
+- [src/server.js](file://src/server.js#L1-L139)
+- [src/config.js](file://src/config.js#L1-L54)
+- [src/tools/index.js](file://src/tools/index.js#L1-L47)
+- [src/tools/componentList.js](file://src/tools/componentList.js#L1-L89)
+- [src/resources/components-info.json](file://src/resources/components-info.json#L1-L200)
+- [debug-client.js](file://debug-client.js#L1-L56)
+- [quick-test.js](file://quick-test.js#L1-L142)
+- [test-mcp.sh](file://test-mcp.sh#L1-L13)
+
+## 性能考虑
+- 组件清单文件加载：组件列表工具会尝试多个可能路径并缓存首个成功加载的路径，避免重复 IO
+- 预加载项目知识：服务器启动时预加载项目知识，确保首次使用时响应更快
+- 埋点配置：批量上报大小与重试次数可调，建议根据网络状况与吞吐量进行优化
+
+章节来源
+- [src/server.js](file://src/server.js#L1-L139)
+- [src/tools/componentList.js](file://src/tools/componentList.js#L1-L89)
+- [src/config.js](file://src/config.js#L1-L54)
+
+## 故障排查指南
+- 无法找到组件清单文件
+  - 现象：组件列表工具返回“找不到组件信息文件”
+  - 处理：确认 src/resources/components-info.json 存在且可读
+- 项目根目录设置错误
+  - 现象：服务器无法定位组件文件或资源文件
+  - 处理：通过环境变量 PROJECT_ROOT 或命令行参数指定正确的项目根目录
+- MCP 连接失败
+  - 现象：调试客户端或测试脚本报错
+  - 处理：检查 npm start 是否正常启动；确认 STDIO 传输正常；使用 test-mcp.sh 验证
+- Cursor 配置无效
+  - 现象：Cursor 无法连接 MCP 服务器
+  - 处理：核对 mcp-config.json 的 command、args、cwd、env 字段；确保路径正确
+
+章节来源
+- [src/tools/componentList.js](file://src/tools/componentList.js#L1-L89)
+- [src/config.js](file://src/config.js#L1-L54)
+- [debug-client.js](file://debug-client.js#L1-L56)
+- [test-mcp.sh](file://test-mcp.sh#L1-L13)
+- [README.md](file://README.md#L329-L343)
+
+## 结论
+通过本指南，你已经完成了：
+- 环境准备与依赖安装
+- 两种启动方式（直接启动与指定项目根目录）
+- Cursor 中 MCP 服务器的配置方法
+- 使用 debug-client.js 验证服务器并调用核心工具
+- 了解服务器架构、工具注册与资源文件要求
+
+下一步建议：
+- 准备好 src/resources/components-info.json 与 src/resources/project-knowledge.md
+- 在 Cursor 中打开 MCP 服务器并调用 get_project_knowledge 以获取项目规范
+- 使用 get_component_list 与其它工具探索组件生态
+
+## 附录
+- 快速测试脚本
+  - quick-test.js：提供更全面的工具测试流程（组件列表、搜索、组件详情、API 定义等）
+- STDIO 测试脚本
+  - test-mcp.sh：通过 STDIO 发送 JSON-RPC 请求，验证工具列表与调用
+
+章节来源
+- [quick-test.js](file://quick-test.js#L1-L142)
+- [test-mcp.sh](file://test-mcp.sh#L1-L13)