Show HN: Code Index MCP – Codebase Indexing Server for LLMs

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.

• Advanced Search: Auto-detects and uses the best available tool (ugrep, ripgrep, ag, or grep)
• Regex Support: Full regex pattern matching with ReDoS attack prevention
• Fuzzy Search: True fuzzy matching with edit distance (ugrep) or word boundary patterns
• File Analysis: Deep insights into structure, imports, classes, methods, and complexity metrics

• Mainstream Languages: Java, Python, JavaScript/TypeScript, C/C++, Go, Rust, C#
• Mobile Development: Swift, Kotlin, Objective-C/C++, React Native
• Web Frontend: Vue, React, Svelte, Astro, HTML, CSS, SCSS
• Database: SQL (MySQL, PostgreSQL, SQLite), NoSQL, stored procedures, migrations
• Scripting: Ruby, PHP, Shell, PowerShell, Bash
• Systems: C/C++, Rust, Go, Zig
• JVM Ecosystem: Java, Kotlin, Scala, Groovy
• Others: Lua, Perl, R, MATLAB, configuration files
• 50+ File Types Total - View complete list

• File Watcher: Automatic index updates when files change
• Cross-platform: Native OS file system monitoring (inotify, FSEvents, ReadDirectoryChangesW)
• Smart Debouncing: Batches rapid changes to prevent excessive rebuilds (default: 6 seconds)
• Thread-safe: Non-blocking background operations with ThreadPoolExecutor

• Smart Indexing: Recursively scans with intelligent filtering of build directories
• Persistent Caching: Stores indexes for lightning-fast subsequent access
• Lazy Loading: Tools detected only when needed for optimal startup
• Memory Efficient: Intelligent caching strategies for large codebases

📁 Programming Languages (Click to expand)

System & Low-Level:

• C/C++ (.c, .cpp, .h, .hpp)
• Rust (.rs)
• Zig (.zig)
• Go (.go)

Object-Oriented:

• Java (.java)
• C# (.cs)
• Kotlin (.kt)
• Scala (.scala)
• Objective-C/C++ (.m, .mm)
• Swift (.swift)

Scripting & Dynamic:

• Python (.py)
• JavaScript/TypeScript (.js, .ts, .jsx, .tsx, .mjs, .cjs)
• Ruby (.rb)
• PHP (.php)
• Shell (.sh, .bash)

🌐 Web & Frontend (Click to expand)

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)

🗄️ Database & SQL (Click to expand)

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)

📄 Documentation & Config (Click to expand)

• Markdown (.md, .mdx)
• Configuration (.json, .xml, .yml, .yaml)

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

Prerequisites: Python 3.10+, uv, and watchdog for file monitoring

⚠️ Auto-refresh Issue: If automatic index updates don't work after setup, try pip install watchdog. This may be due to environment isolation preventing file system monitoring. See Troubleshooting for details.

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

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

Alternative: Manual pip Installation

If you prefer traditional pip management:

Then configure:

Tool Description

set_project_path	Initialize indexing for a project directory
refresh_index	Rebuild the project index after file changes
get_settings_info	View current project configuration and status

Tool Description

search_code_advanced	Smart search with regex, fuzzy matching, and file filtering
find_files	Locate files using glob patterns (e.g., **/*.py)
get_file_summary	Analyze file structure, functions, imports, and complexity

Tool Description

get_file_watcher_status	Check file watcher status and configuration
configure_file_watcher	Enable/disable auto-refresh and configure settings

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.)

1. Initialize Your Project

Automatically indexes your codebase and creates searchable cache

2. Explore Project Structure

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

3. Analyze Key Files

Uses: get_file_summary to show functions, imports, and complexity

Code Pattern Search

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

Fuzzy Function Search

Matches: authenticateUser, authUserToken, userAuthCheck, etc.

Language-Specific Search

Uses: search_code_advanced with file_pattern: "*.py"

Auto-refresh Configuration

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

Project Maintenance

Uses: refresh_index to update the searchable cache

If the automatic index updates aren't working when files change, this may be related to environment isolation issues with the watchdog dependency.

Quick Solution:

What we suspect is happening:

• The uvx environment provides isolated dependency management
• On some systems (particularly Windows), environment isolation may prevent watchdog from accessing the file system monitoring APIs properly
• Installing watchdog in your system Python environment appears to resolve this issue while maintaining all other benefits of uvx isolation
• This is still under investigation, but the workaround above should get you working immediately

Alternative solutions:

• 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

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

---

MIT License

• 繁體中文
• 日本語