Context MCP Server

Context is a personal, offline-first AI coding assistant powered by the Model Context Protocol (MCP). It provides semantic code search, AST analysis, and cross-language code understanding with GPU-accelerated vector embeddings.

✨ Key Features

🚀 Ultra-fast startup: <1 second (97.5% faster than v1.0)
⚡ GPU acceleration: 20-40x performance improvement (2,363.7 embeddings/sec)
🔍 Semantic code search: Vector-based similarity search across your codebase
🌳 AST analysis: Multi-language parsing for Python, JavaScript, TypeScript, Java, C++, Go, Rust
🔗 Cross-language analysis: Detect patterns and similarities across different languages
🤖 MCP integration: Native support for Claude Code CLI via HTTP transport (stdio also supported)
🔒 Privacy-first: Runs completely offline, your code never leaves your machine
✨ NEW: Multi-project workspace support: Index and search across multiple projects simultaneously

📊 Performance Highlights

Metric	Performance
Startup Time	<1 second (down from 40+ seconds)
Embedding Generation	2,363.7 embeddings/sec (GPU)
First Query Latency	11.6ms
GPU Acceleration	20-40x faster than CPU
Vector Dimensions	768 (Docker: Google text-embedding-004); 384 (local dev: all-MiniLM-L6-v2)

🆕 Latest Changes and Fixes

v2.0.0 - Multi-Project Workspace Support (2025-11-11) 🎉

Major Features:

🏢 Workspace Architecture: Index and search across multiple projects simultaneously (frontend, backend, shared libraries, etc.)
🔗 Project Relationships: Track dependencies between projects with automatic relationship discovery
🔍 Cross-Project Search: Search with relationship-aware ranking (dependencies rank higher)
📊 Per-Project Collections: Isolated vector storage for each project (no cross-contamination)
⚡ Parallel Indexing: Index multiple projects concurrently (5x speedup)
🛠️ CLI Commands: 8 new commands for workspace management (context workspace init, add-project, list, index, etc.)
📦 MCP Tools: 7 new/updated MCP tools for workspace support
🔄 Migration Script: Automated v1 → v2 migration with rollback support

See WORKSPACE_QUICKSTART.md for details.

Previous Changes

HTTP transport (Docker) binding fix: server now binds to 0.0.0.0 inside the container; access via http://localhost:8000/. MCP HTTP endpoint is at path /.
Qdrant collection stats compatibility: robust parsing across API versions and single/multi‑vector configurations.
AST vector dimension auto‑migration: AST collections are automatically recreated when embedding dimensions change (e.g., 384 → 768); data is repopulated during indexing.
Verification: Claude CLI shows "Connected"; Docker containers healthy; 52/53 MCP tools passing (one prompt generation tool intentionally skipped).

✅ Verification Status and Testing Matrix

Verification Status: 52/53 tools passing (1 skipped: prompt_generate)

Category	Tools	Status
Health Tools	3	Pass
Capability Tools	2	Pass
Indexing Tools	4	Pass
Vector Tools	4	Pass
Search Tools	6	Pass
Pattern Search Tools	2	Pass
AST Search Tools	5	Pass
Cross-Language Analysis Tools	3	Pass
Dependency Analysis Tools	4	Pass
Query Understanding Tools	6	Pass
Indexing Optimization Tools	6	Pass
Prompt Tools	4	3 Pass / 1 Skip
Context-Aware Prompt Tools	3	Pass

Note: All tests were executed via the MCP HTTP transport against the Docker deployment. The single skipped tool (prompt_generate) is intentionally excluded from CI-style verification.

🏗️ Architecture

Core Components

MCP Server: FastMCP-based server implementing Model Context Protocol
Workspace Manager: Multi-project orchestration with relationship tracking (NEW v2.0)
Vector Database: Qdrant for vector embeddings storage (768d in Docker; 384d in local dev)
Embedding Model: Google text-embedding-004 (768d) in Docker; sentence-transformers all-MiniLM-L6-v2 (384d) for local dev
Cache Layer: Redis for AST and query result caching
AST Parser: Tree-sitter for multi-language syntax analysis
Metadata Store: PostgreSQL (optional, for file indexing history)
Relationship Graph: NetworkX-based dependency and similarity tracking (NEW v2.0)

Technology Stack

┌─────────────────────────────────────────────────┐
│           Claude Code CLI / MCP Client          │
└─────────────────┬───────────────────────────────┘
                  │ MCP Protocol (HTTP or stdio)
┌─────────────────▼───────────────────────────────┐
│              Context MCP Server                 │
│  ┌──────────────────────────────────────────┐  │
│  │  FastMCP (13+ Tool Categories)           │  │
│  │  - Health & Capabilities                 │  │
│  │  - Indexing & Vector Operations          │  │
│  │  - Semantic & Pattern Search             │  │
│  │  - AST & Cross-language Analysis         │  │
│  │  - Dependency & Query Analysis           │  │
│  └──────────────────────────────────────────┘  │
└─────────────────┬───────────────────────────────┘
                  │
    ┌─────────────┼─────────────┬─────────────┐
    │             │             │             │
┌───▼────┐  ┌────▼─────┐  ┌───▼────┐  ┌─────▼──────┐
│ Qdrant │  │  Redis   │  │PyTorch │  │ PostgreSQL │
│ Vector │  │  Cache   │  │  GPU   │  │  Metadata  │
│   DB   │  │  Layer   │  │ Accel. │  │ (Optional) │
└────────┘  └──────────┘  └────────┘  └────────────┘

