scholar-rag-mcp

ステータス: プレビューリリース (v0.1.0)。 インターフェースとストレージレイアウトは将来のバージョンで変更される可能性があります。

scholar-rag-mcp は、公開可能な学術論文ナレッジベースMCPツールです。PDFフォルダを指定すると、実際の解析パイプライン（MinerU）を通じて各論文を取り込み、メタデータを正規化し、セクション構造を注釈し、テキストをチャンク化して埋め込み、すべてをQdrantに保存します。その後、エージェント（またはあなた）は、チャンクのセマンティック検索、PubMedスタイルのドキュメントクエリ、セクションごとの全文読み取り、個別論文の追加・削除、ナレッジベースの管理を、stdio上の11個のMCPツールを通じて行えます。埋め込み、注釈、再ランキングは、OpenAI互換のモデルサービス（vLLM）上で実行され、プロセス内フォールバックも備えています。

Features

• 実際の取り込みパイプライン: MinerU PDF解析（python/cli/apiバックエンド） -> メタデータ抽出（ローカルヒューリスティック、CrossRef、オプションのGROBID） -> クリーニング -> セクション注釈 -> 決定的チャンク化（設定可能な300/1500/100文字） -> 埋め込み。

• 大規模な高速検索: 埋め込みによる一次パス + クロスエンコーダー再ランク、Qdrantインデックス内で評価されるオプションのメタデータフィルタリング（doc_id、section、year、journal、...）。100kチャンクのp95クエリレイテンシ < 1秒（docs/perf-report.md を参照）。

• 非同期ジョブ: create_kb/add_document はバックグラウンドジョブであり、進捗は get_job で照会できます。再起動しても安全です（中断されたジョブは回復され、再実行時にスキップされます）。

• コンテキストに安全な読み取り: ハードなサイズ上限付きのページ分割された get_document_text。アウトラインを先に、ページはオンデマンドで。

• stdio上の11個のMCPツール: list_kbs、create_kb、delete_kb（2段階）、add_document、remove_document、get_document、get_document_text、list_documents、search_documents、search_chunks、get_job。

• 自己完結型ストレージ: ナレッジベースは単一のデータディレクトリ（~/.scholar-rag）の下に置かれます。Qdrantは自動起動（単一バイナリ、バージョン固定）されるか、外部インスタンスに接続されます。

Related MCP server: Athena

Installation

pixi が必要です。リポジトリのルートから:

pixi install                      # installs the default environment

このプロジェクトは3つのpixi環境を定義しており、それぞれ異なる目的を提供します:

組み込みのdoctorで環境を検証します:

pixi run python scripts/doctor.py

Model deployment

環境（'chat'、'embed'、'rerank' クライアント）は、OpenAI互換のHTTPエンドポイントを想定しています。scripts/serve_models.sh は、リファレンスモデルセット用に3つのvLLMインスタンスを起動します:

# point *_MODEL at your local model directories, then:
bash scripts/serve_models.sh

SCHOLAR_RAG_CHAT_MODEL、SCHOLAR_RAG_EMBED_MODEL、SCHOLAR_RAG_RERANK_MODEL は必須です。いずれかが未設定の場合、スクリプトはそれらを列挙したメッセージを表示して終了します。各値はローカルのHuggingFaceモデルディレクトリへの絶対パスである必要があります。vLLMは各モデルをディレクトリのベース名と等しい短い名前で提供するため、クライアント設定ではその短い名前を使用する必要があります（提供される名前はもはやフルパスと等しくありません）。.env.example 内の /path/to/... プレースホルダーをそれに応じて置き換えてください。ポート（CHAT_PORT/EMBED_PORT/RERANK_PORT）とGPU IDは、動作するデフォルト値を持つオプションのままです。

スクリプトは、これらのモデルで検証された正確なvLLMフラグを固定します（Jina埋め込みモデルはカスタムコードのため --trust-remote-code が必要です。再ランカーはデフォルトタスクで実行され、追加フラグは不要です）。モデルの読み込みには数分かかります。スクリプトは3つすべてが応答するまでヘルスチェックをポーリングします。

最小環境

.env.example から始めて、少なくともモデルエンドポイントを設定します（serveスクリプトが公開する短い名前を使用します。これは各モデルディレクトリのベース名と等しいです）:

