Crawl4ai Rag

Crawl4AI RAG MCP Server

AI エージェントと AI コーディングアシスタント向けのウェブクローリングおよび RAG 機能

AI エージェントと AI コーディングアシスタントに高度なウェブクローリングおよび RAG 機能を提供するため、Crawl4AI および Supabase と統合された、Model Context Protocol (MCP) の強力な実装です。

この MCP サーバーを使えば、あらゆるものをスクレイピングして、その知識を RAG にどこでも活用できます。

主な目標は、AI コーディングアシスタントが AI エージェントを構築するためのナレッジエンジンへと進化させている Archon に、この MCP サーバーを導入することです。この Crawl4AI/RAG MCP サーバーの初期バージョンは、今後大幅に改善する予定です。特に、さまざまな埋め込みモデルを使えるよう設定項目を増やし、Ollama を使ってすべてをローカルで実行できるようにします。

この GitHub リポジトリはテストベッドとしてお考えください。そのため、これまで Issue やプルリクエストにはあまり積極的に対応していませんでした。Archon V2 に導入するにあたり、今後は対応していきます。

概要

この MCP サーバーは、AI エージェントがウェブサイトをクロールし、コンテンツをベクトルデータベース（Supabase）に保存して、クロールしたコンテンツを対象に RAG を実行できるツールを提供します。以前、自身のチャンネルで紹介した Mem0 MCP server template に基づく、MCP サーバー構築のベストプラクティスに従っています。

このサーバーには、検索品質を高めるために有効化できる高度な RAG 戦略がいくつか含まれています。

• コンテキスト埋め込みによる意味理解の強化
• ベクトル検索とキーワード検索を組み合わせたハイブリッド検索
• コード例の抽出に特化したエージェント型 RAG
• クロスエンコーダーモデルを使用して結果の関連性を向上させる再ランキング
• AI のハルシネーション検出とリポジトリのコード分析を行うナレッジグラフ

これらの戦略を有効化して設定する方法については、以下の設定セクションを参照してください。

ビジョン

Crawl4AI RAG MCP サーバーは始まりにすぎません。今後の展望は次のとおりです。

1. Archon との統合：Archon にこのシステムを直接組み込み、AI コーディングアシスタントがより優れた AI エージェントを構築するための包括的なナレッジエンジンを作ります。

2. 複数の埋め込みモデル：OpenAI 以外にも対応範囲を広げ、さまざまな埋め込みモデルをサポートします。完全な制御とプライバシーを実現するため、Ollama を使ってすべてをローカルで実行できるようにします。

3. 高度な RAG 戦略：コンテキスト検索、レイトチャンク化などの高度な検索技術を実装し、基本的な「単純検索」を超えて、RAG システムの能力と精度を大幅に高めます。特に Archon との統合に伴い、強化を進めます。

4. チャンク分割戦略の強化：Context 7 に着想を得たチャンク分割方式を実装します。例に重点を置き、チャンクごとに意味的に明確なセクションを作成することで、検索精度を向上させます。

5. パフォーマンスの最適化：クロールとインデックス作成の速度を向上させ、AI コーディングアシスタントのプロンプト内で新しいドキュメントを「すばやく」インデックス化し、そのまま活用できるようにします。

機能

• スマート URL 検出：通常のウェブページ、サイトマップ、テキストファイルなど、さまざまな URL の種類を自動的に検出して処理します
• 再帰的クロール：内部リンクをたどってコンテンツを見つけます
• 並列処理：複数のページを同時に効率よくクロールします
• コンテンツのチャンク分割：処理しやすいように、ヘッダーとサイズに基づいてコンテンツを適切に分割します
• ベクトル検索：クロールしたコンテンツを対象に RAG を実行します。精度を高めるため、データソースで任意に絞り込めます
• ソースの取得：RAG プロセスの指針となる、絞り込み可能なソースを取得します

ツール

このサーバーは、ウェブクローリングと検索に欠かせないツールを提供します。

コアツール（常時利用可能）

