Rag Vault

🚀 RAG Vault

あなたのドキュメント。あなたのマシン。あなたのコントロール。

RAG Vaultは、API仕様書、研究論文、社内文書などのプライベートなドキュメントにAIコーディングアシスタントが高速にアクセスできるようにします。インデックス作成と検索はローカルで実行され、明示的にリモートURLからコンテンツを取り込まない限り、データはあなたのマシン上に留まります。

1つのコマンドで実行でき、最小限のセットアップで、デフォルトでプライバシーが保護されます。

🚀 クイックスタート

初期セットアップチェックリスト

MCP設定を追加する前に以下の手順を実行してください。

1. Node.js 20以上をインストールします。
2. ドキュメントディレクトリを選択し、BASE_DIRをそのパスに設定します。
3. AIツールのプロセスがBASE_DIRを読み取れることを確認します。
4. 設定を編集した後、AIツールを再起動します。

各ツールでの使用方法

Cursorの場合

~/.cursor/mcp.jsonに以下を追加します。

{
  "mcpServers": {
    "local-rag": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:RobThePCGuy/rag-vault"],
      "env": {
        "BASE_DIR": "/path/to/your/documents"
      }
    }
  }
}

/path/to/your/documentsを実際の絶対パスに置き換えてください。

Claude Codeの場合

プロジェクトディレクトリの.mcp.jsonに以下を追加します。

{
  "mcpServers": {
    "local-rag": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:RobThePCGuy/rag-vault"],
      "env": {
        "BASE_DIR": "./documents",
        "DB_PATH": "./documents/.rag-db",
        "CACHE_DIR": "./.cache",
        "RAG_EMBEDDING_DEVICE": "cpu",
        "RAG_HYBRID_WEIGHT": "0.6",
        "RAG_GROUPING": "related"
      }
    }
  }
}

または、CLIを介してインラインで追加します。

claude mcp add local-rag --scope user --env BASE_DIR=/path/to/your/documents -- npx -y github:RobThePCGuy/rag-vault

Codexの場合

~/.codex/config.tomlに以下を追加します。

[mcp_servers.local-rag]
command = "npx"
args = ["-y", "github:RobThePCGuy/rag-vault"]

[mcp_servers.local-rag.env]
BASE_DIR = "/path/to/your/documents"

スキルのインストール（オプション）

クエリの作成や結果の解釈に関するAIガイダンスを強化するために、RAG Vaultのスキルをインストールします。

# Claude Code（プロジェクトレベル - チームプロジェクトでおすすめ）
npx github:RobThePCGuy/rag-vault skills install --claude-code

# Claude Code（ユーザーレベル - すべてのプロジェクトで利用可能）
npx github:RobThePCGuy/rag-vault skills install --claude-code --global

# Codex（ユーザーレベル）
npx github:RobThePCGuy/rag-vault skills install --codex

# カスタム場所
npx github:RobThePCGuy/rag-vault skills install --path /your/custom/path

スキルはClaudeに以下のベストプラクティスを教えます。

• クエリの作成と拡張戦略
• スコアの解釈（< 0.3 = 適切なマッチ、> 0.5 = スキップ）
• ingest_fileとingest_dataの使い分け
• HTMLの取り込みとURLの処理

AIツールを再起動して会話を始めましょう。

You: "Ingest api-spec.pdf"
AI:  Successfully ingested api-spec.pdf (47 chunks)

You: "How does authentication work?"
AI:  Based on section 3.2, authentication uses OAuth 2.0 with JWT tokens...

これで完了です。DockerやPython、サーバーインフラストラクチャの管理は必要ありません。

✨ 主な機能

RAG Vaultを選ぶ理由

セキュリティ

RAG Vaultには、本番環境でのデプロイに必要なセキュリティ機能が含まれています。

• API認証：RAG_API_KEYを介したオプションのAPIキー
• レート制限：設定可能なリクエストスロットリング
• CORS制御：許可されたオリジンの制限
• セキュリティヘッダー：Helmet.jsによる保護

詳細なドキュメントはSECURITY.mdを参照してください。

📦 インストール

コマンドによるインストール

npx github:RobThePCGuy/rag-vault

💻 使用例

コードベースのドキュメントを検索する

You: "Ingest all the markdown files in /docs"
AI:  Ingested 23 files (847 chunks total)

You: "What's the retry policy for failed API calls?"
AI:  According to error-handling.md, failed requests retry 3 times
     with exponential backoff: 1s, 2s, 4s...

Webドキュメントをインデックスする

You: "Fetch https://docs.example.com/api and ingest the HTML"
AI:  Ingested "docs.example.com/api" (156 chunks)

You: "What rate limits apply to the /users endpoint?"
AI:  The API limits /users to 100 requests per minute per API key...

個人の知識ベースを構築する

You: "Ingest my research papers folder"
AI:  Ingested 12 PDFs (2,341 chunks)

You: "What do recent studies say about transformer attention mechanisms?"
AI:  Based on attention-mechanisms-2024.pdf, the key finding is...

正確な技術用語を検索する

RAG Vaultのハイブリッド検索は、意味と正確なマッチの両方を捕捉します。

You: "Search for ERR_CONNECTION_REFUSED"
AI:  Found 3 results mentioning ERR_CONNECTION_REFUSED:
     1. troubleshooting.md - "When you see ERR_CONNECTION_REFUSED..."
     2. network-errors.pdf - "Common causes include..."

純粋な意味検索ではこれを見逃しますが、RAG Vaultは見つけます。

📚 詳細ドキュメント

ウェブインターフェイス

RAG Vaultには、コマンドラインを使用せずにドキュメントを管理するためのフル機能のウェブUIが含まれています。

ウェブUIを起動する

npx github:RobThePCGuy/rag-vault web

ブラウザでhttp://localhost:3000を開きます。

できること

• ドキュメントをアップロードする：PDF、DOCX、Markdown、TXT、JSON、JSONL、NDJSONファイルをドラッグアンドドロップでアップロードできます。
• 即座に検索する：クエリを入力し、関連性スコア付きの結果を表示します。
• コンテンツをプレビューする：任意の結果をクリックして、コンテキスト内の完全なチャンクを表示します。
• ファイルを管理する：すべてのインデックス化されたドキュメントを表示し、不要なものを削除できます。
• データベースを切り替える：複数の知識ベースを作成して切り替えることができます。
• ステータスを監視する：ドキュメント数、メモリ使用量、検索モードを確認できます。
• 設定をエクスポート/インポートする：ボールトの設定をバックアップして復元できます。
• テーマ設定：ライト、ダーク、またはシステムテーマを切り替えることができます。
• フォルダブラウザ：ディレクトリをナビゲートしてドキュメントを選択できます。

REST API

ウェブサーバーは、プログラムからアクセスするためのREST APIを公開しています。認証を要求するにはRAG_API_KEYを設定します。

# 認証付き（RAG_API_KEYが設定されている場合）
curl -X POST "http://localhost:3000/api/v1/search" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication", "limit": 5}'

# ドキュメントを検索する（RAG_API_KEYが設定されていない場合は認証不要）
curl -X POST "http://localhost:3000/api/v1/search" \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication", "limit": 5}'

# すべてのファイルをリストする
curl "http://localhost:3000/api/v1/files"

# ドキュメントをアップロードする
curl -X POST "http://localhost:3000/api/v1/files/upload" \
  -F "file=@spec.pdf"

# ファイルを削除する
curl -X DELETE "http://localhost:3000/api/v1/files" \
  -H "Content-Type: application/json" \
  -d '{"filePath": "/path/to/spec.pdf"}'

# システムステータスを取得する
curl "http://localhost:3000/api/v1/status"

# ヘルスチェック（ロードバランサー用）
curl "http://localhost:3000/api/v1/health"

リーダーAPIエンドポイント

プログラムからのドキュメント読み取りとクロスドキュメント検索のためのエンドポイントです。

# ドキュメントのすべてのチャンクを取得する（インデックス順）
curl "http://localhost:3000/api/v1/documents/chunks?filePath=/path/to/doc.pdf"

# クロスドキュメント検索のための関連チャンクを見つける
curl "http://localhost:3000/api/v1/chunks/related?filePath=/path/to/doc.pdf&chunkIndex=0&limit=5"

# 複数のチャンクのバッチリクエスト（UIに効率的）
curl -X POST "http://localhost:3000/api/v1/chunks/batch-related" \
  -H "Content-Type: application/json" \
  -d '{"chunks": [{"filePath": "/path/to/doc.pdf", "chunkIndex": 0}], "limit": 3}'

リモートモード

RAG Vaultは、Claude.ai、Claude DesktopなどのリモートMCPクライアントや、Streamable HTTPまたはSSEトランスポートをサポートする任意のクライアント向けにHTTPサーバーとしても実行できます。

# リモートサーバーを起動する（デフォルトポート3001）
npx github:RobThePCGuy/rag-vault --remote

# カスタムポート
npx github:RobThePCGuy/rag-vault --remote --port 8080

Stdioモードは変更されません。--remoteを省略すると、Cursor、Claude Code、Codexで以前と同じように動作します。

Claude Desktopから接続する

Claude Desktopの設定に以下を追加します。

{
  "mcpServers": {
    "rag-vault-remote": {
      "type": "url",
      "url": "http://localhost:3001/mcp"
    }
  }
}

またはClaude Code CLIを介して追加します。

claude mcp add --transport http rag-vault http://localhost:3001/mcp

Claude.aiから接続する

Claude.ai（Pro/Max/Team/Enterprise）の場合は、URL https://your-host:3001/mcpでカスタムコネクタとして追加します。ローカル開発の場合は、トンネルを使用してサーバーを公開します。

cloudflared tunnel --url http://localhost:3001

リモートで公開する場合は、認証のためにRAG_API_KEYを設定します。サーバーはStreamable HTTP (/mcp) とレガシーSSE (/sse) の両方のトランスポートをサポートし、/healthでヘルスチェックができます。

🔧 技術詳細

動作原理

Document → Parse → Chunk by meaning → Embed locally → Store in LanceDB
                         ↓
Query → Embed → Vector search → Keyword boost → Quality filter → Results

• スマートチャンキング：文字数ではなく意味で分割します。コードブロックはそのまま保持されます。
• ハイブリッド検索：ベクトル類似度で関連コンテンツを見つけ、キーワードブーストで正確なマッチを上位にランク付けします。
• 品質フィルタリング：任意のトップKカットオフではなく、関連性のギャップで結果をグループ化します。
• デフォルトでローカル：Transformers.jsを介した埋め込み、LanceDBを介したストレージ。ネットワークは初期のモデルダウンロードまたは明示的にリモートURLを取り込む場合にのみ必要です。
• MCPツール付属：query_documents, ingest_file, ingest_data, delete_file, list_files, status, feedback_pin, feedback_dismiss, feedback_stats

サポートされる形式

設定

環境変数

Windowsユーザー: RAG_EMBEDDING_DEVICE=autoはGPUプロバイダー（DirectML）を試みますが、ONNX Runtime GPUバイナリが利用可能でない場合に失敗することがあります。埋め込みの初期化エラーが表示された場合は、MCP設定でRAG_EMBEDDING_DEVICE=cpuを設定して安定した動作を確保してください。詳細は「よくある質問」の「GPUアクセラレーションについては？」を参照してください。

1つのコマンドで上書きすることができます（.envを編集する必要はありません）。

# MCPモード
npx github:RobThePCGuy/rag-vault --embedding-device cpu