SCHOLAR_RAG_DATA_DIR=~/.scholar-rag
SCHOLAR_RAG_QDRANT_STORAGE_DIR=~/.local/share/scholar-rag/qdrant

SCHOLAR_RAG_CHAT_BASE_URL=http://127.0.0.1:8101/v1
SCHOLAR_RAG_CHAT_MODEL=Qwen3.5-0.8B

SCHOLAR_RAG_EMBED_BASE_URL=http://127.0.0.1:8102/v1
SCHOLAR_RAG_EMBED_MODEL=jina-embeddings-v5-text-small

SCHOLAR_RAG_RERANK_BASE_URL=http://127.0.0.1:8103/v1
SCHOLAR_RAG_RERANK_MODEL=jina-reranker-v3.5

埋め込みモデルの次元は、kb作成時に kb_meta.json に記録されます。そのため、後で埋め込みモデルを変更するには新しいkbが必要です。

MCPクライアントのセットアップ

サーバーのエントリポイントを直接起動して、動作することを確認します:

pixi run scholar-rag-mcp

Claude (Claude Desktop / claude CLI)

{
  "mcpServers": {
    "scholar-rag-mcp": {
      "command": "pixi",
      "args": ["run", "scholar-rag-mcp"]
    }
  }
}

opencode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "scholar-rag-mcp": {
      "type": "local",
      "command": ["pixi", "run", "scholar-rag-mcp"]
    }
  }
}

ツール

データレイアウト

<data_dir>/                     # SCHOLAR_RAG_DATA_DIR, default ~/.scholar-rag
├── kbs/<kb_name>/
│   ├── kb_meta.json            # dimension, chunk config, schema version
│   ├── catalog.sqlite3         # documents / authors / keywords / chunks + FTS5
│   └── documents/<doc_id>/     # source.pdf, full_text.md, sections.json
├── cache/parse/                # MinerU markdown cache, keyed by content hash
├── cache/resolver/             # annotation resolver cache, keyed by content hash
├── jobs.sqlite3                # async job history
└── bin/                        # auto-downloaded Qdrant binary (v1.12.5)

Qdrantストレージは data_dir の外側、QDRANT_STORAGE_DIR（デフォルトは ~/.local/share/scholar-rag/qdrant）に置かれます。これはローカルファイルシステム上にある必要があり、9p/ネットワークマウントでは動作しません。

2段階のkb削除

delete_kb は、誤った引数による最初の呼び出しで誤って削除することはありません:

1. delete_kb(kb="...") を呼び出します - kb統計と10分間有効な confirm_token を返します。

2. delete_kb(kb="...", confirm_token="<token>") を呼び出して、Qdrantコレクション、kbディレクトリ、およびそのジョブ履歴を実際に削除します。

開発

pixi run lint          # ruff check src tests
pixi run typecheck     # mypy src
pixi run test          # pytest (unit + integration, no e2e/perf)
pixi run -e mineru pytest tests/e2e/smoke.py -v -m e2e   # real end-to-end smoke
python tests/perf/bench_query.py                          # query latency benchmark (writes docs/perf-report.md)

リリースノート

既知の制限とアップグレードの指針については、docs/handoffs/release-notes-v0.1.0.md を参照してください。

繰り返し述べる価値のある既知の制約:

• Qdrantはv1.12.5に固定されています - これはglibc 2.35で動作する最高バージョンです。自動起動時に初回使用でダウンロードされます。glibc >= 2.38では新しいバージョンを実行できますが、このリリースではデータ形式は古いkbとの前方互換性がありません。

• MinerUは独自のpixi環境で実行されます。そのtransformersバージョンがvLLMのものと相互排他的であるためです。したがって、PDF解析は pixi run -e mineru を優先します。

• MinerUのウェイト（~3.2 GB）は、最初の解析時に ~/.cache/modelscope/ にダウンロードされます。

• メタデータのタイトルヒューリスティック: タイトルは、MinerUマークダウンが #/## 見出しで始まる場合にのみローカルで取得されます。そのため、先頭の ## Abstract などがタイトルとして誤読される可能性があります。これはローカルヒューリスティックメタデータ層のみに影響します。CrossRef層（DOIが見つかった場合に使用）は通常これを修正します。

• ツールディスパッチ: ツールへの未知の追加引数は、拒否されるのではなく黙って無視されます。

• 9pストレージ制限: Qdrantストレージはローカルファイルシステム上にある必要があります。