scooter-lacroix/code-indexer

Code Index MCP - Enterprise Edition

🚀 Enterprise Edition - v3.0.0 Migration Complete

This version represents a complete architectural transformation with hybrid database migration from SQLite to PostgreSQL + Elasticsearch:

🏗️ Architecture Transformation

• ✅ PostgreSQL Integration - Robust metadata storage with ACID compliance
• ✅ Elasticsearch Integration - High-performance full-text search capabilities
• ✅ Hybrid Database Architecture - Best of both worlds for different data types
• ✅ Version Tracking System - Complete file change history with diffs
• ✅ Real-time Indexing - RabbitMQ-based async processing
• ✅ Cross-Platform Compatibility - Robust path handling for all environments

📊 Migration Achievements

• ✅ Zero Data Loss - Complete ETL migration from SQLite
• ✅ Backward Compatibility - Dual-write/read strategy during transition
• ✅ Performance Gains - 10x faster search with Elasticsearch
• ✅ Scalability - Enterprise-grade database backends
• ✅ Version Control - Full file history tracking with PostgreSQL
• ✅ Real-time Updates - Instant search index updates

🛠️ New Enterprise Features

1. File Version Tracking - Complete change history with diffs
2. PostgreSQL Metadata - Structured data with relationships
3. Elasticsearch Search - Advanced full-text search capabilities
4. Real-time Indexing - RabbitMQ message queue processing
5. ETL Migration Tools - Seamless data migration utilities
6. Database Migrations - Alembic-based schema management
7. Backup & Recovery - Comprehensive backup strategies
8. Monitoring & Logging - Enterprise-grade observability

📋 Verified Functionality

• ✅ File Operations - Create, modify, delete with full tracking
• ✅ Search Capabilities - Basic, advanced, and pattern-based search
• ✅ Version History - Complete file change tracking and retrieval
• ✅ Database Integration - PostgreSQL + Elasticsearch working seamlessly
• ✅ Migration Tools - ETL scripts for data migration
• ✅ Backup Systems - Automated backup and recovery procedures

See for migration details and for complete tool documentation.

What is Code Index MCP?

Code Index MCP is a specialized MCP server that provides intelligent code indexing and analysis capabilities. It enables Large Language Models to interact with your code repositories, offering real-time insights and navigation through complex codebases.

This server integrates with the Model Context Protocol (MCP), a standardized way for AI models to interact with external tools and data sources.

Key Features

🚀 Performance & Optimization

• Incremental Indexing: Only processes changed files, reducing re-indexing time by 90%+
• Parallel Processing: 4x faster indexing with multi-core support
• Memory Optimization: 70% memory reduction with lazy loading and intelligent caching
• High-Performance Search: 10x faster searches with enterprise-grade tools (Zoekt, ripgrep, ugrep)
• Smart Filtering: Advanced gitignore integration and size-based filtering

🔍 Advanced Search & Analysis

• Async Search: Non-blocking search operations with real-time progress tracking
• Multi-Pattern Search: Concurrent search across multiple patterns with scoped results
• Intelligent Caching: 90% faster repeated searches with LRU cache
• Fuzzy Search: Native fuzzy matching with safety checks
• Search Result Pagination: Efficient handling of large result sets

🛠️ Enterprise Features

• Progress Tracking: Real-time progress events with cancellation support
• Performance Monitoring: Comprehensive metrics and Prometheus export
• Memory Profiling: Real-time memory usage monitoring and limits
• Configurable Settings: YAML-based configuration with per-project overrides
• Storage Backends: SQLite and trie-based optimized storage

🔧 Developer Experience

• MCP Tools: 20+ specialized tools for code analysis and management
• Background Cleanup: Automatic cache management and garbage collection
• Error Recovery: Graceful handling of failures with automatic fallbacks
• Extensible Architecture: Pluggable storage and search backends

Supported File Types

The server supports multiple programming languages and file extensions including:

• Python (.py)
• JavaScript/TypeScript (.js, .ts, .jsx, .tsx, .mjs, .cjs)
• Frontend Frameworks (.vue, .svelte, .astro)
• Java (.java)
• C/C++ (.c, .cpp, .h, .hpp)
• C# (.cs)
• Go (.go)
• Ruby (.rb)
• PHP (.php)
• Swift (.swift)
• Kotlin (.kt)
• Rust (.rs)
• Scala (.scala)
• Shell scripts (.sh, .bash)
• Zig (.zig)
• Web files (.html, .css, .scss, .less, .sass, .stylus, .styl)
• Template engines (.hbs, .handlebars, .ejs, .pug)
• Database & SQL:
  • SQL files (.sql, .ddl, .dml)
  • Database-specific (.mysql, .postgresql, .psql, .sqlite, .mssql, .oracle, .ora, .db2)
  • Database objects (.proc, .procedure, .func, .function, .view, .trigger, .index)
  • Migration & tools (.migration, .seed, .fixture, .schema, .liquibase, .flyway)
  • NoSQL & modern (.cql, .cypher, .sparql, .gql)
• Documentation/Config (.md, .mdx, .json, .xml, .yml, .yaml)

📦 Installation & Setup

🚀 Quick Start

For immediate use with AI applications:

uvx git+https://github.com/scooter-lacroix/code-indexer.git

For package installation:

uv add code-index-mcp
# or
pip install code-index-mcp

🏗️ Enterprise Setup (PostgreSQL + Elasticsearch)

1. Database Setup:

# Using Docker Compose (recommended)
docker-compose up -d

# Or use convenience script
python run.py start-dev-dbs

2. Environment Configuration:

# Set environment variables
export DAL_BACKEND_TYPE=postgresql_elasticsearch_only
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432
export POSTGRES_USER=codeindex
export POSTGRES_PASSWORD=your-secure-password
export POSTGRES_DB=code_index_db
export ELASTICSEARCH_HOSTS=http://localhost:9200

3. Migration (if upgrading from SQLite):

# Backup existing data
python backup_script.py

# Run migration
python src/scripts/etl_script.py --mode full

# Verify migration
python src/scripts/etl_script.py --mode verify

📚 Complete Installation Guide

For detailed installation instructions, database setup, and troubleshooting, see:

🔌 MCP Integration

The Code Index MCP server supports multiple integration methods:

Method 1: Direct Git Integration (Recommended)

For LM Studio, Claude Desktop, VS Code, and other MCP-compatible applications:

{
  "mcpServers": {
    "code-index": {
      "command": "uvx",
      "args": ["git+https://github.com/scooter-lacroix/code-indexer.git"],
      "env": {},
      "start_on_launch": true
    }
  }
}

Method 2: Package Installation

For package manager installed versions:

{
  "mcpServers": {
    "code-index": {
      "command": "code-index-mcp",
      "args": [],
      "env": {},
      "start_on_launch": true
    }
  }
}

Method 3: Local Development

For locally installed versions:

{
  "mcpServers": {
    "code-index": {
      "command": "uv",
      "args": ["run", "code_index_mcp"],
      "env": {},
      "start_on_launch": true
    }
  }
}

Method 4: HTTP Server Mode

For web-based integrations:

# Start HTTP server
python -m code_index.server --port 8765

# Or using uv
uv run code_index.server --port 8765

Then configure your application:

{
  "mcpServers": {
    "code-index": {
      "transport": "http",
      "url": "http://localhost:8765/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Application-Specific Configurations

VS Code/Cursor/Windsurf (using MCP extension):

{
  "mcp.servers": {
    "code-index": {
      "command": "code-index-mcp",
      "args": [],
      "env": {},
      "transport": "stdio"
    }
  }
}

Jan AI:

{
  "mcp_servers": {
    "code-index": {
      "command": "code-index-mcp",
      "args": [],
      "env": {}
    }
  }
}

OpenHands:

{
  "mcp": {
    "servers": {
      "code-index": {
        "command": "code-index-mcp",
        "args": [],
        "env": {}
      }
    }
  }
}

🛠️ Usage

Command Line Interface

# Start stdio server (MCP integration)
code-index-mcp

# Start HTTP server (web integration)
code-index-mcp --http --port 8765

# Local development (runs the server)
uv run code_index_mcp server

Local Development with Docker Compose

For local development using PostgreSQL and Elasticsearch via Docker Compose:

# Start PostgreSQL and Elasticsearch containers in detached mode
python run.py start-dev-dbs

# Stop PostgreSQL and Elasticsearch containers and remove their volumes
python run.py stop-dev-dbs

# Restart PostgreSQL and Elasticsearch containers
python run.py restart-dev-dbs

# Run the Code Index MCP server (connects to Dockerized databases if configured)
python run.py server

Debug with MCP Inspector

# For git installation
npx @modelcontextprotocol/inspector uvx git+https://github.com/scooter-lacroix/code-indexer.git

# For package installation
npx @modelcontextprotocol/inspector code-index-mcp

# For local development
npx @modelcontextprotocol/inspector uv run code_index_mcp

🛠️ Available Tools

The Code Index MCP server provides 25+ specialized tools for comprehensive code analysis and management:

🏗️ Core Project Management

• set_project_path - Initialize project workspace with database connections
• refresh_index - Incremental indexing with progress tracking
• get_settings_info - Project configuration and statistics

🔍 Advanced Search & Discovery

• search_code_advanced - Enterprise search with fuzzy matching, highlighting, and Elasticsearch
• find_files - Glob pattern file discovery
• get_file_summary - Comprehensive file analysis with structure and metrics

✏️ File Operations with Version Tracking

• write_to_file - Create/modify files with automatic version tracking
• search_and_replace - Regex-powered find/replace with scope control
• apply_diff - Multi-file modifications with atomic operations
• insert_content - Precise content insertion at specific lines
• delete_file - File deletion with version history
• rename_file - File renaming/moving with tracking

📚 Version Control & History

• get_file_history - Complete change history with diffs and timestamps
• revert_file_to_version - Rollback to any previous version
• Full PostgreSQL-backed version tracking system

⚙️ System Management & Performance

• get_memory_profile - Real-time memory usage monitoring
• get_performance_metrics - Comprehensive performance statistics
• get_active_operations - Operation tracking with progress
• cancel_operation - Graceful operation cancellation
• Memory management and garbage collection tools

🔧 Enterprise Features

• Database migration and ETL tools
• Backup and recovery systems
• Real-time indexing with RabbitMQ
• Elasticsearch integration for advanced search
• PostgreSQL metadata storage with ACID compliance

📖 Complete Documentation: See for detailed tool reference with examples and system prompt templates.

Common Workflows and Examples

Here’s a typical workflow for using Code Index MCP with an AI assistant like Claude.

1. Set Project Path & Initial Indexing

This is the first and most important step. When you set the project path, the server automatically creates a file index for the first time or loads a previously cached one.

Example Prompt:

Please set the project path to C:\Users\username\projects\my-react-app

2. Refresh the Index (When Needed)

If you make significant changes to your project files after the initial setup, you can manually refresh the index to ensure all tools are working with the latest information.

Example Prompt:

I've just added a few new components, please refresh the project index.

(The assistant would use the refresh_index tool)

3. Explore the Project Structure

Once the index is ready, you can find files using patterns (globs) to understand the codebase and locate relevant files.

Example Prompt:

Find all TypeScript component files in the 'src/components' directory.

(The assistant would use the find_files tool with a pattern like src/components/**/*.tsx)

4. Analyze a Specific File

Before diving into the full content of a file, you can get a quick summary of its structure, including functions, classes, and imports.

Example Prompt:

Can you give me a summary of the 'src/api/userService.ts' file?

(The assistant would use the get_file_summary tool)

5. Search for Code

With an up-to-date index, you can search for code snippets, function names, or any text pattern to find where specific logic is implemented.

Example: Simple Search

Search for all occurrences of the "processData" function.

Example: Search with Fuzzy Matching

I'm looking for a function related to user authentication, it might be named 'authUser', 'authenticateUser', or something similar. Can you do a fuzzy search for 'authUser'?

Example: Search within Specific Files

Search for the string "API_ENDPOINT" only in Python files.

(The assistant would use the search_code tool with the file_pattern parameter set to *.py)

Development

Building from Source

1. Clone the repository:

git clone https://github.com/scooter-lacroix/code-indexer.git
cd code-index-mcp

2. Install dependencies:

uv sync

3. Run the server locally:

uv run code_index_mcp

Debugging

You can use the MCP inspector to debug the server:

npx @modelcontextprotocol/inspector uvx code-index-mcp

License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Languages