README.md•6.46 kB
# 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 来改进这个项目！