DevRag - Lightweight Local RAG MCP Server

DevRag

Claude Code 的免费本地 RAG——节省 Token 和时间

日文版请点击此处 | 日文版

DevRag 是一款轻量级 RAG（检索增强生成）系统，专为使用 Claude Code 的开发者设计。别再浪费 Token 阅读整篇文档了——让向量搜索精准找到你需要的内容。

为什么选择 DevRag？

使用 Claude Code 时，通过 Read 工具阅读文档会消耗大量 Token：

• ❌ 浪费上下文：每次都阅读整篇文档（每个文件超过 3,000 个 Token）
• ❌ 难以搜索：Claude 不知道哪个文件包含什么内容
• ❌ 重复阅读：同一份文档在不同会话中被多次阅读

使用 DevRag：

• ✅ Token 用量减少 40 倍：向量搜索仅检索相关片段（约 200 个 Token）
• ✅ 速度提升 15 倍：100 毫秒内完成搜索，而阅读需要 30 秒
• ✅ 自动发现：Claude Code 无需知道文件名即可找到文档

功能特性

• 🤖 简易 RAG - 为 Claude Code 提供检索增强生成
• 📝 支持 Markdown - 自动为 .md 文件建立索引
• 🔍 语义搜索 - 支持“JWT authentication method”等自然语言查询
• 🚀 单个二进制文件 - 无需 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 中：

"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

以下场景中很有用：

• 使用不同配置运行多个实例
• 测试不同的模型或分块大小
• 维护独立的开发/测试/生产配置

模式示例

{
  "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（字符串，可选）：文件名的 Glob 模式（例如："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）

操作	耗时	Token 数
启动	2.3s	-
建立索引	8.5s	-
搜索（1 次查询）	95ms	~300
传统读取	25s	~12,000

搜索速度快 260 倍，Token 数减少 40 倍

开发

运行测试

# 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 Release
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 使用 Apple CoreML 加速 GPU / 神经引擎。要求：

• 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 模式会将模型加载到显存中
• 切换到 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

贡献

欢迎提交问题和 Pull Request！

贡献者

特别感谢所有帮助改进 DevRag 的贡献者：

• @badri - 支持多个文档路径和 glob 模式（#2），新增 --config CLI 标志（#3）
• @io41 - 项目清理和文档改进（#4）

你们的贡献让 DevRag 变得更好！

作者

towada

---

日语版

面向 Claude Code 的免费本地 RAG——节省 Token 和时间

DevRag 是一款面向 Claude Code 开发者的轻量级 RAG（检索增强生成）系统。不要再加载整份文档、浪费 Token 了，使用向量搜索，仅获取所需信息。

为什么需要 DevRag？

在 Claude Code 中加载文档会消耗大量 Token：

• ❌ 浪费上下文：每次都加载整份文档（每个文件超过 3,000 个 Token）
• ❌ 缺少可搜索性：Claude 不知道哪些文件中写了什么
• ❌ 重复读取：跨会话反复阅读相同文档

使用 DevRag 后：

• ✅ Token 消耗降至 1/40：通过向量搜索只获取所需部分（约 200 个 Token）
• ✅ 速度提升 15 倍：搜索耗时 100 ms，加载耗时 30 秒
• ✅ 自动发现：Claude Code 无需知道文件名也能找到内容

特点

• 🤖 简易 RAG - 面向 Claude Code 的检索增强生成
• 📝 支持 Markdown - 自动为 .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

为 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