🏭 Deployment Architecture

Hybrid Architecture (Current Production Setup)

Context MCP Server uses a hybrid deployment architecture that separates concerns between indexing/storage and MCP client interface:

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code CLI                          │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Protocol (HTTP)
                         │ http://localhost:8000/
┌────────────────────────▼────────────────────────────────────┐
│      Docker MCP HTTP Server (0.0.0.0:8000 → host:8000)       │
│  - Serves MCP tools to Claude CLI                             │
│  - Persistent FastMCP over HTTP at path '/'                   │
│  - Requires Accept: application/json, text/event-stream       │
└─────────────────────────────────────────────────────────────┘

Why This Architecture?

Separation of Concerns:

Docker Container: Handles heavy lifting (indexing, embeddings, storage)
Local MCP Server: Lightweight interface for Claude CLI integration
Independent Operation: Indexing runs continuously regardless of CLI usage

Benefits:

Reliability: Docker services restart automatically, ensuring uptime
Performance: Indexing doesn't block MCP tool calls
Monitoring: Prometheus/Grafana track indexing progress and health
Scalability: Can scale Docker services independently

Port Configuration

Port 8000 is published from the Docker container to the host:

Service	Bind Address	Purpose	Access
Docker MCP Server	`0.0.0.0:8000`	MCP HTTP endpoint (path `/`)	Host: http://localhost:8000/

Note: Do not run a separate local MCP HTTP server on 127.0.0.1:8000 at the same time, or Docker's port mapping will conflict.

Deployment Status

✅ Phase 1 (Qdrant-only mode): COMPLETE

151 files successfully indexed
Semantic search functional with 768-dimensional Google embeddings
Qdrant collection: context_vectors with 151 points
Average search latency: <50ms

✅ Phase 2 (PostgreSQL integration): COMPLETE

PostgreSQL running and healthy in Docker
Metadata persistence working (confirmed via logs)
File indexing history tracked in database
No additional setup required

🚀 System Status: PRODUCTION READY

📋 Requirements

System Requirements

Python: 3.11 or higher
GPU: NVIDIA GPU with CUDA support (recommended for GPU acceleration)
Memory: 8GB RAM minimum, 16GB recommended
Storage: 2GB for dependencies and models

Required Services

Service	Port	Purpose	Required
Redis	6379	AST and query caching	✅ Yes
Qdrant	6333	Vector embeddings storage	✅ Yes
PostgreSQL	5432	File indexing metadata	⚠️ Optional

Note: PostgreSQL is optional and only used for tracking file indexing history. All core MCP functionality works without it.

GPU Acceleration (Optional but Recommended)

For 20-40x performance improvement:

NVIDIA GPU with CUDA support
CUDA 12.1 or higher
6GB+ VRAM recommended

🚀 Installation

1. Clone the Repository

git clone https://github.com/Kirachon/Context.git
cd Context

2. Install Python Dependencies

# Install base requirements
pip install -r requirements/base.txt

# For GPU acceleration (recommended)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# Verify GPU is detected
python -c "import torch; print(f'GPU Available: {torch.cuda.is_available()}')"

3. Install Tree-sitter for AST Parsing

pip install "tree_sitter==0.21.3" "tree_sitter_languages==1.10.2"

Verify installation:

python3 -c "
from tree_sitter_languages import get_language
languages = ['python', 'javascript', 'typescript', 'java', 'cpp', 'go', 'rust']
for lang in languages:
    try:
        get_language(lang)
        print(f'✓ {lang}: OK')
    except Exception as e:
        print(f'✗ {lang}: {e}')
"

For detailed installation instructions and troubleshooting, see Tree-sitter Installation Guide.

4. Start Required Services

Option A: Using Docker Compose (Recommended)

cd deployment/docker
docker-compose up -d redis qdrant

# Optional: Start PostgreSQL
docker-compose up -d postgres

Option B: Manual Installation

Redis:

# Ubuntu/Debian
sudo apt-get install redis-server
sudo systemctl start redis

# macOS
brew install redis
brew services start redis

# Windows
# Download from https://redis.io/download

Qdrant:

# Using Docker
docker run -d -p 6333:6333 qdrant/qdrant

# Or download from https://qdrant.tech/documentation/quick-start/

5. Configure Environment Variables

Create a .env file in the project root:

# MCP Server Configuration
MCP_ENABLED=true
MCP_SERVER_NAME=Context
MCP_SERVER_VERSION=0.1.0
LOG_LEVEL=INFO
LOG_FORMAT=json

# Python Path
PYTHONPATH=D:\GitProjects\Context  # Adjust to your path

# Database URLs
REDIS_URL=redis://localhost:6379
QDRANT_URL=http://localhost:6333
DATABASE_URL=postgresql://context:password@localhost:5432/context_dev  # Optional
POSTGRES_ENABLED=false  # Optional; when false, server runs in vector-only mode


# GPU Configuration (optional)
CUDA_VISIBLE_DEVICES=0  # Set to specific GPU ID if you have multiple GPUs

6. Verify Installation

Run the smoke tests:

pytest tests/integration/test_tree_sitter_smoke.py -v

Test MCP server startup:

python -m src.mcp_server.stdio_full_mcp
# Should start in <1 second
# Press Ctrl+C to stop

🔧 Configuration for Claude Code CLI

Global MCP Configuration

Context MCP Server supports two transport modes:

Option A: HTTP Transport (Recommended for Production)

Benefits: Persistent server, better reliability, shared resources across projects

Location: C:\Users\<username>\.claude.json (Windows) or ~/.claude.json (macOS/Linux)

{
  "mcpServers": {
    "context": {
      "type": "http",
      "url": "http://localhost:8000/"
    }
  }
}

Start the HTTP server (Docker, recommended):

cd deployment/docker
docker-compose up -d context-server
# Container binds to 0.0.0.0:8000; access at http://localhost:8000/

Optional (local; do not run at the same time as Docker on port 8000):

python start_http_server.py --host 127.0.0.1 --port 8000

Note: MCP HTTP endpoint is at path / and clients must send header Accept: application/json, text/event-stream.

Option B: Stdio Transport (Legacy)

Benefits: Simpler setup, no persistent server needed

Location: C:\Users\<username>\.claude.json (Windows) or ~/.claude.json (macOS/Linux)

{
  "mcpServers": {
    "context": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "src.mcp_server.stdio_full_mcp"],
      "env": {
        "PYTHONPATH": "D:\\GitProjects\\Context",
        "MCP_ENABLED": "true",
        "MCP_SERVER_NAME": "Context",
        "MCP_SERVER_VERSION": "0.1.0",
        "LOG_LEVEL": "INFO",
        "LOG_FORMAT": "json"
      },
      "cwd": "D:\\GitProjects\\Context"
    }
  }
}

Adjust paths to match your installation directory.

Note: Stdio transport spawns a new process for each Claude CLI session, which can be slower and less reliable than HTTP transport.

Verify Connection

# Check MCP server status
claude mcp list

# Should show:
# ✓ context - Connected

Troubleshooting

If you see "Failed to reconnect":

Ensure all required services are running (Redis, Qdrant)
Check that Python path is correct in configuration
Verify PYTHONPATH points to project root
Restart Claude Code CLI completely

For detailed setup guide, see:

Claude Code CLI Setup - Complete configuration guide

🛠️ MCP Tools Available

Context MCP server provides 13 active tool categories for AI-assisted coding:

1. Health & Capabilities

health_check - Check server health and service status
get_capabilities - List all available MCP tools and features
server_info - Get server metadata and version

2. Indexing Tools

index_file - Index a single file for search
index_directory - Recursively index a directory
get_indexing_status - Check indexing progress
remove_file - Remove file from index

3. Vector Operations

get_vector_stats - Get vector database statistics
get_embedding_stats - Get embedding model performance metrics
list_collections - List all Qdrant collections
get_collection_stats - Get statistics for a specific collection

4. Semantic Search

semantic_search - Search code by meaning/intent
search_by_file_type - Filter search by language
search_by_date_range - Search files by modification date
provide_search_feedback - Improve search ranking over time

5. Pattern Search

pattern_search - Search for code patterns (regex, wildcards)
find_similar_code - Find code similar to a given snippet

6. AST Search

ast_search - Search by code structure (functions, classes, imports)
find_symbol - Find specific symbols across codebase
find_class - Find class definitions
find_imports - Find import statements

7. Cross-Language Analysis

analyze_dependencies - Analyze code dependencies
detect_patterns - Detect design patterns across languages
find_similar_across_languages - Find similar code in different languages

8. Dependency Analysis

analyze_imports - Analyze import dependencies
find_circular_dependencies - Detect circular dependencies
generate_dependency_graph - Create dependency visualization

9. Query Understanding

classify_query - Classify user query intent
extract_query_entities - Extract entities from queries
suggest_query_refinements - Suggest query improvements

10. Indexing Optimization

optimize_index - Optimize vector index performance
rebuild_index - Rebuild index from scratch
get_index_stats - Get index statistics

11. Prompt Tools

enhance_prompt - Enhance user prompts with context
generate_prompt_template - Generate prompt templates

12. Context-Aware Prompts

get_relevant_context - Get relevant code context for prompts
summarize_codebase - Generate codebase summaries

13. Result Presentation

format_search_results - Format search results for display
generate_code_snippets - Generate formatted code snippets

💡 Usage Examples

Example 1: Semantic Code Search

# Ask Claude Code CLI:
"Use the Context MCP server to search for authentication logic in my codebase"

# Claude will invoke:
# semantic_search(query="authentication login user verification", limit=10)

Example 2: Find All Classes

# Ask Claude Code CLI:
"Show me all class definitions in the project"

# Claude will invoke:
# ast_search(query="class definitions", search_scope="classes", limit=50)

Example 3: Cross-Language Pattern Detection

# Ask Claude Code CLI:
"Find all singleton pattern implementations across Python and JavaScript"

# Claude will invoke:
# detect_patterns(pattern_type="singleton", languages=["python", "javascript"])

Example 4: Index New Files

# Ask Claude Code CLI:
"Index the new files in the src/api directory"

# Claude will invoke:
# index_directory(path="src/api", recursive=true)

🚀 Optimization Features

Lazy Loading Architecture

Context MCP server uses lazy loading to achieve <1 second startup time:

Deferred imports: Heavy libraries (torch, sentence_transformers) loaded on first use
Lazy service initialization: Qdrant and embeddings initialized when first accessed
Auto-initialization: Services automatically start when needed

Performance Impact:

Startup: 40+ seconds → <1 second (97.5% improvement)
First query: Adds ~2-3 seconds for model loading (one-time cost)
Subsequent queries: Full speed (11.6ms latency)

GPU Acceleration

When NVIDIA GPU is available:

Embedding generation: 20-40x faster than CPU
Batch processing: 2,363.7 embeddings/sec
Memory efficient: Automatic batch sizing based on VRAM

Setup:

