Codebase Intelligence MCP Server

A production-grade Model Context Protocol (MCP) server providing advanced code intelligence capabilities across multiple programming languages. Built with cloud-native architecture integrating 6 managed services for scalability and reliability.

Features

• 🔍 Semantic Code Search - Vector-based search across 100k+ files using Qdrant Cloud
• 🕸️ Dependency Analysis - Graph-based dependency tracking with Neo4j Cloud
• 📊 Code Metrics - Cyclomatic complexity, maintainability index, and more
• 🔄 Duplicate Detection - AST and semantic-based code clone detection
• 📝 Auto-Documentation - Generate API documentation from code
• 🎯 Refactoring Suggestions - AI-powered code improvement recommendations
• 💬 Natural Language Q&A - Ask questions about your codebase in plain English
• 🌳 Call Graph Analysis - Visualize function call relationships

Questions This MCP Tools Can Answer (See Questions.md file)

Supported Languages

• JavaScript/TypeScript
• Python
• Java
• Go

Architecture

The system integrates 6 cloud services for production-grade performance:

• Qdrant Cloud - Vector search for semantic code queries
• Neo4j AuraDB - Graph database for dependency analysis
• Neon PostgreSQL - Serverless database for metadata and metrics
• Upstash Redis - Distributed caching layer
• HuggingFace Inference API - Code embeddings generation
• Render - Deployment platform with auto-scaling

Quick Start

Prerequisites

• Python 3.11+
• Cloud service accounts (see Cloud Setup)

Installation

# Clone the repository
git clone https://github.com/yourusername/codebase-intelligence-mcp.git
cd codebase-intelligence-mcp

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env
# Edit .env with your cloud service credentials

Cloud Setup

1. Qdrant Cloud: Create cluster at cloud.qdrant.io (Free tier: 1GB)
2. Neo4j AuraDB: Create instance at neo4j.com/cloud/aura-free
3. Neon: Create database at neon.tech (Free tier: 0.5GB)
4. Upstash Redis: Create database at upstash.com (Free tier: 10k commands/day)
5. HuggingFace: Get API token at huggingface.co/settings/tokens

Running Locally

# Start in stdio mode (for Cursor/Claude Desktop)
python -m src.server --mode stdio

# Start in HTTP mode (for testing)
python -m src.server --mode http --port 10000

Using with Cursor/Claude Desktop

Add to your MCP configuration:

{
  "mcpServers": {
    "codebase-intelligence": {
      "command": "python",
      "args": ["-m", "src.server", "--mode", "stdio"],
      "cwd": "/path/to/codebase-intelligence-mcp",
      "env": {
        "QDRANT_URL": "your-qdrant-url",
        "QDRANT_API_KEY": "your-api-key",
        ...
      }
    }
  }
}

MCP Tools

1. index_codebase

Index a directory for intelligent code analysis.

{
  "path": "/path/to/codebase",
  "languages": ["python", "typescript"],
  "exclude_patterns": ["node_modules", "*.test.ts"]
}

2. semantic_search

Search code by meaning, not just text.

{
  "query": "authentication middleware",
  "language_filter": "typescript",
  "top_k": 10
}

3. analyze_dependencies

Generate dependency graphs and detect circular dependencies.

{
  "path": "/path/to/module",
  "language": "python",
  "depth": 3
}

4. compute_metrics

Calculate code complexity and quality metrics.

{
  "file_path": "/path/to/file.py"
}

5. detect_duplicates

Find duplicate and similar code across the codebase.

{
  "path": "/path/to/codebase",
  "similarity_threshold": 0.85
}

6. generate_docs

Auto-generate documentation from code.

{
  "path": "/path/to/module",
  "format": "markdown"
}

7. suggest_refactorings

Get AI-powered refactoring suggestions.

{
  "file_path": "/path/to/file.py"
}

8. ask_codebase

Query your codebase in natural language.

{
  "question": "How does authentication work?",
  "top_k": 5
}

9. get_call_graph

Generate call graphs for functions.

{
  "function_name": "authenticate_user",
  "max_depth": 2
}

10. find_symbol

Find symbol definitions and usages.

{
  "symbol_name": "UserService",
  "symbol_type": "class"
}

Deployment

Deploy to Render

1. Push code to GitHub
2. Connect Render to your repository
3. Add environment variables in Render dashboard
4. Deploy automatically on push to main

See docs/deployment.md for detailed instructions.

Development

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

# Run tests
pytest

# Format code
black src/ tests/
ruff check src/ tests/

# Type check
mypy src/

Performance

• Index 10k files in < 5 minutes
• Semantic search response < 500ms
• Dependency graph for 1k files < 2s
• Memory usage < 2GB for 100k files
• Supports 10+ concurrent clients

Cost Estimation

Development: $0 (all services have generous free tiers)

Production (100k files):

• Qdrant Cloud: $25/month
• Neo4j AuraDB: $65/month
• Neon PostgreSQL: $10/month
• Upstash Redis: $10/month
• HuggingFace API: ~$20/month
• Render: $7/month
• Total: ~$137/month

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! Please read our contributing guidelines first.

Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions