DevRag - Lightweight Local RAG MCP Server

DevRag

Claude Code 向けの無料ローカル RAG - トークンと時間を節約

日本語版はこちら | 日本語版

DevRag は、Claude Code を使用する開発者向けに特化して設計された軽量な RAG（検索拡張生成）システムです。ドキュメント全体を読み込んでトークンを浪費するのはやめましょう。ベクトル検索で必要な情報だけを見つけられます。

DevRag を選ぶ理由

Claude Code で Read ツールを使ってドキュメントを読むと、大量のトークンを消費します。

• ❌ コンテキストの浪費：毎回ドキュメント全体を読む（ファイルあたり 3,000 トークン以上）
• ❌ 検索性の低さ：Claude は、どのファイルに何が含まれているか把握していません
• ❌ 繰り返し：セッションをまたいで同じドキュメントを何度も読み込む

DevRag を使えば：

• ✅ トークンを 40 分の 1 に削減：ベクトル検索で関連するチャンクのみを取得（約 200 トークン）
• ✅ 15 倍高速：30 秒かけて読む代わりに、100 ミリ秒で検索
• ✅ 自動検出：Claude Code がファイル名を知らなくてもドキュメントを見つけます

機能

• 🤖 シンプルな RAG - Claude Code 向けの検索拡張生成
• 📝 Markdown 対応 - .md ファイルを自動でインデックス化
• 🔍 セマンティック検索 - 「JWT 認証方式」のような自然言語でのクエリ
• 🚀 単一バイナリ - Python は不要で、モデルは初回実行時に自動ダウンロード
• 💻 CLI と MCP - MCP サーバーまたは単独の CLI コマンドとして利用可能
• 🖥️ クロスプラットフォーム - macOS / Linux / Windows
• ⚡ 高速 - GPU/CPU を自動検出し、差分同期に対応
• 🌐 多言語対応 - 日本語や英語を含む 100 以上の言語に対応

クイックスタート

1. バイナリをダウンロード

リリースから適切なバイナリを入手します。

プラットフォーム	ファイル
macOS（Apple Silicon）	devrag-macos-apple-silicon.tar.gz
macOS（Intel）	devrag-macos-intel.tar.gz
Linux（x64）	devrag-linux-x64.tar.gz
Linux（ARM64）	devrag-linux-arm64.tar.gz
Windows（x64）	devrag-windows-x64.zip

macOS/Linux：

tar -xzf devrag-*.tar.gz
chmod +x devrag-*
sudo mv devrag-* /usr/local/bin/

注：macOS リリースには、CoreML による GPU アクセラレーション用の libonnxruntime.dylib が含まれています。devrag バイナリと同じディレクトリに配置してください。

Windows：

• zip ファイルを展開します
• 任意の場所に配置します（例：C:\Program Files\devrag\）

2. Claude Code を設定

~/.claude.json または .mcp.json に追加します。

{
  "mcpServers": {
    "devrag": {
      "type": "stdio",
      "command": "/usr/local/bin/devrag"
    }
  }
}

カスタム設定ファイルを使用する場合：

{
  "mcpServers": {
    "devrag": {
      "type": "stdio",
      "command": "/usr/local/bin/devrag",
      "args": ["--config", "/path/to/custom-config.json"]
    }
  }
}

3. ドキュメントを追加

mkdir documents
cp your-notes.md documents/

これで完了です。起動時にドキュメントが自動でインデックス化されます。

4. Claude Code で検索

Claude Code で：

"Search for JWT authentication methods"

設定

config.json を作成します。

{
  "document_patterns": [
    "./documents",
    "./notes/**/*.md",
    "./projects/backend/**/*.md"
  ],
  "db_path": "./vectors.db",
  "chunk_size": 500,
  "search_top_k": 5,
  "compute": {
    "device": "auto",
    "fallback_to_cpu": true
  },
  "model": {
    "name": "multilingual-e5-small",
    "dimensions": 384
  }
}

設定オプション

• document_patterns：ドキュメントのパスと glob パターンの配列
  • ディレクトリパスに対応："./documents"
  • glob パターンに対応："./docs/**/*.md"（再帰的）
  • 複数のパターン：異なる場所にあるファイルをインデックス化
  • 注：以前の documents_dir フィールドも引き続き使用できます（自動的に移行されます）
