Skip to main content
Glama
code-index-mcp

code-index-mcp

by johnhuang316

Code Index MCP

MCP Server Python License Sponsor

Intelligent code indexing and analysis for Large Language Models

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

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.

Related MCP server: @lex-tools/codebase-context-dumper

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"]
        }
      }
    }

    Optional: append --project-path /absolute/path/to/repo to the args array so the server initializes with that repository automatically (equivalent to calling set_project_path after startup).

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

  3. Start using (give these prompts to your AI assistant):

    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

    If you launch with --project-path, you can skip the first command above - the server already knows the project location.

Codex CLI Configuration

If you are using Anthropic's Codex CLI, add the server to ~/.codex/config.toml. On Windows the file lives at C:\Users\<you>\.codex\config.toml:

[mcp_servers.code-index]
type = "stdio"
command = "uvx"
args = ["code-index-mcp"]

You can append --project-path C:/absolute/path/to/repo to the args list to set the project automatically on startup (same effect as running the set_project_path tool).

On Windows, uvx needs the standard profile directories to be present. Keep the environment override in the same block so the MCP starts reliably:

env = {
  HOME = "C:\\Users\\<you>",
  APPDATA = "C:\\Users\\<you>\\AppData\\Roaming",
  LOCALAPPDATA = "C:\\Users\\<you>\\AppData\\Local",
  SystemRoot = "C:\\Windows"
}

Linux and macOS already expose the required XDG paths and HOME, so you can usually omit the env table there. Add overrides only if you run the CLI inside a restricted container.

FastMCP & Discovery Manifests

  • Run fastmcp run fastmcp.json to launch the server via FastMCP with the correct source entrypoint and dependency metadata. Pass --project-path (or call the set_project_path tool after startup) so the index boots against the right repository.

  • Serve or copy .well-known/mcp.json to share a standards-compliant MCP manifest. Clients that support the .well-known convention (e.g., Claude Desktop, Codex CLI) can import this file directly instead of crafting configs manually.

  • Publish .well-known/mcp.llmfeed.json when you want to expose the richer LLM Feed metadata. It references the same code-index server definition plus documentation/source links, which helps registries present descriptions, tags, and capabilities automatically.

When sharing the manifests, remind consumers to supply --project-path (or to call set_project_path) so the server indexes the intended repository.

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

  • Dual-Strategy Architecture: Specialized tree-sitter parsing for 10 core languages, fallback strategy for 50+ file types

  • Direct Tree-sitter Integration: No regex fallbacks for specialized languages - fail fast with clear errors

  • Advanced Search: Auto-detects and uses the best available tool (ugrep, ripgrep, ag, or grep)

  • Universal File Support: Comprehensive coverage from advanced AST parsing to basic file indexing

  • File Analysis: Deep insights into structure, imports, classes, methods, and complexity metrics after running build_deep_index

🗂️ Multi-Language Support

  • 10 Languages with Tree-sitter AST Parsing: Python, JavaScript, TypeScript, Java, Kotlin, C#, Go, Objective-C, Zig, Rust

  • 50+ File Types with Fallback Strategy: C/C++, Ruby, PHP, and all other programming languages

  • Document & Config Files: Markdown, JSON, YAML, XML with appropriate handling

  • Web Frontend: Vue, React, Svelte, HTML, CSS, SCSS

  • Java Web & Build: JSP/Tag files (.jsp, .jspx, .jspf, .tag, .tagx), Grails/GSP (.gsp), Gradle & Groovy builds (.gradle, .groovy), .properties, and Protocol Buffers (.proto)

  • 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

  • Shallow Index Refresh: Watches file changes and keeps the file list current; run a deep rebuild when you need symbol metadata

⚡ Performance & Efficiency

  • Tree-sitter AST Parsing: Native syntax parsing for accurate symbol extraction

  • 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

  • Direct Dependencies: No fallback mechanisms - fail fast with clear error messages

Supported File Types

Languages with Specialized Tree-sitter Strategies:

  • Python (.py, .pyw) - Full AST analysis with class/method extraction and call tracking

  • JavaScript (.js, .jsx, .mjs, .cjs) - ES6+ class and function parsing with tree-sitter

  • TypeScript (.ts, .tsx) - Complete type-aware symbol extraction with interfaces

  • Java (.java) - Full class hierarchy, method signatures, and call relationships

  • Kotlin (.kt, .kts) - Package-aware symbol extraction with methods and call relationships

  • C# (.cs) - Namespace-aware type/member extraction with call relationships

  • Go (.go) - Struct methods, receiver types, and function analysis

  • Rust (.rs) - Functions, module-aware names, impl methods, structs/enums/traits, and basic call relationships

  • Objective-C (.m, .mm) - Class/instance method distinction with +/- notation

  • Zig (.zig, .zon) - Function and struct parsing with tree-sitter AST

