Enhanced Fetch MCP

# Enhanced Fetch MCP [English](./README.md) | 简体中文 **一个为 AI 而生的 Web 交互层，它将 Playwright 从一个开发者工具“升维”成为一个为 AI Agent 服务的、智能、安全且高效的解决方案。** | 功能 | Claude 原生 Fetch | 标准 Playwright | Enhanced Fetch MCP | | :--- | :--- | :--- | :--- | | **内容提取** | 基础 | 手动解析 | **高级**: 提取主要内容、元数据、链接和图片，并生成干净的 Markdown。 | | **JavaScript 渲染** | ❌ 不支持 | ✅ 支持 | **✅ 支持**: 为动态页面提供完整的浏览器渲染。 | | **安全性** | ✅ 安全 | ⚠️ 浏览器沙箱 | **🔒 最高安全**: 所有操作都在 Docker 容器中隔离执行。 | | **资源效率** | 高 | 低 | **混合引擎**: 智能地在轻量级 HTTP 和完整浏览器之间切换。 | | **截图 & PDF** | ❌ 不支持 | ✅ 支持 | **✅ 支持**: 捕获截图并生成 PDF。 | | **控制与定制** | 有限 | 高 | **完全控制**: 可定制的请求头、超时等。 | --- ## 快速上手 ### 选项 1: 本地安装 **1. 安装:** ```bash npm install -g enhanced-fetch-mcp ``` **2. 配置 Claude Code (`~/.config/claude/config.json`):** ```json { "mcpServers": { "enhanced-fetch": { "command": "enhanced-fetch-mcp" } } } ``` **3. 使用:** > “帮我获取 `https://example.com` 的主要内容并截图。” ### 选项 2: 通过 Smithery 安装 你也可以使用 Smithery 来简化安装和配置流程。 **通过 Smithery 安装:** [https://smithery.ai/server/@Danielmelody/enhanced-fetch-mcp](https://smithery.ai/server/@Danielmelody/enhanced-fetch-mcp) Smithery 会自动处理安装、依赖管理和 MCP 配置。**重要提示：** 服务器完全运行在你的本地机器上，不会将任何数据发送到外部服务器。你可以完全控制浏览活动、截图和提取的内容，确保最高级别的隐私和安全性。 --- ## 工具 #### 网页抓取工具（3个） | 工具 | 描述 | |------|------| | `fetch_url` | 直接向 URL 发送 HTTP 请求以获取其原始 HTML 内容。支持多种方法（GET、POST 等）、自定义请求头和其他高级选项。 | | `extract_content` | 解析原始 HTML 以提取结构化信息。它能识别并清理主要文章内容，并以多种格式（文本、Markdown 和 HTML）返回，同时附带元数据、链接和图片。 | | `fetch_and_extract` | 一个方便的一体化工具，它首先获取 URL，然后自动提取其内容。它能智能判断是使用简单的 HTTP 请求还是完整的浏览器环境。 | #### 浏览器自动化工具（8个） | 工具 | 描述 | |------|------| | `create_browser_context` | 初始化并启动一个新的、隔离的浏览器实例（如 Chrome、Firefox 或 WebKit），带有一个干净的会话，并返回一个用于后续操作的唯一 ID。 | | `browser_navigate` | 指示特定的浏览器实例访问一个 URL，并等待页面加载完成，包括执行任何初始的 JavaScript。 | | `browser_get_content` | 在浏览器渲染页面后，获取完整的 HTML，确保所有动态内容都已生成。 | | `browser_screenshot` | 捕获浏览器中当前页面的视觉快照，可以是整个页面或特定区域，并返回图像数据。 | | `browser_pdf` | 从当前页面的内容生成一个 PDF 文档，提供一个可打印的、离线的网页版本。 | | `browser_execute_js` | 在当前页面的上下文中运行自定义的 JavaScript 代码片段，从而能够与页面元素交互或检索数据。 | | `list_browser_contexts` | 返回所有当前已创建的活动浏览器实例的列表，包括它们的 ID 和状态。 | | `close_browser_context` | 终止一个浏览器实例并清理所有相关资源，包括关闭其所有页面和释放内存。 | #### Docker 沙箱工具（8个） | 工具 | 描述 | |------|------| | `create_sandbox` | 使用指定的镜像创建一个新的、安全的 Docker 容器，为命令执行提供一个隔离的环境。 | | `execute_in_sandbox` | 在指定的 Docker 沙箱内运行一个 shell 命令，并返回其标准输出、错误和退出码。 | | `list_sandboxes` | 提供所有当前运行的 Docker 沙箱的列表，包括它们的 ID、名称和当前状态。 | | `get_sandbox` | 检索有关特定沙箱的详细信息，例如其配置、运行状态和网络设置。 | | `pause_sandbox` | 暂时冻结一个正在运行的沙箱，在消耗最少 CPU 资源的同时保留其状态。 | | `resume_sandbox` | 取消暂停先前暂停的沙箱，使其从中断处继续执行。 | | `cleanup_sandbox` | 停止并完全移除一个沙箱容器，删除其文件系统并释放所有相关的系统资源。 | | `get_sandbox_stats` | 获取沙箱的实时资源使用指标，包括 CPU、内存和网络 I/O。 | ### 使用示例 #### 简单网页抓取 ``` 用户：获取 https://example.com 的内容 Claude 自动调用 fetch_and_extract： → 获取 HTML → 提取标题、描述、正文 → 转换为 Markdown → 返回结构化内容 ``` #### JavaScript 渲染页面 ``` 用户：这个页面需要浏览器渲染 Claude 自动使用浏览器工具： → 创建浏览器上下文 → 导航到页面 → 等待 JavaScript 执行完成 → 获取完整渲染的内容 ``` #### 网页截图 ``` 用户：给这个页面截个图 Claude 自动调用浏览器截图： → 打开页面 → 等待加载完成 → 截取全页面截图 → 返回 PNG 图片 ``` ### 系统要求 #### 必需 - Node.js >= 18.0.0 - npm >= 8.0.0 #### 可选（用于特定功能） - Docker（用于沙箱功能） - 足够的磁盘空间（Playwright 浏览器约 300MB） ### 验证安装 ```bash # 检查命令是否可用 enhanced-fetch-mcp --version # 输出: v1.0.0 # 查看帮助 enhanced-fetch-mcp --help # 测试运行（Ctrl+C 退出） enhanced-fetch-mcp # 输出: Enhanced Fetch MCP Server running on stdio ``` ### 故障排查 #### 命令找不到 ```bash # 检查安装 npm list -g enhanced-fetch-mcp # 重新安装 npm install -g enhanced-fetch-mcp # 检查路径 which enhanced-fetch-mcp ``` #### Docker 未运行（影响沙箱功能） ```bash # macOS open -a Docker # Linux sudo systemctl start docker # 验证 docker ps ``` #### 查看日志 ```bash # 服务器日志 tail -f ~/.local/share/enhanced-fetch-mcp/logs/browser-mcp.log # 错误日志 tail -f ~/.local/share/enhanced-fetch-mcp/logs/browser-mcp-error.log ``` ### 更新 ```bash npm update -g enhanced-fetch-mcp ``` ### 开发 #### 从源码安装 ```bash # 克隆项目 git clone https://github.com/yourusername/enhanced-fetch-mcp.git cd enhanced-fetch-mcp # 安装依赖 npm install # 构建 npm run build # 全局链接（开发模式） npm link # 运行测试 npm test # 开发模式（监听变化） npm run dev ``` ### 性能指标 | 操作 | 平均耗时 | |------|----------| | HTTP 请求 | 200-300ms | | 内容提取 | 10-50ms | | 浏览器启动 | 300-500ms | | 页面导航 | 1.5-2s | | 截图 | ~50ms | | JavaScript 执行 | <10ms | ### 贡献 欢迎贡献！请提交 Pull Request 或创建 Issue。 ### 许可证 MIT License ### 致谢 - [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) - MCP 协议实现 - [Playwright](https://playwright.dev/) - 浏览器自动化 - [Cheerio](https://cheerio.js.org/) - HTML 解析 - [Turndown](https://github.com/mixmark-io/turndown) - HTML 转 Markdown - [Dockerode](https://github.com/apocas/dockerode) - Docker API