{"id":28769335,"url":"https://github.com/johnhuang316/code-index-mcp","last_synced_at":"2026-08-27T20:23:31.320Z","repository":{"id":282996195,"uuid":"950338765","full_name":"johnhuang316/code-index-mcp","owner":"johnhuang316","description":"A Model Context Protocol (MCP) server that helps large language models index, search, and analyze code repositories with minimal setup","archived":false,"fork":false,"pushed_at":"2026-07-27T08:14:15.000Z","size":1381,"stargazers_count":1005,"open_issues_count":23,"forks_count":121,"subscribers_count":5,"default_branch":"master","last_synced_at":"2026-08-26T20:13:24.002Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnhuang316.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["johnhuang316"]}},"created_at":"2025-03-18T02:21:59.000Z","updated_at":"2026-08-24T08:14:22.000Z","dependencies_parsed_at":"2025-11-29T08:05:36.461Z","dependency_job_id":null,"html_url":"https://github.com/johnhuang316/code-index-mcp","commit_stats":null,"previous_names":["johnhuang316/code-index-mcp"],"tags_count":48,"template":false,"template_full_name":null,"purl":"pkg:github/johnhuang316/code-index-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnhuang316%2Fcode-index-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnhuang316%2Fcode-index-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnhuang316%2Fcode-index-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnhuang316%2Fcode-index-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnhuang316","download_url":"https://codeload.github.com/johnhuang316/code-index-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnhuang316%2Fcode-index-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36946745,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-08-22T15:14:58.755Z","status":"online","status_checked_at":"2026-08-27T02:00:07.166Z","response_time":96,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-17T13:03:50.544Z","updated_at":"2026-08-27T20:23:31.313Z","avatar_url":"https://github.com/johnhuang316.png","language":"Python","funding_links":["https://github.com/sponsors/johnhuang316"],"categories":["Repository \u0026 Code Analysis MCP Servers","📚 Projects (1974 total)","APIs and HTTP Requests","🤖 AI/ML","MCP Servers \u0026 Protocol","Python"],"sub_categories":["MCP Servers"],"readme":"# Code Index MCP\n\n\u003cdiv align=\"center\"\u003e\n\n[![MCP Server](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io)\n[![Python](https://img.shields.io/badge/Python-3.10%2B-green)](https://www.python.org/)\n[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)\n[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-red)](https://github.com/sponsors/johnhuang316)\n\n**Intelligent code indexing and analysis for Large Language Models**\n\nTransform how AI understands your codebase with advanced search, analysis, and navigation capabilities.\n\n\u003c/div\u003e\n\n\u003ca href=\"https://glama.ai/mcp/servers/@johnhuang316/code-index-mcp\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@johnhuang316/code-index-mcp/badge\" alt=\"code-index-mcp MCP server\" /\u003e\n\u003c/a\u003e\n\n## Overview\n\nCode Index MCP is a [Model Context Protocol](https://modelcontextprotocol.io) 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.\n\n**Perfect for:** Code review, refactoring, documentation generation, debugging assistance, and architectural analysis.\n\n## Quick Start\n\n### 🚀 **Recommended Setup (Most Users)**\n\nThe easiest way to get started with any MCP-compatible application:\n\n**Prerequisites:** Python 3.10+ and [uv](https://github.com/astral-sh/uv)\n\n1. **Add to your MCP configuration** (e.g., `claude_desktop_config.json` or `~/.claude.json`):\n   ```json\n   {\n     \"mcpServers\": {\n       \"code-index\": {\n         \"command\": \"uvx\",\n         \"args\": [\"code-index-mcp\"]\n       }\n     }\n   }\n   ```\n   \u003e Optional: append `--project-path /absolute/path/to/repo` to the `args` array so the server\n   \u003e initializes with that repository automatically (equivalent to calling `set_project_path`\n   \u003e after startup).\n\n2. **Restart your application** – `uvx` automatically handles installation and execution\n\n3. **Start using** (give these prompts to your AI assistant):\n   ```\n   Set the project path to /Users/dev/my-react-app\n   Find all TypeScript files in this project  \n   Search for \"authentication\" functions\n   Analyze the main App.tsx file\n   ```\n   *If you launch with `--project-path`, you can skip the first command above - the server already\n   knows the project location.*\n\n### Codex CLI Configuration\n\nIf you are using Anthropic's Codex CLI, add the server to `~/.codex/config.toml`.\nOn Windows the file lives at `C:\\Users\\\u003cyou\u003e\\.codex\\config.toml`:\n\n```toml\n[mcp_servers.code-index]\ntype = \"stdio\"\ncommand = \"uvx\"\nargs = [\"code-index-mcp\"]\n```\n\u003e You can append `--project-path C:/absolute/path/to/repo` to the `args` list to set the project\n\u003e automatically on startup (same effect as running the `set_project_path` tool).\n\nOn Windows, `uvx` needs the standard profile directories to be present.\nKeep the environment override in the same block so the MCP starts reliably:\n\n```toml\nenv = {\n  HOME = \"C:\\\\Users\\\\\u003cyou\u003e\",\n  APPDATA = \"C:\\\\Users\\\\\u003cyou\u003e\\\\AppData\\\\Roaming\",\n  LOCALAPPDATA = \"C:\\\\Users\\\\\u003cyou\u003e\\\\AppData\\\\Local\",\n  SystemRoot = \"C:\\\\Windows\"\n}\n```\n\nLinux and macOS already expose the required XDG paths and `HOME`, so you can usually omit the `env`\ntable there.\nAdd overrides only if you run the CLI inside a restricted container.\n\n### FastMCP \u0026 Discovery Manifests\n\n- Run `fastmcp run fastmcp.json` to launch the server via [FastMCP](https://fastmcp.wiki/) with\n  the correct source entrypoint and dependency metadata. Pass `--project-path` (or call the\n  `set_project_path` tool after startup) so the index boots against the right repository.\n- Serve or copy `.well-known/mcp.json` to share a standards-compliant MCP manifest. Clients that\n  support the `.well-known` convention (e.g., Claude Desktop, Codex CLI) can import this file\n  directly instead of crafting configs manually.\n- Publish `.well-known/mcp.llmfeed.json` when you want to expose the richer LLM Feed metadata.\n  It references the same `code-index` server definition plus documentation/source links, which\n  helps registries present descriptions, tags, and capabilities automatically.\n\nWhen sharing the manifests, remind consumers to supply `--project-path` (or to call\n`set_project_path`) so the server indexes the intended repository.\n\n## Typical Use Cases\n\n**Code Review**: \"Find all places using the old API\"  \n**Refactoring Help**: \"Where is this function called?\"  \n**Learning Projects**: \"Show me the main components of this React project\"  \n**Debugging**: \"Search for all error handling related code\"\n\n## Key Features\n\n### 🔍 **Intelligent Search \u0026 Analysis**\n- **Dual-Strategy Architecture**: Specialized tree-sitter parsing for 10 core languages, fallback strategy for 50+ file types\n- **Direct Tree-sitter Integration**: No regex fallbacks for specialized languages - fail fast with clear errors\n- **Advanced Search**: Auto-detects and uses the best available tool (ugrep, ripgrep, ag, or grep)\n- **Universal File Support**: Comprehensive coverage from advanced AST parsing to basic file indexing\n- **File Analysis**: Deep insights into structure, imports, classes, methods, and complexity metrics after running `build_deep_index`\n\n### 🗂️ **Multi-Language Support**  \n- **10 Languages with Tree-sitter AST Parsing**: Python, JavaScript, TypeScript, Java, Kotlin, C#, Go, Objective-C, Zig, Rust\n- **50+ File Types with Fallback Strategy**: C/C++, Ruby, PHP, and all other programming languages\n- **Document \u0026 Config Files**: Markdown, JSON, YAML, XML with appropriate handling\n- **Web Frontend**: Vue, React, Svelte, HTML, CSS, SCSS\n- **Java Web \u0026 Build**: JSP/Tag files (`.jsp`, `.jspx`, `.jspf`, `.tag`, `.tagx`), Grails/GSP (`.gsp`), Gradle \u0026 Groovy builds (`.gradle`, `.groovy`), `.properties`, and Protocol Buffers (`.proto`)\n- **Database**: SQL variants, NoSQL, stored procedures, migrations\n- **Configuration**: JSON, YAML, XML, Markdown\n- **[View complete list](#supported-file-types)**\n\n### ⚡ **Real-time Monitoring \u0026 Auto-refresh**\n- **File Watcher**: Automatic index updates when files change\n- **Cross-platform**: Native OS file system monitoring\n- **Smart Processing**: Batches rapid changes to prevent excessive rebuilds\n- **Shallow Index Refresh**: Watches file changes and keeps the file list current; run a deep rebuild when you need symbol metadata\n\n### ⚡ **Performance \u0026 Efficiency**\n- **Tree-sitter AST Parsing**: Native syntax parsing for accurate symbol extraction\n- **Persistent Caching**: Stores indexes for lightning-fast subsequent access\n- **Smart Filtering**: Intelligent exclusion of build directories and temporary files\n- **Memory Efficient**: Optimized for large codebases\n- **Direct Dependencies**: No fallback mechanisms - fail fast with clear error messages\n\n## Supported File Types\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e📁 Programming Languages (Click to expand)\u003c/strong\u003e\u003c/summary\u003e\n\n**Languages with Specialized Tree-sitter Strategies:**\n- **Python** (`.py`, `.pyw`) - Full AST analysis with class/method extraction and call tracking\n- **JavaScript** (`.js`, `.jsx`, `.mjs`, `.cjs`) - ES6+ class and function parsing with tree-sitter\n- **TypeScript** (`.ts`, `.tsx`) - Complete type-aware symbol extraction with interfaces\n- **Java** (`.java`) - Full class hierarchy, method signatures, and call relationships\n- **Kotlin** (`.kt`, `.kts`) - Package-aware symbol extraction with methods and call relationships\n- **C#** (`.cs`) - Namespace-aware type/member extraction with call relationships\n- **Go** (`.go`) - Struct methods, receiver types, and function analysis\n- **Rust** (`.rs`) - Functions, module-aware names, impl methods, structs/enums/traits, and basic call relationships\n- **Objective-C** (`.m`, `.mm`) - Class/instance method distinction with +/- notation\n- **Zig** (`.zig`, `.zon`) - Function and struct parsing with tree-sitter AST\n\n**All Other Programming Languages:**\nAll other programming languages use the **FallbackParsingStrategy** which provides basic file indexing and metadata extraction. This includes:\n- **System \u0026 Low-Level:** C/C++ (`.c`, `.cpp`, `.h`, `.hpp`)\n- **Object-Oriented:** Scala (`.scala`), Swift (`.swift`)\n- **Scripting \u0026 Dynamic:** Ruby (`.rb`), PHP (`.php`), Shell (`.sh`, `.bash`)\n- **And 40+ more file types** - All handled through the fallback strategy for basic indexing\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🌐 Web \u0026 Frontend (Click to expand)\u003c/strong\u003e\u003c/summary\u003e\n\n**Frameworks \u0026 Libraries:**\n- Vue (`.vue`)\n- Svelte (`.svelte`)\n- Astro (`.astro`)\n\n**Styling:**\n- CSS (`.css`, `.scss`, `.less`, `.sass`, `.stylus`, `.styl`)\n- HTML (`.html`)\n\n**Templates:**\n- Handlebars (`.hbs`, `.handlebars`)\n- EJS (`.ejs`)\n- Pug (`.pug`)\n- FreeMarker (`.ftl`)\n- Mustache (`.mustache`)\n- Liquid (`.liquid`)\n- ERB (`.erb`)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🗄️ Database \u0026 SQL (Click to expand)\u003c/strong\u003e\u003c/summary\u003e\n\n**SQL Variants:**\n- Standard SQL (`.sql`, `.ddl`, `.dml`)\n- Database-specific (`.mysql`, `.postgresql`, `.psql`, `.sqlite`, `.mssql`, `.oracle`, `.ora`, `.db2`)\n\n**Database Objects:**\n- Procedures \u0026 Functions (`.proc`, `.procedure`, `.func`, `.function`)\n- Views \u0026 Triggers (`.view`, `.trigger`, `.index`)\n\n**Migration \u0026 Tools:**\n- Migration files (`.migration`, `.seed`, `.fixture`, `.schema`)\n- Tool-specific (`.liquibase`, `.flyway`)\n\n**NoSQL \u0026 Modern:**\n- Graph \u0026 Query (`.cql`, `.cypher`, `.sparql`, `.gql`)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e📄 Documentation \u0026 Config (Click to expand)\u003c/strong\u003e\u003c/summary\u003e\n\n- Markdown (`.md`, `.mdx`)\n- Configuration (`.json`, `.xml`, `.yml`, `.yaml`, `.properties`)\n\n\u003c/details\u003e\n\n### 🛠️ **Development Setup**\n\nFor contributing or local development:\n\n1. **Clone and install:**\n   ```bash\n   git clone https://github.com/johnhuang316/code-index-mcp.git\n   cd code-index-mcp\n   uv sync\n   ```\n\n2. **Configure for local development:**\n   ```json\n   {\n     \"mcpServers\": {\n       \"code-index\": {\n         \"command\": \"uv\",\n         \"args\": [\"run\", \"code-index-mcp\"]\n       }\n     }\n   }\n   ```\n\n3. **Debug with MCP Inspector:**\n   ```bash\n   npx @modelcontextprotocol/inspector uv run code-index-mcp\n   ```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAlternative: Manual pip Installation\u003c/strong\u003e\u003c/summary\u003e\n\nIf you prefer traditional pip management:\n\n```bash\npip install code-index-mcp\n```\n\nThen configure:\n```json\n{\n  \"mcpServers\": {\n    \"code-index\": {\n      \"command\": \"code-index-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\n## Available Tools\n\n### 🏗️ **Project Management**\n| Tool | Description |\n|------|-------------|\n| **`set_project_path`** | Initialize indexing for a project directory |\n| **`refresh_index`** | Rebuild the shallow file index after file changes |\n| **`build_deep_index`** | Generate the full symbol index used by deep analysis |\n| **`get_settings_info`** | View current project configuration and status |\n\n*Run `build_deep_index` when you need symbol-level data; the default shallow index powers quick file discovery.*\n\n### 🔍 **Search \u0026 Discovery**\n| Tool | Description |\n|------|-------------|\n| **`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 |\n| **`find_files`** | Locate files using glob patterns (e.g., `**/*.py`) |\n| **`get_file_summary`** | Analyze file structure, functions, imports, and complexity (requires deep index) |\n\n### 🔄 **Monitoring \u0026 Auto-refresh**\n| Tool | Description |\n|------|-------------|\n| **`get_file_watcher_status`** | Check file watcher status and configuration |\n| **`configure_file_watcher`** | Enable/disable auto-refresh and configure settings |\n\n### 🛠️ **System \u0026 Maintenance**\n| Tool | Description |\n|------|-------------|\n| **`create_temp_directory`** | Set up storage directory for index data |\n| **`check_temp_directory`** | Verify index storage location and permissions |\n| **`clear_settings`** | Reset all cached data and configurations |\n| **`refresh_search_tools`** | Re-detect available search tools (ugrep, ripgrep, etc.) |\n\n## Usage Examples\n\n### 🎯 **Quick Start Workflow**\n\n**1. Initialize Your Project**\n```\nSet the project path to /Users/dev/my-react-app\n```\n*Automatically indexes your codebase and creates searchable cache*\n\n**2. Explore Project Structure**\n```\nFind all TypeScript component files in src/components\n```\n*Uses: `find_files` with pattern `src/components/**/*.tsx`*\n\n**3. Analyze Key Files**\n```\nGive me a summary of src/api/userService.ts\n```\n*Uses: `get_file_summary` to show functions, imports, and complexity*\n*Tip: run `build_deep_index` first if you get a `needs_deep_index` response.*\n\n### 🔍 **Advanced Search Examples**\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCode Pattern Search\u003c/strong\u003e\u003c/summary\u003e\n\n```\nSearch for all function calls matching \"get.*Data\" using `regex=True`\n```\n*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.*\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFuzzy Function Search\u003c/strong\u003e\u003c/summary\u003e\n\n```\nFind authentication-related functions with fuzzy search for 'authUser'\n```\n*Matches: `authenticateUser`, `authUserToken`, `userAuthCheck`, etc.*\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eLanguage-Specific Search\u003c/strong\u003e\u003c/summary\u003e\n\n```\nSearch for \"API_ENDPOINT\" only in Python files\n```\n*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)*\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAuto-refresh Configuration\u003c/strong\u003e\u003c/summary\u003e\n\n```\nConfigure automatic index updates when files change\n```\n*Uses: `configure_file_watcher` to enable/disable monitoring and set debounce timing*\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eProject Maintenance\u003c/strong\u003e\u003c/summary\u003e\n\n```\nI added new components, please refresh the project index\n```\n*Uses: `refresh_index` to update the searchable cache*\n\n\u003c/details\u003e\n\n## Troubleshooting\n\n### 🔄 **Auto-refresh Not Working**\n\nIf automatic index updates aren't working when files change, try:\n- `pip install watchdog` (may resolve environment isolation issues)\n- Use manual refresh: Call the `refresh_index` tool after making file changes\n- Check file watcher status: Use `get_file_watcher_status` to verify monitoring is active\n\n### **macOS File Watcher Options**\n\nThe default FSEvents observer works well for most projects. If you experience issues, you can switch to an alternative observer via `configure_file_watcher`:\n\n- `\"auto\"` (default): Platform default (FSEvents on macOS)\n- `\"kqueue\"`: Kqueue observer (macOS/BSD)\n- `\"fsevents\"`: Force FSEvents (macOS only)\n- `\"polling\"`: Cross-platform polling fallback\n\nNote: Kqueue opens one file descriptor per watched file. For large projects using kqueue, you may need to increase the limit: `ulimit -n 10240`\n\n## Development \u0026 Contributing\n\n### 🔧 **Building from Source**\n```bash\ngit clone https://github.com/johnhuang316/code-index-mcp.git\ncd code-index-mcp\nuv sync\nuv run code-index-mcp\n```\n\n### 🐛 **Debugging**\n```bash\nnpx @modelcontextprotocol/inspector uvx code-index-mcp\n```\n\n### 🤝 **Contributing**\nContributions are welcome! Please feel free to submit a Pull Request.\n\n---\n\n### 📜 **License**\n[MIT License](LICENSE)\n\n### 🌐 **Translations**\n- [繁體中文](README_zh.md)\n- [日本語](README_ja.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnhuang316%2Fcode-index-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnhuang316%2Fcode-index-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnhuang316%2Fcode-index-mcp/lists"}