Qdrant RAG Server - Practical Usage Examples with Claude Code

This guide provides real-world examples of how to effectively use the Qdrant RAG server when working with Claude Code to enhance your development workflow.

Setting Correct Working Directory
Finding Implementation Details
Understanding Configuration
Debugging Issues
Finding Examples
Architecture Questions
Finding Related Code
Configuration Updates
Cross-Project Search
Understanding Scripts
Using Hybrid Search Effectively
Finding Test Examples
Checking for File Changes
Indexing Custom File Types
Pro Tips

0. Setting Correct Working Directory (v0.2.2+)

Scenario: You're working in /project-a but health check shows the wrong project context.

Natural Language Approach (No Configuration Required!)

You: "Get the current working directory with pwd, export MCP_CLIENT_CWD to that value, then run a health check"

Claude: I'll set the correct working directory for the MCP server and verify the project context.
[Runs: pwd]
[Output: /Users/you/projects/project-a]
[Runs: export MCP_CLIENT_CWD=/Users/you/projects/project-a]
[Uses: qdrant-rag:health_check]

✓ Health check shows:
- Project: project_a
- Path: /Users/you/projects/project-a
- The MCP server now correctly knows your working directory!

For Indexing with Correct Context

You: "First run pwd and export MCP_CLIENT_CWD=$(pwd), then reindex this directory"

Claude: I'll ensure the MCP server knows the correct directory before indexing.
[Runs: export MCP_CLIENT_CWD=$(pwd)]
[Uses: qdrant-rag:reindex_directory with correct project context]

Why this works: The MCP server runs in its own process and doesn't automatically know where you're working. By setting MCP_CLIENT_CWD, you tell it your actual location.

Pro tip: Start every Claude Code session with the working directory setup to ensure correct project detection throughout your session.

1. Finding Implementation Details

Scenario: You need to understand how a specific feature is implemented.

You: "How does the embedding model get initialized in this project?"

Claude: Let me search for embedding model initialization...
[Uses: qdrant-rag:search "embedding model initialization"]
[Finds: EmbeddingsManager class in src/utils/embeddings.py]

The embedding model is initialized in the EmbeddingsManager class at 
src/utils/embeddings.py:21. It uses lazy initialization with auto-device 
detection (CPU/CUDA/MPS) and defaults to 'all-MiniLM-L6-v2' model...

What's happening: Claude uses hybrid search (v0.1.4+) combining semantic understanding with keyword matching. This finds relevant code even if you don't know exact names, while also prioritizing exact matches like "EmbeddingsManager".

2. Understanding Configuration

Scenario: You need to know what configuration options are available.

You: "What environment variables does this project use?"

Claude: Let me search for environment variable usage...
[Uses: qdrant-rag:search "environment variables env getenv"]
[Finds: config.py, .env.example, various script files]

The project uses these environment variables:
- EMBEDDING_MODEL: Choose embedding model (default: all-MiniLM-L12-v2)
- QDRANT_HOST/QDRANT_PORT: Qdrant connection
- SENTENCE_TRANSFORMERS_HOME: Model cache directory
- HTTP_SERVER_PORT: HTTP test server port (default: 8081)
[Shows actual values from config.py]

What's happening: The RAG server indexes configuration files, making it easy to discover all configurable options.

3. Debugging Issues

Scenario: You encounter an error and need to trace its origin.

You: "I'm getting a 'chunk_id' attribute error. Where is this used?"

Claude: Let me search for chunk_id usage...
[Uses: qdrant-rag:search_code "chunk_id attribute"]
[Finds: qdrant_mcp_context_aware.py where chunk_id is generated]

I found the issue. The chunk_id is generated in src/qdrant_mcp_context_aware.py:239 
using hashlib. The error suggests you might be running an older cached version 
of the MCP server. Try restarting the MCP connection...

What's happening: Claude can quickly locate error-related code and provide context about potential causes.

4. Finding Examples

Scenario: You need to understand how to use a specific component.

You: "Show me how to use the code indexer"

Claude: Let me find code indexer usage examples...
[Uses: qdrant-rag:search_code "code_indexer index_file"]
[Finds: actual usage in qdrant_mcp_context_aware.py]

