Code Index MCP Simple

Intelligent code indexing and analysis for Large Language Models

Transform how AI understands your codebase with advanced search, analysis, and navigation capabilities.

🔔 Project Notice

This is a simplified and enhanced fork of code-index-mcp by johnhuang316, focusing on a streamlined API for core code intelligence features.

⚠️ BREAKING CHANGES IN v3.x

Version 3.x consolidates all search, project setup, and indexing functionalities into a single unified_search tool. See MIGRATION.md for upgrade guide.

Overview

Code Index MCP Simple is a Model Context Protocol server designed to provide AI models with intelligent indexing, advanced search, and detailed code analysis capabilities. It simplifies how AI assistants interact with and understand complex codebases.

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

Quick Start

🚀 Installation

Prerequisites

Python 3.10+
uv (recommended)

Method 1: Direct from GitHub (Recommended)

Install and run directly from GitHub without cloning:

Add to your MCP configuration (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "code-index-simple": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/catlog22/code-index-mcp-simple.git",
        "code-index-mcp-simple"
      ]
    }
  }
}

Restart your application and start using:

Find all TypeScript files in this project
Search for "authentication" functions
Analyze the main App.tsx file

Method 2: Local Clone

For offline use or development:

Clone the repository:

git clone https://github.com/catlog22/code-index-mcp-simple.git
cd code-index-mcp-simple

Add to your MCP configuration (e.g., claude_desktop_config.json):

Windows:

{
  "mcpServers": {
    "code-index-simple": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\code-index-mcp-simple",
        "run",
        "code-index-mcp-simple"
      ]
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "code-index-simple": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/code-index-mcp-simple",
        "run",
        "code-index-mcp-simple"
      ]
    }
  }
}

Restart your application – Changes will take effect.

Method 3: Local Development

For contributing or local development:

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

Debug with MCP Inspector:

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

Key Features

🔍 Intelligent Search & Analysis

Unified Search: A single unified_search tool handles all search modes (content, files, summary), project setup, and indexing.
Dual-Strategy Architecture: Tree-sitter parsing for 7 core languages, with a robust fallback for 50+ file types.
Advanced Search: Auto-detects and utilizes the best available search tools (ugrep, ripgrep, ag, or grep).
File Analysis: Provides deep insights into file structure, functions, imports, and complexity metrics.

🗂️ Multi-Language Support

Tree-sitter AST Parsing (7 languages): Python, JavaScript, TypeScript, Java, Go, Objective-C, Zig.
Fallback Strategy (50+ languages): Comprehensive coverage for C/C++, Rust, Ruby, PHP, C#, Kotlin, Scala, Swift, Shell, Vue, React, Svelte, HTML, CSS, SQL, JSON, YAML, XML, Markdown, and more.

⚡ Real-time Monitoring & Efficiency

File Watcher: Automatic index updates when files change, with smart processing to prevent excessive rebuilds.
Persistent Caching: Stores indexes for lightning-fast subsequent access.
Memory Efficient: Optimized for large codebases with intelligent exclusion of build directories and temporary files.

The `unified_search` Tool: Your Single Entry Point

This simplified version of Code Index MCP focuses on a single, powerful unified_search tool. It consolidates all project setup, indexing, and search functionalities for maximum convenience.

Usage

unified_search(
    mode: str,             # 'content', 'files', or 'summary'
    project_path: str,     # REQUIRED: Absolute path to project. Auto-initializes and indexes.
    query: Optional[str],  # REQUIRED for 'content' and 'files' modes
    file_path: Optional[str], # REQUIRED for 'summary' mode
    # ... other optional parameters like case_sensitive, file_pattern, fuzzy, regex
)

Search Modes

Content Mode (mode='content')
- Purpose: Search code patterns using regex, fuzzy matching, and file filtering.
- Key Parameter: query (text or regex pattern).
- Example: unified_search(mode='content', project_path='D:\\my-project', query='TODO|FIXME', regex=True, file_pattern='*.py')
Files Mode (mode='files')
- Purpose: Locate files using glob patterns.
- Key Parameter: query (file name or glob pattern).
- Example: unified_search(mode='files', project_path='D:\\my-project', query='**/*.tsx')
Summary Mode (mode='summary')
- Purpose: Analyze file structure, functions, imports, and complexity.
- Key Parameter: file_path (relative path to the file).
- Example: unified_search(mode='summary', project_path='D:\\my-project', file_path='src/main.py')

Usage Examples

🎯 Quick Start Workflow

Ultra-simple 2-step process!

Step 1: Set Project Path (Auto-indexes everything)

Set the project path to G:\my-react-app

This single command:

✅ Sets the project directory
✅ Auto-builds file index (for mode='content' and mode='files')
✅ Auto-builds symbol index (for mode='summary')
✅ Makes unified_search immediately ready to use!

Step 2: Start Searching!

No additional setup needed - search immediately!

Search for "authentication" in the codebase
Find all TypeScript component files
Give me a summary of src/api/userService.ts

🔍 Advanced Search Examples

Code Pattern Search

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

Finds: getData(), getUserData(), getFormData(), etc.

Fuzzy Function Search

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

Matches: authenticateUser, authUserToken, userAuthCheck, etc.

Language-Specific Search

Search for "API_ENDPOINT" only in Python files

Troubleshooting

🔄 Auto-refresh Not Working

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

pip install watchdog (may resolve environment isolation issues)
The unified_search tool automatically handles indexing. If you need to force a re-index, simply call unified_search again with the project_path.

Development & Contributing

🔧 Building from Source

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

🐛 Debugging

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

🤝 Contributing

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

Credits

This project is a fork of code-index-mcp by johnhuang316. Special thanks to the original author for creating this excellent MCP server.

License

MIT License

Contact

GitHub Issues: https://github.com/catlog22/code-index-mcp-simple/issues
Original Project: https://github.com/johnhuang316/code-index-mcp

Name		Name	Last commit message	Last commit date
Latest commit History 151 Commits
.github/workflows		.github/workflows
.history		.history
src/code_index_mcp		src/code_index_mcp
test		test
tests		tests
.coverage		.coverage
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.pylintrc		.pylintrc
.python-version		.python-version
AGENTS.md		AGENTS.md
Dockerfile		Dockerfile
LICENSE		LICENSE
MIGRATION.md		MIGRATION.md
README.md		README.md
README.zh-CN.md		README.zh-CN.md
RELEASE_NOTE.txt		RELEASE_NOTE.txt
TESTING.md		TESTING.md
UNIFIED_SEARCH_GUIDE.md		UNIFIED_SEARCH_GUIDE.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
run.py		run.py
uv.lock		uv.lock

License

catlog22/code-index-mcp-simple

Folders and files

Latest commit

History

Repository files navigation

Code Index MCP Simple

Overview

Quick Start

🚀 Installation

Prerequisites

Method 1: Direct from GitHub (Recommended)

Method 2: Local Clone

Method 3: Local Development

Key Features

🔍 Intelligent Search & Analysis

🗂️ Multi-Language Support

⚡ Real-time Monitoring & Efficiency

The unified_search Tool: Your Single Entry Point

Usage

Search Modes

Usage Examples

🎯 Quick Start Workflow

Step 1: Set Project Path (Auto-indexes everything)

Step 2: Start Searching!

🔍 Advanced Search Examples

Code Pattern Search

Fuzzy Function Search

Language-Specific Search

Troubleshooting

🔄 Auto-refresh Not Working

Development & Contributing

🔧 Building from Source

🐛 Debugging

🤝 Contributing

Credits

License

Contact

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

The `unified_search` Tool: Your Single Entry Point

Packages