# ウェブモード
npx github:RobThePCGuy/rag-vault web --embedding-device dml

# 明示的に自動検出を強制する
npx github:RobThePCGuy/rag-vault --gpu-auto

検索の微調整

セキュリティ（オプション）

高度な設定

をコピーして、完全な設定テンプレートを取得してください。

コード主体のコンテンツの場合、以下の設定を試してみてください。

"env": {
  "RAG_HYBRID_WEIGHT": "0.8",
  "RAG_GROUPING": "similar"
}

よくある質問

"env": {
  "RAG_EMBEDDING_DEVICE": "cpu"
}

"MODEL_NAME": "onnx-community/embeddinggemma-300m-ONNX"

トラブルシューティング

開発

git clone https://github.com/RobThePCGuy/rag-vault.git
cd rag-vault
pnpm install
pnpm --prefix web-ui install

# ローカルのgitフックをインストールする（推奨、単独開発でも）
pnpm hooks:install

# 高速なローカル品質ゲート（バックエンド + ウェブUIの型チェック/リント/フォーマット、依存関係、未使用コード、ビルド、単体テスト）
pnpm check:all

# 単体テストのみ（モデルダウンロード不要）
pnpm test:unit

# 統合/E2Eテスト（モデルダウンロード/ネットワークが必要）
pnpm test:integration

# ビルド
pnpm build

# ローカルでMCPサーバーを実行する（stdio）
pnpm dev

# ローカルでMCPサーバーを実行する（リモートHTTP + SSE）
pnpm dev:remote

# ローカルでウェブサーバーを実行する
pnpm web:dev

# npmにリリースする（ローカル、保護付き）
pnpm release          # patch
pnpm release:minor
pnpm release:major
pnpm release:dry

テストのレベル

• pnpm test:unit: モデルダウンロードの統合パスを除く、ローカル/CIの品質チェック用の決定的なテスト。
• pnpm test:integration: 埋め込みモデルの初期化を含む、完全な統合およびE2Eワークフロー。

RUN_EMBEDDING_INTEGRATION=1を使用して、ネットワーク/モデルに依存するテストスイートを明示的に選択できます。

リリース戦略

• リリースはscripts/release-npm.shを介してローカルでスクリプト化されています。
• サポートされるバンプ: patch, minor, major。
• スクリプトは、依存関係のインストール、pnpm check:all、pnpm ui:buildを実行してから、バージョンファイルに触れます。
• package.jsonとserver.jsonのバージョンは、チェックが通過した後にのみ更新され、後続のステップで失敗した場合は自動的に復元されます。
• pnpm release:dryは完全なゲートとnpmのドライラン公開を実行し、常にバージョンファイルを復元します。

プロジェクト構造

src/
├── bin/             # CLIサブコマンド（skills install）
├── chunker/         # 意味に基づくテキスト分割
├── embedder/        # Transformers.jsラッパー
├── errors/          # エラー処理ユーティリティ
├── explainability/  # キーワードベースの結果説明
├── flywheel/        # フィードバックループ（ピン留め/却下の再ランキング）
├── parser/          # PDF、DOCX、HTMLの解析
├── query/           # 高度なクエリ構文解析器
├── server/          # MCPツールハンドラー + リモートトランスポート
├── utils/           # 設定、ファイルヘルパー、プロセスハンドラー
├── vectordb/        # LanceDB + ハイブリッド検索
└── web/             # Expressサーバー + REST API

web-ui/              # Reactフロントエンド（Vite + Tailwind）

📄 ライセンス

MITライセンス: 個人および商用利用に無料です。

謝辞

Model Context Protocol、LanceDB、Transformers.jsを使用して構築されています。

Shinsuke Kagawaによるmcp-local-ragのフォークから始まりました。現在は独自のプロジェクトになっています。 基礎を提供してくれた上流の貢献者に大きな感謝を表します。私はそこから精力的に開発を続けています。 常にローカルファーストの開発ツールを目指しています。