Skip to content

ancoleman/qdrant-rag-mcp

BranchesTags

Repository files navigation

Qdrant RAG MCP Server

A context-aware Model Context Protocol (MCP) server that provides semantic search capabilities across your codebase using Qdrant vector database. Now with intelligent GitHub issue resolution (v0.3.0), GitHub Projects V2 management (v0.3.4), and hierarchical sub-issues support (v0.3.4.post4). Designed to work seamlessly with Claude Code.

Why MCP RAG? This server enables AI agents to efficiently work with entire codebases while using 95%+ fewer tokens. Learn how →

🌟 Features

🆕 GitHub Integration (v0.3.0) + Projects V2 (v0.3.4) + Sub-Issues (v0.3.4.post4)

  • 🤖 Intelligent Issue Resolution: RAG-powered GitHub issue analysis and automated fix generation
  • 🔄 End-to-End Workflows: Analyze issues → Generate fixes → Create PRs with dry-run safety
  • 📋 GitHub Projects V2 Management: Create projects, manage roadmaps, track progress with custom dashboards
  • 🎯 29 GitHub MCP Tools: Complete issue lifecycle + 8 project management tools + 5 sub-issues tools via natural language
  • 📑 Hierarchical Sub-Issues: Break down complex work with parent/child issue relationships
    • List, add, remove, create, and reorder sub-issues
    • Bulk add sub-issues to Projects V2 with smart field assignment
    • Re-parenting support for reorganizing work
    • Automatic issue number to ID conversion for intuitive usage
  • 💬 Issue Comments: Add comments to existing issues for workflow updates and collaboration
  • 🧠 Smart Project Assignment: RAG-enhanced field assignment based on issue content analysis
  • 📊 Project Templates: Pre-built templates for roadmaps, bug tracking, and feature planning
  • 🔐 Flexible Authentication: Personal Access Token and GitHub App support
  • 📊 RAG-Enhanced Analysis: Leverage full codebase search for issue understanding
  • 🛡️ Safety-First Design: Dry-run mode, file protection, rate limiting, and audit logging

🆕 Context Tracking (v0.3.1)

  • 👁️ Context Window Visibility: Monitor what Claude knows in the current session
  • 📊 Token Usage Tracking: Real-time estimates of context window consumption
  • ⚠️ Usage Warnings: Automatic alerts at 60% and 80% context usage
  • 📈 Session Timeline: Chronological view of all context-consuming operations
  • 💾 Session Persistence: Automatic saving for later analysis
  • 🔍 Session Viewer: Utility to analyze patterns across sessions

🆕 Specialized Embeddings (v0.3.3)

  • 🎯 Content-Type Specific Models: Different AI models optimized for different content types
    • Code: Programming-aware embeddings for 30-50% better code search relevance
    • Config: Structure-aware models for precise JSON/YAML/XML navigation
    • Documentation: Prose-optimized embeddings for natural documentation search
  • 🧠 Language-Specific Understanding: Python idioms, JavaScript patterns, and more
  • 🔥 Reduced Cross-Type Noise: Configs don't pollute code searches and vice versa
  • 🛡️ Thread-Safe & Reliable: Comprehensive thread safety with fallback protection
  • 🍎 Apple Silicon Optimized: Memory management with MPS acceleration

🆕 Progressive Context Management (v0.3.2)

  • 🎯 Multi-Level Context: File → Class → Method hierarchy for optimal token usage
  • 💰 50-70% Token Reduction: Get high-level overviews without sacrificing detail access
  • 🧠 Query Intent Detection: Automatically determines the right context level for your query
  • ⚡ Semantic Caching: Similar queries hit cache with 0.85 similarity threshold
  • 🔄 Drill-Down Options: Start with overview, expand to details as needed
  • 🏗️ Smart Structure Building: Automatically constructs code hierarchies from search results

Core RAG Capabilities

  • 🎯 Context-Aware: Automatically detects and scopes to your current project
  • 🔍 Hybrid Search: Combines semantic understanding with keyword matching for +30% better precision
  • 🧠 AST-Based Chunking: Structure-aware code parsing for Python, Shell, Go, JavaScript, and TypeScript (-40% tokens)
  • 🔗 Dependency-Aware Search: Automatically includes files that import or are imported by your search results (v0.1.9)
  • 📊 Enhanced Search Context: Get surrounding code chunks automatically for better understanding (v0.2.0)
  • 🎯 Multi-Signal Ranking: 5-factor ranking system for 45% better search precision (v0.2.1)
  • 📚 Documentation Indexing: Index and search markdown documentation files (v0.2.3)
  • ⚡ Smart Incremental Reindexing: Only process changed files for 90%+ faster reindexing (v0.2.4)
  • 📁 Multi-Project Support: Keep different projects' knowledge separate
  • 🚀 Fast Local Execution: Supports Apple Silicon MPS acceleration
  • 🔧 Specialized Indexers: Language-aware code parsing and config file understanding
  • 🔄 Optional Auto-Indexing: Keep your index up-to-date automatically as files change
  • 📊 Project-Aware Logging: Automatic log separation by project with rich debugging tools
  • 🏥 Health Monitoring: Built-in health checks with detailed system status

📚 Documentation Overview

Complete documentation for setting up and using the Qdrant RAG server with Claude Code.

🚀 Quick Start

Prerequisites

  • Claude Code CLI
  • Docker
  • Python 3.10+ with uv (ultraviolet package manager)

Installing uv (Ultraviolet)

This project uses uv for fast, reliable Python package management. If you don't have it installed:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with Homebrew
brew install uv

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Why uv? It's 10-100x faster than pip and provides better dependency resolution. Learn more

Installation

# 1. Clone the repository
git clone <repository-url> ~/mcp-servers/qdrant-rag
cd ~/mcp-servers/qdrant-rag

# 2. Run setup (starts Qdrant, installs dependencies)
./scripts/setup.sh

# 3. Install globally with context awareness (ONE TIME ONLY)
./install_global.sh

# That's it! The MCP server is now available in ALL projects

# 4. Test in any project
cd ~/any-project
claude
# Ask: "What's my current project context?"

Optional: Enable Auto-Indexing

# For current session only
export QDRANT_RAG_AUTO_INDEX=true
claude

# For permanent auto-indexing
echo 'export QDRANT_RAG_AUTO_INDEX=true' >> ~/.bashrc
# or for zsh users:
echo 'export QDRANT_RAG_AUTO_INDEX=true' >> ~/.zshrc

🔧 Working Directory Configuration (Important!)

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

Option 1: Natural Language (No Configuration Required!)

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!

Option 2: Environment Variable Configuration

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

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

Option 3: Command Line Argument

{
  "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. See Claude Code Configuration Guide for more details.

📖 Documentation

Core Guides

Reference Documentation

Technical Documentation

📋 Quick Decision Guide

I want to...

⚡ Quick Commands

Global Setup (One-Time)

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

Daily Usage

Manual Indexing (Default)

# 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?"

🆕 GitHub Issue Resolution (v0.3.0)

# 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

With Auto-Indexing

# 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

Reindexing (Clean Index)

# 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

Dependency-Aware Search (v0.1.9+)

# 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

✨ Key Features

Enhanced Indexing

  • 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

Custom File Patterns

  • 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"
  • Supported Patterns: Any glob pattern (*.ext, specific-file.ext, etc.)

AST-Based Chunking (v0.1.5+)

  • 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

Dependency-Aware Search (v0.1.9+)

  • 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

Hybrid Search (v0.1.4+)

  • 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

Enhanced Ranking (v0.2.1+)

  • 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)
  • Configurable Weights: Tune ranking for your workflow via server_config.json
  • 45% Better Precision: Measured improvement in search relevance
  • Visible Signals: See why results ranked as they did with ranking_signals
  • Configuration Guide: Learn how to customize ranking

