johnhuang316/code-index-mcp

Code Index MCP

Overview

Code Index MCP is a Model Context Protocol server that bridges the gap between AI models and complex codebases. It provides intelligent indexing, advanced search capabilities, and detailed code analysis to help AI assistants understand and navigate your projects effectively.

Perfect for: Code review, refactoring, documentation generation, debugging assistance, and architectural analysis.

Quick Start

🚀 Recommended Setup (Most Users)

The easiest way to get started with any MCP-compatible application:

Prerequisites: Python 3.10+ and uv

1. Add to your MCP configuration (e.g., claude_desktop_config.json or ~/.claude.json):

   {
     "mcpServers": {
       "code-index": {
         "command": "uvx",
         "args": ["code-index-mcp"]
       }
     }
   }
   

2. Restart your application – uvx automatically handles installation and execution

3. Start using:

   Set the project path to /Users/dev/my-react-app
   Find all TypeScript files in this project  
   Search for "authentication" functions
   Analyze the main App.tsx file
   

Typical Use Cases

Code Review: "Find all places using the old API"
Refactoring Help: "Where is this function called?"
Learning Projects: "Show me the main components of this React project"
Debugging: "Search for all error handling related code"

Key Features

🔍 Intelligent Search & Analysis

• SCIP-Powered: Industry-standard code intelligence format used by major IDEs
• Advanced Search: Auto-detects and uses the best available tool (ugrep, ripgrep, ag, or grep)
• Universal Understanding: Single system comprehends all programming languages
• File Analysis: Deep insights into structure, imports, classes, methods, and complexity metrics

🗂️ Multi-Language Support

• 50+ File Types: Java, Python, JavaScript/TypeScript, C/C++, Go, Rust, C#, Swift, Kotlin, Ruby, PHP, and more
• Web Frontend: Vue, React, Svelte, HTML, CSS, SCSS
• Database: SQL variants, NoSQL, stored procedures, migrations
• Configuration: JSON, YAML, XML, Markdown
• View complete list

⚡ Real-time Monitoring & Auto-refresh

• File Watcher: Automatic index updates when files change
• Cross-platform: Native OS file system monitoring
• Smart Processing: Batches rapid changes to prevent excessive rebuilds
• Rich Metadata: Captures symbols, references, definitions, and relationships

⚡ Performance & Efficiency

• SCIP Indexing: Fast protobuf-based unified indexing system
• Persistent Caching: Stores indexes for lightning-fast subsequent access
• Smart Filtering: Intelligent exclusion of build directories and temporary files
• Memory Efficient: Optimized for large codebases

Supported File Types

🛠️ Development Setup

For contributing or local development:

1. Clone and install:

   git clone https://github.com/johnhuang316/code-index-mcp.git
   cd code-index-mcp
   uv sync
   

2. Configure for local development:

   {
     "mcpServers": {
       "code-index": {
         "command": "uv",
         "args": ["run", "code-index-mcp"]
       }
     }
   }
   

3. Debug with MCP Inspector:

   npx @modelcontextprotocol/inspector uv run code-index-mcp
   

pip install code-index-mcp

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

Available Tools

🏗️ Project Management

🔍 Search & Discovery

🔄 Monitoring & Auto-refresh

🛠️ System & Maintenance

Usage Examples

🎯 Quick Start Workflow

1. Initialize Your Project

Set the project path to /Users/dev/my-react-app

Automatically indexes your codebase and creates searchable cache

2. Explore Project Structure

Find all TypeScript component files in src/components

Uses: find_files with pattern src/components/**/*.tsx

3. Analyze Key Files

Give me a summary of src/api/userService.ts

Uses: get_file_summary to show functions, imports, and complexity

🔍 Advanced Search Examples

Search for all function calls matching "get.*Data" using regex

Find authentication-related functions with fuzzy search for 'authUser'

Search for "API_ENDPOINT" only in Python files

Configure automatic index updates when files change

I added new components, please refresh the project index

Troubleshooting

🔄 Auto-refresh Not Working

If automatic index updates aren't working when files change, try:

• pip install watchdog (may resolve environment isolation issues)
• Use manual refresh: Call the refresh_index tool after making file changes
• Check file watcher status: Use get_file_watcher_status to verify monitoring is active

Development & Contributing

🔧 Building from Source

git clone https://github.com/johnhuang316/code-index-mcp.git
cd code-index-mcp
uv sync
uv run code-index-mcp

🐛 Debugging

npx @modelcontextprotocol/inspector uvx code-index-mcp

🤝 Contributing

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

📜 License

🌐 Translations