# 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 →](docs/reference/why-mcp-rag-agentic-coding.md)
## 🌟 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:
```bash
# 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](https://github.com/astral-sh/uv)
### Installation
```bash
# 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
```bash
# 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`):
```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
```json
{
"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](docs/claude-code-config-example.md) for more details.
## 📖 Documentation
### Core Guides
- **[Complete Setup & Usage Guide](docs/complete-setup-and-usage-guide.md)** 📚 - Comprehensive setup and usage instructions
- Includes: [Changing Embedding Models](docs/complete-setup-and-usage-guide.md#what-to-expect-changing-embedding-models) - What to expect when switching models
- **[GitHub Integration Guide](docs/github-integration-guide.md)** 🤖 - Setup and use GitHub issue resolution (v0.3.0)
- **[GitHub Projects Guide](docs/github-projects-guide.md)** 📋 - Manage GitHub Projects V2 with custom fields (v0.3.4)
- **[Context-Aware Guide](docs/context-aware-guide.md)** 🎯 - How the context-aware system works
- **[MCP Scope Configuration Guide](docs/mcp-scope-configuration-guide.md)** 🔧 - Understanding local vs global configuration
- **[Practical Usage Examples](docs/rag-usage-examples.md)** 💡 - Real-world examples with Claude Code
### Reference Documentation
- **[Why MCP RAG for Agentic Coding](docs/reference/why-mcp-rag-agentic-coding.md)** 🤖 - Understand how MCP enables efficient AI coding
- **[Context Tracking Guide](docs/reference/context-tracking-guide.md)** 👁️ - Monitor and understand Claude's context window usage (v0.3.1)
- **[Qdrant Quick Reference](docs/reference/qdrant-quick-reference.md)** - Quick commands for Qdrant operations
- **[MPS Quick Reference](docs/reference/mps-quick-reference.md)** - Apple Silicon optimization guide
- **[Troubleshooting Guide](docs/reference/troubleshooting.md)** - Common issues and solutions
### Technical Documentation
- **[Enhanced RAG Guide](docs/technical/enhanced-qdrant-rag-guide.md)** - Technical implementation details
- **[Development Workflow Guide](docs/development-workflow-guide.md)** 🛠️ - Efficient development patterns using RAG search
- **[Progressive Context Implementation](docs/technical/progressive-context/)** 🎯 - Multi-level context retrieval system (v0.3.2)
- **[AST Chunking Implementation](docs/technical/ast-chunking-implementation.md)** - How AST-based chunking works (v0.1.5+)
- **[Hybrid Search Implementation](docs/technical/hybrid-search-implementation.md)** - How hybrid search works (v0.1.4+)
- **[Enhanced Ranking Guide](docs/enhanced-ranking-guide.md)** 🎯 - Configure multi-signal ranking for better results (v0.2.1+)
- **[MCP Protocol Research](docs/technical/qdrant_mcp_research.md)** - Research on MCP protocol and race conditions
- **[Installation Playbook](docs/technical/installation-playbook.md)** - Detailed breakdown of how installation works
- **[Context Awareness Playbook](docs/technical/context-awareness-playbook.md)** - Deep dive into context detection
## 📋 Quick Decision Guide
### I want to...
- **Get started quickly** → [Complete Setup & Usage Guide](docs/complete-setup-and-usage-guide.md)
- **🆕 Automate GitHub issues** → [GitHub Integration Guide](docs/github-integration-guide.md)
- **🆕 Manage GitHub Projects** → [GitHub Projects Guide](docs/github-projects-guide.md)
- **🆕 Use progressive search efficiently** → [Progressive Search Usage Guide](docs/technical/progressive-context/progressive-search-usage-guide.md)
- **Load context fast in Claude** → [Quick Context Setup](docs/quick-context-setup.md)
- **Use RAG in ALL my projects** → [MCP Scope Configuration Guide](docs/mcp-scope-configuration-guide.md)
- **Understand project isolation** → [Context-Aware Guide](docs/context-aware-guide.md)
- **See practical examples** → [Usage Examples](docs/rag-usage-examples.md)
- **Troubleshoot issues** → [Troubleshooting Guide](docs/reference/troubleshooting.md)
- **Optimize for Apple Silicon** → [MPS Quick Reference](docs/reference/mps-quick-reference.md)
## ⚡ Quick Commands
### Global Setup (One-Time)
```bash
# Run the installer - it handles everything
./install_global.sh
```
### Daily Usage
**Manual Indexing (Default)**
```bash
# 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)**
```bash
# 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)**
```bash
# 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)**
```bash
# 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**
```bash
# 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)**
```bash
# 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+)**
```bash
# 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**:
```bash
# 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](docs/enhanced-ranking-guide.md)**: 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:
```bash
# 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
```bash
# 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:
```bash
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](mcp-scope-configuration-guide.md) |
| Wrong project detected | Check project markers | [Context-Aware Guide](context-aware-guide.md) |
| MPS not working | Use local mode | [MPS Guide](mps-quick-reference.md) |
| No search results | Index first, check scope | [Troubleshooting](claude-code-troubleshooting.md) |
## 📈 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](docs/technical/memory-optimization-recommendations.md)**: 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](docs/github-projects-guide.md)**: 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](docs/github-integration-guide.md)**: 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](docs/enhanced-ranking-guide.md)**: 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! 🎉