1. crawl_single_page：単一のウェブページをすばやくクロールし、その内容をベクトルデータベースに保存します
2. smart_crawl_url：指定された URL の種類（サイトマップ、llms-full.txt、または再帰的なクロールが必要な通常のウェブページ）に応じて、ウェブサイト全体をインテリジェントにクロールします
3. get_available_sources：データベース内で利用可能なすべてのソース（ドメイン）の一覧を取得します
4. perform_rag_query：任意のソースフィルタリングを使ったセマンティック検索で、関連コンテンツを検索します

条件付きツール

5. search_code_examples（USE_AGENTIC_RAG=true が必要）：クロールしたドキュメントから、コード例とその要約を対象に検索します。このツールは、AI コーディングアシスタント向けに、対象を絞ったコードスニペットの取得を提供します。

ナレッジグラフツール（USE_KNOWLEDGE_GRAPH=true が必要です。詳細は以下を参照）

6. parse_github_repository：GitHub リポジトリを Neo4j のナレッジグラフに解析し、幻覚検出のためにクラス、メソッド、関数、およびそれらの関係を抽出します
7. check_ai_script_hallucinations：Python スクリプトのインポート、メソッド呼び出し、クラスの使用状況をナレッジグラフと照合し、AI による幻覚を分析します
8. query_knowledge_graph：repos、classes、methods などのコマンドやカスタム Cypher クエリを使って、Neo4j ナレッジグラフを探索、検索します

前提条件

• MCP サーバーをコンテナとして実行する場合は Docker/Docker Desktop（推奨）
• uv を通じて MCP サーバーを直接実行する場合は Python 3.12+
• Supabase（RAG 用データベース）
• OpenAI API key（埋め込みベクトルの生成用）
• Neo4j（任意。ナレッジグラフ機能用）。ナレッジグラフのセットアップセクションを参照してください

インストール

Docker を使用する場合（推奨）

1. このリポジトリをクローンします：

   git clone https://github.com/coleam00/mcp-crawl4ai-rag.git
   cd mcp-crawl4ai-rag
   

2. Docker イメージをビルドします：

   docker build -t mcp/crawl4ai-rag --build-arg PORT=8051 .
   

3. 以下の設定セクションを参考に .env ファイルを作成します

uv を直接使用する場合（Docker なし）

1. このリポジトリをクローンします：

   git clone https://github.com/coleam00/mcp-crawl4ai-rag.git
   cd mcp-crawl4ai-rag
   

2. uv がインストールされていない場合はインストールします：

   pip install uv
   

3. 仮想環境を作成し、有効化します：

   uv venv
   .venv\Scripts\activate
   # on Mac/Linux: source .venv/bin/activate
   

4. 依存関係をインストールします：

   uv pip install -e .
   crawl4ai-setup
   

5. 以下の設定セクションを参考に .env ファイルを作成します

データベースのセットアップ

サーバーを実行する前に、pgvector 拡張機能を使ってデータベースをセットアップする必要があります：

1. Supabase ダッシュボードの SQL Editor に移動します（必要に応じて、先に新しいプロジェクトを作成してください）

2. 新しいクエリを作成し、crawled_pages.sql の内容を貼り付けます

3. クエリを実行して、必要なテーブルと関数を作成します

ナレッジグラフのセットアップ（任意）

AI の幻覚検出機能とリポジトリ分析機能を有効にするには、Neo4j をセットアップする必要があります。

また、ナレッジグラフの実装はまだ Docker と完全には互換性がないため、MCP サーバー内で幻覚検出を使いたい場合は、現時点では uv から直接実行することをおすすめします。

Neo4j のインストール方法：

Local AI Package（推奨）

Neo4j をローカルで実行する最も簡単な方法は、Neo4j を含むローカル AI サービスの厳選コレクションである Local AI Package を利用することです：

1. Local AI Package をクローンする：

   git clone https://github.com/coleam00/local-ai-packaged.git
   cd local-ai-packaged
   

2. Neo4j を起動する： Local AI Package リポジトリの手順に従い、Docker Compose で Neo4j を起動します

3. デフォルトの接続情報：

   • URI：bolt://localhost:7687
   • ユーザー名：neo4j
   • パスワード：デフォルトのパスワードについては Local AI Package のドキュメントを確認してください

Neo4j の手動インストール

または、Neo4j を直接インストールします。

1. Neo4j Desktop をインストールする：neo4j.com/download からダウンロードします。