# Install PyTorch with CUDA support
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# Verify GPU detection
python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}')"
python -c "import torch; print(f'GPU Name: {torch.cuda.get_device_name(0)}')"

Caching Strategy

Redis: Caches AST parse results and query results
TTL: Configurable cache expiration (default: 1 hour)
Invalidation: Automatic cache invalidation on file changes

🔍 Troubleshooting

Understanding the Hybrid Architecture

The Context MCP Server uses a two-tier architecture:

Docker Container (context-server): Production indexing pipeline
- Runs on 0.0.0.0:8000 (accessible externally)
- Handles file monitoring, indexing, and storage
- Uses Google Gemini embeddings (768 dimensions)
- Stores vectors in Qdrant; metadata optionally in PostgreSQL (disabled by default)
Local MCP HTTP Server: Claude CLI interface
- Runs on 127.0.0.1:8000 (localhost only)
- Serves MCP tools to Claude Code CLI
- Queries Docker services for data
- Uses sentence-transformers embeddings (384 dimensions) for local queries

Both services run on port 8000 but on different network interfaces, so they don't conflict.

Verifying System Status

Check Docker Services

# Check all Docker containers
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# Expected output:
# context-server      Up X hours    0.0.0.0:8000->8000/tcp
# context-qdrant      Up X hours    0.0.0.0:6333-6334->6333-6334/tcp
# context-postgres    Up X hours    0.0.0.0:5432->5432/tcp
# context-redis       Up X hours    0.0.0.0:6379->6379/tcp

Check Qdrant Vector Database

# Check Qdrant health
curl -s http://localhost:6333/collections

# Check vector count
curl -s -X POST "http://localhost:6333/collections/context_vectors/points/count" \
  -H "Content-Type: application/json" \
  -d '{"exact": true}'

# Expected: {"result":{"count":151},"status":"ok","time":0.000123}

Check Local MCP Server

# Check if local MCP server is running
netstat -ano | findstr :8000

# Expected: Two entries (Docker on 0.0.0.0:8000, local on 127.0.0.1:8000)

Test Semantic Search (Docker Container)

# Test semantic search inside Docker container
docker exec context-server python -c "
import asyncio, json
from src.vector_db.qdrant_client import connect_qdrant
from src.vector_db.embeddings import generate_code_embedding
from src.vector_db.vector_store import search_vectors

async def test():
    await connect_qdrant()
    query = 'authentication login'
    emb = await generate_code_embedding(code=query, file_path='query', language='text')
    results = await search_vectors(query_vector=emb, limit=5)
    print(json.dumps(results, indent=2))

asyncio.run(test())
"

# Expected: JSON array with 5 search results and similarity scores

Common Issues

1. "Failed to reconnect to context" in Claude Code CLI

Symptoms: MCP server shows as disconnected in Claude Code CLI

Solutions:

# 1. Verify services are running
docker ps  # Check Redis and Qdrant are up

# 2. Test MCP server manually
python -m src.mcp_server.stdio_full_mcp

# 3. Check configuration
cat ~/.claude.json  # Verify paths are correct

# 4. Restart Claude Code CLI completely
# Close and reopen the application

2. Slow Startup (>5 seconds)

Cause: Lazy loading not working properly

Solutions:

# Check if heavy imports are at module level
grep -r "^import torch" src/  # Should be inside functions, not at top

# Verify lazy loading is enabled
grep "lazy" src/mcp_server/stdio_full_mcp.py

3. GPU Not Detected

Symptoms: Falling back to CPU, slow embedding generation

Solutions:

# Verify CUDA installation
nvidia-smi

# Check PyTorch CUDA support
python -c "import torch; print(torch.cuda.is_available())"

# Reinstall PyTorch with CUDA
pip uninstall torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

4. PostgreSQL Connection Failed

PostgreSQL is optional and disabled by default. When POSTGRES_ENABLED=false, the server runs in vector-only mode and will not attempt any database connections.

If you see connection errors in logs, set POSTGRES_ENABLED=false in your .env and restart the server.
To enable metadata persistence, set POSTGRES_ENABLED=true and provide a valid DATABASE_URL.

If you need PostgreSQL:

# Start PostgreSQL
docker-compose up -d postgres

# Create database and user
psql -U postgres
CREATE USER context WITH PASSWORD 'password';
CREATE DATABASE context_dev OWNER context;
GRANT ALL PRIVILEGES ON DATABASE context_dev TO context;

5. Vector Dimension Mismatch

Symptoms: Search returns no results or errors about dimension mismatch

Cause: Docker container uses 768‑dim Google embeddings, local server uses 384‑dim sentence‑transformers

Understanding the Difference:

Docker Container (Production): Uses Google Gemini text-embedding-004 model (768 dimensions)
- Higher quality embeddings
- Requires Google API key
- Used for production indexing
Local MCP Server (Development): Uses all-MiniLM-L6-v2 model (384 dimensions)
- Runs completely offline
- Faster for local testing
- Used for MCP tool queries

Solutions:

Auto-fix for AST collections: As of the latest release, AST collections (context_symbols, context_classes, context_imports) auto-detect vector dimension changes and will be safely recreated with the correct size during indexing. No manual action is required—just re-run AST indexing or let background indexing repopulate.

Option A: Use Docker for Everything (Recommended)

# All indexing and search happens in Docker with 768-dim embeddings
# Local MCP server just forwards requests to Docker services
# No configuration needed - this is the default setup

Option B: Align Local Server to Docker

