MCP-RAG

✨100% AIによって作成

AIクライアント向けのサービス優先RAGサービスであり、現在はFastAPI HTTPサービスおよびStreamable HTTP MCPエンドポイントを主軸としています。

コードは現在、統一されたバックエンドシェルを提供しています：

• FastAPI HTTPサービス

• Streamable HTTP MCP

• 共有ランタイム、設定のホットリロード、認証、レート制限、クォータ、オブザーバビリティ

• ナレッジベースレジストリに基づく検索およびドキュメント管理

現在の機能

• ドキュメントインポート：テキストの直接追加、および txt、md、pdf、docx のアップロードをサポート

• 検索：ベクトル検索 + キーワード検索の融合

• Q&A：/search、/chat、MCP rag_ask

• マルチナレッジベース：単一ナレッジベースおよび kb_ids による複数ナレッジベースの集約検索/対話をサポート

• ナレッジベーススコープ：public および agent_private

• テナントコンテキスト：base_collection + user_id + agent_id

• ランタイムガバナンス：APIキー、メモリレート制限、アップロード/インデックスクォータ、リクエストレベルの検索キャッシュ

• プロバイダーガバナンス：プロバイダー予算、サーキットブレーカー、フォールバック

• オブザーバビリティ：/health、/ready、/metrics

• フロントエンド：組み込みのシングルページ管理パネル /app

アーキテクチャ

メインリンク：

HTTP / MCP
  -> app_factory.py
  -> http_server.py / mcp_server.py
  -> context.py
  -> service_facade.py
  -> services/
       - runtime.py
       - indexing_service.py
       - retrieval_service.py
       - chat_service.py
  -> knowledge_bases.py
  -> core/indexing/
  -> retrieval/

主要ファイル：

• src/mcp_rag/cli.py: CLIエントリーポイント、serve および init を提供

• src/mcp_rag/main.py: HTTPサービス起動エントリーポイント

• src/mcp_rag/http_server.py: HTTP API、SPAエントリーポイント、Streamable HTTP MCPマウント

• src/mcp_rag/mcp_server.py: MCPツール定義および rag_ask

• src/mcp_rag/app_factory.py: アプリコンテキスト、ランタイム、ガードレールの統一アセンブリ

• src/mcp_rag/knowledge_bases.py: ナレッジベースレジストリおよびデフォルトナレッジベースの解決

• src/mcp_rag/config.py: 設定モデル、JSON/SQLite永続化、ホットリロード

環境要件

• Python >= 3.13

• uv

インストール

CLIのインストール：

uv tool install mcp-rag

インストール後、直接実行：

mcp-rag serve

リポジトリ内での開発：

uv sync

ローカル埋め込み（embedding）が必要な場合：

uv sync --extra local-embeddings

境界条件の説明：

• uv tool install mcp-rag を使用してインストールするユーザーは、Node.jsや pnpm は不要です

• pnpm はフロントエンドビルドの保守にのみ使用され、サービスランタイムの依存関係ではありません

起動と初期化

サービスの起動：

uv run mcp-rag serve

データディレクトリの初期化：

uv run mcp-rag init --data-dir ./data

デフォルトポートは 8060 で、サービスはデフォルトで 0.0.0.0:8060 をリッスンします。

一般的なエントリーポイント：

• 管理パネル：http://127.0.0.1:8060/app

• APIドキュメント：http://127.0.0.1:8060/docs

• MCPエンドポイント：http://127.0.0.1:8060/mcp

互換性のあるエントリーポイント：

• / は /app にリダイレクトされます

• /doc は /docs にリダイレクトされます

• /documents-page は /app/documents にリダイレクトされます

• /config-page は /app/config にリダイレクトされます

初回起動時の動作：

• ./data/config.json が存在しない場合、設定読み込み時にデフォルト値が使用されます

• サービス起動時に ensure_config_file() が呼び出され、デフォルト設定がディスクに書き込まれます

• データディレクトリ内の ./data/chroma および関連するSQLiteファイルは必要に応じて作成されます

フロントエンドと静的リソース

リリースパッケージには src/mcp_rag/static/ がwheel / sdistに同梱されます。

これは以下を意味します：

• インストールユーザーは uv tool install mcp-rag 後、直接 /app にアクセス可能です

• フロントエンドの個別ビルドやNode.jsは不要です

• フロントエンドのメンテナーは、リリース前に最新の静的リソースを生成する必要があります

フロントエンドのソースコードは frontend/ にあり、ビルド出力は src/mcp_rag/static/app に配置されます。

典型的なフロー：

cd frontend
pnpm install
pnpm build

ナレッジベースモデル

現在のプロジェクトは、単なる collection によるデータ整理ではなく、ナレッジベースレジストリを主軸としています。

ナレッジベースの特性：

• 永続化レジストリは knowledge_base_db_path が指すSQLiteファイル内にあります

• デフォルトでパブリックナレッジベースの存在が保証されます

• user_id + agent_id が渡されると、対応するデフォルトの agent_private ナレッジベースの存在が保証されます

• 新しいナレッジベース作成後、安定した内部コレクション名（例：kb_<id>）が割り当てられます

インターフェース層では引き続き collection パラメータが保持されていますが、これは古い呼び出し方法との互換性のためです。現在の実際の動作は以下の通りです：

• kb_id を明示的に渡すことが可能

• 引き続き古い collection を渡すことも可能