• db_path：ベクトルデータベースのファイルパス
• chunk_size：ドキュメントのチャンクサイズ（文字数）
• search_top_k：返す検索結果の数
• compute.device：計算デバイス（auto、cpu、gpu）
• compute.fallback_to_cpu：GPU を利用できない場合に CPU にフォールバックするかどうか
• model.name：埋め込みモデル名
• model.dimensions：ベクトルの次元数

コマンドラインオプション

• --config <path>：カスタム設定ファイルのパスを指定します（デフォルト：config.json）

例：

devrag --config /path/to/custom-config.json

次のような場合に便利です。

• 異なる設定で複数のインスタンスを実行する
• 異なるモデルやチャンクサイズをテストする
• dev/test/prod の設定を個別に管理する

パターンの例

{
  "document_patterns": [
    "./documents",                    // All .md files in documents/
    "./notes/**/*.md",                // Recursive search in notes/
    "./projects/*/docs/*.md",         // docs/ in each project
    "/path/to/external/docs"          // Absolute path
  ]
}

MCP ツール

DevRag は、Model Context Protocol を通じて以下のツールを提供します。

search

オプションのフィルタリングを使用して、セマンティックベクトル検索を実行します

パラメーター：

• query（文字列、必須）：自然言語での検索クエリ
• top_k（数値、任意）：結果の最大件数（デフォルト：5）
• directory（文字列、任意）：特定のディレクトリに絞り込みます（例：「docs/api」）
• file_pattern（文字列、任意）：ファイル名に適用するグロブパターン（例：「api-.md」、「.md」）

戻り値： ファイル名、チャンクの内容、類似度スコアを含む検索結果の配列

使用例：

// Basic search
search(query: "JWT authentication")

// Search only in docs/api directory
search(query: "user endpoints", directory: "docs/api")

// Search only files matching pattern
search(query: "deployment", file_pattern: "guide-*.md")

// Combined filters
search(query: "authentication", directory: "docs/api", file_pattern: "auth*.md")

index_markdown

Markdown ファイルをインデックス化します

パラメーター：

• filepath（文字列）：インデックス化するファイルのパス

list_documents

インデックス化されたすべてのドキュメントを一覧表示します

戻り値： ファイル名とタイムスタンプを含むドキュメント一覧

delete_document

インデックスからドキュメントを削除します

パラメーター：

• filepath（文字列）：削除するファイルのパス

reindex_document

ドキュメントを再インデックス化します

パラメーター：

• filepath（文字列）：再インデックス化するファイルのパス

CLI の使用方法

DevRag はスタンドアロンの CLI ツールとしても使用できます。すべての MCP ツールを CLI コマンドとして利用できます。

# Start MCP server (default)
devrag
devrag serve

# Search documents
devrag search "JWT authentication"
devrag search "deployment" --top-k 10 --directory docs/api

# Index files
devrag index ./docs/api-spec.md
devrag index-code --directory ./src

# List indexed documents
devrag list
devrag list --fields filename

# Delete / Reindex
devrag delete ./docs/old-spec.md --dry-run
devrag reindex ./docs/updated-spec.md

# Code symbol relations
devrag search-relations handleAuth --type calls

# Build dictionary (Japanese-English mapping)
devrag build-dictionary

# Show CLI schema (machine-readable)
devrag schema

出力形式

すべてのコマンドはデフォルトで JSON を出力します。人間が読みやすい形式で出力するには、--output text を使用します。

# JSON (default, suitable for scripts and AI agents)
devrag search "authentication"

# Text (human-readable)
devrag search "authentication" --output text

MCP ツール名との互換性

CLI コマンドでは、アンダースコアを含む MCP ツール名も使用できます。

devrag index_markdown ./docs/api.md    # same as: devrag index
devrag list_documents                  # same as: devrag list
devrag delete_document ./docs/old.md   # same as: devrag delete
devrag reindex_document ./docs/api.md  # same as: devrag reindex

フラグの構文

フラグは位置引数より前に指定する必要があります。

# Correct
devrag delete --dry-run file.md

# Incorrect (--dry-run is ignored)
devrag delete file.md --dry-run

チームでの開発

大規模なドキュメントリポジトリを持つチームに最適です。

1. Git でドキュメントを管理：通常の Git ワークフローを使用します
2. 各開発者が DevRag を実行：各自のマシンにローカルでセットアップします
3. Claude Code で検索：全員がすべてのドキュメントを検索できます
4. 自動同期：git pull によりインデックスが自動的に更新されます

プロジェクトのドキュメントディレクトリに合わせて設定します。

{
  "document_patterns": [
    "./docs",
    "./api-docs/**/*.md",
    "./wiki/**/*.md"
  ],
  "db_path": "./.devrag/vectors.db"
}

パフォーマンス

環境：MacBook Pro M2、100 ファイル（合計 1MB）

操作	時間	トークン数
起動	2.3s	-
インデックス化	8.5s	-
検索（1 クエリ）	95ms	~300
従来の読み取り	25s	~12,000

検索が 260 倍高速に、トークン数が 40 分の 1 に

開発

テストの実行

# All tests
go test ./...

# Specific packages
go test ./internal/config -v
go test ./internal/indexer -v
go test ./internal/embedder -v
go test ./internal/vectordb -v

# Integration tests
go test . -v -run TestEndToEnd

ビルド

# Using build script
./build.sh

# Direct build
go build -o devrag cmd/main.go

# Cross-platform release build
./scripts/build-release.sh

リリースの作成

# Create version tag
git tag v1.0.1

# Push tag
git push origin v1.0.1

GitHub Actions により、以下が自動的に実行されます。

1. すべてのプラットフォーム向けにビルド
2. GitHub リリースを作成
3. バイナリをアップロード
4. チェックサムを生成

プロジェクト構成

devrag/
├── cmd/
│   └── main.go              # Entry point
├── internal/
│   ├── cli/                 # CLI commands
│   ├── config/              # Configuration
│   ├── embedder/            # Vector embeddings
│   ├── indexer/             # Indexing logic
│   ├── mcp/                 # MCP server
│   └── vectordb/            # Vector database
├── models/                  # ONNX models
├── build.sh                 # Build script
└── integration_test.go      # Integration tests

トラブルシューティング

モデルのダウンロードに失敗する

原因：インターネット接続または Hugging Face サーバーの問題

解決策：

1. インターネット接続を確認します
2. プロキシ環境の場合：

   export HTTP_PROXY=http://your-proxy:port
   export HTTPS_PROXY=http://your-proxy:port
   

3. 手動でダウンロードします（models/DOWNLOAD.md を参照）
4. 再試行します（不完全なファイルは自動的に削除されます）

GPU / CoreML が動作しない

macOS では、DevRag は GPU / Neural Engine による高速化に Apple CoreML を使用します。要件：

• libonnxruntime.dylib が devrag バイナリと同じディレクトリにある必要があります
• GitHub で配布される macOS 版には、このファイルが自動的に含まれます

CoreML が利用できない場合、DevRag は自動的に CPU に切り替えます。パフォーマンスを調整するには：

# Adjust CPU thread count (default: 4)
DEVRAG_THREADS=4 devrag

CPU モードを明示的に強制するには：

{
  "compute": {
    "device": "cpu",
    "fallback_to_cpu": true
  }
}

起動しない

• Go 1.21 以降がインストールされていることを確認します（ビルドする場合）
• CGO が有効になっているか確認します：go env CGO_ENABLED
• 依存関係がインストールされていることを確認します
• 初回実行時にはインターネット接続が必要です（モデルのダウンロードのため）

検索結果が予期しない内容になる

• chunk_size を調整します（デフォルト：500）
• インデックスを再構築します（vectors.db を削除して再起動します）

メモリ使用量が多い

• GPU モードではモデルが VRAM に読み込まれます
• メモリ使用量を抑えるには、CPU モードに切り替えます

要件

• Go 1.21 以降（ソースからビルドする場合）
• CGO が有効であること（sqlite-vec 用）
• macOS、Linux、または Windows

ライセンス

MIT ライセンス

クレジット

• 埋め込みモデル：intfloat/multilingual-e5-small
• ベクトルデータベース：sqlite-vec
• MCP プロトコル：Model Context Protocol
• ONNX Runtime：onnxruntime-go

コントリビューション

Issue とプルリクエストを歓迎します！

Contributors

Special thanks to all contributors who helped improve DevRag:

• @badri - Multiple document paths with glob patterns (#2), --config CLI flag (#3)
• @io41 - Project cleanup and documentation improvements (#4)

Your contributions make DevRag better for everyone!

Author

towada

---

日本語版

Claude Code用の無料ローカルRAG - トークン＆時間を節約

DevRagは、Claude Codeを使う開発者のための軽量RAG（Retrieval-Augmented Generation）システムです。ドキュメント全体を読み込んでトークンを無駄にするのをやめて、ベクトル検索で必要な情報だけを取得しましょう。

なぜDevRagが必要か？

Claude Codeでドキュメントを読み込むと、大量のトークンを消費します：

• ❌ コンテキストの浪費: 毎回ドキュメント全体を読み込み（1ファイル3,000トークン以上）
• ❌ 検索性の欠如: Claudeはどのファイルに何が書いてあるか知らない
• ❌ 繰り返し: セッションをまたいで同じドキュメントを何度も読む

DevRagを使えば:

• ✅ トークン消費1/40: ベクトル検索で必要な部分だけ取得（約200トークン）
• ✅ 15倍高速: 検索100ms vs 読み込み30秒
• ✅ 自動発見: ファイル名を知らなくてもClaude Codeが見つける

特徴

• 🤖 簡易RAG - Claude Code用の検索拡張生成
• 📝 マークダウン対応 - .mdファイルを自動インデックス化
• 🔍 意味検索 - 「JWTの認証方法」のような自然言語クエリ
• 🚀 ワンバイナリー - Python不要、モデルは初回起動時に自動ダウンロード
• 💻 CLI & MCP - MCPサーバーとしても、CLIコマンドとしても使える
• 🖥️ クロスプラットフォーム - macOS / Linux / Windows
• ⚡ 高速 - GPU/CPU自動検出、差分同期
• 🌐 多言語 - 日本語・英語を含む100以上の言語対応

クイックスタート

1. バイナリダウンロード

Releasesから環境に合ったファイルをダウンロード：

プラットフォーム	ファイル
macOS (Apple Silicon)	devrag-macos-apple-silicon.tar.gz
macOS (Intel)	devrag-macos-intel.tar.gz
Linux (x64)	devrag-linux-x64.tar.gz
Linux (ARM64)	devrag-linux-arm64.tar.gz
Windows (x64)	devrag-windows-x64.zip

macOS/Linux:

tar -xzf devrag-*.tar.gz
chmod +x devrag-*
sudo mv devrag-* /usr/local/bin/

注意: macOS版リリースにはCoreML GPU高速化用のlibonnxruntime.dylibが含まれています。devragバイナリと同じディレクトリに配置してください。

Windows:

• zipファイルを解凍
• 任意の場所に配置（例: C:\Program Files\devrag\）

2. Claude Code設定

~/.claude.json または .mcp.json に追加：

{
  "mcpServers": {
    "devrag": {
      "type": "stdio",
      "command": "/usr/local/bin/devrag"
    }
  }
}

カスタム設定ファイルを使用する場合:

{
  "mcpServers": {
    "devrag": {
      "type": "stdio",
      "command": "/usr/local/bin/devrag",
      "args": ["--config", "/path/to/custom-config.json"]
    }
  }
}

3. ドキュメントを配置

mkdir documents
cp your-notes.md documents/

これで完了！起動時に自動的にインデックス化されます。

4. Claude Codeで検索

Claude Codeで：

「JWTの認証方法について検索して」

設定

config.jsonを作成：

{
  "document_patterns": [
    "./documents",
    "./notes/**/*.md",
    "./projects/backend/**/*.md"
  ],
  "db_path": "./vectors.db",
  "chunk_size": 500,
  "search_top_k": 5,
  "compute": {
    "device": "auto",
    "fallback_to_cpu": true
  },
  "model": {
    "name": "multilingual-e5-small",
    "dimensions": 384
  }
}

設定項目

• document_patterns: ドキュメントのパスとglobパターンの配列
  • ディレクトリパス対応: "./documents"
  • globパターン対応: "./docs/**/*.md" (再帰的)
  • 複数パターン: 異なる場所からファイルをインデックス化
  • 注意: 旧形式のdocuments_dirもサポート（自動的に移行）
• db_path: ベクトルデータベースのパス
• chunk_size: ドキュメントのチャンクサイズ（文字数）
• search_top_k: 検索結果の返却件数
• compute.device: 計算デバイス（auto, cpu, gpu）
• compute.fallback_to_cpu: GPU利用不可時にCPUにフォールバック
• model.name: 埋め込みモデル名
• model.dimensions: ベクトル次元数

コマンドラインオプション

• --config <path>: カスタム設定ファイルのパスを指定（デフォルト: config.json）

使用例:

devrag --config /path/to/custom-config.json

これは以下の用途で便利です：

• 異なる設定で複数のインスタンスを実行
• 異なるモデルやチャンクサイズをテスト
• 開発/テスト/本番環境の設定を分離

パターン例

{
  "document_patterns": [
    "./documents",                    // documents/内の全.mdファイル
    "./notes/**/*.md",                // notes/内を再帰的に検索
    "./projects/*/docs/*.md",         // 各プロジェクトのdocs/
    "/path/to/external/docs"          // 絶対パス
  ]
}

MCPツール

Model Context Protocolを通じて以下のツールを提供：

search

フィルター機能付き意味ベクトル検索を実行

パラメータ:

• query (string, 必須): 自然言語の検索クエリ
• top_k (number, 任意): 最大結果数（デフォルト: 5）
• directory (string, 任意): 特定ディレクトリに絞り込み（例: "docs/api"）
• file_pattern (string, 任意): ファイル名のglobパターン（例: "api-.md", ".md"）

戻り値: ファイル名、チャンク内容、類似度スコアを含む検索結果の配列

使用例:

// 基本検索
search(query: "JWT認証")

// docs/apiディレクトリ内のみ検索
search(query: "ユーザーエンドポイント", directory: "docs/api")

// パターンに一致するファイルのみ検索
search(query: "デプロイ", file_pattern: "guide-*.md")

// フィルターの組み合わせ
search(query: "認証", directory: "docs/api", file_pattern: "auth*.md")

index_markdown

マークダウンファイルをインデックス化

パラメータ:

• filepath (string): インデックス化するファイルのパス

list_documents

インデックス化されたドキュメントの一覧を取得

戻り値: ファイル名とタイムスタンプを含むドキュメントリスト

delete_document

ドキュメントをインデックスから削除

パラメータ:

• filepath (string): 削除するファイルのパス

reindex_document

ドキュメントを再インデックス化

パラメータ:

• filepath (string): 再インデックス化するファイルのパス

CLI使用方法

DevRagはスタンドアロンのCLIツールとしても使用できます。すべてのMCPツールがCLIコマンドとして利用可能です。

# MCPサーバーを起動（デフォルト）
devrag
devrag serve

# ドキュメントを検索
devrag search "JWT認証"
devrag search "デプロイ" --top-k 10 --directory docs/api

# ファイルをインデックス化
devrag index ./docs/api-spec.md
devrag index-code --directory ./src

# インデックス済みドキュメント一覧
devrag list
devrag list --fields filename

# 削除 / 再インデックス
devrag delete ./docs/old-spec.md --dry-run
devrag reindex ./docs/updated-spec.md

# コードシンボル関係検索
devrag search-relations handleAuth --type calls

# 辞書ビルド（日本語→英語マッピング）
devrag build-dictionary

# CLIスキーマ表示（機械可読）
devrag schema

出力形式

全コマンドはデフォルトでJSONを出力します。--output textで人間が読みやすい形式になります。

# JSON（デフォルト、スクリプトやAIエージェント向け）
devrag search "認証"

# テキスト（人間向け）
devrag search "認証" --output text

MCPツール名との互換性

CLIコマンドはアンダースコア形式のMCPツール名でも動作します：

devrag index_markdown ./docs/api.md    # devrag index と同じ
devrag list_documents                  # devrag list と同じ
devrag delete_document ./docs/old.md   # devrag delete と同じ
devrag reindex_document ./docs/api.md  # devrag reindex と同じ

フラグの構文

フラグは位置引数の前に置く必要があります：

# 正しい
devrag delete --dry-run file.md

# 誤り（--dry-runが無視される）
devrag delete file.md --dry-run

チーム開発

大量のドキュメントがあるチームに最適：

1. Gitでドキュメント管理: 通常のGitワークフロー
2. 各開発者がDevRagを起動: 各マシンでローカルセットアップ
3. Claude Codeで検索: 全員が全ドキュメントを検索可能
4. 自動同期: git pullでインデックスを自動更新

プロジェクトのdocsディレクトリ用に設定：

{
  "document_patterns": [
    "./docs",
    "./api-docs/**/*.md",
    "./wiki/**/*.md"
  ],
  "db_path": "./.devrag/vectors.db"
}

パフォーマンス

環境: MacBook Pro M2, 100ファイル (合計1MB)

操作	時間	トークン
起動	2.3秒	-
インデックス化	8.5秒	-
検索 (1クエリ)	95ms	~300
従来のRead	25秒	~12,000

検索は260倍速、トークンは40分の1

開発

テスト実行

# すべてのテスト
go test ./...

# 特定のパッケージ
go test ./internal/config -v
go test ./internal/indexer -v
go test ./internal/embedder -v
go test ./internal/vectordb -v

# 統合テスト
go test . -v -run TestEndToEnd

ビルド

# ビルドスクリプト使用
./build.sh

# 直接ビルド
go build -o devrag cmd/main.go

# クロスプラットフォームリリースビルド
./scripts/build-release.sh

リリース作成

# バージョンタグを作成
git tag v1.0.1

# タグをプッシュ
git push origin v1.0.1

GitHub Actionsが自動的に：

1. 全プラットフォーム向けにビルド
2. GitHub Releaseを作成
3. バイナリをアップロード
4. チェックサムを生成

プロジェクト構造

devrag/
├── cmd/
│   └── main.go              # エントリーポイント
├── internal/
│   ├── cli/                 # CLIコマンド
│   ├── config/              # 設定管理
│   ├── embedder/            # ベクトル埋め込み
│   ├── indexer/             # インデックス処理
│   ├── mcp/                 # MCPサーバー
│   └── vectordb/            # ベクトルDB
├── models/                  # ONNXモデル
├── build.sh                 # ビルドスクリプト
└── integration_test.go      # 統合テスト

トラブルシューティング

モデルのダウンロードに失敗

原因: インターネット接続またはHugging Faceサーバーの問題

解決方法:

1. インターネット接続を確認
2. プロキシ環境の場合：

   export HTTP_PROXY=http://your-proxy:port
   export HTTPS_PROXY=http://your-proxy:port
   

3. 手動ダウンロード（models/DOWNLOAD.md参照）
4. 再試行（不完全なファイルは自動削除）

GPU / CoreMLが動作しない

macOSではApple CoreMLによるGPU/Neural Engine高速化を使用します。条件：

• libonnxruntime.dylibがdevragバイナリと同じディレクトリにあること
• GitHubのmacOS版リリースにはこのファイルが含まれています

CoreMLが利用できない場合は自動的にCPUにフォールバックします。パフォーマンス調整：

# CPUスレッド数の変更（デフォルト: 4）
DEVRAG_THREADS=4 devrag

明示的にCPUモードを指定する場合：

{
  "compute": {
    "device": "cpu",
    "fallback_to_cpu": true
  }
}

起動しない

• Go 1.21+がインストールされているか確認（ソースからビルドする場合）
• CGOが有効か確認: go env CGO_ENABLED
• 依存関係がインストールされているか確認
• 初回起動時はインターネット接続が必要（モデルダウンロード）

検索結果が期待と異なる

• chunk_sizeを調整（デフォルト: 500）
• インデックスを再構築（vectors.dbを削除して再起動）

メモリ使用量が多い

• GPUモードではモデルがVRAMにロード
• CPUモードに切り替えるとメモリ使用量が減少

必要要件

• Go 1.21+（ソースからビルドする場合）
• CGO有効（sqlite-vecのため）
• macOS, Linux, または Windows

ライセンス

MIT License

クレジット

• 埋め込みモデル: intfloat/multilingual-e5-small
• ベクトルデータベース: sqlite-vec
• MCPプロトコル: Model Context Protocol
• ONNX Runtime: onnxruntime-go

コントリビューション

IssuesとPull Requestsを歓迎します！

コントリビューター

DevRagの改善に貢献してくださった皆様に感謝します：

• @badri - 複数ドキュメントパスとglobパターン対応 (#2)、--config CLIフラグ (#3)
• @io41 - プロジェクトのクリーンアップとドキュメント改善 (#4)

皆様の貢献がDevRagをより良くしています！

作者

towada