Modular RAG MCP Server

DIY留学サービスチームの内部コンサルタント向けの留学申請知識検索・可観測RAG基盤

Modular RAG MCP Serverは、ローカル優先・プラグイン可能・可観測な検索拡張生成（RAG）サービスです。本システムはModel Context Protocol（MCP）を通じてAIクライアントに知識検索機能を提供し、Streamlit Dashboardでドキュメント、取り込みタスク、クエリチェーン、評価結果を管理します。

本プロジェクトは大学在学中の実際の協働シナリオに由来します。学部内のDIY留学サービスチームが学生に海外大学出願支援を提供しており、本システムはコンサルタントが大学要件、出願書類、プロセス規範、過去の経験の間で繰り返し検索し、出典を追跡することが難しい問題を解決するために開発されました。現在、システムはチーム内で本番デプロイ済みです。公開リポジトリには匿名化された合成サンプルのみが含まれ、実際の学生データ、内部ドキュメント、実行データは含まれません。

リポジトリ内のサンプル資料はすべて匿名化された合成データを使用する必要があります。システム出力はコンサルタントが検証するための検索根拠であり、コンサルタントの判断を代替するものではなく、大学、ビザ、法的アドバイスを構成するものでもありません。

目次

• ビジネス背景

• システム境界

• コア機能

• システムアーキテクチャ

• データとストレージの一貫性

• MCP Tools

• Dashboard

• クイックスタート

• 品質保証

• セキュリティと運用上の制約

• 現在の状態と進化計画

Related MCP server: Modular RAG MCP Server

ビジネス背景

DIY留学コンサルタントは出願処理時に、大学公式サイトの説明、プログラムハンドブック、資料テンプレート、内部操作チェックリスト、過去のケースを同時に参照する必要があります。元の資料は通常PDF形式で分散保存されており、以下の問題があります：

• 同じ要件が複数の資料に異なる表現で記載されている場合があり、純粋なキーワード検索ではリコール漏れが発生しやすい。

• 大学、専攻、学位、入学シーズンなどの固有名詞は正確なマッチングが必要であり、ベクトル検索のみでは誤リコールが発生しやすい。

• PDF内の表、フローチャート、スクリーンショットには重要な情報が含まれており、テキストのみの解析ではコンテキストが失われる。

• コンサルタントは回答がどの資料のどの断片から来ているかを知り、資料がまだ有効かどうかを判断する必要がある。

• ドキュメント更新後、ベクトルDB、BM25インデックス、画像インデックス、取り込み記録の一貫性を維持する必要がある。

• 検索効果は安定したテストセットによる回帰評価が必要であり、主観的な体験に依存すべきではない。

システムのサービス対象はチーム内コンサルタントです。典型的なワークフローは以下の通りです：

1. 大学プログラム資料、内部チェックリスト、匿名化ケースを指定のCollectionに取り込む。

2. MCP Clientまたはコマンドラインで自然言語の質問を送信する。

3. システムがDense + BM25のデュアルパスリコール、RRFフュージョン、オプションのRerankを実行する。

4. 出典引用付きのテキスト断片を返し、画像がヒットした場合はマルチモーダルコンテンツブロックを返す。

5. Dashboardで取り込みプロセス、リコール結果、レイテンシ、評価指標を確認する。

システム境界

本プロジェクトは知識の取り込み、検索、引用、評価、チェーン観測を担当し、以下は担当しません：

• コンサルタントに代わって出願校選定、合格確率、ビザの結論を下すこと。

• 出願の自動提出、メール送信、学生資料の修正。

• 学生向けアカウント、CRM、決済、出願進捗管理の提供。

• 最新の大学方針を自動取得して把握していると主張すること。

• 出典の裏付けがない場合に確定的な業務結論を生成すること。

コア機能

システムアーキテクチャ

flowchart LR
    A["PDF 业务资料"] --> B["Ingestion Pipeline"]
    B --> C["Chroma 向量库"]
    B --> D["BM25 索引"]
    B --> E["SQLite 摄取历史"]
    B --> F["图片文件与索引"]
    G["顾问 / MCP Client"] --> H["MCP Server"]
    H --> I["Query Processor"]
    I --> J["Dense Retrieval"]
    I --> K["Sparse Retrieval"]
    J --> L["RRF Fusion"]
    K --> L
    L --> M["Optional Rerank"]
    M --> N["Response + Citations + Images"]
    B --> O["Ingestion Trace"]
    I --> P["Query Trace"]
    O --> Q["Streamlit Dashboard"]
    P --> Q

コアディレクトリ：

src/
├── core/            # 数据契约、查询编排、响应构建、Trace、配置
├── ingestion/       # Chunk、Transform、Embedding、Storage 与 Pipeline
├── libs/            # LLM/Embedding/Loader/Reranker/Splitter/VectorStore 抽象
├── mcp_server/      # MCP 协议处理、Server 与 Tools
└── observability/   # Dashboard、评估与结构化日志

scripts/             # ingest、query、evaluate、Dashboard 启动入口
config/              # Provider、检索、重排、评估与摄取配置
tests/               # Unit、Integration、E2E 测试与固定样例