• サービスはリクエストを具体的なナレッジベースと実際のコレクション名に解決します

HTTPインターフェース

システムインターフェース：

• GET /health

• GET /ready

• GET /metrics

設定インターフェース：

• GET /config

• POST /config

• POST /config/bulk

• POST /config/reset

• POST /config/reload

プロバイダーインターフェース：

• GET /providers/{provider}/models

ナレッジベースインターフェース：

• GET /collections

• GET /knowledge-bases

• POST /knowledge-bases

ドキュメントインターフェース：

• POST /add-document

• POST /upload-files

• GET /list-documents

• DELETE /delete-document

• GET /list-files

• DELETE /delete-file

検索とQ&A：

• GET /search

• POST /chat

MCPデバッグインターフェース：

• GET /debug/mcp/tools

• POST /debug/mcp/call

いくつかの注意点：

• /search および /chat は kb_id をサポートしています

• /search および /chat は kb_ids による複数ナレッジベースの集約もサポートしています

• /upload-files は multipart/form-data を使用します

• /delete-document および /delete-file はリクエストボディを通じて削除パラメータを渡します

セキュリティポリシーが有効な場合、APIキーは以下の方法で渡すことができます：

• HTTP Header: x-api-key

• Header: Authorization: Bearer <token>

• クエリパラメータ、JSONボディ、またはフォーム内の api_key

MCP

現在の主な形態はStreamable HTTP MCPです：

{
  "mcpServers": {
    "rag": {
      "url": "http://127.0.0.1:8060/mcp"
    }
  }
}

実装済みのMCPツール：

• rag_ask

rag_ask の主要パラメータ：

• query

• mode: raw または summary

• collection

• kb_id

• scope

• limit

• threshold

• tenant

• user_id / agent_id

• _user_id / _agent_id

• api_key

• request_id

• trace_id

例：

{
  "name": "rag_ask",
  "arguments": {
    "query": "FastAPI 是什么",
    "kb_id": 1,
    "mode": "summary",
    "limit": 5
  }
}

設定

デフォルト設定ファイル：

./data/config.json

デフォルトナレッジベースデータベース：

./data/knowledge_bases.sqlite3

現在の設定には重要な変更があります：

• 通常の実行設定は config.json に保存されます

• プロバイダー関連の設定は config.json に書き戻されず、SQLiteに永続化されます

つまり、以下のフィールドはSQLite内の service_provider_settings に保存されます：

• embedding_provider

• embedding_fallback_provider

• provider_configs

• llm_provider

• llm_fallback_provider

• llm_model

• llm_base_url

• llm_api_key

その他の設定は引き続き config.json に保存されます（例：

{
  "http_port": 8060,
  "chroma_persist_directory": "./data/chroma",
  "knowledge_base_db_path": "./data/knowledge_bases.sqlite3",
  "enable_llm_summary": false,
  "security": {
    "enabled": false,
    "allow_anonymous": true,
    "api_keys": [],
    "tenant_api_keys": {}
  },
  "rate_limit": {
    "requests_per_window": 120,
    "window_seconds": 60,
    "burst": 30
  },
  "quotas": {
    "max_upload_files": 20,
    "max_upload_bytes": 52428800,
    "max_upload_file_bytes": 10485760,
    "max_index_documents": 500,
    "max_index_chunks": 2000,
    "max_index_chars": 500000
  },
  "cache": {
    "enabled": false,
    "max_entries": 256,
    "ttl_seconds": 300
  },
  "provider_budget": {
    "enabled": true
  }
}

現在の組み込みプロバイダー関連機能：

• embeddingプロバイダーのデフォルト値は zhipu

• LLMプロバイダーのデフォルト値は doubao

• 組み込みプロバイダー設定には doubao、zhipu、aliyun が含まれます

• qwen / dashscope は aliyun に正規化されます

• /providers/{provider}/models はOpenAI互換モデルサービスからのモデルリスト取得をサポートしています

• ローカルembeddingは m3e-small および e5-small をサポートしています

• LLMは追加で ollama をサポートしています

ホットリロードとランタイム更新

ホットリロードの動作：

• /config、/config/bulk、/config/reset、/config/reload を通じて変更されると、ランタイムは即座に更新されます

• リクエスト受信時に reload_if_changed() を通じてディスク上の設定変更が検出されます

• プロバイダー設定や検索設定が変更されると、関連するランタイム依存関係が再構築され、検索キャッシュがクリアされます

Readiness（準備状況）とMetrics（メトリクス）

• /health はヘルスサマリー、ランタイムスナップショット、config_revision を返します

• /ready はブートストラップが完了していない、または重要な依存関係が準備できていない場合に 503 を返します

• /metrics は操作/プロバイダーごとに集約された観測メトリクスを返します

現在のreadinessスナップショットには以下が含まれます：

• document_processor

• embedding_model

• vector_store

• hybrid_service

• llm_model

• retrieval_cache

• provider_budget

テスト

全量テストの実行：

uv run python -m unittest discover -s tests

コンパイルチェック：

uv run python -m compileall src

現在のテスト範囲：

• 設定のデフォルト値、ディスクリロード、プロバイダー設定の移行

• HTTPシェルおよびMCPシェルの動作

• リクエストコンテキスト / テナント解決

• リクエストレベルの検索キャッシュ

• プロバイダー予算 / フォールバック

• readiness / health / metrics

• パッケージメタデータと静的リソース

ライセンス

MIT