web-fetcher-mcp 1.0.10 → 1.0.14

package/README.md

@@ -2,7 +2,7 @@
 
 一个通用的 MCP 工具，可以获取任意网页的内容（包括文字和图片），支持需要登录的页面。
 
-## MCP 配置
+## 安装
 
 ### 方式一：全局安装（推荐）
 
@@ -37,28 +37,11 @@ npm install -g web-fetcher-mcp
 
 ### 各编辑器配置位置
 
-#### Claude Desktop
-文件：`%APPDATA%\Claude\claude_desktop_config.json` (Windows)  
-或 `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac)
-
-#### Cursor
-设置 → MCP → 添加服务器
-
-#### VSCode + Cline/Roo Code
-在插件设置中找到 MCP 配置
-
-#### 完整配置示例
-
-```json
-{
-  "mcpServers": {
-    "web-fetcher": {
-      "command": "npx",
-      "args": ["-y", "web-fetcher-mcp"]
-    }
-  }
-}
-```
+| 编辑器 | 配置位置 |
+|--------|----------|
+| Claude Desktop | `%APPDATA%\Claude\claude_desktop_config.json` (Windows) / `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) |
+| Cursor | 设置 → MCP → 添加服务器 |
+| VSCode + Cline/Roo Code | 插件设置中找到 MCP 配置 |
 
 ---
 
@@ -69,14 +52,25 @@ npm install -g web-fetcher-mcp
 - 支持需要登录的页面
 - 自动保存和复用登录状态（Cookie）
 - 可自定义内容选择器，精准提取页面特定区域
+- 页面滚动和导航控制
+- 鼠标悬停、表单填写、下拉选择等交互操作
+- 文件上传支持
+- 元素属性获取和等待
+
+## 系统要求
 
-## 使用方法
+- Node.js 18+
+- Google Chrome 浏览器
+
+---
 
-### 工具 1: fetch-web-page
+## 工具列表
+
+### 1. fetch-web-page
 
 获取网页内容（文字和图片）
 
-### 参数说明
+#### 参数说明
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
@@ -85,17 +79,21 @@ npm install -g web-fetcher-mcp
 | downloadImages | boolean | 否 | true | 是否下载图片 |
 | loginMode | string | 否 | 'skip' | 登录模式：skip/auto/manual |
 | waitForLogin | boolean | 否 | false | 检测到需要登录时是否等待用户手动登录 |
-| includeHtmlSkeleton | boolean | 否 | false | 是否返回 HTML 骨架结构（默认 false，节省 token） |
+| includeHtmlSkeleton | boolean | 否 | false | 是否返回 HTML 骨架结构 |
+
+#### 登录模式说明
 
-### 登录模式说明
+| 模式 | 说明 |
+|------|------|
+| skip (默认) | 不检测登录状态，直接获取页面内容 |
+| auto | 使用保存的 Cookie 自动登录 |
+| manual | 打开浏览器等待用户手动完成登录 |
 
-- **skip** (默认): 不检测登录状态，直接获取页面内容
-- **auto**: 使用保存的 Cookie 自动登录
-- **manual**: 打开浏览器等待用户手动完成登录
+#### 示例
 
-### 示例调用
+<details>
+<summary>普通网页抓取</summary>
 
-#### 普通网页抓取
 ```json
 {
   "name": "fetch-web-page",
@@ -104,8 +102,11 @@ npm install -g web-fetcher-mcp
   }
 }
 ```
+</details>
+
+<details>
+<summary>抓取特定区域内容</summary>
 
-#### 抓取特定区域内容
 ```json
 {
   "name": "fetch-web-page",
@@ -115,8 +116,11 @@ npm install -g web-fetcher-mcp
   }
 }
 ```
+</details>
+
+<details>
+<summary>需要登录的页面（首次）</summary>
 
-#### 需要登录的页面（首次）
 ```json
 {
   "name": "fetch-web-page",
@@ -127,8 +131,11 @@ npm install -g web-fetcher-mcp
   }
 }
 ```
+</details>
+
+<details>
+<summary>需要登录的页面（后续）</summary>
 
-#### 需要登录的页面（后续）
 ```json
 {
   "name": "fetch-web-page",
@@ -138,10 +145,11 @@ npm install -g web-fetcher-mcp
   }
 }
 ```
+</details>
 
 ---
 
-### 工具 2: focus-input-element
+### 2. focus-input-element
 
 获取页面输入框焦点，支持通过 CSS 选择器定位元素。
 
@@ -150,97 +158,303 @@ npm install -g web-fetcher-mcp
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
 | url | string | 否 | 'current' | 网页 URL，使用 'current' 则操作当前已打开的页面 |
