Crawlab MCP Server

Crawlab MCP 服务

这是一个适用于 Crawlab 的模型上下文协议（MCP）服务，可让 AI 应用与 Crawlab 的功能进行交互。

概述

MCP 服务为 AI 应用提供了一种标准化方式，以便访问 Crawlab 的功能，包括：

• 爬虫管理（创建、读取、更新、删除）
• 任务管理（运行、取消、重启）
• 文件管理（读取、写入）
• 资源访问（爬虫、任务）

架构

MCP 服务端/客户端架构支持 AI 应用与 Crawlab 之间的通信：

graph TB
    User[User] --> Client[MCP Client]
    Client --> LLM[LLM Provider]
    Client <--> Server[MCP Server]
    Server <--> Crawlab[Crawlab API]

    subgraph "MCP System"
        Client
        Server
    end

    subgraph "Crawlab System"
        Crawlab
        DB[(Database)]
        Crawlab <--> DB
    end

    class User,LLM,Crawlab,DB external;
    class Client,Server internal;

    %% Flow annotations
    LLM -.-> |Tool calls| Client
    Client -.-> |Executes tool calls| Server
    Server -.-> |API requests| Crawlab
    Crawlab -.-> |API responses| Server
    Server -.-> |Tool results| Client
    Client -.-> |Human-readable response| User

    classDef external fill:#f9f9f9,stroke:#333,stroke-width:1px;
    classDef internal fill:#d9edf7,stroke:#31708f,stroke-width:1px;

通信流程

1. 用户查询：用户向 MCP 客户端发送自然语言查询
2. 大模型处理：客户端将查询转发给大模型提供商（例如 Claude、OpenAI）
3. 工具选择：大模型识别所需工具并生成工具调用
4. 工具执行：客户端将工具调用发送给 MCP 服务
5. API 交互：服务执行相应的 Crawlab API 请求
6. 生成响应：结果经由服务返回客户端，再传递给大模型
7. 回复用户：客户端向用户提供最终的易读回复

安装和使用

选项 1：安装为 Python 包

你可以将 MCP 服务安装为 Python 包，以便使用便捷的命令行界面：

# Install from source
pip install -e .

# Or install from GitHub (when available)
# pip install git+https://github.com/crawlab-team/crawlab-mcp-server.git

安装后，你可以使用命令行界面：

# Start the MCP server
crawlab_mcp-mcp server [--spec PATH_TO_SPEC] [--host HOST] [--port PORT]

# Start the MCP client
crawlab_mcp-mcp client SERVER_URL

选项 2：在本地运行

前提条件

• Python 3.8+
• 正在运行且可访问的 Crawlab 实例
• Crawlab API 令牌

配置

1. 将 .env.example 文件复制为 .env：

   cp .env.example .env
   

2. 在 .env 文件中填写 Crawlab API 详细信息：

   CRAWLAB_API_BASE_URL=http://your-crawlab-instance:8080/api
   CRAWLAB_API_TOKEN=your_api_token_here
   

在本地运行

1. 安装依赖项：

   pip install -r requirements.txt
   

2. 运行服务：

   python server.py
   

使用 Docker 运行

1. 构建 Docker 镜像：

   docker build -t crawlab-mcp-server .
   

2. 运行容器：

   docker run -p 8000:8000 --env-file .env crawlab-mcp-server
   

与 Docker Compose 集成

若要将 MCP 服务添加到现有的 Crawlab Docker Compose 配置中，请将以下服务添加到你的 docker-compose.yml：

services:
  # ... existing Crawlab services
  
  mcp-server:
    build: ./backend/mcp-server
    ports:
      - "8000:8000"
    environment:
      - CRAWLAB_API_BASE_URL=http://backend:8000/api
      - CRAWLAB_API_TOKEN=your_api_token_here
    depends_on:
      - backend

与 AI 应用配合使用

MCP 服务可让 AI 应用通过自然语言与 Crawlab 交互。参照上方的架构图，以下是 MCP 系统的使用方法：

设置连接

1. 启动 MCP 服务：确保 MCP 服务正在运行且可访问
2. 配置 AI 客户端：将 AI 应用连接到 MCP 服务

示例：与 Claude Desktop 配合使用

1. 打开 Claude Desktop
2. 前往 Settings > MCP Servers
3. 添加新服务，并填写 MCP 服务的 URL（例如，http://localhost:8000）
4. 在与 Claude 的对话中，现在可以用自然语言描述想要执行的操作，以使用 Crawlab 功能

交互示例

以下是根据我们的架构与系统交互的示例：

创建爬虫：

User: "Create a new spider named 'Product Scraper' for the e-commerce project"
↓
LLM identifies intent and calls the create_spider tool
↓
MCP Server executes the API call to Crawlab
↓
Spider is created and details are returned to the user

运行任务：

User: "Run the 'Product Scraper' spider on all available nodes"
↓
LLM calls the run_spider tool with appropriate parameters
↓
MCP Server sends the command to Crawlab API
↓
Task is started and confirmation is returned to the user

可用命令

你可以使用以下自然语言命令与系统交互：

• “列出我的所有爬虫”
• “根据这些规格创建一个新爬虫……”
• “显示名为 X 的爬虫代码”
• “使用以下代码更新爬虫 X 中的 main.py 文件……”
• “运行爬虫 X，并在运行完成时通知我”
• “显示爬虫 X 上次运行的结果”

可用资源和工具

以下是支持自然语言交互的底层工具：

资源

• spiders：列出所有爬虫
• tasks：列出所有任务

工具

爬虫管理

• get_spider：获取特定爬虫的详细信息
• create_spider：创建新爬虫
• update_spider：更新现有爬虫
• delete_spider：删除爬虫

任务管理

• get_task：获取特定任务的详细信息
• run_spider：运行爬虫
• cancel_task：取消正在运行的任务
• restart_task：重启任务
• get_task_logs：获取任务日志

文件管理

• get_spider_files：列出爬虫的文件
• get_spider_file：获取特定文件的内容
• save_spider_file：将内容保存到文件