# Configure local server to use Google embeddings (768-dim)
# Edit .env file:
EMBEDDING_PROVIDER=google
GOOGLE_API_KEY=your_api_key_here
QDRANT_VECTOR_SIZE=768

# Restart local MCP server

Option C: Rebuild Docker with Local Embeddings

# Rebuild Docker to use 384-dim sentence-transformers
# Edit docker-compose.yml environment:
EMBEDDING_PROVIDER=sentence_transformers
QDRANT_VECTOR_SIZE=384

# Rebuild and restart
docker-compose down
docker-compose up -d --build

6. Indexing Not Processing Files

Symptoms: Files queued but not indexed, queue size stays at 189

Check Indexing Status:

# Via Docker container
docker exec context-server python -c "
from src.indexing.queue import indexing_queue
print(f'Queue size: {indexing_queue.qsize()}')
print(f'Processed: {indexing_queue.processed_count}')
print(f'Failed: {indexing_queue.failed_count}')
"

Common Causes:

Qdrant not running:

# Check Qdrant status
curl -s http://localhost:6333/collections

# Start Qdrant if needed
docker-compose up -d qdrant

Docker Desktop not running (Windows):

# Check Docker status
docker ps

# If error: Start Docker Desktop application

File monitor not started:

# Check Docker logs
docker logs context-server | grep "File monitor"

# Expected: "File monitor started for paths: [...]"

7. Redis Connection Failed

Symptoms: "Connection refused" on port 6379

Solutions:

# Start Redis
docker-compose up -d redis

# Or install locally
sudo systemctl start redis  # Linux
brew services start redis   # macOS

6. Qdrant Connection Failed

Symptoms: "Connection refused" on port 6333

Solutions:

# Start Qdrant
docker-compose up -d qdrant

# Or run standalone
docker run -d -p 6333:6333 qdrant/qdrant

Debug Mode

Enable detailed logging:

# Set environment variable
export LOG_LEVEL=DEBUG

# Or in .env file
LOG_LEVEL=DEBUG
LOG_FORMAT=json

# Run MCP server
python -m src.mcp_server.stdio_full_mcp

Getting Help

Documentation: See docs/ directory for detailed guides
Issues: Open an issue on GitHub
Logs: Check logs/ directory for error details

📊 Monitoring & Production Readiness

Production Status Dashboard

The Docker deployment includes a complete monitoring stack:

# Access monitoring dashboards
Grafana:     http://localhost:3000     # Metrics visualization
Prometheus:  http://localhost:9090     # Metrics collection
Qdrant UI:   http://localhost:6333/dashboard  # Vector database UI

Health Check Endpoints

# Docker container health
curl http://localhost:8000/health

# Qdrant health
curl http://localhost:6333/collections

# PostgreSQL health (via Docker)
docker exec context-postgres pg_isready -U context

# Redis health
docker exec context-redis redis-cli ping

Production Readiness Checklist

✅ Phase 1 (Vector Storage): COMPLETE

Qdrant running and accessible
151 files successfully indexed
Semantic search functional (verified with test queries)
Vector collection: context_vectors with 768 dimensions
Average search latency: <50ms

✅ Phase 2 (Metadata Persistence): COMPLETE

PostgreSQL running and healthy
Metadata persistence working (confirmed via logs)
File indexing history tracked
Database connection stable

✅ Phase 3 (MCP Integration): COMPLETE

Local MCP HTTP server running on 127.0.0.1:8000
Claude Code CLI configuration verified
MCP initialize handshake successful
All MCP tools registered and accessible

✅ Phase 4 (Monitoring): COMPLETE

Prometheus collecting metrics
Grafana dashboards configured
Alert manager configured
Health check endpoints operational

🚀 System Status: PRODUCTION READY

Key Metrics to Monitor

Indexing Performance:
- Files processed per minute
- Queue size (should decrease over time)
- Failed indexing attempts
Search Performance:
- Query latency (p50, p95, p99)
- Search result relevance scores
- Cache hit rate
Resource Usage:
- Qdrant memory usage
- PostgreSQL connection pool
- Redis memory usage
- GPU utilization (if available)
System Health:
- Docker container uptime
- Service restart count
- Error rate in logs

Viewing Logs

# Docker container logs
docker logs context-server -f --tail 100

# Filter for errors
docker logs context-server 2>&1 | grep ERROR

# Filter for indexing progress
docker logs context-server 2>&1 | grep "Indexed file"

# Check specific service logs
docker logs context-qdrant -f
docker logs context-postgres -f
docker logs context-redis -f

Performance Optimization Tips

For Large Codebases (>1000 files):
- Increase Qdrant memory limit in docker-compose.yml
- Enable PostgreSQL connection pooling
- Adjust indexing batch size
For GPU Acceleration:
- Ensure CUDA drivers are up to date
- Monitor GPU memory usage
- Adjust batch size based on VRAM
For Network Performance:
- Use local Docker network for service communication
- Enable Redis caching for frequent queries
- Consider Qdrant replication for high availability

🧪 Testing

Run All Tests

# Run full test suite
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test categories
pytest tests/unit/ -v                    # Unit tests
pytest tests/integration/ -v             # Integration tests
pytest tests/e2e/ -v                     # End-to-end tests

Test Specific Components

# Tree-sitter smoke tests
pytest tests/integration/test_tree_sitter_smoke.py -v

# MCP server tests
pytest tests/integration/test_mcp_server.py -v

# Vector search tests
pytest tests/integration/test_vector_search.py -v

# AST indexer tests
pytest tests/unit/test_ast_indexer.py -v

Performance Tests

