feat: MCP服务拆解优化

Author: Taois

drpy-node-mcp/README.md

@@ -2,7 +2,7 @@
 
 这是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 实现的辅助服务，旨在帮助 AI 助手更方便地维护 `drpy-node` 项目。
 
-通过这个 MCP 服务，AI 可以直接安全地访问项目文件系统、管理爬虫源、检查路由信息以及执行基本的运维操作。
+通过这个 MCP 服务，AI 可以直接安全地访问项目文件系统、管理爬虫源、检查路由信息、分析日志、查询数据库以及执行基本的运维操作。
 
 ## 目录
 
@@ -14,11 +14,9 @@
   - [客户端配置 (Trae/Claude Desktop)](#客户端配置-traeclaude-desktop)
   - [可用工具 (Tools)](#可用工具-tools)
     - [文件系统操作](#文件系统操作)
-    - [爬虫源管理](#爬虫源管理)
-    - [高级开发工具 (New)](#高级开发工具-new)
-    - [系统维护](#系统维护)
+    - [爬虫开发与调试 (New)](#爬虫开发与调试-new)
+    - [系统维护与监控 (New)](#系统维护与监控-new)
   - [AI 交互示例 (Best Practice)](#ai-交互示例-best-practice)
-  - [配置说明](#配置说明)
 
 ## 安装与运行
 
@@ -64,154 +62,114 @@ node index.js
 
 ## 可用工具 (Tools)
 
-本服务提供以下工具供 AI 调用：
+本服务提供以下工具供 AI 调用，旨在覆盖项目维护的全生命周期。
 
 ### 文件系统操作
 
 *   **`list_directory`**
-    *   **描述**: 列出项目中的文件和目录。
-    *   **参数**: `path` (可选，默认为项目根目录 `.`)
-    *   **用途**: 探索项目结构。
+    *   描述: 列出项目中的文件和目录。
+    *   参数: `path` (可选，默认为项目根目录 `.`)
+    *   用途: 探索项目结构。
 
 *   **`read_file`**
-    *   **描述**: 读取指定文件的内容。
-    *   **参数**: `path` (必填，相对于项目根目录的文件路径)
-    *   **用途**: 读取代码、配置文件等。
+    *   描述: 读取指定文件的内容（支持自动解密 DS 格式的加密 JS 源文件）。
+    *   参数: `path` (必填)
+    *   用途: 读取代码、配置文件等。
 
 *   **`write_file`**
-    *   **描述**: 写入内容到文件（如果目录不存在会自动创建）。
-    *   **参数**:
-        *   `path` (必填)
-        *   `content` (必填)
-    *   **用途**: 修改代码、新建文件。
+    *   描述: 写入内容到文件（自动创建目录）。
+    *   参数: `path` (必填), `content` (必填)
+    *   用途: 修改代码、新建文件。
 
 *   **`delete_file`**
-    *   **描述**: 删除指定的文件或目录。
-    *   **参数**: `path` (必填)
-    *   **用途**: 清理废弃文件。
+    *   描述: 删除指定的文件或目录。
+    *   参数: `path` (必填)
+    *   用途: 清理废弃文件。
 
-### 爬虫源管理
+### 爬虫开发与调试 (New)
 
-*   **`list_sources`**
-    *   **描述**: 专门列出 `spider/js/` 和 `spider/catvod/` 目录下的所有爬虫源文件。
-    *   **参数**: 无
-    *   **用途**: 快速获取当前项目中的所有爬虫源列表，无需遍历整个目录。
-
-*   **`check_syntax`**
-    *   **描述**: 检查指定 JavaScript 文件的语法是否正确（使用 `node --check`）。
-    *   **参数**: `path` (必填)
-    *   **用途**: 在修改或创建 JS 文件后，验证是否存在语法错误。
+这些工具专门为编写和调试 drpy 爬虫源（JS）设计，赋予 AI 强大的代码理解和验证能力。
 
-### 高级开发工具 (New)
+*   **`list_sources`**
+    *   描述: 列出 `spider/js/` 和 `spider/catvod/` 下的所有源文件。
+    *   用途: 快速概览现有爬虫源。
 
 *   **`fetch_spider_url`**
-    *   **描述**: 使用 `drpy-node` 的请求库抓取 URL 内容，支持自定义 Header 和 Method。
-    *   **参数**:
-        *   `url` (必填): 目标 URL。
-        *   `options` (可选): 请求配置对象。
-            *   `method`: HTTP 方法 (GET, POST)。
-            *   `headers`: 请求头 (User-Agent, Cookie, Referer 等)。
-            *   `data`: 请求体数据 (POST 数据)。
-    *   **用途**: AI 在编写源之前，先调用此工具确认网站的可访问性，测试反爬策略（如是否需要特定 UA 或 Cookie），并获取原始内容以供分析。
+    *   描述: 使用 drpy-node 的请求库 (`req`) 抓取 URL。
+    *   参数: `url` (必填), `options` (可选: method, headers, data)
+    *   用途: 调试目标网站的连通性、反爬策略（如 Headers 校验）。
 
 *   **`debug_spider_rule`**
-    *   **描述**: 调试 drpy 爬虫规则，支持解析 HTML 内容或在线抓取 URL。
-    *   **参数**: 
-        *   `html` (可选): 需要解析的 HTML 文本内容。
-        *   `url` (可选): 需要抓取的网页 URL（若未提供 `html`，则会自动请求此 URL）。
-        *   `rule` (必填): drpy 解析规则 (如 `.list li`, `a&&href`, `body&&Text`)。
-        *   `mode` (必填): 解析模式，可选 `pdfa` (列表), `pdfh` (HTML), `pd` (URL)。
-        *   `baseUrl` (可选): 用于拼接相对链接的基础 URL。
-        *   `options` (可选): 请求配置 (method, headers, data)。
-    *   **用途**: AI 在编写或修复源时，可直接使用此工具验证选择器是否正确，无需运行完整爬虫。
-
-*   **`get_spider_template`**
-    *   **描述**: 获取标准的 `drpy` JS 爬虫源模板代码。
-    *   **参数**: 无
-    *   **特性**: 
-        *   **默认使用基础写法**: `一级`, `二级`, `搜索`, `推荐` 均采用字符串/对象规则，简单易懂。
-        *   **保留高级选项**: 包含注释掉的 `async function` 模板，供复杂场景（如动态加载、加密参数）使用。
-    *   **用途**: AI 创建新源时，优先使用基础模板；仅在基础规则无法满足需求时，才启用高级异步函数。
-
-*   **`get_drpy_libs_info`**
-    *   **描述**: 获取 `drpy-node` 运行环境中可用的全局变量、辅助函数及开发规范。
-    *   **参数**: 无
-    *   **包含信息**:
-        *   全局函数: `request`, `pdfa`, `pdfh`, `ungzip`, `$.require` 等
-        *   开发规范: 明确指出优先使用字符串/对象规则，避免滥用异步函数。
-        *   上下文变量 (`this`): `input`, `MY_PAGE`, `MY_CATE` 等
-        *   第三方库: `Cheerio`, `CryptoJS`, `Underscore`
-    *   **用途**: 帮助 AI 了解当前的沙箱环境支持哪些能力，以便正确使用 `this` 上下文和内置库。
+    *   描述: 使用 drpy 的解析规则（pdfa/pdfh/pd）解析 HTML 或 URL 内容。
+    *   参数: `rule` (规则), `mode` (模式), `html` 或 `url`
+    *   用途: 验证选择器（CSS Selector/Regex）是否正确，无需运行完整爬虫。
 
 *   **`validate_spider`**
-    *   **描述**: 对爬虫源文件进行深度校验，包括 JS 语法检查和 `drpy` 规则结构检查。
-    *   **参数**: `path` (必填)
-    *   **检查项**:
-        *   JS 语法正确性 (`node --check`)
-        *   `rule` 对象及必要字段 (`title`, `url`) 存在性
-        *   高级特性检测: 异步解析函数、代理规则 (`proxy_rule`)、本地导入 (`$.require`)
-        *   逻辑一致性: `filterable` 与 `filter_def` 的对应关系
-    *   **用途**: 在编写完源文件后，进行最终的质量把关，确保源码符合 drpy-node 的运行规范。
-
-### 系统维护
-
-*   **`get_routes_info`**
-    *   **描述**: 分析 `controllers/index.js`，返回当前系统注册的所有 Fastify 路由控制器信息。
-    *   **参数**: 无
-    *   **用途**: 帮助 AI 理解当前的 API 和页面路由结构。
-
-*   **`restart_service`**
-    *   **描述**: 尝试通过 PM2 重启 `drpys` 服务。
-    *   **参数**: 无
-    *   **注意**: 仅在服务器环境安装了 PM2 且服务名为 `drpys` 时有效。
-
-## AI 交互示例 (Best Practice)
-
-配置完成后，您可以直接用自然语言向 AI 提出需求，AI 会自动选择合适的工具。以下是几个典型场景：
-
-### 场景 1：修改现有爬虫源
-
-**用户指令**:
-> "请帮我检查一下 '360影视[官].js' 这个源，把它的 api 地址更新为 'https://new-api.360.com'，修改完记得检查一下语法。"
+    *   描述: 验证爬虫源文件的语法和基本结构。
+    *   参数: `path` (必填)
+    *   用途: 确保编写的代码没有语法错误且包含必要的 `rule` 定义。
 
-**AI 执行流程**:
-1.  调用 `list_sources` 确认文件名。
-2.  调用 `read_file` 读取 `spider/js/360影视[官].js` 的内容。
-3.  在内存中修改代码。
-4.  调用 `write_file` 将新代码写回。
-5.  调用 `check_syntax` 确保没有引入语法错误。
+*   **`get_spider_template`**
+    *   描述: 获取标准的 drpy JS 爬虫模板。
+    *   用途: AI 生成新爬虫时的起手式。
 
-### 场景 2：排查服务启动问题
+*   **`get_drpy_libs_info`**
+    *   描述: 获取 drpy 环境中可用的全局函数和库信息（如 `pdfa`, `req`, `CryptoJS` 等）。
+    *   用途: 帮助 AI 了解可用的 API 和工具函数。
 
-**用户指令**:
-> "我最近加了几个新路由，但是服务启动好像有问题，帮我看看现在注册了哪些控制器，然后重启一下服务。"
+*   **`check_syntax`**
+    *   描述: 通用的 JS 语法检查工具。
+    *   参数: `path` (必填)
+    *   用途: 快速检查任何 JS 文件的语法正确性。
 
-**AI 执行流程**:
-1.  调用 `get_routes_info` 获取当前 `controllers/index.js` 中的注册信息。
-2.  向用户汇报发现的路由。
-3.  调用 `restart_service` 重启 PM2 服务。
+### 系统维护与监控 (New)
 
-### 场景 3：创建新源
+用于项目运行时的状态监控和配置管理。
 
-**用户指令**:
-> "在 js 目录下帮我新建一个名为 'test_spider.js' 的源，写入一个基础的 drpy 模板。"
+*   **`read_logs`**
+    *   描述: 读取最新的应用程序日志（支持日志轮转）。
+    *   参数: `lines` (读取行数，默认 50)
+    *   用途: 排查运行时错误、分析系统行为。
 
-**AI 执行流程**:
-1.  调用 `write_file` 创建 `spider/js/test_spider.js` 并写入模板代码。
-2.  调用 `list_sources` 确认文件已创建。
+*   **`sql_query`**
+    *   描述: 对 `database.db` 执行只读 SQL 查询 (SELECT)。
+    *   参数: `query` (SQL 语句)
+    *   用途: 检查数据库状态、用户数据或缓存记录。
 
-### 场景 4：智能创建与校验爬虫源 (New)
+*   **`manage_config`**
+    *   描述: 读取或更新项目配置 (`config/env.json`)。
+    *   参数: `action` (get/set), `key` (支持点号嵌套), `value`
+    *   用途: 动态调整系统参数（如端口、超时设置等）。
 
-**用户指令**:
-> "我要写一个新网站的源，网站叫 '酷酷影视'，首页是 'https://kuku.com'。需要支持二级页面的异步解析，并且有防盗链处理。请用 drpy 模板帮我写好结构，如果不确定环境里有哪些库，先查一下。"
+*   **`get_routes_info`**
+    *   描述: 获取已注册的 Fastify 路由和控制器信息。
+    *   用途: 了解系统当前的 API 暴露情况。
 
-**AI 执行流程**:
-1.  调用 `get_spider_template` 获取标准模板。
-2.  调用 `get_drpy_libs_info` 确认 `pdfh` 等函数是否可用。
-3.  基于模板和用户提供的网址，生成代码并调用 `write_file` 写入 `spider/js/酷酷影视.js`。
-4.  最后调用 `validate_spider` 对新文件进行语法和结构双重检查，确保可以直接运行。
+*   **`restart_service`**
+    *   描述: 重启 drpy-node 服务 (PM2)。
+    *   用途: 应用配置更改或代码更新后重启服务。
 
-## 配置说明
+## AI 交互示例 (Best Practice)
 
-*   **安全限制**: 所有文件操作都被限制在 `drpy-node` 项目根目录下，无法访问项目外部的文件。
-*   **依赖**: 本服务依赖于 `@modelcontextprotocol/sdk`, `fs-extra`, `zod` 等库。
+**场景 1：修复爬虫源**
+> User: "XX 网站的爬虫好像失效了，列表页解析不到数据。"
+> AI Action:
+> 1. 调用 `fetch_spider_url` 获取目标网页源码，确认网站是否能访问或有反爬。
+> 2. 读取原爬虫代码 (`read_file`)。
+> 3. 调用 `debug_spider_rule` 测试原有规则是否还能匹配到内容。
+> 4. 如果规则失效，调整规则并再次测试。
+> 5. 确认修复后，使用 `write_file` 更新代码。
+
+**场景 2：系统故障排查**
+> User: "服务好像报错了，看一下日志。"
+> AI Action:
+> 1. 调用 `read_logs` 获取最近的错误堆栈。
+> 2. 根据错误信息定位相关代码文件。
+> 3. 分析并提出修复建议。
+
+**场景 3：配置修改**
+> User: "把服务端口改成 3000。"
+> AI Action:
+> 1. 调用 `manage_config` 读取当前配置，确认键名（如 `port` 或 `server.port`）。
+> 2. 调用 `manage_config` (action=set) 更新配置。
+> 3. 调用 `restart_service` 使配置生效。