RAG Retriever - QUICKSTART

July 20, 2025 · View on GitHub

This guide provides the EXACT commands to get RAG Retriever installed and running for semantic search.

Prerequisites

  • Python 3.10+ installed
  • OpenAI API key (keep it secret!)
  • Git installed
  • Sufficient disk space (~500MB for dependencies)

Step-by-Step Commands

1. Install RAG Retriever

Use uv tool install for complete isolation from other Python projects:

# Install using uv tool (recommended)
uv tool install rag-retriever

# Find where the executable is installed (needed for MCP server setup later)
uv tool dir

The executable will be installed in something like:

  • macOS: /Users/YOUR_USERNAME/.local/share/uv/tools/rag-retriever/bin/rag-retriever
  • Windows: C:\Users\YOUR_USERNAME\AppData\Roaming\uv\tools\rag-retriever\Scripts\rag-retriever.exe
  • Linux: /home/YOUR_USERNAME/.local/share/uv/tools/rag-retriever/bin/rag-retriever

Quick Start with uvx (Less Desirable)

For quick testing only - may cause Python dependency conflicts:

# Quick test (shared environment - may have conflicts)
uvx rag-retriever --help

⚠️ Warning: Using uvx runs packages in a shared environment which can lead to dependency conflicts with other Python tools. For any real usage, always prefer uv tool install.

Note: Other installation methods (pip, pipx, development) are not supported. Use at your own risk.

2. Initialize Configuration

# Create config file with all settings pre-configured
rag-retriever --init

Config file locations:

  • macOS/Linux: ~/.config/rag-retriever/config.yaml
  • Windows: %APPDATA%\rag-retriever\config.yaml

3. Configure API Key (ONLY Required Change)

IMPORTANT: Replace null with your OpenAI API key in the config file.

macOS/Linux:

# Edit the config file
nano ~/.config/rag-retriever/config.yaml

# Find this line and replace null:
api:
  openai_api_key: sk-your-actual-api-key-here  # Change from: null

Windows:

# Edit the config file
notepad %APPDATA%\rag-retriever\config.yaml

# Find this line and replace null:
api:
  openai_api_key: sk-your-actual-api-key-here  # Change from: null

4. Verify Installation (browsers auto-installed)

# Check that everything is working (browsers should be pre-installed)
rag-retriever --help

# If you see browser errors, run:
python -m playwright install chromium

5. Verify Installation

# Check that everything is working
rag-retriever --help

# Should show no system validation errors

6. Test with Sample Content

# Index a simple website
rag-retriever --fetch "https://example.com" --collection test

# Search the indexed content
rag-retriever --search "example" --collection test

Optional: Claude Code Integration

If you want to use RAG Retriever with Claude Code:

7. Configure MCP Server

For Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "rag-retriever": {
      "command": "/absolute/path/to/uv/tools/rag-retriever/bin/rag-retriever",
      "args": ["--mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Replace /absolute/path/to/uv/tools/rag-retriever with the actual path from uv tool dir.

For Claude Code CLI

# Get the uv tools directory
uv tool dir

# Add RAG Retriever as MCP server using the FULL path from above
# Example: If uv tool dir shows /Users/username/.local/share/uv/tools
claude mcp add-json -s user rag-retriever '{"type":"stdio","command":"/Users/username/.local/share/uv/tools/rag-retriever/bin/mcp-rag-retriever"}'

# Verify it's added
claude mcp list

For Other AI Assistants (Windsurf, Cursor, etc.)

Add this JSON configuration (use path from uv tool dir):

"rag-retriever": {
  "command": "/path/from/uv/tool/dir/rag-retriever/bin/mcp-rag-retriever"
}

8. Grant Permissions

Edit ~/.claude/settings.json and add to the "allow" array:

"mcp__rag-retriever__*"

9. Test Claude Code Integration

# Restart Claude Code
claude

# Test basic integration:
/list-collections

10. Test with Real Content

Index Claude Code documentation to verify full functionality:

/index-website "https://docs.anthropic.com/en/docs/claude-code/overview 3 claude_code_docs"

Wait 1-2 minutes for crawling, then test search:

/search-knowledge "MCP server setup claude_code_docs"

Common Commands

Basic Usage

# Index a website
rag-retriever --fetch "https://docs.python.org" --collection python_docs

# Search content
rag-retriever --search "list comprehension" --collection python_docs

# Search all collections
rag-retriever --search "python" --search-all-collections

# Launch web interface
rag-retriever --ui

Collection Management

# List all collections
rag-retriever --list-collections

# Clean specific collection
rag-retriever --clean-db --collection old_collection

# Clean all collections
rag-retriever --clean-db

Advanced Crawling

# Deep crawl with custom depth
rag-retriever --fetch "https://docs.site.com" --max-depth 3 --collection site_docs

# Use faster Crawl4AI crawler (edit config.yaml first)
crawler:
  type: "crawl4ai"

Configuration Options

Crawler Selection

Edit ~/.config/rag-retriever/config.yaml:

# Use Crawl4AI (20x faster)
crawler:
  type: "crawl4ai"

# Or use Playwright (more reliable)
crawler:
  type: "playwright"

Search Settings

search:
  default_limit: 10
  default_score_threshold: 0.3

Content Processing

content:
  chunk_size: 2000
  chunk_overlap: 400

Troubleshooting Quick Fixes

Installation Issues

# If uv is not installed
curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS/Linux
# Or visit https://github.com/astral-sh/uv for Windows

# If uv tool install fails
uv tool uninstall rag-retriever  # Clean any partial install
uv tool install rag-retriever    # Retry

# If browser install fails
python -m playwright install chromium --force

# If dependencies are missing
pip install --upgrade pip

Dependency Conflicts

If you experience Python dependency conflicts:

  1. Use isolated installation: Always prefer uv tool install over uvx
  2. Check existing tools: Run uv tool list to see installed tools
  3. Clean installation: 
    uv tool uninstall rag-retriever
uv tool install rag-retriever
  4. Verify isolation: The tool should be completely isolated in its own environment

For detailed dependency conflict resolution, see the MCP Server Installation Guide.

API Key Issues

# Test API key directly
curl -H "Authorization: Bearer sk-your-key" https://api.openai.com/v1/models

# Set environment variable as fallback
export OPENAI_API_KEY=sk-your-key-here

Search Issues

# Check what's indexed
rag-retriever --list-collections

# Lower search threshold
rag-retriever --search "query" --score-threshold 0.2

# Search all collections
rag-retriever --search "query" --search-all-collections

That's It!

You now have RAG Retriever installed and ready to use for semantic search.

Next Steps

  1. Index your important content:

    rag-retriever --fetch "https://your-important-site.com" --collection important_docs

  2. Organize with collections:

    • Use descriptive names: python_docs, company_wiki, research_papers
    • Keep related content together
    • Use the default collection for general content

  3. Use Claude Code commands (if MCP configured):

    • /list-collections - See what's available
    • /search-knowledge "query" - Search your content
    • /index-website "https://site.com" - Add new content
    • /audit-collections - Review collection health

  4. Explore the web interface:

    rag-retriever --ui

Data Storage

Your data is stored in:

  • macOS/Linux: ~/.local/share/rag-retriever/
  • Windows: %LOCALAPPDATA%\rag-retriever\

Collections persist between sessions and are automatically backed up.

Getting Help

  • Run with --verbose for detailed logging
  • Check TROUBLESHOOTING_ASSISTANT_PROMPT.md for common issues
  • Use USAGE_ASSISTANT_PROMPT.md for advanced usage patterns