Rag Starter

rag-starter — ドキュメントとチャットする（RAG）、出典付き

ドキュメントのフォルダーを出典付きの Q&A サービスに変える、本番環境ですぐに使えるスターターです。PDF、Markdown、テキストを追加して質問すると、情報源に基づいた回答が得られます。すべての主張について、元になった正確な箇所を確認できます。

1 つのコードベースから、次の 2 つの方法で利用できます。

• MCP サーバー — Claude Desktop、Claude Code、その他の MCP ホストに接続して、ドキュメントとチャットできます。
• HTTP API（FastAPI）— あらゆるアプリから呼び出せます。

一度構築し、クライアントごとに外観を変更します。data/ フォルダーを差し替え、config.py を調整して、デプロイします。

他と異なる点

• デフォルトでキー不要。 埋め込みはローカル（ONNX MiniLM）で実行されるため、API キーもクエリごとのコストも不要で、オフラインでも動作します。どこでも数秒でデモできます。
• 幻覚ではなく、出典を提示。 検索結果として、[source#chunk]／[file.pdf p3] のタグが付いた関連箇所がランキング順に返されます。回答が見つからない場合は 「ドキュメント内に見つかりません」 と返し、決して捏造しません。
• 回答の生成は任意。 ANTHROPIC_API_KEY を設定すると、出典付きの回答を生成します。設定しない場合は、ホスト側の LLM が回答できるように該当箇所を返します。どちらの場合も RAG は動作します。
• 冪等な取り込み。 ファイルを再取り込みすると、重複を作らずにその場で更新します。

クイックスタート

pip install -r requirements.txt          # or: pip install -e .
PYTHONUTF8=1 python tests/test_smoke.py   # proves retrieval works on the sample docs

HTTP API として

rag-starter-api            # uvicorn on 127.0.0.1:8000
# then:
curl -X POST localhost:8000/ingest  -H "content-type: application/json" -d '{"path":"./data"}'
curl -X POST localhost:8000/search  -H "content-type: application/json" -d '{"query":"refund policy"}'
curl -X POST localhost:8000/answer  -H "content-type: application/json" -d '{"query":"how long is the refund window?"}'

MCP サーバーとして（Claude Desktop）

claude_desktop_config.json の mcpServers に追加します：

{
  "rag-starter": {
    "command": "python",
    "args": ["-m", "rag_starter"],
    "cwd": "C:/path/to/rag-starter"
  }
}

Claude Desktop を再起動し、続けて「フォルダー ./data を取り込んで」と入力し、その後「返金ポリシーは何ですか？」と尋ねます。

ツール／エンドポイント

MCP ツール	HTTP	用途
rag_ingest(path)	POST /ingest	ファイルまたはフォルダー（txt/md/pdf）のインデックスを作成します。
rag_search(query, k)	POST /search	上位 k 件の出典付き箇所を返します（キー不要）。
rag_answer(query, k)	POST /answer	出典付きの回答（キーあり）、または該当箇所（キーなし）を返します。
—	GET /health	稼働状態、インデックス済みチャンク数、埋め込みバックエンドを返します。

設定

設定はすべて config.py（または環境変数／.env。.env.example を参照）にあります。チャンクサイズとオーバーラップ、top-k、埋め込みバックエンド（default のローカルまたは openai）、回答モデルを設定できます。クライアント向けに外観を変更する場合、通常は data/ を差し替え、RAG_COLLECTION を設定して、再取り込みするだけです。

アーキテクチャ

documents ──ingest.py──> chunks(+citations) ──store.py──> Chroma (local, persistent)
                                                              │
question ─────────────────retrieve.py──> top-k cited passages┤
                                                              ├─> rag_search  (host LLM answers)
                                                  answer.py ──┴─> rag_answer  (server synthesizes, optional)

mcp-factory の契約（Result、formatting、cache）を再利用するため、カタログの他の要素と組み合わせられます。

ライセンス

MIT。