Crawlab MCP Server

Crawlab MCP サーバー

これは Crawlab 用の Model Context Protocol（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. LLM による処理：クライアントがクエリを LLM プロバイダー（Claude、OpenAI など）に転送します
3. ツールの選択：LLM が必要なツールを特定し、ツール呼び出しを生成します
4. ツールの実行：クライアントがツール呼び出しを MCP サーバーに送信します
5. API との連携：サーバーが対応する Crawlab API リクエストを実行します
6. 応答の生成：結果がサーバーからクライアントを経由して LLM に返されます
7. ユーザーへの応答：クライアントが最終的な、人が読める形式の応答をユーザーに返します

インストールと使用方法

オプション 1：Python パッケージとしてインストールする

MCP サーバーは、便利な CLI が付属する 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

インストール後、CLI を使用できます。

# 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 との統合

既存の Crawlab Docker Compose 設定に MCP サーバーを追加するには、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：ファイルに内容を保存します