Context Awareness

  • 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

Apple Silicon Optimization

  • 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

Project-Aware Logging

  • 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

Reliability & Security

  • 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

🔧 Architecture

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

Server Components

This project includes two distinct servers:

  1. 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

  2. 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

🎯 Use Cases

RAG-Powered Code Search

  • 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"

🆕 GitHub Issue Resolution (v0.3.0)

  • 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"

🏥 Health Monitoring

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

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

The health check reports:

  • 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

Connection Resilience

The server automatically retries failed operations:

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

📊 Logging & Debugging

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

View Logs

# 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

Log Location

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

Configuration

Control logging via environment variables:

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

🐛 Common Issues & Solutions

Issue Solution Reference
MCP not available globally Add with -s user flag MCP Scope Guide
Wrong project detected Check project markers Context-Aware Guide
MPS not working Use local mode MPS Guide
No search results Index first, check scope Troubleshooting

📈 Recent Improvements

🚀 v0.3.3 (Latest) - Specialized Embeddings & Critical Bug Fixes

  • ✅ Content-Type Specific Models: Different embedding models for different content types
    • Code: nomic-ai/CodeRankEmbed (768D) - Programming-aware embeddings for superior code search
    • Config: jinaai/jina-embeddings-v3 (1024D) - Structure-aware for JSON/YAML/XML files
    • Documentation: hkunlp/instructor-large (768D) - Prose-optimized for markdown/docs
    • General: sentence-transformers/all-MiniLM-L12-v2 (384D) - Backward compatibility
  • ✅ 30-50% Better Code Search: Programming-aware embeddings understand code context better
  • ✅ Unified Memory Management: Apple Silicon optimizations with conservative memory limits
  • ✅ Model Registry System: Central model management with compatibility checking
  • ✅ Enhanced Model Scripts: Improved download_models.sh with specialized model support
  • ✅ Critical Post-Release Fixes (v0.3.3.post1-4):
    • Fixed Critical Search Error: Payload type validation preventing search failures
    • Fixed Context Tracking Error: Configuration float handling for proper context tracking
    • 🔧 Fixed Dimension Mismatch: Resolved "Vector dimension error: expected dim: 768, got 384"
      • Root Cause: Thread safety issues causing CodeRankEmbed model eviction
      • Solution: Comprehensive thread safety + dimension-compatible fallback logic
      • Impact: Code files now always get correct 768D embeddings
  • ✅ Test Suite Reorganization: Clean categorization (unit/integration/performance/debug)
  • 📖 Memory Management Guide: Apple Silicon optimization details

v0.3.4 - GitHub Projects V2 Integration

  • ✅ GitHub Projects V2 Support: Full GraphQL API integration for modern project management
  • ✅ 8 New Project Tools: Create projects, add items, update fields, track progress
  • ✅ Smart Field Assignment: RAG-enhanced analysis automatically assigns priority/status/type
  • ✅ Project Templates: Pre-built templates for roadmaps, bug tracking, feature planning
  • ✅ Custom Field Support: Create and manage TEXT, NUMBER, DATE, SINGLE_SELECT fields
  • ✅ Progress Dashboards: Automatic completion metrics and status tracking
  • ✅ GraphQL Adapter Pattern: Clean separation preserving existing REST functionality
  • 📖 GitHub Projects Guide: Complete guide with examples and templates

v0.3.2 - Progressive Context Management

  • ✅ Multi-Level Context Retrieval: File → Class → Method hierarchy for 50-70% token reduction
  • ✅ Semantic Caching: Similar queries hit cache with 0.85 similarity threshold
  • ✅ Query Intent Detection: Automatically determines optimal context level
  • ✅ Configurable Scoring Pipeline: Modular scoring system with pluggable stages
  • ✅ Enhanced BM25 Tokenization: Code-specific preprocessing (camelCase, snake_case)
  • ✅ Linear Combination Scoring: More accurate hybrid search scores (0.6-0.9 vs 0.01-0.02)

