DevRag

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

mkdir documents cp your-notes.md documents/

That's it! Documents are automatically indexed on startup.

"Search for JWT authentication methods"

- document_patterns: Array of document paths and glob patterns

DevRag provides the following tools via Model Context Protocol:

Perform semantic vector search with optional filtering

Returns:Array of search results with filename, chunk content, and similarity score

- filepath(string): Path to the file to index

Returns:Document list with filenames and timestamps

- filepath(string): Path to the file to delete

- filepath(string): Path to the file to re-index

DevRag can also be used as a standalone CLI tool. All MCP tools are available as CLI commands.

# 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

All commands output JSON by default. Use--output textfor human-readable output.

# JSON (default, suitable for scripts and AI agents) devrag search "authentication" # Text (human-readable) devrag search "authentication" --output text

CLI commands also accept MCP tool names with underscores:

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

Flags must be placedbeforepositional arguments:

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

Perfect for teams with large documentation repositories:
- Manage docs in Git: Normal Git workflow
- Each developer runs DevRag: Local setup on each machine
- Search via Claude Code: Everyone can search all docs
- Auto-sync:git pullautomatically updates the index

Configure for your project's docs directory:

Environment: MacBook Pro M2, 100 files (1MB total)

# 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

- Builds for all platforms
- Creates GitHub Release
- Uploads binaries
- Generates checksums

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

Cause: Internet connection or Hugging Face server issues
- Check internet connection
- For proxy environments:

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

On macOS, DevRag uses Apple CoreML for GPU/Neural Engine acceleration. Requirements:

- libonnxruntime.dylibmust be in the same directory as thedevragbinary
- macOS releases from GitHub include this file automatically

If CoreML is not available, DevRag falls back to CPU automatically. To tune performance:

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

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

- Ensure Go 1.21+ is installed (for building)
- Check CGO is enabled:go env CGO_ENABLED
- Verify dependencies are installed
- Internet required for first run (model download)

- Adjustchunk_size(default: 500)
- Rebuild index (delete vectors.db and restart)

- GPU mode loads model into VRAM
- Switch to CPU mode for lower memory usage

- Go 1.21+ (for building from source)
- CGO enabled (for sqlite-vec)
- macOS, Linux, or Windows

- Embedding Model:intfloat/multilingual-e5-small
- Vector Database:sqlite-vec
- MCP Protocol:Model Context Protocol
- ONNX Runtime:onnxruntime-go

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