-| selector | string | 是 | - | CSS 选择器，支持类名、ID、属性选择器等 |
+| selector | string | 是 | - | CSS 选择器 |
 | useExistingPage | boolean | 否 | true | 是否使用已存在的页面 |
 
-#### 示例调用
+#### 示例
 
-##### 通过 ID 获取焦点
 ```json
-{
-  "name": "focus-input-element",
-  "arguments": {
-    "selector": "#username"
-  }
-}
+// 通过 ID
+{ "selector": "#username" }
+
+// 通过类名
+{ "selector": ".search-input" }
+
+// 通过属性
+{ "selector": "input[name='email']" }
 ```
 
-##### 通过类名获取焦点
+---
+
+### 3. type-input-element
+
+在指定的输入框中输入文本内容
+
+#### 参数说明
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| selector | string | 是 | - | CSS 选择器 |
+| text | string | 是 | - | 要输入的文本 |
+| clearFirst | boolean | 否 | true | 是否先清空输入框 |
+| pressEnter | boolean | 否 | false | 输入后是否按回车 |
+
+---
+
+### 4. click-element
+
+点击页面上的指定元素
+
+#### 参数说明
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| selector | string | 是 | - | CSS 选择器 |
+
+---
+
+### 5. capture-element
+
+截取网页或指定元素的截图
+
+#### 参数说明
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| selector | string | 否 | - | CSS 选择器，不传则全屏截图 |
+
+---
+
+### 6. get-page-info
+
+获取当前页面的信息（HTML骨架、文本内容等）
+
+---
+
+### 7. open-devtools
+
+打开浏览器开发者工具
+
+#### 参数说明
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| mobileMode | boolean | 否 | false | 是否开启手机设备模拟模式 |
+
+---
+
+### 8. get-console-logs
+
+获取浏览器控制台日志
+
+---
+
+### 9. scroll-page
+
+滚动页面到指定位置或元素
+
+#### 参数说明
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| url | string | 否 | 'current' | 网页 URL，使用 'current' 则操作当前已打开的页面 |
+| direction | string | 否 | 'down' | 滚动方向：up/down/left/right |
+| amount | number | 否 | 500 | 滚动的像素量 |
+| selector | string | 否 | - | CSS 选择器，提供后则滚动到该元素位置 |
+| useExistingPage | boolean | 否 | true | 是否使用已存在的页面 |
+
+#### 示例
+
 ```json
-{
-  "name": "focus-input-element",
-  "arguments": {
-    "selector": ".search-input"
-  }
-}
+// 向下滚动 500px
+{ "direction": "down", "amount": 500 }
+
+// 滚动到指定元素
+{ "selector": "#footer" }
 ```
 
-##### 通过属性选择器获取焦点
+---
+
+### 10. wait-for-element
+
+等待指定元素出现在页面上
+
+#### 参数说明
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| url | string | 否 | 'current' | 网页 URL，使用 'current' 则操作当前已打开的页面 |
+| selector | string | 是 | - | CSS 选择器 |
+| timeout | number | 否 | 30000 | 超时时间（毫秒） |
+| state | string | 否 | 'visible' | 等待状态：attached/visible/hidden |
+| useExistingPage | boolean | 否 | true | 是否使用已存在的页面 |
+
+#### 示例
+
 ```json
-{
-  "name": "focus-input-element",
-  "arguments": {
-    "selector": "input[name='email']"
-  }
-}
+// 等待元素可见
+{ "selector": ".result-item", "timeout": 10000 }
+
+// 等待元素消失（如 loading）
+{ "selector": ".loading", "state": "hidden" }
 ```
 
-##### 操作特定页面的输入框
+---
+
+### 11. hover-element
+
+鼠标悬停在指定元素上
+
+#### 参数说明
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| url | string | 否 | 'current' | 网页 URL，使用 'current' 则操作当前已打开的页面 |
+| selector | string | 是 | - | CSS 选择器 |
+| useExistingPage | boolean | 否 | true | 是否使用已存在的页面 |
+
+#### 示例
+
 ```json
-{
-  "name": "focus-input-element",
-  "arguments": {
-    "url": "https://example.com/login",
-    "selector": "#password"
-  }
-}
+{ "selector": ".dropdown-trigger" }
 ```
 
-#### 返回结果
+---
+
+### 12. get-element-attributes
 
