Crawlab MCP 服务器

这是一个 Crawlab 的模型上下文协议 (MCP) 服务器，允许 AI 应用程序与 Crawlab 的功能进行交互。

概述

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

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

架构

MCP 服务器/客户端架构促进了 AI 应用程序和 Crawlab 之间的通信：

graph TB
    User[用户] --> Client[MCP 客户端]
    Client --> LLM[LLM 提供商]
    Client <--> Server[MCP 服务器]
    Server <--> Crawlab[Crawlab API]

    subgraph "MCP 系统"
        Client
        Server
    end

    subgraph "Crawlab 系统"
        Crawlab
        DB[(数据库)]
        Crawlab <--> DB
    end

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

    %% Flow annotations
    LLM -.-> |工具调用| Client
    Client -.-> |执行工具调用| Server
    Server -.-> |API 请求| Crawlab
    Crawlab -.-> |API 响应| Server
    Server -.-> |工具结果| Client
    Client -.-> |人类可读的响应| User

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

通信流程

1. 用户查询: 用户向 MCP 客户端发送自然语言查询
2. LLM 处理: 客户端将查询转发给 LLM 提供商（例如，Claude、OpenAI）
3. 工具选择: LLM 识别必要的工具并生成工具调用
4. 工具执行: 客户端将工具调用发送到 MCP 服务器
5. API 交互: 服务器执行相应的 Crawlab API 请求
6. 响应生成: 结果通过服务器流回客户端到 LLM
7. 用户响应: 客户端将最终的人类可读响应传递给用户

安装和使用

选项 1：作为 Python 包安装

您可以将 MCP 服务器作为 Python 包安装，它提供了一个方便的 CLI：

# 从源代码安装
pip install -e .

# 或者从 GitHub 安装（如果可用）
# pip install git+https://github.com/crawlab-team/crawlab-mcp-server.git

安装后，您可以使用 CLI：

# 启动 MCP 服务器
crawlab_mcp-mcp server [--spec PATH_TO_SPEC] [--host HOST] [--port PORT]

# 启动 MCP 客户端
crawlab_mcp-mcp client SERVER_URL

选项 2：本地运行

前提条件

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

配置

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

   cp .env.example .env
   

2. 使用您的 Crawlab API 详细信息编辑 .env 文件：

   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:
  # ... 现有的 Crawlab 服务
  
  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. 添加一个新服务器，其 URL 为您的 MCP 服务器（例如，http://localhost:8000）
4. 在与 Claude 的对话中，您现在可以通过用自然语言描述您想做什么来使用 Crawlab 功能

示例交互

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

创建爬虫：

用户: "创建一个名为 'Product Scraper' 的新爬虫，用于电子商务项目"
↓
LLM 识别意图并调用 create_spider 工具
↓
MCP 服务器执行对 Crawlab 的 API 调用
↓
创建爬虫，并将详细信息返回给用户

运行任务：

用户: "在所有可用节点上运行 'Product Scraper' 爬虫"
↓
LLM 使用适当的参数调用 run_spider 工具
↓
MCP 服务器将命令发送到 Crawlab API
↓
任务启动，并将确认信息返回给用户

可用命令

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

• "列出我所有的爬虫"
• "创建一个具有以下规格的新爬虫..."
• "显示名为 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: 将内容保存到文件