内容
# 网络浏览器
适用于任何MCP客户端的外部网络工具。搜索网络，爬取网页，驱动反检测Firefox浏览器绕过机器人墙，并从维基百科、维基数据、GitHub和YouTube拉取结构化数据。
需要明确两点：
- **仅限免费API。** 没有付费服务，没有计量配额。它使用DuckDuckGo、维基百科、维基数据、公共GitHub API和YouTube自己的字幕端点。任何工具读取的唯一凭证是GitHub令牌，它是免费的，只有`github`使用（用于代码搜索和问题操作；普通文件和仓库读取无需令牌）。参见下面的凭证。
- **从您的IP地址运行。** 每个请求都从运行服务器的机器直接发送到源。没有代理，没有中继，没有第三方爬虫服务在中间转售您的流量。
## 工具
| 工具 | 功能 |
|------|--------------|
| `web` | DuckDuckGo搜索和直接网页爬取，提取可读文本。新闻搜索。 |
| `fx` | 反检测Firefox（Camoufox），适用于受机器人保护的网站（Cloudflare、Datadome、验证墙）。持久化配置文件在重启后保留cookie和已解决的挑战。可选安装，参见下文。 |
| `wiki` | 维基百科搜索和完整文章获取。 |
| `wikidata_query` | 维基数据SPARQL查询，获取结构化实体数据（人物、地点、组织、关系）。 |
| `github` | 获取文件，分析仓库结构，搜索代码，通过公共GitHub API读取或管理问题。代码搜索和问题操作需要免费的`GITHUB_TOKEN`；文件和仓库读取无需。 |
| `youtube` | 任何视频的字幕和元数据。首先使用youtube-transcript-api，备用方案为yt-dlp。任意URL形状或裸视频ID。 |
每个工具都接受一个`action`参数，除了`wikidata_query`，它接受SPARQL `query`。从您的客户端调用`list_tools`以获取每个操作和参数的确切模式。每个操作的作用：
### `web`
- `search` - 网络结果显示为标题、网址和摘要。`news=true`切换到DuckDuckGo新闻端点（为每个结果添加日期和来源）；`timelimit`过滤到`d`、`w`或`m`。
- `crawl` - 获取一个网址并提取可读的文章文本（trafilatura，带有BeautifulSoup备用方案），包括PDF。`summary=true`（默认）返回简短版本，`summary=false`返回全文。
结果缓存20分钟。如果页面受到机器人保护，`crawl`会指向`fx`。
### `fx`（可选安装）
适用于阻止直接获取的网站的真实Camoufox（强化Firefox）会话。
- `read` - 导航，等待JavaScript挑战，提取干净的文本，自动关闭。常见的一次性情况。
- 分步自动化：`navigate`、`click`、`fill`、`type`、`press`、`scroll`、`wait`、`extract`（原始HTML）、`text`（正文文本）、`evaluate`（运行JavaScript）、`screenshot`（元素或`full_page`）、`cookies` / `add_cookies`和`close`。
- `status` - 报告当前会话。
选项包括`visible`（显示窗口）、`stealth`（人性化光标）和`load_images`。配置文件持久化到磁盘；参见安全注意事项下的说明。
### `wiki`
- `search` - 匹配查询的文章标题。
- `page` - 标题的完整文章文本。
缓存一小时。
### `wikidata_query`
对维基数据运行只读SPARQL查询，获取结构化实体数据。限制：查询长度5000字符，超时15秒，结果1000条。更新操作（INSERT、DELETE、DROP等）被拒绝。
### `github`
- `fetch` - 原始文件内容。`analyze` - 仓库元数据、语言、文件数量。
- `search` - 代码搜索（需要令牌）。
- 问题：`get_issue`、`list_issues`、`create_issue`、`comment_issue`、`update_issue`。写入操作需要令牌。参见凭证。
缓存10分钟。
### `youtube`
- `transcript` - 仅字幕。`metadata` - 标题、频道、时长、描述、章节。`info` - 同时获取两者（常见情况）。
- `list_languages` - 可用的字幕轨道。`search` - 在字幕中查找短语，返回带有`t=`深链接的带时间戳的匹配项。
字幕`format`可以是`text`（默认）、`timestamped`、`srt`、`vtt`或`json`。长字幕自动分页，带有`segment_offset`和`max_segments`。
### 保存上下文：`harvest=True`
`web`、`fx`、`github`和`youtube`接受`harvest=True`。与其将大页面或字幕返回到您的上下文窗口，不如将内容写入`harvested/<harvest_dest>/`，并返回文件路径和简短摘要。如果需要，请将`HARVEST_ROOT`指向其他目录。
## 安装
Python 3.10或更新版本。
作为包安装，以在您的PATH上获取`web-explorer`命令：
```bash
pipx install git+https://github.com/cutlerbenjamin1-cmd/web-explorer
```
从本地检出：`pip install .` 或直接安装依赖并运行`server.py`：
```bash
pip install -r requirements.txt
```
这涵盖了服务器和五个免费API工具（`web`、`wiki`、`wikidata_query`、`github`、`youtube`）。
### 可选：`fx`浏览器
反检测浏览器是一个较重的依赖，因此它是可选的。服务器和其他工具在没有它的情况下也能正常工作；`fx`只会返回一条明确的“未安装”消息，直到您添加它。
```bash
pip install -r requirements-fx.txt # 或：pip install "web-explorer[fx]"
python -m camoufox fetch
```
`python -m camoufox fetch`是一次性下载补丁的Firefox构建（约150 MB）。camoufox还引入了playwright和browserforge。
## 与MCP客户端一起使用
通过stdio与MCP通信。如果您安装了包，请将客户端指向`web-explorer`命令：
```json
{
"mcpServers": {
"web-explorer": {
"command": "web-explorer"
}
}
}
```
否则，将`python`指向`server.py`，使用绝对路径：
```json
{
"mcpServers": {
"web-explorer": {
"command": "python",
"args": ["/absolute/path/to/web-explorer/server.py"]
}
}
}
```
## 通过HTTP运行（可选）
要通过MCP可流式HTTP提供此服务而不是stdio，请使用[mcp-http-bridge](https://github.com/cutlerbenjamin1-cmd/mcp-http-bridge)：从此目录运行它，并将您的客户端指向桥。如果您将其公开给localhost以外的访问，请保持工具过滤严格，因为`fx`可以驱动真实的浏览器。
## 安全
- **不受信任的内容横幅。** 这些工具返回的所有内容都是来自您机器外部的数据。每个响应都被标记为外部和不受信任的，因此代理不会将页面内容视为指令。
- **SSRF保护。** `web(crawl)`拒绝私有和环回地址范围，因此爬取的URL不能指向您的内部网络。
- **礼貌的速率限制。** 每个工具的冷却时间间隔开请求，以免您从自己的IP地址轰炸主机并触发429错误。
- **`fx`配置文件是真实的浏览器状态。** `fx`在`data/fx_profile/`中保留一个持久的Firefox配置文件。您在其中执行的操作都会保留： 如果您通过`fx`登录到某个网站，该会话及其cookie将被写入磁盘，就像正常的浏览器配置文件一样。 这就是让登录和已解决的Cloudflare挑战在重启后存活下来的原因。 文件夹被gitignore，因此不会被提交，但请像对待密码存储一样对待它：请勿共享或复制它，并删除`data/fx_profile/`以清除所有已保存的会话。
## 凭证
只有`github`工具读取凭证，它是一个普通的免费GitHub个人访问令牌。
- 无令牌：`github`文件获取和仓库分析有效，受GitHub的匿名速率限制（约每小时60次请求）。
- 有令牌：该限制上升到每小时5000次，`github`代码搜索和问题操作（创建、评论、更新）变得可用。否则返回明确的“需要令牌”错误。
在启动服务器之前，在环境中设置它：
```bash
set GITHUB_TOKEN=ghp_your_token_here # Windows
export GITHUB_TOKEN=ghp_your_token_here # macOS / Linux
```
其他工具不需要帐户或密钥。DuckDuckGo、维基百科、维基数据和YouTube都未经身份验证使用。
## 环境变量
以下每个变量都是可选的。
| 变量 | 影响 |
|----------|--------|
| `GITHUB_TOKEN` | GitHub身份验证。参见上面的凭证。 |
| `HARVEST_ROOT` | `harvest=True`输出的目录。默认：`./harvested`。 |
| `YOUTUBE_COOKIES_BROWSER` | 浏览器名称（例如`firefox`），以便yt-dlp可以在视频被IP阻止时借用其cookie。 |
| `YOUTUBE_COOKIES_PROFILE` | 上述cookie的浏览器配置文件路径。 |
| `YOUTUBE_BIND_IP` | 绑定传出YouTube请求的本地源IP地址。 |
| `MCP_DEBUG` | 设置为`true`以进行stderr调试日志记录。 |
| `OUTPUT_MAX_CHARS` | 单个工具响应的硬上限。默认：15000。 |
| `GITHUB_MAX_RESPONSE_BYTES` | 获取的GitHub文件大小上限。默认：约2MB。 |
| `WEB_CRAWL_MAX_BYTES` | `web(crawl)`的HTML或文本大小上限。默认：约2MB。 |
| `WEB_CRAWL_MAX_PDF_BYTES` | `web(crawl)`的PDF大小上限。默认：约50MB。 |
## 许可证
MIT。参见LICENSE。
