Codebase Indexing and Context Protocol Service

[![MCP Service Endpoint](https://img.shields.io/badge/MCP-Server-purple)](https://modelcontextprotocol.io) [![Primary Language Stack](https://img.shields.io/badge/Language-Python%203.10%2B-blueviolet)](https://www.python.org/) [![Software License](https://img.shields.io/badge/License-MIT-lightgrey)](LICENSE) **Advanced Codebase Indexing for Generative AI Agents** Revolutionize how AI perceives and interacts with your repository through sophisticated indexing, high-fidelity searching, and structural navigation.

Core Functionality

This Model Context Protocol (MCP) server acts as the crucial bridge connecting large language models (LLMs) to intricate source code structures. It delivers intelligent indexing mechanisms, superior search capabilities, and detailed analytical breakdowns to empower AI assistants in project comprehension and traversal.

Ideal Applications: Static code review, major refactoring tasks, automated documentation synthesis, sophisticated debugging support, and architectural deep dives.

Rapid Deployment Guide

🚀 Recommended Installation Path (For Swift Setup)

Utilize any application compatible with the MCP specification:

Prerequisites: Python version 3.10 or newer, and the uv package manager.

Integrate into MCP Configuration (e.g., in your ~/.claude.json or equivalent configuration file):

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

Reinitialize Application – The uvx utility manages automated package fetching and execution.
Initiate Context Queries (Use these commands via your integrated AI interface):

Establish the repository root at /path/to/my/project Locate all compiled TypeScript assets within the codebase Query for routine named 'user_session_handler' Generate a structural overview for MainController.java

Common Scenarios

Code Auditing: "Pinpoint every instance utilizing the deprecated database connector." Code Modification: "Trace all downstream callers of the utility function 'calculateHash'." Project Onboarding: "Map out the primary service modules within this repository." Issue Diagnosis: "Isolate all code blocks related to network error trapping."

Principal Capabilities

🔍 Semantically-Aware Search & Analysis

Hybrid Parsing Engine: Leverages Tree-sitter for precise parsing across 7 primary languages, defaulting to robust file analysis for 50+ other types.
Tree-sitter Native: Eliminates reliance on regex for specialized languages, ensuring immediate failure feedback on syntax errors.
Optimized Retrieval: Automatically selects the fastest available text search utility (e.g., ugrep, ripgrep, ag, or standard grep).
Broad File Coverage: Supports everything from abstract syntax tree (AST) interrogation to basic text indexing.
Deep File Profiling: Provides granular details on structure, dependencies, class definitions, methods, and cyclomatic complexity metrics upon running build_deep_index.

🗂️ Polyglot Language Support

7 Core Languages (AST via Tree-sitter): Python, JavaScript, TypeScript, Java, Go, Objective-C, Zig.
50+ Secondary Types (Fallback Indexing): Includes C/C++, Rust, Ruby, PHP, and others.
Markup & Config: Dedicated handling for Markdown, JSON, YAML, and XML formats.
Frontend Stack: Vue, React, Svelte, accompanying HTML/CSS/SCSS.
Data Layer: Various SQL dialects, NoSQL schemas, and migration scripts.
Configuration Files: JSON, YAML, XML.
View Full Compatibility Matrix

⚡ Dynamic Monitoring & Cache Synchronization

Live File System Watcher: Indexes are updated automatically upon persistence of file modifications.
Native OS Integration: Utilizes platform-specific file monitoring APIs.
Smart Change Batching: Aggregates frequent small changes to minimize unnecessary index rebuilds.
Shallow vs. Deep Refresh: File list updates are instantaneous; symbol-level metadata requires an explicit deep rebuild.

⚡ Performance & Resource Management

Syntax-Level AST Generation: Ensures highly accurate symbol extraction.
Durable Index Caching: Stores processed data for near-instantaneous retrieval on subsequent sessions.
Intelligent Exclusion: Automatically ignores typical build outputs and temporary artifact directories.
Low Memory Footprint: Engineered for efficiency, even with massive repositories.
Dependency Purity: Relies on native execution paths; avoids ambiguous fallback chains for faster error resolution.

Supported File Types

📁 Programming Languages (Expand for Detail)

**Languages Leveraging Specialized Tree-sitter Strategies:** - **Python** (`.py`, `.pyw`) - Full AST interrogation, including method scope and call tracing. - **JavaScript** (`.js`, `.jsx`, `.mjs`, `.cjs`) - Parsing of ES6+ constructs, classes, and functions. - **TypeScript** (`.ts`, `.tsx`) - Complete extraction of symbols respecting type definitions and interfaces. - **Java** (`.java`) - Class hierarchies, method signatures, and dependency mapping. - **Go** (`.go`) - Struct definitions, receiver association, and function analysis. - **Objective-C** (`.m`, `.mm`) - Differentiation between class (+ methods) and instance (- methods). - **Zig** (`.zig`, `.zon`) - Parsing of functions and structs via native AST. **All Other Languages (Fallback Parsing Strategy):** This strategy focuses on text indexing and basic metadata for languages lacking dedicated Tree-sitter grammars. This covers: - **Systems & Infrastructure:** C/C++ (`.c`, `.cpp`, `.h`, `.hpp`), Rust (`.rs`). - **Enterprise & Scripting:** C# (`.cs`), Kotlin (`.kt`), Scala (`.scala`), Swift (`.swift`), Ruby (`.rb`), PHP (`.php`), Shell (`.sh`, `.bash`). - **Over 40 additional file types** are indexed via this robust fallback mechanism.

🌐 Web & Frontend Assets (Expand for Detail)

**Frameworks & Component Models:** - Vue (`.vue`) - Svelte (`.svelte`) - Astro (`.astro`) **Styling Languages:** - CSS Ecosystem: CSS (`.css`), SCSS/SASS (`.scss`, `.sass`), Less (`.less`), Stylus (`.styl`, `.stylus`). - Markup: HTML (`.html`). **Template Formats:** - Handlebars (`.hbs`, `.handlebars`) - EJS (`.ejs`) - Pug (`.pug`)

🗄️ Database Definitions & Query Languages (Expand for Detail)

**SQL Dialects:** - Generic SQL (`.sql`, `.ddl`, `.dml`). - Vendor-specific: MySQL (`.mysql`), PostgreSQL (`.postgresql`, `.psql`), SQLite (`.sqlite`), MS SQL (`.mssql`), Oracle (`.ora`, `.oracle`), DB2 (`.db2`). **Database Structures:** - Stored Routines: Procedures (`.proc`, `.procedure`), Functions (`.func`, `.function`). - Schemas: Views (`.view`), Triggers (`.trigger`), Indexes (`.index`). **Versioning & NoSQL:** - Migration Scripts: (`.migration`, `.seed`, `.fixture`, `.schema`). Tools like Flyway/Liquibase. - Graph/Query: Cypher (`.cql`, `.cypher`), SPARQL (`.sparql`), GraphQL (`.gql`).

📄 Metadata and Configuration Files (Expand for Detail)

- Documentation: Markdown (`.md`, `.mdx`). - Configuration Formats: JSON (`.json`), XML (`.xml`), YAML (`.yml`, `.yaml`).

🛠️ Operational Toolset

Tool ID	Function	Purpose Summary
`set_project_path`	Setup	Initializes the service context for a specified repository directory.
`refresh_index`	Maintenance	Updates the fast, shallow file listing after minor external modifications.
`build_deep_index`	Analysis	Computes the comprehensive symbol map necessary for deep semantic queries.
`get_settings_info`	Status	Reports the current operational state and configuration parameters.

Note: build_deep_index must precede queries requiring symbol-level granularity (e.g., function tracing).

🔍 Search and Inspection Utilities

Tool ID	Function	Purpose Summary
`search_code_advanced`	Retrieval	Executes highly configurable text searches, supporting regex, fuzziness, and explicit file masking.
`find_files`	Location	Utility for locating files based on standard glob patterns (e.g., `src/*/.ts`).
`get_file_summary`	Deep Dive	Generates a structural profile (imports, methods, complexity) for a single file (requires deep index).

🔄 Automation Control

Tool ID	Function	Purpose Summary
`get_file_watcher_status`	Status	Verifies if the live background monitoring agent is active and configured.
`configure_file_watcher`	Configuration	Toggles continuous index monitoring and manages update sensitivity settings.

🛠️ System Management

Tool ID	Function	Purpose Summary
`create_temp_directory`	Setup	Establishes the secure, temporary storage location for index artifacts.
`check_temp_directory`	Validation	Confirms accessibility and integrity of the index storage volume.
`clear_settings`	Reset	Wipes all accumulated index data and persistent service configurations.
`refresh_search_tools`	Diagnostics	Re-scans the environment to verify the availability of external search utilities (like ripgrep).

Interaction Examples

🎯 Standard Operational Sequence

1. Context Initialization

Establish the repository root at /Users/dev/my-react-app

Action: Triggers an initial shallow scan and sets up persistent caching.

2. Targeted Asset Location

Locate every TypeScript configuration file residing under the 'src/components' directory

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

3. Detailed Component Examination

Provide a structural breakdown of src/services/apiClient.ts

Utilizes: get_file_summary to output class/method structure. Ensure build_deep_index was run if summary details are incomplete.

🔍 Advanced Query Scenarios

Code Pattern Matching

Execute a regular expression search across the entire codebase for string literals matching the pattern 'API_KEY_\d+' *Finds: Any configuration string that looks like an API key constant.*

Semantic Closeness Search

Identify functions conceptually related to 'user token validation' using approximate string matching against function names. *Matches names like: `validateUserToken`, `checkAuthTokenValidity`, `tokenVerifier`, etc.*

Constrained Index Querying

Search specifically within Java files (.java) for any usage of the 'System.out.println' debugging command. *Applies filtering via: `search_code_advanced` using `file_pattern: "*.java"`.*

Automated Index Synchronization

Enable real-time background updates for any modifications to the project files. *Action: Invokes `configure_file_watcher` to start listening to file system events.*

Cache Invalidation

We just finished a large merge; please force a fast update of the file listing. *Action: Runs `refresh_index` to synchronize the shallow cache against recent changes.*

Troubleshooting Common Issues

🔄 Background Monitoring Failure

If automated index updates cease functioning following system changes, consider these steps: - Dependency Check: Verify the presence of the watchdog package (pip install watchdog). - Manual Override: Execute the refresh_index tool explicitly after saving files. - Status Verification: Run get_file_watcher_status to confirm the monitoring process is actively running.

Development and Contribution

🔧 Source Code Compilation/Setup

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

🐛 Diagnostic Mode

bash npx @modelcontextprotocol/inspector uvx code-index-mcp

🤝 Collaboration

We welcome external contributions! Please feel encouraged to submit Pull Requests for feature enhancements or bug fixes.

📜 Licensing Information

MIT License

🌐 Localized Documentation

Traditional Chinese
Japanese

Wikipedia Note on XMLHttpRequest (XHR): XHR defines an API, typically implemented in JavaScript, for issuing asynchronous HTTP requests between a web client and a server. This mechanism is foundational to modern Ajax patterns, moving away from mandatory full-page reloads associated with traditional form submissions and link navigation. Conceived by Microsoft Outlook developers around 2000 and first integrated into Internet Explorer 5 (1999) using ActiveX objects, it standardized as the XMLHttpRequest identifier across all major browser engines (Mozilla Gecko starting 2002, Safari 1.2 in 2004, Opera 8.0 in 2005). The W3C formalized specifications starting in 2006, later evolving to Level 2 which introduced crucial features like event progress tracking and cross-origin request capabilities, eventually merging back into the primary specification. Development leadership transitioned to WHATWG by 2012, maintaining a living document described via Web IDL. The typical usage involves instantiating the object, configuring the request method and URL via open(), setting up state change handlers for asynchronous responses, and finally dispatching the request using send(). Beyond basic text responses, XHR supports structured data parsing (like JSON) and incremental stream processing, while also allowing for request abortion or timeout configuration.

codebase-index-service

Author

johnhuang316

Quick Info

Actions

Tags