# Benchmark embedding generation
python tests/performance/benchmark_embeddings.py

# Benchmark startup time
python tests/performance/benchmark_startup.py

# Benchmark search performance
python tests/performance/benchmark_search.py

🏗️ Development

Project Structure

Context/
├── src/
│   ├── mcp_server/          # MCP server implementation
│   │   ├── mcp_app.py       # FastMCP application
│   │   ├── stdio_full_mcp.py # Stdio transport entry point
│   │   └── tools/           # MCP tool implementations
│   ├── vector_db/           # Vector database operations
│   │   ├── embeddings.py    # Embedding generation (GPU accelerated)
│   │   ├── qdrant_client.py # Qdrant client wrapper
│   │   └── vector_store.py  # Vector storage operations
│   ├── indexing/            # File indexing
│   │   ├── file_indexer.py  # File metadata indexing
│   │   ├── ast_indexer.py   # AST parsing and indexing
│   │   └── models.py        # Database models
│   ├── search/              # Search implementations
│   │   ├── semantic_search.py   # Vector-based search
│   │   ├── pattern_search.py    # Pattern matching
│   │   └── ast_search.py        # AST-based search
│   ├── parsing/             # Code parsing
│   │   └── parser.py        # Tree-sitter parser wrapper
│   └── config/              # Configuration
│       └── settings.py      # Pydantic settings
├── tests/                   # Test suite
├── deployment/              # Deployment configurations
│   └── docker/              # Docker compose files
├── docs/                    # Documentation
├── scripts/                 # Utility scripts
└── requirements/            # Python dependencies

Development Setup

# Install development dependencies
pip install -r requirements/dev.txt

# Install pre-commit hooks
pre-commit install

# Run linters
black src/ tests/
ruff check src/ tests/
mypy src/

# Run formatters
isort src/ tests/

Adding New MCP Tools

Create tool file in src/mcp_server/tools/
Implement tool function with @mcp.tool() decorator
Register tool in src/mcp_server/mcp_app.py
Add tests in tests/integration/
Update documentation

Example:

# src/mcp_server/tools/my_tool.py
from fastmcp import FastMCP

def register_my_tools(mcp: FastMCP):
    @mcp.tool()
    async def my_tool(query: str) -> dict:
        """Tool description for AI clients."""
        # Implementation
        return {"result": "success"}

Contributing

Fork the repository
Create a feature branch (git checkout -b feat/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feat/amazing-feature)
Open a Pull Request

Commit Convention: Use Conventional Commits

feat: - New features
fix: - Bug fixes
docs: - Documentation changes
perf: - Performance improvements
refactor: - Code refactoring
test: - Test additions/changes
chore: - Maintenance tasks

📚 Documentation

Quick Start Guides

🚀 Quick Start Guide - Deploy in under 5 minutes
🔧 Deployment Guide - Detailed deployment instructions
📋 Production Readiness - Deployment checklist

Setup Guides

Claude Code CLI Setup - Configure for Claude Code CLI
Tree-sitter Installation - AST parser setup

Architecture & Technical Docs

Architecture Documentation - System architecture
Technical Specifications - Technical details

Feature Guides

Performance Docs

Phase 1 Performance Benchmarks

CI Workflows (Smoke/Flags)

Staging Compose Smoke: .github/workflows/staging_compose_smoke.yml (runs on push/PR)
Feature Flags Rollout Smoke: .github/workflows/staging_flags_rollout.yml (workflow_dispatch)
Production Smoke: .github/workflows/production_smoke.yml (workflow_dispatch, protected env)

Troubleshooting Guides

PostgreSQL Analysis - PostgreSQL setup and analysis
MCP Startup Optimization - Startup performance guide
GPU Optimization - GPU acceleration setup

🤝 MCP Client Integration

Context MCP server is designed for Claude Code CLI via stdio transport:

MCP Client	Platform	Status	Setup Guide
Claude Code CLI	Windows/macOS/Linux	✅ Tested & Working	Setup Guide

Quick Configuration:

# Windows PowerShell
.\scripts\configure_mcp_servers.ps1

# Or manually edit: C:\Users\<username>\.claude.json
# Add the Context MCP server configuration (see Configuration section above)

Note: While the codebase contains experimental scripts for other MCP clients (Codex CLI), only Claude Code CLI has been tested and verified to work with the current implementation.

📊 Performance Benchmarks

Startup Performance

Version	Startup Time	Improvement
v1.0 (eager loading)	40+ seconds	Baseline
v2.0 (lazy loading)	<1 second	97.5% faster

Embedding Generation

Hardware	Performance	Batch Size
CPU (Intel i7)	~100 embeddings/sec	32
GPU (RTX 4050)	2,363.7 embeddings/sec	128
Speedup	20-40x faster	-

Search Performance

Operation	Latency	Throughput
First query (cold start)	11.6ms	-
Subsequent queries	5-8ms	125-200 queries/sec
Batch search (10 queries)	45ms	222 queries/sec

🔒 Privacy & Security

Offline-first: All processing happens locally, no data sent to external servers
No telemetry: No usage tracking or analytics
Local models: Embedding models run on your machine
Your data stays yours: Code never leaves your computer

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

🙏 Acknowledgments

FastMCP: MCP server framework
Qdrant: Vector database
Sentence Transformers: Embedding models
Tree-sitter: Multi-language parsing
PyTorch: GPU acceleration
Anthropic: Model Context Protocol specification

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: See docs/ directory

Made with ❤️ for developers who value privacy and performance

