# URL Fetcher MCP Server

一个基于 FastMCP 的网页内容获取服务器，允许 AI 通过 MCP 协议获取指定网址的网页内容。

## 🚀 功能特性

- 🌐 **网页内容获取**: 支持获取任何 HTTP/HTTPS 网页的完整内容
- 📝 **智能内容提取**: 自动提取网页正文，过滤广告和导航元素
- 📊 **元数据提取**: 自动提取页面标题、描述、关键词等元信息
- ✂️ **内容摘要**: 支持生成指定长度的内容摘要
- 🔍 **URL 验证**: 提供 URL 格式验证功能
- 🛡️ **错误处理**: 完善的错误处理和超时机制
- 📡 **异步处理**: 基于 asyncio 的高性能异步处理

## 📦 安装

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

或手动安装：
```bash
pip install fastmcp>=2.0.0 aiohttp>=3.8.0 beautifulsoup4>=4.11.0
```

### 2. 启动服务器

```bash
python url_fetcher_server.py
```

服务器将在 STDIO 模式下启动，等待 MCP 客户端连接。

## ⚙️ 配置 Cline

### 找到配置文件

**Windows:**
```
%APPDATA%\Cline\mcp_servers.json
```
通常位于：`C:\Users\你的用户名\AppData\Roaming\Cline\mcp_servers.json`

**macOS:**
```
~/Library/Application Support/Cline/mcp_servers.json
```

**Linux:**
```
~/.config/Cline/mcp_servers.json
```

### 添加服务器配置

```json
{
  "mcpServers": {
    "url-fetcher": {
      "command": "python",
      "args": ["path/to/your/url_fetcher_server.py"],
      "env": {},
      "autoApprove": [
        "fetch_web_content",
        "fetch_web_content_summary",
        "fetch_multiple_web_content",
        "fetch_multiple_web_content_summary",
        "validate_url"
      ]
    }
  }
}
```

**重要提示:** 请将路径修改为您实际的项目路径。

### 重启 Cline

保存配置后，重启 VSCode 或重新加载 Cline 窗口使配置生效。

## 🛠️ 可用工具

### 1. fetch_web_content

获取指定网址的完整网页内容。

**参数:**
- `url` (string, 必需): 要获取内容的完整网址

**使用示例:**
```
请帮我获取 https://example.com 的内容
```

### 2. fetch_web_content_summary

获取网页内容的摘要版本。

**参数:**
- `url` (string, 必需): 要获取内容的完整网址
- `max_length` (integer, 可选): 摘要的最大长度，默认 2000 字符

**使用示例:**
```
请获取 https://github.com 的内容摘要，限制在1000字符以内
```

### 3. fetch_multiple_web_content 🆕

批量获取多个网址的完整内容，支持并发处理。

**参数:**
- `urls` (list, 必需): 要获取内容的网址列表
- `max_concurrent` (integer, 可选): 最大并发请求数，默认5

**使用示例:**
```
请批量获取这些网址的内容：
- https://example.com
- https://github.com
- https://news.ycombinator.com
```

### 4. fetch_multiple_web_content_summary 🆕

批量获取多个网址的内容摘要，支持并发处理。

**参数:**
- `urls` (list, 必需): 要获取内容的网址列表
- `max_length` (integer, 可选): 每个网址摘要的最大长度，默认2000字符
- `max_concurrent` (integer, 可选): 最大并发请求数，默认5

**使用示例:**
```
请批量获取这些网址的内容摘要，每个限制1500字符：
- https://example.com
- https://github.com
- https://news.ycombinator.com
```

### 5. validate_url

验证 URL 格式并返回基本信息。

**参数:**
- `url` (string, 必需): 要验证的网址

**使用示例:**
```
请验证这个网址是否有效：https://example.com/test
```

## 🚀 批量处理优势

### 单个 vs 批量对比

**单个处理（AI多次调用）:**
- AI 需要分别调用多次工具
- 每次调用都有独立的请求/响应周期
- 总耗时 = 所有网址处理时间之和
- 适合少量网址或需要分别处理的场景

**批量处理（一次调用）:**
- 一次调用处理多个网址
- 并发处理，显著提升效率
- 总耗时 ≈ 最慢网址的处理时间
- 适合大量网址或需要汇总的场景

### 性能特点

- ✅ **并发处理**: 默认5个并发，可调整
- ✅ **错误隔离**: 单个网址失败不影响其他
- ✅ **统计信息**: 提供成功/失败统计
- ✅ **限制保护**: 单次最多20个网址，防止滥用
- ✅ **超时控制**: 每个网址30秒超时

## 🔧 技术实现

### 核心技术栈

- **FastMCP**: MCP 服务器框架
- **aiohttp**: 异步 HTTP 客户端
- **BeautifulSoup4**: HTML 解析和内容提取
- **asyncio**: 异步编程支持

### 内容提取策略

1. **智能内容识别**: 优先查找 `<main>`, `<article>`, `.content` 等常见内容区域
2. **噪音过滤**: 自动移除脚本、样式、导航、页脚等非内容元素
3. **文本清理**: 移除多余空白字符，保留可读的文本格式
4. **元数据提取**: 自动提取页面的 SEO 相关元信息

## 📋 使用场景

1. **AI 助手**: 让 AI 能够访问和分析网页内容
2. **内容聚合**: 批量获取多个网页的内容
3. **网页摘要**: 为长网页生成简洁的摘要
4. **内容分析**: 分析网页结构和元数据
5. **监控工具**: 监控网页内容变化

## ⚠️ 注意事项

1. **遵守 robots.txt**: 请确保遵守目标网站的 robots.txt 规则
2. **请求频率**: 避免过于频繁的请求，以免对目标服务器造成压力
3. **内容版权**: 尊重网页内容的版权，仅用于合法用途
4. **网络环境**: 确保网络连接稳定，某些网站可能需要特殊访问权限

## 🐛 故障排除

### 常见问题

1. **连接超时**: 检查网络连接和目标网站可访问性
2. **403 错误**: 某些网站可能阻止自动化访问
3. **内容为空**: 目标网页可能使用了 JavaScript 动态加载
4. **编码问题**: 某些网页可能使用特殊编码

### 调试建议

1. 先使用 `validate_url` 工具验证 URL 格式
2. 检查返回的错误信息了解具体问题
3. 尝试访问其他网站测试连接
4. 确保依赖包正确安装：`pip list | grep -E "(fastmcp|aiohttp|beautifulsoup4)"`

### 配置问题

如果 MCP 服务器无法连接：

1. **检查 Python 路径**: 确保配置中的 Python 路径正确
2. **检查脚本路径**: 确保 `url_fetcher_server.py` 路径正确
3. **重启 VSCode**: 完全关闭并重新打开 VSCode
4. **重新加载 Cline**: 使用 `Ctrl+Shift+P` 执行 "Developer: Reload Window"

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目！