Codedox

🚀 CodeDox - ドキュメントコードの抽出と検索

強力なシステムで、ドキュメントウェブサイトをクロールし、コードスニペットを抽出し、MCP（Model Context Protocol）の統合を通じて高速な検索機能を提供します。

✨ 主な機能

• 制御可能なウェブクローリング：手動でクローリング可能で、深さを0 - 3レベルで設定できます。
• スマートなコード抽出：コンテキストを保持したままコードブロックを抽出します。
• 言語検出：LLMを使用したコンテキスト認識型の言語検出機能。
• 高速検索：PostgreSQLの全文検索を使用し、応答時間は100ms未満。
• MCP統合：Model Context Protocolを通じてAIアシスタントにツールを公開します。
• ソース管理：複数のドキュメントソースを追跡し、統計情報を管理します。
• クリーンなコンテンツ：Crawl4AIの統合により、ナビゲーション、広告、不要な要素を削除します。
• モダンなウェブUI：Reactベースのダッシュボードで、クローリングの管理、コードの検索、システムアクティビティの監視ができます。
• 自動サイトコンテンツの重複排除：変更されたコンテンツのみを更新または追加します。

🔧 アーキテクチャ

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Web UI       │────▶│   FastAPI       │────▶│   PostgreSQL    │
│ (React + Vite)  │     │   Server        │     │  (Full-Text)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                              │
┌─────────────────┐           │
│   MCP Client    │────▶│ MCP Tools │
│  (AI Assistant) │     │           │
└─────────────────┘     └───────────┘
                              │
                              ▼
                       ┌─────────────────┐
                       │   Crawl4AI      │
                       │  (Web Crawler)  │
                       └─────────────────┘

🚀 クイックスタート

前提条件

• Python 3.10以上
• PostgreSQL 12以上
• Playwright（crawl4aiと共に自動インストールされます）

📦 インストール

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

git clone https://github.com/yourusername/codedox.git
cd codedox

2. 仮想環境を作成します：

uv venv
source .venv/bin/activate  # Windowsの場合: .venv\Scripts\activate

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

uv pip install -r requirements.txt

# ウェブクローリングに必要なPlaywrightブラウザをインストールします
crawl4ai-setup

4. PostgreSQLをセットアップします：

# データベースを作成します
createdb codedox

# データベーススキーマを初期化します（初回のみ）
python cli.py init

# すべてのテーブルをリセットして再作成します（注意: すべてのデータが削除されます）
python cli.py init --drop

5. 環境を設定します：

cp .env.example .env
# .envを自分の設定で編集します

アプリケーションの実行

クイックスタート

# 仮想環境を作成してアクティブ化します（まだ行っていない場合）
uv venv
source .venv/bin/activate  # Windowsの場合: .venv\Scripts\activate

# データベースを初期化します（初回のみ）
python cli.py init

# すべてを起動します（API + Web UI）
python cli.py all

これにより、以下のことが行われます：

• ✅ APIサーバがhttp://localhost:8000で起動します。
• ✅ Web UIがhttp://localhost:5173で起動します。
• ✅ MCPツールがhttp://localhost:8000/mcpで利用可能になります。
• ✅ 両サービスのホットリロードが有効になります。

⚠️ 重要提示

Web UIは、クローリング、検索、監視などのすべての操作にユーザーフレンドリーなインターフェースを提供します。CLIコマンドを覚える必要はありません！

サービスを個別に実行する

# APIサーバのみを起動します
python cli.py run

# Web UIのみを起動します（別のターミナルで）
python cli.py ui

# APIサーバのみを起動します（別の方法）
python cli.py api

🔌 MCP（Model Context Protocol）の統合

CodeDoxは、2つのモードでMCPをサポートしています。

1. HTTPモード（推奨） - メインAPIサーバ上のHTTPエンドポイントを通じてMCPツールが公開されます。
2. Stdioモード - 直接AIアシスタントと統合するための従来型のMCPサーバ。

HTTPモード（APIサーバに組み込まれています）

APIサーバを実行するとき（python cli.py api または python cli.py all）、MCPツールは自動的にHTTPエンドポイントを通じて利用可能になります。別のMCPサーバは必要ありません。

MCPプロトコルエンドポイント（AIアシスタントに推奨）:

• POST /mcp - ストリーミング可能なHTTPトランスポート（MCP 2025-03-26仕様） - 最新かつ推奨
• POST /mcp/v1/sse - サーバー送信イベントトランスポート（旧仕様のサポート）

旧RESTエンドポイント:

• GET /mcp/health - ヘルスチェック
• GET /mcp/tools - スキーマ付きの利用可能なツールのリスト
• POST /mcp/execute/{tool_name} - 特定のツールを実行する
• POST /mcp/stream - シンプルな統合のためのストリーミングエンドポイント

使用例:

MCPプロトコルを使用するAIアシスタント（ストリーミング可能なHTTP - 推奨）:

# AIアシスタントを最新のストリーミング可能なトランスポートを使用するように構成します:
# URL: http://localhost:8000/mcp
# トランスポート: ストリーミング可能なHTTP
# ヘッダー: Accept: application/json, text/event-stream

MCPプロトコルを使用するAIアシスタント（SSE - 旧仕様）:

# AIアシスタントをSSEトランスポートを使用するように構成します:
# URL: http://localhost:8000/mcp/v1/sse
# トランスポート: サーバー送信イベント（SSE）

直接APIを使用する場合:

# 利用可能なツールのリストを取得します
curl http://localhost:8000/mcp/tools

# ライブラリからコードスニペットを取得します（ライブラリ名を使用）
curl -X POST http://localhost:8000/mcp/execute/get_content \
  -H "Content-Type: application/json" \
  -d '{"library_id": "nextjs", "query": "authentication"}'

# またはUUIDを使用する場合
curl -X POST http://localhost:8000/mcp/execute/get_content \
  -H "Content-Type: application/json" \
  -d '{"library_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "query": "authentication"}'

Stdioモード（スタンドアロンMCPサーバ）

従来のstdioベースのMCP通信を必要とするAIアシスタントの場合:

# スタンドアロンMCPサーバを実行します
python cli.py mcp

このモードは、HTTPエンドポイントをサポートしていない特定のAI統合にのみ必要です。

利用可能なMCPツール

1. init_crawl - ドキュメントのクローリングを開始します

   • name: ライブラリ/フレームワーク名（オプション - 提供されない場合は自動検出）
   • start_urls: クローリングするURLのリスト
   • max_depth: クローリングの深さ（0 - 3）
   • domain_filter: オプションのドメイン制限
   • url_patterns: 含めるURLパターンのオプションのリスト（例: ["docs", "guide"]）
   • max_concurrent_crawls: 最大同時ページクローリング数（デフォルト: 20）
   • metadata: 追加のメタデータ（オプション）

2. search_libraries - 名前で利用可能なライブラリを検索します

   • query: ライブラリ名の検索クエリ（例: 'react', 'nextjs', 'django'）
   • max_results: 返す最大結果数（1 - 50、デフォルト: 10）

3. get_content - ライブラリからコードスニペットを取得します

   • library_id: ライブラリID（UUID）またはライブラリ名（例: 'nextjs', 'react'）
   • query: 結果をフィルタリングするためのオプションの検索用語
   • max_results: 結果を制限する（1 - 50、デフォルト: 10）

4. get_snippet_details - 特定のコードスニペットに関する詳細情報を取得します

   • snippet_id: スニペットのID（get_contentの結果から）

📚 APIエンドポイント

クローリング

• POST /crawl/init - オプションのURLパターンフィルタリングで新しいクローリングジョブを開始します
• GET /crawl/status/{job_id} - クローリングの状態を確認します
• POST /crawl/cancel/{job_id} - 実行中のジョブをキャンセルします

検索

• POST /search - コードスニペットを検索します
• GET /search/languages - 利用可能な言語のリストを取得します
• GET /search/recent - 最近のスニペットを取得します

ソース

• GET /sources - ドキュメントソースのリストを取得します
• GET /snippets/{id} - 特定のスニペットを取得します
• GET /export/{job_id} - クローリング結果をエクスポートします

アップロード

• POST /upload/markdown - Markdownコンテンツをアップロードします
• POST /upload/file - Markdownファイルをアップロードします

💻 Web UI

CodeDoxには、ReactとTypeScriptで構築されたモダンでレスポンシブなウェブインターフェースが含まれています。開発サーバを実行するときに、http://localhost:5173 でアクセスできます。

機能