詳細なインターフェース、データフロー、モジュール制約については DEV_SPEC.md を参照してください。

データとストレージの一貫性

1回の取り込みで複数のストレージバックエンドを調整します：

ファイル整合性チェックではSHA256を使用して、正常に処理済みで変更のないファイルをスキップします。Chunk IDはソース、位置、コンテンツから安定して生成され、重複取り込みは冪等Upsertを採用します。DocumentManagerはChroma、BM25、取り込み履歴、画像インデックスにわたる調整済み削除を担当し、部分的な失敗情報を返します。

MCP Tools

現在のServerは4つのToolsを公開しています。最初の3つの汎用Toolはそのまま保持され、4つ目は留学ビジネス適応レイヤーです：

MCPはStdio Transportを使用します。stdoutはJSON-RPC専用で、実行ログはstderrに書き込まれ、プロトコルフレームを破壊しません。

search_admissions_knowledgeはデフォルトでadmissions_knowledgeをクエリし、常にbusiness_domain=study_abroad_admissionsに限定されます。国、大学、プログラム、学位レベル、入学シーズン、出願ラウンド、ソースタイプによる正確なフィルタリングをサポートします。デフォルトでは、クエリ業務日付より前にvalid_untilが到来した資料を除外します。有効期限が欠落している、または解析できない資料はneeds_reviewとしてマークされ、黙示的に現行ルールとして扱われません。ビジネスToolはパラメータとレスポンスの適応レイヤーに過ぎず、基盤では引き続きDense + BM25、RRF、Cross-Encoder/LLM Rerank、引用、マルチモーダル返却を実行します。

Dashboard

Dashboardは6ページ構成を維持します：

1. Overview：コンポーネント設定、データ資産、実行状態、および留学資料の現行・要レビュー・期限切れ統計。

2. Data Browser：ドキュメント、Chunk、Metadata、関連画像。国、大学、プログラム、学位、入学シーズン、出願ラウンド、ソースタイプ、有効期限状態の組み合わせフィルタをサポート。

3. Ingestion Manager：取り込みのトリガー、進捗確認、ドキュメントの調整済み削除。

4. Ingestion Traces：取り込み段階、処理方法、レイテンシ、例外。

5. Query Traces：Dense/Sparseリコール、フュージョン、リランキング、最終結果。

6. Evaluation Panel：評価の実行と指標・履歴結果の確認。

クイックスタート

1. 環境準備

要件：Python 3.10–3.12。

git clone https://github.com/xiaoxinbuxingyeyuan/MODULAR-RAG-MCP-SERVER.git
cd MODULAR-RAG-MCP-SERVER
python -m venv .venv

Windows PowerShell：

.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

macOS / Linux：

source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

pyproject.toml は本プロジェクトで現在検証済みの直接依存関係のバージョンを固定しています。MCP、Ragas、LangChain、ストレージコンポーネントをアップグレードする場合は、個別にアップグレードし、オフラインとオンラインの回帰テストを再実行してください。

2. Providerの設定

config/settings.yaml を編集し、LLM、Embedding、Vision LLM、VectorStore、Reranker、評価バックエンドを設定します。API Keyは安全な設定注入を通じて提供し、リポジトリにコミットしないでください。

ローカルにモデルサービスがない場合は、不要なLLM拡張とRerankを無効化し、外部サービスに依存しない基本チェーンを検証できます。

3. ドキュメントの取り込み

python scripts/ingest.py \
  --path tests/fixtures/sample_documents/simple.pdf \
  --collection admissions_knowledge

ディレクトリ取り込み：

python scripts/ingest.py \
  --path tests/fixtures/sample_documents/ \
  --collection admissions_knowledge

留学ビジネスManifestを使用した取り込み：

python scripts/ingest.py \
  --path examples/documents/synthetic/ \
  --collection admissions_knowledge \
  --manifest examples/admissions_manifest.example.jsonl

ManifestはUTF-8 JSONLを使用し、各行が1つのPDFに対応します。相対document_pathはManifestが置かれているディレクトリを基準に解決されます。必須フィールドはdocument_path、title、country、source_typeです。オプションフィールドにはinstitution、program、degree_level、intake、application_round、published_at、valid_until、language、tags、access_scopeが含まれます。完全な例は examples/admissions_manifest.example.jsonl を参照してください。

Manifestを渡すと、取り込む各PDFに一意のマッチングが必要です。未知のフィールド、重複パス、不正な列挙値、日付の逆転は、ストレージへの書き込み前に失敗します。ManifestメタデータはDocumentからChunkとChromaレコードに伝播します。ChunkレベルのLLMタイトルとタグはdocument_titleとbusiness_tagsを上書きしません。

インクリメンタル判断では、PDF SHA256と正規化されたビジネスメタデータSHA256を同時に比較します。両方が変更されていない場合のみスキップします。Manifestのみを変更した場合は、自動的に再取り込みされ、安定したChunk IDに対応するメタデータが上書きされます。PDFコンテンツが変更された場合、システムはまず新しいバージョンを書き込み、その後古いdoc_hashに基づいてChroma Chunk、画像、古い取り込みレコードをクリーンアップします。BM25は安定したソースパスプレフィックスに基づいてpostingsを置換します。旧バージョンのSQLite取り込み履歴には自動的にmetadata_hashフィールドが追加され、手動マイグレーションは不要です。--forceは明示的な再構築に引き続き使用できますが、Manifest更新の適用には必須ではなくなりました。

リポジトリには、完全に架空で個人情報を含まない3つのビジネスサンプルが提供されており、現行資料、有効期限欠落、期限切れ資料をそれぞれカバーしています。コースガイドにはマルチモーダルチェーン検証用のフローチャートが1枚含まれています。サンプルPDFを再生成する必要がある場合は以下を実行します：

python examples/generate_synthetic_admissions_pdfs.py

4. コマンドラインクエリ

python scripts/query.py \
  --query "申请材料需要包含哪些证明？" \
  --collection admissions_knowledge \
  --verbose

5. Dashboardの起動

python scripts/start_dashboard.py

デフォルトアドレスは http://localhost:8501 です。

6. MCP Serverの起動

python -m src.mcp_server.server

MCP Clientによって設定形式は若干異なりますが、コアプロセス設定は以下の通りです：

{
  "command": "<project>/.venv/Scripts/python.exe",
  "args": ["-m", "src.mcp_server.server"],
  "cwd": "<project>"
}

macOS / LinuxではPythonパスを <project>/.venv/bin/python に置き換えます。

7. 評価の実行

python scripts/evaluate.py \
  --test-set examples/admissions_golden_test_set.json \
  --collection admissions_knowledge

外部検索環境がない場合は以下を実行できます：

python scripts/evaluate.py --no-search

品質保証

プロジェクトは3層のテスト構造を採用しています：

• Unit：データ契約、アルゴリズム、Factory、Tool Handler、ストレージアダプター。

• Integration：取り込み、ハイブリッド検索、MCP、Provider、Traceの組み合わせ動作。

• E2E：CLI取り込み、MCP Client、Dashboard smoke、Recall回帰。

python -m pytest tests/unit
python -m pytest tests/integration
python -m pytest tests/e2e
python -m pytest

上記のコマンドはデフォルトでonlineとマークされたすべてのテストケースをスキップし、実際のProviderを積極的に呼び出しません。実際のAzure、OpenAI、Ollamaサービスが必要な場合は、対応する認証情報とサービスが利用可能な環境で明示的に実行します：

python -m pytest --run-online -m online

OpenAI互換ゲートウェイはOPENAI_API_KEY、OPENAI_BASE_URL、OPENAI_MODELを通じて注入でき、リポジトリ設定の変更や認証情報のコミットは不要です。設定されていないProviderのテストケースはスキップ状態を維持する必要があります。

オンラインケースが正しく分類されているかどうかのみを確認し、呼び出しを発行しない場合は、python -m pytest --collect-only -m online を実行できます。オフラインとオンラインの結果は分けて記録する必要があります。--run-onlineはスキップ制限の解除のみを行い、Provider設定を代替しません。

評価レイヤーは引き続きCustom EvaluatorとRagasをサポートします。ビジネスGolden Test Setには、組み合わせフィルタ、業務日付、期限切れポリシー、期待ソース、参照回答が追加で記録されます。オフライン業務受け入れテストでは、これらのフィールドとMCPビジネスアダプターの有効期限動作の両方をチェックします。汎用評価インターフェースと既存のGolden Test Setは変更されていません。

セキュリティと運用上の制約

• デフォルトではローカルStdioとローカルストレージを使用し、ネットワークポートを開放しません。

• ログ、Trace、テスト固定データ、Git履歴にAPI Keyと学生の個人情報を保存しません。

• ビジネス資料はナレッジベースに入る前に、承認確認とプライバシー匿名化を完了する必要があります。

• 検索結果はソース引用を保持する必要があり、信頼できる根拠が見つからない場合は空の結果を返すか、手動検証を促す必要があります。

• 大学要件には有効期限があります。ビジネスToolはデフォルトでvalid_untilが過ぎた資料を除外し、有効期限欠落項目を明示的に通知しますが、コンサルタントは公式ソースを照合する必要があります。

• 現在のアーキテクチャはシングルユーザーのローカルサービスであり、認証、権限分離、マルチテナント保証は提供しません。

現在の状態と進化計画

既存のmainは完全な汎用RAG、MCP、Dashboard、Trace、評価の骨格を備えています。留学ドメインの改修はインクリメンタル方式で進められ、既存の技術能力を削除または簡略化することはできません。

どの段階の実装でも、PDF全チェーン取り込み、Dense + BM25、RRF、Rerank、マルチモーダル、マルチストレージ連携、インクリメンタルと削除、元の3つのMCP Tools、6ページDashboard、デュアルチェーンTrace、Custom + Ragas、3層テスト、すべてのプラグイン可能インターフェースを保持する必要があります。