2. 新しいデータベースを作成する：

   • Neo4j Desktop を開きます
   • 新しいプロジェクトとデータベースを作成します
   • neo4j ユーザーのパスワードを設定します
   • データベースを起動します

3. 接続情報を控える：

   • URI：bolt://localhost:7687（デフォルト）
   • ユーザー名：neo4j（デフォルト）
   • パスワード：作成時に設定したもの

設定

プロジェクトのルートに .env ファイルを作成し、次の変数を設定します。

# MCP Server Configuration
HOST=0.0.0.0
PORT=8051
TRANSPORT=sse

# OpenAI API Configuration
OPENAI_API_KEY=your_openai_api_key

# LLM for summaries and contextual embeddings
MODEL_CHOICE=gpt-4.1-nano

# RAG Strategies (set to "true" or "false", default to "false")
USE_CONTEXTUAL_EMBEDDINGS=false
USE_HYBRID_SEARCH=false
USE_AGENTIC_RAG=false
USE_RERANKING=false
USE_KNOWLEDGE_GRAPH=false

# Supabase Configuration
SUPABASE_URL=your_supabase_project_url
SUPABASE_SERVICE_KEY=your_supabase_service_key

# Neo4j Configuration (required for knowledge graph functionality)
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_neo4j_password

RAG 戦略のオプション

Crawl4AI RAG MCP サーバーでは、4 つの強力な RAG 戦略を個別に有効にできます。

1. USE_CONTEXTUAL_EMBEDDINGS

有効にすると、ドキュメント全体から追加のコンテキストを取り込み、各チャンクの埋め込みを強化します。システムはドキュメント全体と対象のチャンクの両方を LLM（MODEL_CHOICE で設定）に渡し、チャンクの内容とともに埋め込むコンテキストを生成します。

• 使用する場面：用語の意味がセクションごとに異なる技術文書など、コンテキストが重要となる高精度な検索が必要な場合に有効にします。
• トレードオフ：チャンクごとに LLM を呼び出すためインデックス作成が遅くなりますが、検索精度は大幅に向上します。
• コスト：インデックス作成時に追加の LLM API 呼び出しが発生します。

2. USE_HYBRID_SEARCH

従来のキーワード検索とセマンティックなベクトル検索を組み合わせ、より網羅的な結果を提供します。システムは両方の検索を並行して実行し、結果をインテリジェントに統合します。両方の検索結果に含まれるドキュメントを優先します。

• 使用する場面：ユーザーが特定の技術用語や関数名で検索する場合、またはセマンティックな理解と併せてキーワードの完全一致が重要な場合に有効にします。
• トレードオフ：検索クエリの処理はやや遅くなりますが、特に技術的なコンテンツでより確実な結果が得られます。
• コスト：追加の API コストは発生せず、計算処理の負荷のみが増加します。

3. USE_AGENTIC_RAG

専用のコード例抽出と保存を有効にします。ドキュメントのクロール時に、システムはコードブロック（300 文字以上）を特定し、前後のコンテキストとともに抽出して要約を生成します。その後、コード検索専用に設計された別のベクトルデータベーステーブルに保存します。

• 使用する場面：ドキュメントから特定のコード例、実装パターン、使用例を見つける必要がある AI コーディングアシスタントには不可欠です。
• トレードオフ：コードの抽出と要約によりクロールが大幅に遅くなり、より多くのストレージ容量が必要になります。
• コスト：コード例ごとの要約に追加の LLM API 呼び出しが発生します。
• メリット：AI エージェントが特定のコード実装を見つけるために使用できる、専用の search_code_examples ツールを提供します。

4. USE_RERANKING

初期検索の後、検索結果にクロスエンコーダーによる再ランキングを適用します。軽量なクロスエンコーダーモデル（cross-encoder/ms-marco-MiniLM-L-6-v2）を使用して各結果を元のクエリに照らしてスコア付けし、関連性の高い順に結果を並べ替えます。

• 使用する場面：検索精度が重要で、最も関連性の高い結果を上位に表示する必要がある場合に有効にします。特に、セマンティックな類似性だけではクエリの意図を捉えにくい複雑なクエリで役立ちます。
• トレードオフ：結果の件数に応じて検索クエリに約 100～200 ミリ秒が追加されますが、結果の並び順は大幅に改善されます。
• コスト：追加の API コストは発生しません。CPU 上で動作するローカルモデルを使用します。
• メリット：特に複雑なクエリで、結果の関連性が向上します。通常の RAG 検索とコード例検索の両方で利用できます。