Name		Name	Last commit message	Last commit date
Latest commit History 125 Commits
.augment/commands/bmad		.augment/commands/bmad
.claude/commands/bmad		.claude/commands/bmad
.github/workflows		.github/workflows
alembic		alembic
benchmarks		benchmarks
bmad		bmad
deployment/docker		deployment/docker
docs		docs
examples		examples
requirements		requirements
scripts		scripts
src		src
tests		tests
.context-workspace.example.json		.context-workspace.example.json
.env.example		.env.example
.gitignore		.gitignore
.roomodes		.roomodes
=0.1.0		=0.1.0
=1.10.2		=1.10.2
=3.0.0		=3.0.0
ACTION_PLAN_MCP_FIX.md		ACTION_PLAN_MCP_FIX.md
AGENTS_IMPLEMENTATION_SUMMARY.md		AGENTS_IMPLEMENTATION_SUMMARY.md
AGENT_TEST_REPORT.md		AGENT_TEST_REPORT.md
ANALYTICS_IMPLEMENTATION_SUMMARY.md		ANALYTICS_IMPLEMENTATION_SUMMARY.md
ARCHITECTURE_PROJECT_AWARE.md		ARCHITECTURE_PROJECT_AWARE.md
AUTODISCOVERY_EXAMPLE.md		AUTODISCOVERY_EXAMPLE.md
AUTODISCOVERY_IMPLEMENTATION_SUMMARY.md		AUTODISCOVERY_IMPLEMENTATION_SUMMARY.md
CACHING_SYSTEM_COMPLETE.md		CACHING_SYSTEM_COMPLETE.md
CLAUDE_CODE_CLI_MCP_CONNECTION_FIX.md		CLAUDE_CODE_CLI_MCP_CONNECTION_FIX.md
CLAUDE_CODE_CLI_MCP_SHUTDOWN_DIAGNOSIS.md		CLAUDE_CODE_CLI_MCP_SHUTDOWN_DIAGNOSIS.md
CLI_IMPLEMENTATION_SUMMARY.md		CLI_IMPLEMENTATION_SUMMARY.md
CLI_OVERVIEW.txt		CLI_OVERVIEW.txt
CLI_QUICK_REFERENCE.md		CLI_QUICK_REFERENCE.md
CLI_USAGE.md		CLI_USAGE.md
CODEBASE_AUDIT_2025-11-06.md		CODEBASE_AUDIT_2025-11-06.md
COMPLETE_DIAGNOSIS_AND_SOLUTION.md		COMPLETE_DIAGNOSIS_AND_SOLUTION.md
CONTEXT_AWARE_TOOLS_ENABLED.md		CONTEXT_AWARE_TOOLS_ENABLED.md
CRITICAL_ISSUE_DIAGNOSIS.md		CRITICAL_ISSUE_DIAGNOSIS.md
DEPLOYMENT_GUIDE.md		DEPLOYMENT_GUIDE.md
DEPLOYMENT_SUMMARY.md		DEPLOYMENT_SUMMARY.md
DOCKER_SETUP_COMPLETE.md		DOCKER_SETUP_COMPLETE.md
ENV_FILE_SECURITY_GUIDE.md		ENV_FILE_SECURITY_GUIDE.md
EXTERNAL_PROJECTS_TEST_RESULTS.md		EXTERNAL_PROJECTS_TEST_RESULTS.md
FINAL_MCP_CONNECTION_SOLUTION.md		FINAL_MCP_CONNECTION_SOLUTION.md
GOOGLE_EMBEDDINGS_SOLUTION.md		GOOGLE_EMBEDDINGS_SOLUTION.md
IMPLEMENTATION_COMPLETE.md		IMPLEMENTATION_COMPLETE.md
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
INTEGRATION_SUMMARY.md		INTEGRATION_SUMMARY.md
INTELLIGENT_SEARCH_IMPLEMENTATION.md		INTELLIGENT_SEARCH_IMPLEMENTATION.md
INTELLIGENT_SEARCH_SUMMARY.txt		INTELLIGENT_SEARCH_SUMMARY.txt
LICENSE		LICENSE
MCP_CONFIGURATION_COMPLETE.md		MCP_CONFIGURATION_COMPLETE.md
MCP_CONNECTION_PRODUCTION_SOLUTION.md		MCP_CONNECTION_PRODUCTION_SOLUTION.md
MCP_FIX_IMPLEMENTATION_SUMMARY.md		MCP_FIX_IMPLEMENTATION_SUMMARY.md
MEMORY_IMPLEMENTATION_SUMMARY.md		MEMORY_IMPLEMENTATION_SUMMARY.md
PRODUCTION_READINESS_ASSESSMENT.md		PRODUCTION_READINESS_ASSESSMENT.md
QUICKSTART.md		QUICKSTART.md
QUICK_FIX_GUIDE.md		QUICK_FIX_GUIDE.md
QUICK_START_GOOGLE_EMBEDDINGS.md		QUICK_START_GOOGLE_EMBEDDINGS.md
README.md		README.md
README_AUDIT_UPDATE_SUMMARY.md		README_AUDIT_UPDATE_SUMMARY.md
README_MCP_CONNECTION_FIX.md		README_MCP_CONNECTION_FIX.md
RELATIONSHIP_GRAPH_API_REFERENCE.md		RELATIONSHIP_GRAPH_API_REFERENCE.md
RELATIONSHIP_GRAPH_SUMMARY.md		RELATIONSHIP_GRAPH_SUMMARY.md
RELEASE_NOTES_v2.0.0.md		RELEASE_NOTES_v2.0.0.md
SECURITY_AUDIT_CHECKLIST.md		SECURITY_AUDIT_CHECKLIST.md
SECURITY_AUDIT_REPORT.md		SECURITY_AUDIT_REPORT.md
SECURITY_AUDIT_SUMMARY.md		SECURITY_AUDIT_SUMMARY.md
SECURITY_AUDIT_TECHNICAL_DETAILS.md		SECURITY_AUDIT_TECHNICAL_DETAILS.md
SETUP_COMPLETE.md		SETUP_COMPLETE.md
V3.0_TESTING_COMPLETE.md		V3.0_TESTING_COMPLETE.md
WORKSPACE_CONFIG_COMPLETE.md		WORKSPACE_CONFIG_COMPLETE.md
WORKSPACE_CONFIG_VALIDATION_SUMMARY.md		WORKSPACE_CONFIG_VALIDATION_SUMMARY.md
WORKSPACE_IMPLEMENTATION_SUMMARY.md		WORKSPACE_IMPLEMENTATION_SUMMARY.md
WORKSPACE_MANAGER_IMPLEMENTATION.md		WORKSPACE_MANAGER_IMPLEMENTATION.md
WORKSPACE_QUICKSTART.md		WORKSPACE_QUICKSTART.md
WORKSPACE_SEARCH_IMPLEMENTATION.md		WORKSPACE_SEARCH_IMPLEMENTATION.md
WORKSPACE_USAGE_EXAMPLES.md		WORKSPACE_USAGE_EXAMPLES.md
WORKSPACE_V2.5_ARCHITECTURE.md		WORKSPACE_V2.5_ARCHITECTURE.md
WORKSPACE_V2.5_FINAL_SUMMARY.md		WORKSPACE_V2.5_FINAL_SUMMARY.md
WORKSPACE_V2.5_IMPLEMENTATION_SUMMARY.md		WORKSPACE_V2.5_IMPLEMENTATION_SUMMARY.md
WORKSPACE_V2.5_PRD.md		WORKSPACE_V2.5_PRD.md
WORKSPACE_V2_AUGMENTED_BRAINSTORM.md		WORKSPACE_V2_AUGMENTED_BRAINSTORM.md
WORKSPACE_V3.0_ARCHITECTURE.md		WORKSPACE_V3.0_ARCHITECTURE.md
WORKSPACE_V3.0_BRAINSTORM.md		WORKSPACE_V3.0_BRAINSTORM.md
WORKSPACE_V3.0_FINAL_SUMMARY.md		WORKSPACE_V3.0_FINAL_SUMMARY.md
WORKSPACE_V3.0_PRD.md		WORKSPACE_V3.0_PRD.md
WORKSPACE_V3.0_STORIES.md		WORKSPACE_V3.0_STORIES.md
alembic.ini		alembic.ini
commitmsg.txt		commitmsg.txt
fix_datetime_utcnow.py		fix_datetime_utcnow.py
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements-parsing.txt		requirements-parsing.txt
research_spike_results.json		research_spike_results.json
run_mcp_server.bat		run_mcp_server.bat
run_research_spike.py		run_research_spike.py
setup.py		setup.py
start_http_server.ps1		start_http_server.ps1
start_http_server.py		start_http_server.py