-成功时返回元素信息：
+获取页面元素的属性值
+
+#### 参数说明
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| url | string | 否 | 'current' | 网页 URL，使用 'current' 则操作当前已打开的页面 |
+| selector | string | 是 | - | CSS 选择器 |
+| attributes | string[] | 否 | [] | 要获取的属性名列表，为空则获取所有属性 |
+| useExistingPage | boolean | 否 | true | 是否使用已存在的页面 |
+
+#### 示例
+
+```json
+// 获取所有属性
+{ "selector": "#my-link" }
+
+// 获取指定属性
+{ "selector": "#my-link", "attributes": ["href", "data-id", "class"] }
 ```
-✅ 成功获取焦点！
 
-元素信息:
-- 标签: input
-- 类型: text
-- ID: username
-- Name: user
-- Class: form-control
-- Placeholder: 请输入用户名
-- 当前值: 
+---
+
+### 13. select-option
+
+选择下拉菜单的选项，支持原生 select 和常见 UI 框架自定义下拉
+
+#### 参数说明
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| url | string | 否 | 'current' | 网页 URL，使用 'current' 则操作当前已打开的页面 |
+| selector | string | 是 | - | CSS 选择器，指向 select 元素或自定义下拉触发元素 |
+| value | string | 否 | - | 按 option 的 value 属性选择 |
+| label | string | 否 | - | 按 option 的显示文本选择 |
+| index | number | 否 | - | 按索引选择（从 0 开始） |
+| useExistingPage | boolean | 否 | true | 是否使用已存在的页面 |
+
+#### 示例
+
+```json
+// 按 value 选择
+{ "selector": "#country", "value": "cn" }
+
+// 按显示文本选择
+{ "selector": "#country", "label": "中国" }
+
+// 按索引选择
+{ "selector": "#country", "index": 0 }
 ```
 
-## 数据存储
+---
 
-- **Cookie 存储位置**: `~/.web-fetcher-mcp/cookies.json`
-- **图片存储位置**: `~/.web-fetcher-mcp/images/`
+### 14. navigate-history
 
-## 系统要求
+浏览器前进或后退导航
 
-- Node.js 18+
-- Google Chrome 浏览器
+#### 参数说明
 
-## 安装和运行
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| direction | string | 否 | 'back' | 导航方向：back(后退) / forward(前进) |
 
-```bash
-# 安装依赖
-npm install
+#### 示例
 
-# 构建
-npm run build
+```json
+// 后退
+{ "direction": "back" }
 
-# 运行
-npm start
+// 前进
+{ "direction": "forward" }
 ```
 
-## 使用已有 Chrome 实例（推荐）
+---
 
-如需使用日常浏览器的书签和登录状态，先用以下命令启动 Chrome：
+### 15. upload-file
 
-```bash
-"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
+上传文件到页面上的文件输入框
+
+#### 参数说明
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| url | string | 否 | 'current' | 网页 URL，使用 'current' 则操作当前已打开的页面 |
+| selector | string | 是 | - | CSS 选择器，指向 input[type="file"] 元素 |
+| filePath | string | 是 | - | 要上传的文件的绝对路径 |
+| useExistingPage | boolean | 否 | true | 是否使用已存在的页面 |
+
+#### 示例
+
+```json
+{
+  "selector": "input[type='file']",
+  "filePath": "C:/Users/test/document.pdf"
+}
 ```
 
-然后 MCP 工具会自动连接到该实例。
+---
+
+### 16. execute-js
+
+在页面中执行任意 JavaScript 代码并返回结果。可以用于执行复杂的 DOM 操作、获取数据、调用页面上的函数等。
+
+#### 参数说明
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| url | string | 否 | 'current' | 网页 URL，使用 'current' 则操作当前已打开的页面 |
+| script | string | 是 | - | 要执行的 JavaScript 代码 |
+| useExistingPage | boolean | 否 | true | 是否使用已存在的页面 |
+
+#### 示例
+
+```json
+// 点击元素
+{ "script": "document.getElementById('btn').click()" }
+
+// 获取元素文本
+{ "script": "document.querySelector('.title').textContent" }
+
+// 滚动到底部
+{ "script": "window.scrollTo(0, document.body.scrollHeight)" }
+
+// 获取所有链接
+{ "script": "Array.from(document.querySelectorAll('a')).map(a => ({text: a.textContent, href: a.href}))" }
+
+// 修改元素样式
+{ "script": "document.body.style.backgroundColor = 'lightblue'" }
+
+// 获取页面数据
+{ "script": "JSON.stringify({title: document.title, url: location.href, cookies: document.cookie})" }
+```
+
+---
+
+## 数据存储
+
+| 数据类型 | 存储位置 |
+|----------|----------|
+| Cookie | `~/.web-fetcher-mcp/cookies.json` |
+| 图片 | `~/.web-fetcher-mcp/images/` |
+
+## License
+
+MIT