5. USE_KNOWLEDGE_GRAPH

Neo4j ナレッジグラフを使用して、AI の幻覚を検出し、リポジトリを分析します。有効にすると、GitHub リポジトリをグラフデータベースに解析し、AI が生成したコードを実際のリポジトリ構造に照らして検証できます。（Docker との互換性はまだ完全ではないため、uv 経由で実行することをおすすめします）

• 使用するタイミング：生成コードを実際の実装に照らして検証する必要がある AI コーディングアシスタントを使う場合や、AI モデルが存在しないメソッドやクラス、誤った使用パターンを幻覚として生成していないか検出したい場合に有効にします。
• トレードオフ：Neo4j のセットアップと追加の依存関係が必要です。大規模なコードベースではリポジトリの解析に時間がかかることがあり、検証の前にリポジトリをインデックス化しておく必要があります。
• コスト：検証に追加の API コストはかかりませんが、Neo4j のインフラが必要です（無料のローカルインストールまたはクラウドの AuraDB を使用できます）。
• メリット：次の 3 つの強力なツールを利用できます。コードベースをインデックス化する parse_github_repository、AI が生成したコードを検証する check_ai_script_hallucinations、インデックス化されたリポジトリを探索する query_knowledge_graph です。

AI コーディングアシスタントに、次のように Python の GitHub リポジトリをナレッジグラフに追加するよう指示できます。

「https://github.com/pydantic/pydantic-ai.git をナレッジグラフに追加してください」

リポジトリの URL が .git で終わっていることを確認してください。

AI コーディングアシスタントに、作成したばかりのスクリプトの幻覚をチェックさせることもできます。また、次のコマンドを手動で実行することもできます。

python knowledge_graphs/ai_hallucination_detector.py [full path to your script to analyze]

推奨構成

一般的なドキュメント RAG の場合：

USE_CONTEXTUAL_EMBEDDINGS=false
USE_HYBRID_SEARCH=true
USE_AGENTIC_RAG=false
USE_RERANKING=true

コード例を扱う AI コーディングアシスタントの場合：

USE_CONTEXTUAL_EMBEDDINGS=true
USE_HYBRID_SEARCH=true
USE_AGENTIC_RAG=true
USE_RERANKING=true
USE_KNOWLEDGE_GRAPH=false

幻覚検出機能を備えた AI コーディングアシスタントの場合：

USE_CONTEXTUAL_EMBEDDINGS=true
USE_HYBRID_SEARCH=true
USE_AGENTIC_RAG=true
USE_RERANKING=true
USE_KNOWLEDGE_GRAPH=true

高速で基本的な RAG の場合：

USE_CONTEXTUAL_EMBEDDINGS=false
USE_HYBRID_SEARCH=true
USE_AGENTIC_RAG=false
USE_RERANKING=false
USE_KNOWLEDGE_GRAPH=false

サーバーの実行

Docker を使用する場合

docker run --env-file .env -p 8051:8051 mcp/crawl4ai-rag

Python を使用する場合

uv run src/crawl4ai_mcp.py

サーバーが起動し、設定されたホストとポートでリクエストを待ち受けます。

MCP クライアントとの統合

SSE の設定

SSE トランスポートでサーバーを起動したら、次の設定を使用して接続できます。

{
  "mcpServers": {
    "crawl4ai-rag": {
      "transport": "sse",
      "url": "http://localhost:8051/sse"
    }
  }
}

Windsurf ユーザーへの注意：設定では url の代わりに serverUrl を使用してください。

{
  "mcpServers": {
    "crawl4ai-rag": {
      "transport": "sse",
      "serverUrl": "http://localhost:8051/sse"
    }
  }
}

Docker ユーザーへの注意：クライアントが別のコンテナで実行されている場合は、localhost の代わりに host.docker.internal を使用してください。n8n 内でこの MCP サーバーを使用する場合も同様です。

Claude Code ユーザーへの注意：

claude mcp add-json crawl4ai-rag '{"type":"http","url":"http://localhost:8051/sse"}' --scope user