Folders and files

Latest commit

History

Repository files navigation

Context MCP Server

✨ Key Features

📊 Performance Highlights

🆕 Latest Changes and Fixes

v2.0.0 - Multi-Project Workspace Support (2025-11-11) 🎉

Previous Changes

✅ Verification Status and Testing Matrix

🏗️ Architecture

Core Components

Technology Stack

🏭 Deployment Architecture

Hybrid Architecture (Current Production Setup)

Why This Architecture?

Port Configuration

Deployment Status

📋 Requirements

System Requirements

Required Services

GPU Acceleration (Optional but Recommended)

🚀 Installation

1. Clone the Repository

2. Install Python Dependencies

3. Install Tree-sitter for AST Parsing

4. Start Required Services

Option A: Using Docker Compose (Recommended)

Option B: Manual Installation

5. Configure Environment Variables

6. Verify Installation

🔧 Configuration for Claude Code CLI

Global MCP Configuration

Option A: HTTP Transport (Recommended for Production)

Option B: Stdio Transport (Legacy)

Verify Connection

Troubleshooting

🛠️ MCP Tools Available

1. Health & Capabilities

2. Indexing Tools

3. Vector Operations

4. Semantic Search

5. Pattern Search

6. AST Search

7. Cross-Language Analysis

8. Dependency Analysis

9. Query Understanding

10. Indexing Optimization

11. Prompt Tools

12. Context-Aware Prompts

13. Result Presentation

💡 Usage Examples

Example 1: Semantic Code Search

Example 2: Find All Classes

Example 3: Cross-Language Pattern Detection

Example 4: Index New Files

🚀 Optimization Features

Lazy Loading Architecture

GPU Acceleration

Caching Strategy

🔍 Troubleshooting

Understanding the Hybrid Architecture

Verifying System Status

Check Docker Services

Check Qdrant Vector Database

Check Local MCP Server

Test Semantic Search (Docker Container)

Common Issues

1. "Failed to reconnect to context" in Claude Code CLI

2. Slow Startup (>5 seconds)

3. GPU Not Detected

4. PostgreSQL Connection Failed

5. Vector Dimension Mismatch

6. Indexing Not Processing Files

7. Redis Connection Failed

6. Qdrant Connection Failed

Debug Mode

Getting Help

📊 Monitoring & Production Readiness

Packages