Crawl4AI 网络爬虫 MCP 服务器

<!-- 可选：添加许可证 -->

本项目提供了一个 MCP (模型上下文协议) 服务器，它使用 crawl4ai 库来执行网络爬取和智能内容提取任务。它允许 AI 代理（如 Claude，或使用 LangChain/LangGraph 构建的代理）与网页交互、检索内容、搜索特定文本，并根据自然语言指令执行基于 LLM 的提取。

此服务器使用：

• FastMCP: 用于创建 MCP 服务器端点。
• crawl4ai: 用于核心网络爬取和提取逻辑。
• dotenv: 用于通过 .env 文件管理 API 密钥。
• (可选) Docker: 用于容器化部署，捆绑 Python 和依赖项。

功能

• 公开用于网络交互的 MCP 工具：
  • scrape_url: 获取网页的完整内容，格式为 Markdown。
  • extract_text_by_query: 根据查询查找页面上的特定文本片段。
  • smart_extract: 使用 LLM（目前为 Google Gemini）根据指令提取结构化信息。
• 可通过环境变量（API 密钥）配置。
• 包含 Docker 配置 (Dockerfile)，便于独立部署。
• 默认情况下，通过端口 8002 上的服务器发送事件 (SSE) 进行通信。

公开的 MCP 工具

scrape_url

爬取网页并以 Markdown 格式返回其内容。

参数：

• url (str, 必需): 要爬取的网页的 URL。

返回值：

• (str): 网页内容，格式为 Markdown，或错误消息。

extract_text_by_query

从网页中提取包含特定搜索查询的相关文本片段。最多返回找到的前 5 个匹配项。

参数：

• url (str, 必需): 要在其中搜索的网页的 URL。
• query (str, 必需): 要搜索的文本查询（不区分大小写）。
• context_size (int, 可选): 在每个片段中包含匹配的查询文本之前和之后的字符数。默认为 300。

返回值：

• (str): 包含找到的文本片段的格式化字符串，或指示未找到匹配项的消息，或错误消息。

smart_extract

使用配置的 LLM（目前需要 Google Gemini API 密钥）根据自然语言指令从网页中智能提取特定信息。

参数：

• url (str, 必需): 要分析和提取的网页的 URL。
• instruction (str, 必需): 指定要提取的信息的自然语言指令（例如，“列出此页面上提到的所有发言人”，“提取主要联系人电子邮件地址”，“总结主要发现”）。

返回值：

• (str): 提取的信息（通常格式化为 JSON 或基于指令的结构化文本），或指示未找到相关信息的消息，或错误消息（包括缺少必需的 API 密钥的情况）。

设置和运行

您可以本地运行此服务器，也可以使用提供的 Docker 配置运行。

选项 1：使用 Docker 运行（推荐用于部署）

此方法捆绑了 Python 和所有必需的库。您只需要在主机上安装 Docker。

1. 安装 Docker： 下载并安装适用于您的操作系统的 Docker Desktop。启动 Docker Desktop。
2. 克隆存储库：

   git clone https://github.com/your-username/your-repo-name.git # 替换为您的存储库 URL
   cd your-repo-name
   

3. 创建 .env 文件： 在项目根目录中创建一个名为 .env 的文件，并添加您的 API 密钥：

   # smart_extract 工具需要
   GOOGLE_API_KEY=your_google_ai_api_key_here
   
   # 可选，服务器检查但当前工具未使用
   # OPENAI_API_KEY=your_openai_key_here
   # MISTRAL_API_KEY=your_mistral_key_here
   

4. 构建 Docker 镜像：

   docker build -t crawl4ai-mcp-server .
   

5. 运行容器： 这将启动服务器，使端口 8002 在您的主机上可用。它使用 --env-file 将 API 密钥从您的本地 .env 文件安全地传递到容器的环境中。

   docker run -it --rm -p 8002:8002 --env-file .env crawl4ai-mcp-server
   

   • -it: 以交互方式运行。
   • --rm: 退出时删除容器。
   • -p 8002:8002: 将主机端口 8002 映射到容器端口 8002。
   • --env-file .env: 将环境变量从您的本地 .env 文件加载到容器中。对于 API 密钥至关重要。
   • crawl4ai-mcp-server: 您构建的镜像的名称。
6. 服务器正在运行： 将显示日志，指示服务器正在侦听 SSE (http://0.0.0.0:8002)。
7. 连接客户端： 配置您的 MCP 客户端（例如，LangChain 代理）以使用 transport: "sse" 连接到 http://127.0.0.1:8002/sse。

选项 2：本地运行

这需要在您的主机上安装 Python 并手动安装依赖项。

1. 安装 Python： 确保 Python >= 3.9（如果需要，检查 crawl4ai 要求，建议使用 3.10+）。
2. 克隆存储库：

   git clone https://github.com/your-username/your-repo-name.git # 替换为您的存储库 URL
   cd your-repo-name
   

3. 创建虚拟环境（推荐）：

   python -m venv venv
   source venv/bin/activate # Linux/macOS
   # venv\Scripts\activate # Windows
   

   (或使用 Conda: conda create --name crawl4ai-env python=3.11 -y && conda activate crawl4ai-env)
4. 安装依赖项：

   pip install -r requirements.txt
   

5. 创建 .env 文件： 在项目根目录中创建一个名为 .env 的文件，并添加您的 API 密钥（与 Docker 设置步骤 3 中的内容相同）。
6. 运行服务器：

   python your_server_script_name.py # 例如，python webcrawl_mcp_server.py
   

7. 服务器正在运行： 它将侦听 http://127.0.0.1:8002/sse。
8. 连接客户端： 配置您的 MCP 客户端以连接到 http://127.0.0.1:8002/sse。

环境变量

服务器使用以下环境变量，通常从 .env 文件加载：

• GOOGLE_API_KEY: smart_extract 工具正常运行必需（使用 Google Gemini）。从 Google AI Studio 获取一个。
• OPENAI_API_KEY: 检查是否存在，但此版本中的任何工具当前未使用。
• MISTRAL_API_KEY: 检查是否存在，但此版本中的任何工具当前未使用。

示例代理交互

# 使用先前设置中的代理 CLI 的示例

You: scrape_url https://example.com
Agent: Thinking...
[Agent calls scrape_url tool]
Agent: [Markdown content of example.com]
------------------------------
You: extract text from https://en.wikipedia.org/wiki/Web_scraping using the query "ethical considerations"
Agent: Thinking...
[Agent calls extract_text_by_query tool]
Agent: Found X matches for 'ethical considerations' on the page. Here are the relevant sections:
Match 1:
... text snippet ...
---
Match 2:
... text snippet ...
------------------------------
You: Use smart_extract on https://blog.google/technology/ai/google-gemini-ai/ to get the main points about Gemini models
Agent: Thinking...
[Agent calls smart_extract tool with Google API Key]
Agent: Successfully extracted information based on your instruction:
{
  "main_points": [
    "Gemini is Google's most capable AI model family (Ultra, Pro, Nano).",
    "Designed to be multimodal, understanding text, code, audio, image, video.",
    "Outperforms previous models on various benchmarks.",
    "Being integrated into Google products like Bard and Pixel."
  ]
}

文件

• your_server_script_name.py: MCP 服务器的主要 Python 脚本（例如，webcrawl_mcp_server.py）。
• Dockerfile: 用于构建 Docker 容器镜像的说明。
• requirements.txt: Python 依赖项。
• .env.example: (推荐) 显示所需密钥的示例环境文件。不要提交您实际的 .env 文件。
• .gitignore: 指定 Git 故意不跟踪的文件（应包括 .env）。
• README.md: 此文件。

贡献

（如果需要，添加贡献指南）

许可证

（指定您的许可证，例如，MIT 许可证）