Stdio の設定

Claude Desktop、Windsurf、その他の MCP クライアント用の MCP 設定に、このサーバーを追加してください。

{
  "mcpServers": {
    "crawl4ai-rag": {
      "command": "python",
      "args": ["path/to/crawl4ai-mcp/src/crawl4ai_mcp.py"],
      "env": {
        "TRANSPORT": "stdio",
        "OPENAI_API_KEY": "your_openai_api_key",
        "SUPABASE_URL": "your_supabase_url",
        "SUPABASE_SERVICE_KEY": "your_supabase_service_key",
        "USE_KNOWLEDGE_GRAPH": "false",
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_neo4j_password"
      }
    }
  }
}

Stdio 設定での Docker の使用

{
  "mcpServers": {
    "crawl4ai-rag": {
      "command": "docker",
      "args": ["run", "--rm", "-i", 
               "-e", "TRANSPORT", 
               "-e", "OPENAI_API_KEY", 
               "-e", "SUPABASE_URL", 
               "-e", "SUPABASE_SERVICE_KEY",
               "-e", "USE_KNOWLEDGE_GRAPH",
               "-e", "NEO4J_URI",
               "-e", "NEO4J_USER",
               "-e", "NEO4J_PASSWORD",
               "mcp/crawl4ai"],
      "env": {
        "TRANSPORT": "stdio",
        "OPENAI_API_KEY": "your_openai_api_key",
        "SUPABASE_URL": "your_supabase_url",
        "SUPABASE_SERVICE_KEY": "your_supabase_service_key",
        "USE_KNOWLEDGE_GRAPH": "false",
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_neo4j_password"
      }
    }
  }
}

ナレッジグラフのアーキテクチャ

ナレッジグラフシステムは、次のコンポーネントを使用して、リポジトリのコード構造を Neo4j に保存します。

コアコンポーネント（knowledge_graphs/ フォルダー）：

• parse_repo_into_neo4j.py：GitHub リポジトリをクローンして解析し、Python のクラス、メソッド、関数、インポートを抽出して、Neo4j のノードとリレーションシップに格納します。
• ai_script_analyzer.py：AST を使用して Python スクリプトを解析し、インポート、クラスのインスタンス化、メソッド呼び出し、関数の使用を抽出します。
• knowledge_graph_validator.py：AI が生成したコードをナレッジグラフに照らして検証し、幻覚（存在しないメソッド、不正なパラメーターなど）を検出します。
• hallucination_reporter.py：検出された幻覚について、信頼度スコアと推奨事項を含む包括的なレポートを生成します。
• query_knowledge_graph.py：ナレッジグラフを探索する対話型 CLI ツールです（この機能は現在 MCP ツールに統合されています）。

ナレッジグラフのスキーマ：

Neo4j データベースには、コード構造が次のように保存されています。

ノード：

• Repository：GitHub リポジトリ
• File：リポジトリ内の Python ファイル
• Class：メソッドと属性を持つ Python クラス
• Method：パラメーター情報を持つクラスメソッド
• Function：独立した関数
• Attribute：クラス属性

リレーションシップ：

• Repository -[:CONTAINS]-> File
• File -[:DEFINES]-> Class
• File -[:DEFINES]-> Function
• Class -[:HAS_METHOD]-> Method
• Class -[:HAS_ATTRIBUTE]-> Attribute

ワークフロー：

1. リポジトリの解析：parse_github_repository ツールを使用して、オープンソースのリポジトリをクローンし、分析します
2. コードの検証：check_ai_script_hallucinations ツールを使用して、AI が生成した Python スクリプトを検証します
3. ナレッジの探索：query_knowledge_graph ツールを使用して、利用可能なリポジトリ、クラス、メソッドを探索します

独自のサーバーを構築する

この実装は、ウェブクローリング機能を備えた、より複雑な MCP サーバーを構築するための基盤となります。独自のサーバーを構築するには、次の手順に従います。

1. @mcp.tool() デコレーターを使用したメソッドを作成して、独自のツールを追加します
2. 独自の依存関係を追加するためのライフスパン関数を作成します
3. 必要なヘルパー関数に合わせて utils.py ファイルを変更します
4. より特化したクローラーを追加して、クローリング機能を拡張します