v0.3.1 - Context Tracking

  • ✅ Context Window Visibility: Monitor what Claude knows in current session
  • ✅ Token Usage Tracking: Real-time estimates with warnings at 60%/80%
  • ✅ Session Timeline: Chronological view of all context-consuming operations
  • ✅ Session Persistence: Automatic saving for later analysis

v0.3.0 - GitHub Integration

  • ✅ 10 GitHub MCP Tools: Complete issue lifecycle management via Claude Code
  • ✅ RAG-Powered Issue Analysis: Leverage codebase search for intelligent issue understanding
  • ✅ Automated Fix Generation: Generate code fixes with confidence scoring and templates
  • ✅ End-to-End Workflows: Analyze → Generate → Create PR with dry-run safety
  • ✅ Issue Comments: Add comments to existing issues for workflow updates
  • ✅ Flexible Authentication: Personal Access Token and GitHub App support
  • ✅ HTTP API Testing: 10 new endpoints under /github/ for testing and integration
  • ✅ Safety-First Design: Dry-run mode, rate limiting, audit logging, file protection
  • ✅ Configuration Enhanced: Fixed environment variable resolution for better config management
  • 📖 GitHub Integration Guide: Comprehensive 700+ line setup and usage guide

v0.2.1 - Enhanced Ranking

  • ✅ Multi-Signal Ranking: Search results now ranked by 5 configurable factors
  • ✅ File Proximity Scoring: Boosts results from same/nearby directories
  • ✅ Dependency Distance: Prioritizes files with import relationships
  • ✅ Code Structure Similarity: Groups similar code patterns together
  • ✅ Recency Weighting: Recently modified files surface first
  • ✅ 45% Better Precision: Significant improvement in search relevance
  • 📖 Configuration Guide: Learn how to tune ranking for your workflow

v0.2.0 - Enhanced Context

  • ✅ Automatic Context Expansion: Get surrounding chunks with search results
  • ✅ Configurable Context: Control how much context with context_chunks parameter
  • ✅ Get File Chunks Tool: Retrieve complete files or specific chunk ranges
  • ✅ Doubled Chunk Sizes: Better semantic understanding (code: 3000, config: 2000 chars)
  • ✅ 60% Fewer Operations: Reduced need for follow-up grep/read operations

v0.1.9

  • ✅ Dependency-Aware Search: Automatically include files that import or are imported by search results
  • ✅ Dependency Graph Builder: Tracks bidirectional import/export relationships across codebase
  • ✅ Enhanced Code Understanding: See how code modules relate and depend on each other

v0.1.8

  • ✅ JavaScript/TypeScript Support: Full AST parsing for JS/TS files including React components
  • ✅ ES6 Module Support: Handles modern import/export syntax and arrow functions
  • ✅ Expanded Language Coverage: Now supports 5 languages with AST parsing

v0.1.7

  • ✅ Shell Script Indexing: Fixed default patterns to include .sh, .bash, .zsh files
  • ✅ Better Script Support: Improved handling of executable scripts

Previous Releases

  • ✅ AST-Based Chunking: Structure-aware parsing for better code understanding (v0.1.5)
  • ✅ Hybrid Search: Combined vector + keyword search for 30% better precision (v0.1.4)
  • ✅ Context-Aware System: Automatic project detection and scoping
  • ✅ Global Installation: Works across all projects with proper setup
  • ✅ MPS Support: Apple Silicon GPU acceleration for faster embeddings
  • ✅ Project-Aware Logging: Automatic log separation and rich debugging tools
  • ✅ Smart Reindexing: Clean index updates to prevent stale data

Happy coding with context-aware semantic search! 🎉

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

3 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 2

v0.3.4.post6 - Bug Fixes and Improvements Latest
Jun 13, 2025
+ 1 release

Packages

No packages published

Contributors 2

  •  
  •  

Languages