All Other Programming Languages: All other programming languages use the FallbackParsingStrategy which provides basic file indexing and metadata extraction. This includes:

  • System & Low-Level: C/C++ (.c, .cpp, .h, .hpp)

  • Object-Oriented: Scala (.scala), Swift (.swift)

  • Scripting & Dynamic: Ruby (.rb), PHP (.php), Shell (.sh, .bash)

  • And 40+ more file types - All handled through the fallback strategy for basic indexing

Frameworks & Libraries:

  • Vue (.vue)

  • Svelte (.svelte)

  • Astro (.astro)

Styling:

  • CSS (.css, .scss, .less, .sass, .stylus, .styl)

  • HTML (.html)

Templates:

  • Handlebars (.hbs, .handlebars)

  • EJS (.ejs)

  • Pug (.pug)

  • FreeMarker (.ftl)

  • Mustache (.mustache)

  • Liquid (.liquid)

  • ERB (.erb)

SQL Variants:

  • Standard SQL (.sql, .ddl, .dml)

  • Database-specific (.mysql, .postgresql, .psql, .sqlite, .mssql, .oracle, .ora, .db2)

Database Objects:

  • Procedures & Functions (.proc, .procedure, .func, .function)

  • Views & Triggers (.view, .trigger, .index)

Migration & Tools:

  • Migration files (.migration, .seed, .fixture, .schema)

  • Tool-specific (.liquibase, .flyway)

NoSQL & Modern:

  • Graph & Query (.cql, .cypher, .sparql, .gql)

  • Markdown (.md, .mdx)

  • Configuration (.json, .xml, .yml, .yaml, .properties)

🛠️ 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

If you prefer traditional pip management:

pip install code-index-mcp

Then configure:

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

Available Tools

🏗️ Project Management

Tool

Description

set_project_path

Initialize indexing for a project directory

refresh_index

Rebuild the shallow file index after file changes

build_deep_index

Generate the full symbol index used by deep analysis

get_settings_info

View current project configuration and status

Run build_deep_index when you need symbol-level data; the default shallow index powers quick file discovery.

🔍 Search & Discovery

Tool

Description

search_code_advanced

Smart search with literal-by-default matching, optional regex=True, fuzzy matching, file filtering, and paginated results (10 per page by default); regex mode requires a native search tool because the basic fallback is literal-only

find_files