• ダッシュボード：リアルタイムの統計情報、システムの概要、最近のアクティビティの監視
• 高度な検索：言語フィルターと構文ハイライトを備えた強力なコードスニペット検索
• ソース管理：詳細な統計情報を伴うドキュメントソースの閲覧と管理
• クローリング監視：WebSocketを通じた進行状況の更新で、クローリングジョブをリアルタイムで追跡
• 設定：直感的なインターフェースを通じてアプリケーションの設定を構成

技術

• フロントエンドフレームワーク：TypeScriptを使用したReact 18
• ビルドツール：高速開発のためのVite
• スタイリング：ダークモードをサポートするTailwind CSS
• 状態管理：効率的なデータ取得のためのReact Query
• リアルタイム更新：ライブクローリングの進行状況のためのWebSocket統合

Web UIは、すべての主要な操作にCLIの代替手段としてユーザーフレンドリーなインターフェースを提供し、コマンドを覚えることなくドキュメントパイプラインを簡単に管理できます。

並列リクエストのためのLLM構成

ローカルLLMサーバで最適なパフォーマンスを得るには、.env ファイルで並列リクエストの設定を構成します。

# LLM構成
LLM_ENDPOINT=http://localhost:8080
LLM_MODEL=gpt-4
LLM_API_KEY=your-api-key-here
LLM_MAX_TOKENS=1000
LLM_TEMPERATURE=0.1

# 並列リクエストの設定（LLMサーバの機能に基づいて調整）
LLM_MAX_CONCURRENT_REQUESTS=20    # LLMへの最大並列リクエスト数
LLM_REQUEST_TIMEOUT=30.0          # リクエストのタイムアウト時間（秒）
LLM_RETRY_ATTEMPTS=3              # 失敗時のリトライ回数

最適な値を見つける:

含まれている構成テストを使用して、LLMセットアップの最適な設定を決定します。

# 最適な設定を見つけるためのクイックテスト（推奨）
python scripts/test_llm_config.py

# または包括的なパフォーマンス分析を実行する
python tests/performance/test_llm_concurrency_performance.py
python tests/performance/visualize_concurrency_results.py

構成ガイドライン:

• ローカルLLM（Ollamaなど）：LLM_MAX_CONCURRENT_REQUESTS=5 - 10 から始めます。
• GPUサーバ：VRAMに応じて LLM_MAX_CONCURRENT_REQUESTS=15 - 30 を処理できます。
• クラウドAPI（OpenAI、Claude）：レート制限に基づいて LLM_MAX_CONCURRENT_REQUESTS=20 - 50 を使用します。
• CPUのみ：システムを圧迫しないように LLM_MAX_CONCURRENT_REQUESTS=2 - 5 を維持します。

LLMサーバのリソース使用状況を監視し、適宜調整してください。高い並行性はクローリング速度を向上させますが、レイテンシを増加させたりタイムアウトを引き起こす可能性があります。

🌐 言語サポート

以下の言語が自動検出されます:

• Python、JavaScript、TypeScript
• Java、Go、Rust、C/C++、C#
• Ruby、PHP、SQL、Bash
• HTML、CSS、YAML、JSON、XML

🛠️ 開発

プロジェクト構造

codedox/
├── src/
│   ├── api/          # FastAPIエンドポイント
│   ├── crawler/      # ウェブクローリングロジック
│   ├── database/     # モデルと検索
│   ├── language/     # 言語検出
│   ├── mcp_server/   # MCPサーバの実装
│   └── parser/       # コード抽出
├── tests/            # テストスイート
├── config.yaml       # 構成
└── requirements.txt  # 依存関係

テストの実行

pytest tests/

📈 パフォーマンス

• 検索速度：全文検索で100ms未満
• ストレージ：コンテキスト付きのコードスニペットあたり約50KB

🐞 トラブルシューティング

一般的な問題

データベース接続に失敗しました

• PostgreSQLが実行中であることを確認します。
• .env の資格情報を確認します。

🤝 コントリビューション

1. リポジトリをフォークします。
2. 機能ブランチを作成します (git checkout -b feature/amazing)。
3. 変更をコミットします (git commit -m 'Add amazing feature')。
4. ブランチをプッシュします (git push origin feature/amazing)。
5. プルリクエストを開きます。

👤 作者

Chris Scott - 初期の開発と作業

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています - 詳細については LICENSE ファイルを参照してください。