Here's how the code indexer is used:

```python
from indexers.code_indexer import CodeIndexer

# Initialize
code_indexer = get_code_indexer()

# Index a file
chunks = code_indexer.index_file(str(file_path))

# Process chunks
for chunk in chunks:
    # chunk.content - the code text
    # chunk.line_start/line_end - line numbers
    # chunk.chunk_index - position in file


**What's happening**: The search finds actual usage patterns in your codebase, providing real examples.

## 5. Architecture Questions

**Scenario**: You need to understand how a system component works.

You: "How does the context-aware project detection work?"

Claude: [Uses: qdrant-rag:search "project detection get_current_project"] [Finds: implementation details and marker files]

The context-aware detection works by:

Starting from the current working directory
Looking for project markers in parent directories:
- .git directory
- package.json, pyproject.toml, Cargo.toml
- go.mod, pom.xml, etc.
Creating project-specific collections like 'project_myapp_code'
Scoping searches to the current project by default

Implementation is in get_current_project() function.


**What's happening**: Claude can explain architectural decisions by finding and analyzing relevant code.

## 6. Finding Related Code

**Scenario**: You need to find all files related to a specific feature.

You: "What files handle MCP protocol communication?"

Claude: [Uses: qdrant-rag:search "mcp protocol @mcp.tool FastMCP"] [Finds: all MCP-related files]

The MCP protocol is handled by:

src/qdrant_mcp_context_aware.py - Main MCP server implementation
config/mcp_manifest.json - API method definitions
run_mcp.sh - Server startup script
src/qdrant_mcp_debug.py - Debug version

Key decorators:

@mcp.tool() - Defines MCP-callable functions
Functions like index_code(), search(), get_context()


**What's happening**: The semantic search understands related concepts and finds all relevant files.

## 7. Configuration Updates

**Scenario**: You need to add a new configuration option.

You: "I need to add a new config option for chunk size"

Claude: Let me find where chunk configuration is defined... [Uses: qdrant-rag:search_config "chunk_size chunk_overlap"] [Finds: config files and usage]

Chunk size is configured in multiple places:

config/server_config.json - Default values:

"chunking": {
  "chunk_size": 1500,
  "chunk_overlap": 200
}

src/config.py:45 - Where it's loaded
src/indexers/code_indexer.py:64 - Where it's used

To add a new option, update all three locations.


**What's happening**: The config search specifically targets configuration files and their usage.

## 8. Cross-Project Search (Global)

**Scenario**: You need to find implementations across multiple projects.

You: "Search all my projects for OAuth implementation"

Claude: [Uses: qdrant-rag:search "OAuth authentication" cross_project=true] [Finds: OAuth implementations across different indexed projects]

Found OAuth implementations across your projects:

project_webapp: src/auth/oauth_handler.py
- Implements OAuth2 flow with Google/GitHub
project_api: lib/oauth2/provider.js
- JWT-based OAuth provider
project_mobile: auth/OAuthManager.swift
- iOS OAuth integration

Would you like me to examine any specific implementation?


**What's happening**: With cross_project=true, the search spans all indexed projects, not just the current one.

## 9. Understanding Scripts

**Scenario**: You need to understand what a script does before running it.

You: "What does the setup.sh script do?"

Claude: [Uses: qdrant-rag:search "setup.sh script"] [Finds: the script and related documentation]

The setup.sh script (scripts/setup.sh) performs initial setup:

Creates Python virtual environment
Installs dependencies via uv
Downloads embedding models
Creates necessary directories (data/, logs/)
Copies .env.example to .env if needed
Verifies Qdrant connection

Safe to run multiple times - it checks for existing setup.


**What's happening**: Claude reads and summarizes script contents, explaining what will happen.

## 10. Using Hybrid Search Effectively (v0.1.4+)

**Scenario**: You want to leverage the new hybrid search for better results.

You: "Find the BM25Manager class"

Claude: Let me search for that class definition... [Uses: qdrant-rag:search "BM25Manager class"] [Hybrid search combines keyword match for "BM25Manager" with semantic understanding]

Found BM25Manager class at src/utils/hybrid_search.py:47. This class manages BM25 keyword indices for collections. The hybrid search gives this high ranking because:

Keyword match: Exact match on "BM25Manager"
Semantic match: Understanding you want a class definition


**Comparing Search Modes**:

Default (Hybrid) - Best for most searches

You: "Find calculate_sum function" [Finds both exact matches AND semantically similar calculation functions]

Keyword mode - When you need exact matches

You: "Search for 'def calculate_sum(' using keyword mode" [Only finds exact text matches]

Vector mode - When you need conceptual matches

You: "Find all calculation-related functions using vector mode"
[Finds semantically similar code regardless of naming]


**What's happening**: Hybrid search automatically balances exact keyword matching (great for function/class names) with semantic understanding (great for concepts), giving you the best of both approaches.

## 11. Finding Test Examples

**Scenario**: You need to know how to test specific functionality.

You: "How do I test the HTTP API?"

Claude: [Uses: qdrant-rag:search "test http api curl"] [Finds: test scripts and documentation]

You can test the HTTP API using tests/integration/http_api/test_http_api.sh which includes:

# Test search endpoint
curl -X POST http://localhost:8081/search \
  -H "Content-Type: application/json" \
  -d '{"query": "your search term", "n_results": 5}'

# Test indexing
curl -X POST http://localhost:8081/index_directory \
  -H "Content-Type: application/json" \
  -d '{"directory": "/path/to/project"}'

# Test health check
curl http://localhost:8081/health

Full test suite available in the script.


**What's happening**: The search finds testing documentation and examples.

## 12. Checking for File Changes (v0.2.4+)

**Scenario**: You want to see what files have changed since the last indexing without running a full reindex.

You: "Check what files have changed in this project"

Claude: I'll check for changes since the last index... [Uses: qdrant-rag:detect_changes]

Here's what changed:

Added: 2 files
- src/new_feature.py
- tests/test_new_feature.py
Modified: 3 files
- src/main.py (updated 2 hours ago)
- config/settings.json (updated 1 hour ago)
- README.md (updated 30 minutes ago)
Deleted: 1 file
- src/deprecated_module.py
Unchanged: 156 files

Would you like me to reindex these changes?


**Use Cases for detect_changes**:
- **Pre-reindex check**: See what would be updated before running reindex
- **CI/CD integration**: Automate index updates based on changes
- **Monitoring**: Track codebase evolution over time
- **Debugging**: Verify the indexer is tracking files correctly

## 13. Indexing Custom File Types

**Scenario**: You need to index file types not included in the default patterns (like .sql, .graphql, .proto files).

You: "Index this directory including SQL and GraphQL files"

Claude: I'll index the directory with custom patterns for SQL and GraphQL files... [Uses: qdrant-rag:index_directory with patterns [".sql", ".graphql"]]

Successfully indexed:

156 Python files (.py)
23 SQL files (.sql)
8 GraphQL schema files (.graphql)
45 JSON config files (.json) Total: 232 files indexed


**Common Custom Pattern Examples**:

Database files

"Index with patterns *.sql *.ddl *.dml"

API definitions

"Index patterns *.proto *.graphql *.openapi.yaml"

Infrastructure as Code

"Index patterns *.tf *.tfvars for Terraform"

Specific project types

"Index only Rust: *.rs *.toml Cargo.lock" "Index only Go: *.go go.mod go.sum" "Index Flutter: *.dart pubspec.yaml"


**Note**: When you specify custom patterns, they're added to the default patterns, not replacing them. To index ONLY specific types, be explicit about it.

## Pro Tips

### 1. **Be Specific with Queries**
- ❌ Poor: "error"
- ✅ Good: "error handling in indexers"
- ✅ Better: "error handling CodeIndexer try except"

### 2. **Use the Right Search Type**
- `search` - General semantic search across all content
- `search_code` - When you need actual implementation code
- `search_config` - When looking for configuration values

### 3. **Leverage Search Modes (v0.1.4+)**
The server now supports three search modes for better precision:

**Hybrid Mode (Default)** - Best of both worlds:

Automatically combines keyword and semantic search

"Find the authenticate_user function" "Search for database connection handling"


**Keyword Mode** - For exact matches:

Use when you know exact function/variable names

"Search for 'def calculate_sum' using keyword mode" "Find BM25Manager class with keyword search"


**Vector Mode** - For concepts:

Use when searching for patterns or ideas

"Find error handling patterns using vector mode" "Search for authentication flows with semantic search"


### 4. **Include Multiple Keywords**
- ❌ Poor: "model"
- ✅ Good: "embedding model initialization device"
- ✅ Better: "EmbeddingsManager model initialization MPS CUDA"

### 5. **Use After Major Changes**
```bash
# After significant code changes
qdrant-rag:index_directory .

6. Leverage Project Context

# Searches current project by default
qdrant-rag:search "database connection"

# Search across all projects
qdrant-rag:search "database connection" cross_project=true

7. Common Search Patterns

Finding where something is defined:

"class MyClass definition"
"function process_data defined"
"where is CONFIG_FILE set"

Finding usage examples:

"how to use DataProcessor"
"examples calling api_endpoint"
"usage of decorator @cache"

Finding configuration:

"port configuration"
"timeout settings"
"environment variables for production"

Debugging:

"AttributeError chunk_id"
"ImportError module not found"
"where is logging configured"

8. Understanding Code Flow

You: "Trace the flow from HTTP request to database query"

Claude: [Uses multiple searches to trace the path]
[Builds a complete picture of the request flow]

Benefits of Using RAG with Claude Code

Instant Context: Claude understands your entire codebase structure
Hybrid Search (v0.1.4+): Combines keyword matching with semantic understanding for +30% better precision
Cross-File Intelligence: Understands relationships between files
Up-to-Date Information: Always searches current code, not outdated documentation
Project Isolation: Searches are scoped to your current project by default
Smart Ranking: Balances exact matches (function names) with conceptual similarity

When RAG is Most Valuable

Large Codebases: When manual searching becomes impractical
Unfamiliar Projects: When onboarding to a new codebase
Complex Architectures: When tracing through multiple layers
Debugging: When you need to find all usages of something
Refactoring: When you need to understand impact of changes
Documentation: When written docs are outdated or missing

The RAG server essentially gives Claude Code a semantic understanding of your entire codebase, making it much more effective at finding relevant code and understanding your project's architecture.

Navigation Menu

Repository navigation

rag-usage-examples.md

rag-usage-examples.md

Qdrant RAG Server - Practical Usage Examples with Claude Code

Table of Contents

0. Setting Correct Working Directory (v0.2.2+)

Natural Language Approach (No Configuration Required!)

For Indexing with Correct Context

1. Finding Implementation Details

2. Understanding Configuration

3. Debugging Issues

4. Finding Examples

Default (Hybrid) - Best for most searches

Keyword mode - When you need exact matches

Vector mode - When you need conceptual matches

Database files

API definitions

Infrastructure as Code

Specific project types

Automatically combines keyword and semantic search

Use when you know exact function/variable names

Use when searching for patterns or ideas

6. Leverage Project Context

7. Common Search Patterns

8. Understanding Code Flow

Benefits of Using RAG with Claude Code

When RAG is Most Valuable

FilesExpand file tree

rag-usage-examples.md

Latest commit

History

rag-usage-examples.md

File metadata and controls

Qdrant RAG Server - Practical Usage Examples with Claude Code

Table of Contents

0. Setting Correct Working Directory (v0.2.2+)

Natural Language Approach (No Configuration Required!)

For Indexing with Correct Context

1. Finding Implementation Details

2. Understanding Configuration

3. Debugging Issues

4. Finding Examples

Default (Hybrid) - Best for most searches

Keyword mode - When you need exact matches

Vector mode - When you need conceptual matches

Database files

API definitions

Infrastructure as Code

Specific project types

Automatically combines keyword and semantic search

Use when you know exact function/variable names

Use when searching for patterns or ideas

6. Leverage Project Context

7. Common Search Patterns

8. Understanding Code Flow

Benefits of Using RAG with Claude Code

When RAG is Most Valuable