Locate files using glob patterns (e.g., **/*.py)

get_file_summary

Analyze file structure, functions, imports, and complexity (requires deep index)

🔄 Monitoring & Auto-refresh

Tool

Description

get_file_watcher_status

Check file watcher status and configuration

configure_file_watcher

Enable/disable auto-refresh and configure settings

🛠️ System & Maintenance

Tool

Description

create_temp_directory

Set up storage directory for index data

check_temp_directory

Verify index storage location and permissions

clear_settings

Reset all cached data and configurations

refresh_search_tools

Re-detect available search tools (ugrep, ripgrep, etc.)

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 Tip: run build_deep_index first if you get a needs_deep_index response.

🔍 Advanced Search Examples

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

Finds: getData(), getUserData(), getFormData(), etc. Regex search is opt-in; install a native search tool and use regex=True because the basic fallback stays literal-only.

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

Matches: authenticateUser, authUserToken, userAuthCheck, etc.

Search for "API_ENDPOINT" only in Python files

Uses: search_code_advanced with literal matching and file_pattern: "*.py" (defaults to 10 matches; use max_results to expand or start_index to page)

Configure automatic index updates when files change

Uses: configure_file_watcher to enable/disable monitoring and set debounce timing

I added new components, please refresh the project index

Uses: refresh_index to update the searchable cache

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

macOS File Watcher Options

The default FSEvents observer works well for most projects. If you experience issues, you can switch to an alternative observer via configure_file_watcher:

  • "auto" (default): Platform default (FSEvents on macOS)

  • "kqueue": Kqueue observer (macOS/BSD)

  • "fsevents": Force FSEvents (macOS only)

  • "polling": Cross-platform polling fallback

Note: Kqueue opens one file descriptor per watched file. For large projects using kqueue, you may need to increase the limit: ulimit -n 10240

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

MIT License

🌐 Translations

Available Tools

14 tools
build_deep_indexA
Build the deep index (full symbol extraction) for the current project.

This performs a complete re-index and loads it into memory.
Uses parallel processing by default. For large codebases (3000+ files),
tuning max_workers can significantly improve build times.

Args:
    max_workers: Maximum number of parallel workers for file processing.
        Defaults to min(4, cpu_count) when not specified.
        Increase for I/O-bound workloads on machines with many cores.
    timeout: Parallel build timeout in seconds. When not specified,
        scales dynamically based on file count (0.5s per file,
        min 30s, max 600s).

Inputs: max_workers, timeout. Returns: result

check_temp_directoryA

Check the temporary directory used for storing index data.

Inputs: no named parameters. Returns: object

clear_settingsB

Clear all settings and cached data.

Inputs: no named parameters. Returns: result

configure_file_watcherA

Configure file watcher service settings.

Args:
    enabled: Whether to enable file watcher
    debounce_seconds: Debounce time in seconds before triggering rebuild
    additional_exclude_patterns: Additional directory/file patterns to exclude
    observer_type: Observer backend to use. Options:
        - "auto" (default): platform default observer
        - "kqueue": Force kqueue observer (macOS/BSD)
        - "fsevents": Force FSEvents observer (macOS only, has known reliability issues)
        - "polling": Cross-platform polling fallback (slower but most compatible)

Inputs: enabled, debounce_seconds, additional_exclude_patterns, observer_type. Returns: result

create_temp_directoryA

Create the temporary directory used for storing index data.

Inputs: no named parameters. Returns: object

find_filesA

Find files matching glob pattern using in-memory index. Supports path patterns (.py, test_.js) and filename-only matching (README.md).

Inputs: pattern (required). Returns: result

get_file_summaryB
Get a summary of a specific file, including:
- Line count
- Function/class definitions (for supported languages)
- Import statements
- Basic complexity metrics

Inputs: file_path (required). Returns: object

get_file_watcher_statusA

Get file watcher service status and statistics.

Inputs: no named parameters. Returns: object

get_settings_infoB

Get information about the project settings.

Inputs: no named parameters. Returns: object

get_symbol_bodyA
Get the source code body of a specific symbol (function, method, or class).

This tool retrieves only the code for the specified symbol, enabling efficient
context usage by avoiding loading entire files.

Args:
    file_path: Path to the file containing the symbol
    symbol_name: Name of the symbol to retrieve (e.g., "process_data", "MyClass.my_method")

Returns:
    Dictionary containing:
    - status: "success" or "error"
    - symbol_name: Name of the symbol
    - type: Type of symbol (function, method, class)
    - line: Start line number
    - end_line: End line number
    - code: The actual source code
    - signature: Function/method signature (if available)
    - docstring: Documentation string (if available)
    - called_by: List of symbols that call this symbol

Inputs: file_path (required), symbol_name (required). Returns: object

refresh_indexA

Manually rebuild the project file index. Use after git operations or when index seems stale.

Inputs: no named parameters. Returns: result

refresh_search_toolsA

Manually re-detect the available command-line search tools on the system. This is useful if you have installed a new tool (like ripgrep) after starting the server.

Inputs: no named parameters. Returns: result

search_code_advancedA

Search for code pattern with pagination. Auto-selects best search tool (ugrep/ripgrep/ag/grep). Supports glob file_pattern (e.g., "*.py"), explicit regex mode, and fuzzy matching (ugrep only). Regex matching requires passing regex=True and may require an external search tool.

Inputs: pattern (required), case_sensitive, context_lines, file_pattern, +4 more. Returns: object

set_project_pathC

Set the base project path for indexing.

Inputs: path (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct action: index building, file watching, settings management, searching, etc. Overlap is minimal and descriptions clarify the differences.

    Naming Consistency5/5

    All tool names use a consistent verb_noun snake_case pattern (e.g., build_deep_index, check_temp_directory, get_file_summary). No mixing of conventions.

    Tool Count5/5

    14 tools cover indexing, searching, file details, symbol retrieval, settings, and utilities. This is well-scoped for a code index server, neither sparse nor excessive.

    Completeness4/5

    Covers core operations: index build/refresh, file and code search, symbol body retrieval, settings, file watcher. Minor gaps like listing symbols or index statistics exist but do not hinder primary use.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers