repository·master·Indexed 21 days ago
https://github.com/johnhuang316/code-index-mcpA Model Context Protocol (MCP) server providing intelligent code indexing, advanced search, and deep analysis for LLMs. It features AST-based parsing for 10 languages (including Python, TypeScript, Go, and Rust) and a fallback strategy for 50+ other file types. Tools include symbol-level analysis via build_deep_index, regex and fuzzy search, and real-time file monitoring with a configurable file watcher.
mcp.get_context() directly. Instead, annotate your parameters with ctx: Context to allow FastMCP to inject the request context automatically.When building or deploying MCP servers, follow these best practices:
capabilities metadata during the initialize phase. The server should gracefully error if a client offers a protocol version that is too new.device, jwt-bearer) your deployment expects, especially following the introduction of SEP-985.The project has addressed a critical issue where tree-sitter byte offsets (node.start_byte, node.end_byte) were being used to slice Python str objects (which use character indices). This caused symbol corruption and incorrect line numbers in any codebase containing multi-byte characters (e.g., Chinese, emojis, or accented characters like é).
Core Rule for Implementation:
To ensure accuracy, all slicing must be performed on the exact same bytes object that was passed to parser.parse().
Key Changes:
base_strategy.py: Introduced _slice_bytes and _line_at_byte to handle slicing directly on bytes objects. The previous _safe_extract_text and _extract_line_number methods (which mixed str and byte offsets) have been removed to prevent future errors.typescript, java, javascript, kotlin, and zig strategies have been updated to encode the file content to UTF-8 once and use the resulting bytes for both parsing and slicing via the new _slice_bytes method.Code Index MCP uses two levels of indexing to balance speed and depth:
build_deep_index): Generates a full symbol index (classes, methods, imports, etc.) using Tree-sitter AST parsing. This is required for advanced analysis like get_file_summary or complex structural queries.Note: If you need symbol-level data, you must explicitly run build_deep_index.
Code Index MCP uses a dual-strategy architecture for analyzing files.
The following languages use dedicated tree-sitter parsers for full AST analysis (extracting classes, methods, types, etc.):
.py, .pyw): Full AST analysis including class/method extraction and call tracking..js, .jsx, .mjs, .cjs): ES6+ class and function parsing..ts, .tsx): Type-aware symbol extraction including interfaces..java): Class hierarchies, method signatures, and call relationships..go): Struct methods, receiver types, and function analysis..m, .mm): Class/instance method distinction..zig, .zon): Function and struct analysis via AST.For 50+ other formats, the server provides basic metadata and file indexing using a fallback strategy. This includes:
.c, .cpp, .h, .hpp), Rust (.rs)..cs), Kotlin (.kt), Scala (.scala), Swift (.swift)..rb), PHP (.php), Shell (.sh, .bash)..vue), Svelte (.svelte), Astro (.astro), CSS/SCSS, HTML._slice_bytes implementation in csharp_strategy.py (around line 497) has a specific semantic behavior that differs from the base version: it returns an empty string "" when an out-of-bounds slice is requested, rather than clamping the range. This behavior is intentional and should not be modified to match the base implementation.Before merging an upgrade to the MCP SDK, complete the following validation steps:
uv lock --upgrade mcp and verify the server help command still works: uv run python -m code_index_mcp.server --help.uv run code-index-mcp --project-path <repo>. This must successfully execute set_project_path, build_deep_index, and search_code_advanced.uv run code-index-mcp --project-path <repo>To prevent symbol corruption when files contain non-ASCII characters (like Unicode comments), the KotlinParsingStrategy must use byte-based slicing instead of string-based slicing. This ensures that tree-sitter byte offsets align correctly with the content.
Key Changes:
_get_kotlin_type_name and _extract_kotlin_import_from_node to accept content_bytes: bytes instead of content: str._get_kotlin_function_name and _get_kotlin_function_signature to use content_bytes._slice_bytes implementations with the base self._slice_bytes method which operates on bytes.context.content_bytes.Verification: Run the following to ensure Unicode symbols match their ASCII counterparts and that fallback mechanisms (header/snippet) are not broken by byte offsets:
venv/bin/pytest tests/strategies/test_kotlin_non_ascii.py tests/strategies/test_kotlin_discovery.py tests/ -q# Example of the required change in Kotlin strategy helpers
def _get_kotlin_function_name(self, node, content_bytes: bytes) -> Optional[str]:
# Use content_bytes for slicing to maintain byte-offset fidelity
header = self._slice_bytes(content_bytes, node.start_byte, node.end_byte).split("\n", 1)[0]Once the MCP tools have been validated, run the following commands in the repository root to perform an end-to-end smoke test. Treat any warnings or stderr output as a blocker.
uv run code-index-mcp --project-path <path>uv run pytestuv run code-index-mcp --project-path C:\Users\p10362321\project\code-index-mcp
uv run pytestTo run the project from the source code or debug it using the MCP inspector, use the following commands:
Running from source (using uv):
git clone https://github.com/johnhuang316/code-index-mcp.git
cd code-index-mcp
uv sync
uv run code-index-mcpDebugging with MCP Inspector:
npx @modelcontextprotocol/inspector uvx code-index-mcpThe easiest way to use Code Index MCP with any MCP-compatible application (like Claude Desktop) is using uvx. This method automatically handles installation and execution.
Prerequisites:
Setup Steps:
claude_desktop_config.json or ~/.claude.json).To automatically set a specific project path upon startup, append --project-path /absolute/path/to/repo to the args array. This is equivalent to calling the set_project_path tool immediately after launch.
{
"mcpServers": {
"code-index": {
"command": "uvx",
"args": ["code-index-mcp"]
}
}
}If you are using Anthropic's Codex CLI, add the server to your ~/.codex/config.toml (on Windows: C:\Users\<you>\.codex\config.toml).
[mcp_servers.code-index]
type = "stdio"
command = "uvx"
args = ["code-index-mcp"]To automatically specify a project path, add --project-path <path> to the args list.
On Windows, uvx requires specific environment variables to ensure stability. You must include an env block in your configuration:
[mcp_servers.code-index]
type = "stdio"
command = "uvx"
args = ["code-index-mcp"]
[mcp_servers.code-index.env]
HOME = "C:\Users\<you>"
APPDATA = "C:\Users\<you>\AppData\Roaming"
LOCALAPPDATA = "C:\Users\<you>\AppData\Local"
SystemRoot = "C:\Windows"