Qdrant RAG MCP Server

The MCP server needs to know your actual working directory to correctly detect projects. You have three options:

Simply tell Claude Code to set the working directory at the start of your session:

"Get current directory with pwd, export MCP_CLIENT_CWD to that value, then run health check"

This works immediately without any configuration changes!

In your Claude Code configuration (~/.claude-code/config.json):

{ "mcpServers": { "qdrant-rag": { "command": "python", "args": ](https://github.com/astral-sh/uv)["/path/to/qdrant-rag/src/qdrant_mcp_context_aware.py"], "env": { "MCP_CLIENT_CWD": "${workspaceFolder}" } } } }

{ "mcpServers": { "qdrant-rag": { "command": "python", "args": [ "/path/to/qdrant-rag/src/qdrant_mcp_context_aware.py", "--client-cwd", "${workspaceFolder}" ] } } }

Note: Without proper working directory setup, the server may detect the wrong project. The natural language approach (Option 1) is the quickest way to get started. SeeClaude Code Configuration Guidefor more details.

- Complete Setup & Usage Guide📚 - Comprehensive setup and usage instructions

- Includes:Changing Embedding Models- What to expect when switching models

- Why MCP RAG for Agentic Coding🤖 - Understand how MCP enables efficient AI coding
- Context Tracking Guide👁️ - Monitor and understand Claude's context window usage (v0.3.1)
- Qdrant Quick Reference- Quick commands for Qdrant operations
- MPS Quick Reference- Apple Silicon optimization guide
- Troubleshooting Guide- Common issues and solutions

- Enhanced RAG Guide- Technical implementation details
- Development Workflow Guide🛠️ - Efficient development patterns using RAG search
- Progressive Context Implementation🎯 - Multi-level context retrieval system (v0.3.2)
- AST Chunking Implementation- How AST-based chunking works (v0.1.5+)
- Hybrid Search Implementation- How hybrid search works (v0.1.4+)
- Enhanced Ranking Guide🎯 - Configure multi-signal ranking for better results (v0.2.1+)
- MCP Protocol Research- Research on MCP protocol and race conditions
- Installation Playbook- Detailed breakdown of how installation works
- Context Awareness Playbook- Deep dive into context detection

- Get started quickly→Complete Setup & Usage Guide
- 🆕 Automate GitHub issues→GitHub Integration Guide
- 🆕 Manage GitHub Projects→GitHub Projects Guide
- 🆕 Use progressive search efficiently→Progressive Search Usage Guide
- Load context fast in Claude→Quick Context Setup
- Use RAG in ALL my projects→MCP Scope Configuration Guide
- Understand project isolation→Context-Aware Guide
- See practical examples→Usage Examples
- Troubleshoot issues→Troubleshooting Guide
- Optimize for Apple Silicon→[MPS Quick Reference

# Run the installer - it handles everything ./install_global.sh

# Navigate to any project cd ~/projects/my-app claude # In Claude: # - Index: "Index all code files in this project" # - Search: "Find authentication functions" # - Context: "What's my current project context?"

# In Claude with GitHub integration: # - Setup: "Switch to repository owner/repo-name" # - Create: "Create a test issue with title 'Bug in login' and labels 'bug'" # - Analyze: "Analyze issue #123 using RAG search" # - Fix: "Generate fix suggestions for issue #123" # - Resolve: "Resolve issue #123 in dry-run mode"

🆕 GitHub Projects V2 Management (v0.3.4)

# In Claude with GitHub Projects: # - Create: "Create a roadmap project for Q1 2025" # - Template: "Create a bug tracking project from template" # - Add Items: "Add issue #123 to project with smart field assignment" # - Status: "Show project #1 status with completion metrics" # - Update: "Update issue #123 status to In Progress" # - Custom Fields: "Create a priority field with High/Medium/Low options"

🆕 Progressive Context Management (v0.3.2)

# In Claude - use progressive context for token efficiency: # - Overview: "What does the authentication system do?" (70% token reduction) # - Navigation: "Find the DatabaseManager class" (50% token reduction) # - Debugging: "Show me the bug in save_user function" (20% token reduction) # - Explicit: "Search for logging with context_level=file" # - Full detail: "Search for validate_user with progressive_mode=false" # The system automatically: # - Detects query intent (understanding vs debugging) # - Uses semantic cache for similar queries # - Provides drill-down options for deeper exploration

# Enable for this session export QDRANT_RAG_AUTO_INDEX=true cd ~/projects/my-app claude # Files are automatically indexed as you work! # Just search - no manual indexing needed

# Use reindex when files have been: # - Renamed or moved # - Deleted # - You see stale results # In Claude: # "Reindex this project" - Clears old data before indexing # "Reindex the src directory" - Clean reindex of specific directory # Regular index only adds new content # Reindex removes old + adds new content

# In Claude - search with dependencies: # "Search for 'validate_user' and include files that import it" # "Find 'database connection' including dependent files" # The include_dependencies parameter automatically: # - Finds files that import the search results # - Finds files imported by the search results # - Shows related code for better understanding

- Specialized Code Indexer: Language-specific parsing for 10+ programming languages
- Advanced Config Indexer: Support for JSON, XML, YAML, TOML, INI, ENV files
- Structure-Aware Chunking: Functions, classes, and config sections
- Rich Metadata: Line numbers, imports, dependencies, schema extraction

- Default Patterns: Automatically indexes common code, config, and doc files
- Custom Patterns: Specify exactly which file types to index
- Usage Examples:

# In Claude Code "Index directory with patterns .sql .graphql" "Index only Rust files: .rs .toml Cargo.lock" "Reindex with patterns .proto .pb.go for protobuf"

- Structure-Aware Parsing: Uses Abstract Syntax Trees to understand code structure
- Complete Code Units: Never splits functions or classes in the middle
- Multi-Language Support: Python, JavaScript/TypeScript, Shell scripts, and Go
- Hierarchical Metadata: Tracks relationships (module → class → method)
- 40-60% Fewer Chunks: More efficient token usage while preserving meaning
- Language-Specific Features:

- Python: Classes, methods, functions with decorators and docstrings
- JavaScript/TypeScript: ES6 modules, React components, arrow functions (v0.1.8)
- Shell: Function extraction with setup code preservation
- Go: Packages, structs, interfaces with visibility rules

- Automatic Dependency Inclusion: Find files that import or are imported by your search results
- Bidirectional Relationships: Tracks both imports and exports across the codebase
- Smart Scoring: Related files included with reduced scores to maintain relevance
- Import Resolution: Handles relative and absolute imports with path resolution
- Use Cases:

- Find all files using a specific function or class
- Understand the impact of changes by seeing dependent code
- Trace code flow through import chains
- Discover usage patterns across your project

- Three Search Modes: Hybrid (default), vector-only, keyword-only
- Smart Ranking: Combines exact keyword matches with semantic understanding
- Score Transparency: See individual contributions (vector_score, bm25_score)
- Automatic Mode: Hybrid search works out-of-the-box for best results

- 5 Ranking Signals: Combines multiple factors for optimal relevance

- Base score (semantic + keyword match)
- File proximity (same directory boost)
- Dependency distance (import relationships)
- Code structure similarity (functions, classes)
- Recency (recent modifications prioritized)

- Automatic Project Detection: Based on .git, package.json, etc.
- Project Isolation: Each project gets separate collections
- Smart Scoping: Searches default to current project only
- Cross-Project Option: Available when needed

- MPS Acceleration: Metal Performance Shaders support for M1/M2/M3 chips
- Local Mode: Native macOS execution for maximum performance
- Smart Caching: Efficient model storage and loading

- Automatic Log Separation: Logs organized by project, no mixing
- Structured JSON Format: Rich metadata for every operation
- Performance Tracking: Operation timing and success metrics
- Log Viewer Utility: Search, filter, and tail logs easily
- Configurable Levels: Debug specific operations as needed

- Connection Retry Logic: Automatic retry with exponential backoff
- Health Monitoring: Built-in health check for all services
- Progress Indicators: Track long-running operations
- Input Validation: Path traversal prevention and sanitization
- Better Error Handling: User-friendly messages with error codes

Claude Code ←→ MCP Protocol ←→ Context-Aware RAG Server ←→ Qdrant Vector DB ↓ Project Detection ↓ Project-Specific Collections ↓ Specialized Indexers (Code + Config)

This project includes two distinct servers:
-

MCP Server(src/qdrant_mcp_context_aware.py) - The main server

- Integrates directly with Claude Code via stdio
- No network port - communicates via stdin/stdout
- Started automatically by Claude Code when needed
- This is what you use for normal operation

HTTP Test Server(src/http_server.py) - Optional testing interface

- Provides REST API endpoints on port 8081
- Only for testing indexing/search without Claude Code
- Not required for normal Claude Code usage
- Useful for debugging and integration testing

- Semantic Code Search: "Find authentication functions similar to UserService"
- Configuration Discovery: "Where is the database connection configured?"
- Pattern Analysis: "Show me error handling patterns in this codebase"
- Code Understanding: "How does the logging system work?"
- Cross-Project Insights: "Show JWT implementations across all my projects"

- Intelligent Issue Analysis: "Analyze issue #123 to understand the bug and find related code"
- Automated Fix Generation: "Generate fix suggestions for the authentication issue in #456"
- Repository Management: "Switch to my backend repository and show open issues"
- Issue Workflow: "Create a test issue, analyze it, and generate a fix in dry-run mode"
- Pull Request Creation: "Create a PR to resolve the login bug with automated content"

The server includes a health check tool to monitor all services:

# In Claude Code "Check health status" "Run health check"

- Qdrant Connection: Status and collection count
- Embedding Model: Model name and dimension verification
- Disk Space: Available storage with warnings
- Memory Usage: System memory status (if psutil installed)
- Project Context: Current project information

The server automatically retries failed operations:

- Exponential backoff for transient failures
- Automatic reconnection to Qdrant
- Graceful degradation with clear error messages

The server includes comprehensive project-aware logging for debugging and monitoring.

# View logs for current project ./scripts/qdrant-logs # Follow logs in real-time ./scripts/qdrant-logs -f # Filter by log level ./scripts/qdrant-logs --level ERROR # Search logs ./scripts/qdrant-logs --search "index.*failed" # View logs for specific project ./scripts/qdrant-logs --project /path/to/project # Export logs for analysis ./scripts/qdrant-logs --export json > debug-logs.json

Logs are stored in~/.mcp-servers/qdrant-rag/logs/:

- global/- Server startup and non-project operations
- projects/- Separated by project with friendly names (e.g.,qdrant-rag_70e24d/)
- errors/- Critical errors across all projects

Control logging via environment variables:

export QDRANT_LOG_LEVEL=DEBUG # Set log level export QDRANT_LOG_DIR=/custom/path # Custom log directory