Skip to content
Back to search

code-index-mcp

A Model Context Protocol (MCP) server that helps large language models index, search, and analyze code repositories with minimal setup

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/johnhuang316--code-index-mcp/badge.svg)](/listings/johnhuang316--code-index-mcp)

HTML

<a href="/listings/johnhuang316--code-index-mcp"><img src="/api/listings/johnhuang316--code-index-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

πŸš€ **Recommended Setup (Most Users)**

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

**Prerequisites:** Python 3.10+ and [uv](https://github.com/astral-sh/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](https://fastmcp.wiki/) 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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 427 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Code Index MCP
  2. <div align="center">
  3. [![MCP Server](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io)
  4. [![Python](https://img.shields.io/badge/Python-3.10%2B-green)](https://www.python.org/)
  5. [![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)
  6. [![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-red)](https://github.com/sponsors/johnhuang316)
  7. **Intelligent code indexing and analysis for Large Language Models**
  8. Transform how AI understands your codebase with advanced search, analysis, and navigation capabilities.
  9. </div>
  10. <a href="https://glama.ai/mcp/servers/@johnhuang316/code-index-mcp">
  11. <img width="380" height="200" src="https://glama.ai/mcp/servers/@johnhuang316/code-index-mcp/badge" alt="code-index-mcp MCP server" />
  12. </a>
  13. ## Overview
  14. Code 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.
  15. **Perfect for:** Code review, refactoring, documentation generation, debugging assistance, and architectural analysis.
  16. ## Quick Start
  17. ### πŸš€ **Recommended Setup (Most Users)**
  18. The easiest way to get started with any MCP-compatible application:
  19. **Prerequisites:** Python 3.10+ and [uv](https://github.com/astral-sh/uv)
  20. 1. **Add to your MCP configuration** (e.g., `claude_desktop_config.json` or `~/.claude.json`):
  21. ```json
  22. {
  23. "mcpServers": {
  24. "code-index": {
  25. "command": "uvx",
  26. "args": ["code-index-mcp"]
  27. }
  28. }
  29. }
  30. ```
  31. > Optional: append `--project-path /absolute/path/to/repo` to the `args` array so the server
  32. > initializes with that repository automatically (equivalent to calling `set_project_path`
  33. > after startup).
  34. 2. **Restart your application** – `uvx` automatically handles installation and execution
  35. 3. **Start using** (give these prompts to your AI assistant):
  36. ```
  37. Set the project path to /Users/dev/my-react-app
  38. Find all TypeScript files in this project
  39. Search for "authentication" functions
  40. Analyze the main App.tsx file
  41. ```
  42. *If you launch with `--project-path`, you can skip the first command above - the server already
  43. knows the project location.*
  44. ### Codex CLI Configuration
  45. If you are using Anthropic's Codex CLI, add the server to `~/.codex/config.toml`.
  46. On Windows the file lives at `C:\Users\<you>\.codex\config.toml`:
  47. ```toml
  48. [mcp_servers.code-index]
  49. type = "stdio"
  50. command = "uvx"
  51. args = ["code-index-mcp"]
  52. ```
  53. > You can append `--project-path C:/absolute/path/to/repo` to the `args` list to set the project
  54. > automatically on startup (same effect as running the `set_project_path` tool).
  55. On Windows, `uvx` needs the standard profile directories to be present.
  56. Keep the environment override in the same block so the MCP starts reliably:
  57. ```toml
  58. env = {
  59. HOME = "C:\\Users\\<you>",
  60. APPDATA = "C:\\Users\\<you>\\AppData\\Roaming",
  61. LOCALAPPDATA = "C:\\Users\\<you>\\AppData\\Local",
  62. SystemRoot = "C:\\Windows"
  63. }
  64. ```
  65. Linux and macOS already expose the required XDG paths and `HOME`, so you can usually omit the `env`
  66. table there.
  67. Add overrides only if you run the CLI inside a restricted container.
  68. ### FastMCP & Discovery Manifests
  69. - Run `fastmcp run fastmcp.json` to launch the server via [FastMCP](https://fastmcp.wiki/) with
  70. the correct source entrypoint and dependency metadata. Pass `--project-path` (or call the
  71. `set_project_path` tool after startup) so the index boots against the right repository.
  72. - Serve or copy `.well-known/mcp.json` to share a standards-compliant MCP manifest. Clients that
  73. support the `.well-known` convention (e.g., Claude Desktop, Codex CLI) can import this file
  74. directly instead of crafting configs manually.
  75. - Publish `.well-known/mcp.llmfeed.json` when you want to expose the richer LLM Feed metadata.
  76. It references the same `code-index` server definition plus documentation/source links, which
  77. helps registries present descriptions, tags, and capabilities automatically.
  78. When sharing the manifests, remind consumers to supply `--project-path` (or to call
  79. `set_project_path`) so the server indexes the intended repository.
  80. ## Typical Use Cases
  81. **Code Review**: "Find all places using the old API"
  82. **Refactoring Help**: "Where is this function called?"
  83. **Learning Projects**: "Show me the main components of this React project"
  84. **Debugging**: "Search for all error handling related code"
  85. ## Key Features
  86. ### πŸ” **Intelligent Search & Analysis**
  87. - **Dual-Strategy Architecture**: Specialized tree-sitter parsing for 10 core languages, fallback strategy for 50+ file types
  88. - **Direct Tree-sitter Integration**: No regex fallbacks for specialized languages - fail fast with clear errors
  89. - **Advanced Search**: Auto-detects and uses the best available tool (ugrep, ripgrep, ag, or grep)
  90. - **Universal File Support**: Comprehensive coverage from advanced AST parsing to basic file indexing
  91. - **File Analysis**: Deep insights into structure, imports, classes, methods, and complexity metrics after running `build_deep_index`
  92. ### πŸ—‚οΈ **Multi-Language Support**
  93. - **10 Languages with Tree-sitter AST Parsing**: Python, JavaScript, TypeScript, Java, Kotlin, C#, Go, Objective-C, Zig, Rust
  94. - **50+ File Types with Fallback Strategy**: C/C++, Ruby, PHP, and all other programming languages
  95. - **Document & Config Files**: Markdown, JSON, YAML, XML with appropriate handling
  96. - **Web Frontend**: Vue, React, Svelte, HTML, CSS, SCSS
  97. - **Java Web & Build**: JSP/Tag files (`.jsp`, `.jspx`, `.jspf`, `.tag`, `.tagx`), Grails/GSP (`.gsp`), Gradle & Groovy builds (`.gradle`, `.groovy`), `.properties`, and Protocol Buffers (`.proto`)
  98. - **Database**: SQL variants, NoSQL, stored procedures, migrations
  99. - **Configuration**: JSON, YAML, XML, Markdown
  100. - **[View complete list](#supported-file-types)**
  101. ### ⚑ **Real-time Monitoring & Auto-refresh**
  102. - **File Watcher**: Automatic index updates when files change
  103. - **Cross-platform**: Native OS file system monitoring
  104. - **Smart Processing**: Batches rapid changes to prevent excessive rebuilds
  105. - **Shallow Index Refresh**: Watches file changes and keeps the file list current; run a deep rebuild when you need symbol metadata
  106. ### ⚑ **Performance & Efficiency**
  107. - **Tree-sitter AST Parsing**: Native syntax parsing for accurate symbol extraction
  108. - **Persistent Caching**: Stores indexes for lightning-fast subsequent access
  109. - **Smart Filtering**: Intelligent exclusion of build directories and temporary files
  110. - **Memory Efficient**: Optimized for large codebases
  111. - **Direct Dependencies**: No fallback mechanisms - fail fast with clear error messages
  112. ## Supported File Types
  113. <details>
  114. <summary><strong>πŸ“ Programming Languages (Click to expand)</strong></summary>
  115. **Languages with Specialized Tree-sitter Strategies:**
  116. - **Python** (`.py`, `.pyw`) - Full AST analysis with class/method extraction and call tracking
  117. - **JavaScript** (`.js`, `.jsx`, `.mjs`, `.cjs`) - ES6+ class and function parsing with tree-sitter
  118. - **TypeScript** (`.ts`, `.tsx`) - Complete type-aware symbol extraction with interfaces
  119. - **Java** (`.java`) - Full class hierarchy, method signatures, and call relationships
  120. - **Kotlin** (`.kt`, `.kts`) - Package-aware symbol extraction with methods and call relationships
  121. - **C#** (`.cs`) - Namespace-aware type/member extraction with call relationships
  122. - **Go** (`.go`) - Struct methods, receiver types, and function analysis
  123. - **Rust** (`.rs`) - Functions, module-aware names, impl methods, structs/enums/traits, and basic call relationships
  124. - **Objective-C** (`.m`, `.mm`) - Class/instance method distinction with +/- notation
  125. - **Zig** (`.zig`, `.zon`) - Function and struct parsing with tree-sitter AST
  126. **All Other Programming Languages:**
  127. All other programming languages use the **FallbackParsingStrategy** which provides basic file indexing and metadata extraction. This includes:
  128. - **System & Low-Level:** C/C++ (`.c`, `.cpp`, `.h`, `.hpp`)
  129. - **Object-Oriented:** Scala (`.scala`), Swift (`.swift`)
  130. - **Scripting & Dynamic:** Ruby (`.rb`), PHP (`.php`), Shell (`.sh`, `.bash`)
  131. - **And 40+ more file types** - All handled through the fallback strategy for basic indexing
  132. </details>
  133. <details>
  134. <summary><strong>🌐 Web & Frontend (Click to expand)</strong></summary>
  135. **Frameworks & Libraries:**
  136. - Vue (`.vue`)
  137. - Svelte (`.svelte`)
  138. - Astro (`.astro`)
  139. **Styling:**
  140. - CSS (`.css`, `.scss`, `.less`, `.sass`, `.stylus`, `.styl`)
  141. - HTML (`.html`)
  142. **Templates:**
  143. - Handlebars (`.hbs`, `.handlebars`)
  144. - EJS (`.ejs`)
  145. - Pug (`.pug`)
  146. - FreeMarker (`.ftl`)
  147. - Mustache (`.mustache`)
  148. - Liquid (`.liquid`)
  149. - ERB (`.erb`)
  150. </details>
  151. <details>
  152. <summary><strong>πŸ—„οΈ Database & SQL (Click to expand)</strong></summary>
  153. **SQL Variants:**
  154. - Standard SQL (`.sql`, `.ddl`, `.dml`)
  155. - Database-specific (`.mysql`, `.postgresql`, `.psql`, `.sqlite`, `.mssql`, `.oracle`, `.ora`, `.db2`)
  156. **Database Objects:**
  157. - Procedures & Functions (`.proc`, `.procedure`, `.func`, `.function`)
  158. - Views & Triggers (`.view`, `.trigger`, `.index`)
  159. **Migration & Tools:**
  160. - Migration files (`.migration`, `.seed`, `.fixture`, `.schema`)
  161. - Tool-specific (`.liquibase`, `.flyway`)
  162. **NoSQL & Modern:**
  163. - Graph & Query (`.cql`, `.cypher`, `.sparql`, `.gql`)
  164. </details>
  165. <details>
  166. <summary><strong>πŸ“„ Documentation & Config (Click to expand)</strong></summary>
  167. - Markdown (`.md`, `.mdx`)
  168. - Configuration (`.json`, `.xml`, `.yml`, `.yaml`, `.properties`)
  169. </details>
  170. ### πŸ› οΈ **Development Setup**
  171. For contributing or local development:
  172. 1. **Clone and install:**
  173. ```bash
  174. git clone https://github.com/johnhuang316/code-index-mcp.git
  175. cd code-index-mcp
  176. uv sync
  177. ```
  178. 2. **Configure for local development:**
  179. ```json
  180. {
  181. "mcpServers": {
  182. "code-index": {
  183. "command": "uv",
  184. "args": ["run", "code-index-mcp"]
  185. }
  186. }
  187. }
  188. ```
  189. 3. **Debug with MCP Inspector:**
  190. ```bash
  191. npx @modelcontextprotocol/inspector uv run code-index-mcp
  192. ```
  193. <details>
  194. <summary><strong>Alternative: Manual pip Installation</strong></summary>
  195. If you prefer traditional pip management:
  196. ```bash
  197. pip install code-index-mcp
  198. ```
  199. Then configure:
  200. ```json
  201. {
  202. "mcpServers": {
  203. "code-index": {
  204. "command": "code-index-mcp",
  205. "args": []
  206. }
  207. }
  208. }
  209. ```
  210. </details>
  211. ## Available Tools
  212. ### πŸ—οΈ **Project Management**
  213. | Tool | Description |
  214. |------|-------------|
  215. | **`set_project_path`** | Initialize indexing for a project directory |
  216. | **`refresh_index`** | Rebuild the shallow file index after file changes |
  217. | **`build_deep_index`** | Generate the full symbol index used by deep analysis |
  218. | **`get_settings_info`** | View current project configuration and status |
  219. *Run `build_deep_index` when you need symbol-level data; the default shallow index powers quick file discovery.*
  220. ### πŸ” **Search & Discovery**
  221. | Tool | Description |
  222. |------|-------------|
  223. | **`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 |
  224. | **`find_files`** | Locate files using glob patterns (e.g., `**/*.py`) |
  225. | **`get_file_summary`** | Analyze file structure, functions, imports, and complexity (requires deep index) |
  226. ### πŸ”„ **Monitoring & Auto-refresh**
  227. | Tool | Description |
  228. |------|-------------|
  229. | **`get_file_watcher_status`** | Check file watcher status and configuration |
  230. | **`configure_file_watcher`** | Enable/disable auto-refresh and configure settings |
  231. ### πŸ› οΈ **System & Maintenance**
  232. | Tool | Description |
  233. |------|-------------|
  234. | **`create_temp_directory`** | Set up storage directory for index data |
  235. | **`check_temp_directory`** | Verify index storage location and permissions |
  236. | **`clear_settings`** | Reset all cached data and configurations |
  237. | **`refresh_search_tools`** | Re-detect available search tools (ugrep, ripgrep, etc.) |
  238. ## Usage Examples
  239. ### 🎯 **Quick Start Workflow**
  240. **1. Initialize Your Project**
  241. ```
  242. Set the project path to /Users/dev/my-react-app
  243. ```
  244. *Automatically indexes your codebase and creates searchable cache*
  245. **2. Explore Project Structure**
  246. ```
  247. Find all TypeScript component files in src/components
  248. ```
  249. *Uses: `find_files` with pattern `src/components/**/*.tsx`*
  250. **3. Analyze Key Files**
  251. ```
  252. Give me a summary of src/api/userService.ts
  253. ```
  254. *Uses: `get_file_summary` to show functions, imports, and complexity*
  255. *Tip: run `build_deep_index` first if you get a `needs_deep_index` response.*
  256. ### πŸ” **Advanced Search Examples**
  257. <details>
  258. <summary><strong>Code Pattern Search</strong></summary>
  259. ```
  260. Search for all function calls matching "get.*Data" using `regex=True`
  261. ```
  262. *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.*
  263. </details>
  264. <details>
  265. <summary><strong>Fuzzy Function Search</strong></summary>
  266. ```
  267. Find authentication-related functions with fuzzy search for 'authUser'
  268. ```
  269. *Matches: `authenticateUser`, `authUserToken`, `userAuthCheck`, etc.*
  270. </details>
  271. <details>
  272. <summary><strong>Language-Specific Search</strong></summary>
  273. ```
  274. Search for "API_ENDPOINT" only in Python files
  275. ```
  276. *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)*
  277. </details>
  278. <details>
  279. <summary><strong>Auto-refresh Configuration</strong></summary>
  280. ```
  281. Configure automatic index updates when files change
  282. ```
  283. *Uses: `configure_file_watcher` to enable/disable monitoring and set debounce timing*
  284. </details>
  285. <details>
  286. <summary><strong>Project Maintenance</strong></summary>
  287. ```
  288. I added new components, please refresh the project index
  289. ```
  290. *Uses: `refresh_index` to update the searchable cache*
  291. </details>
  292. ## Troubleshooting
  293. ### πŸ”„ **Auto-refresh Not Working**
  294. If automatic index updates aren't working when files change, try:
  295. - `pip install watchdog` (may resolve environment isolation issues)
  296. - Use manual refresh: Call the `refresh_index` tool after making file changes
  297. - Check file watcher status: Use `get_file_watcher_status` to verify monitoring is active
  298. ### **macOS File Watcher Options**
  299. The default FSEvents observer works well for most projects. If you experience issues, you can switch to an alternative observer via `configure_file_watcher`:
  300. - `"auto"` (default): Platform default (FSEvents on macOS)
  301. - `"kqueue"`: Kqueue observer (macOS/BSD)
  302. - `"fsevents"`: Force FSEvents (macOS only)
  303. - `"polling"`: Cross-platform polling fallback
  304. Note: Kqueue opens one file descriptor per watched file. For large projects using kqueue, you may need to increase the limit: `ulimit -n 10240`
  305. ## Development & Contributing
  306. ### πŸ”§ **Building from Source**
  307. ```bash
  308. git clone https://github.com/johnhuang316/code-index-mcp.git
  309. cd code-index-mcp
  310. uv sync
  311. uv run code-index-mcp
  312. ```
  313. ### πŸ› **Debugging**
  314. ```bash
  315. npx @modelcontextprotocol/inspector uvx code-index-mcp
  316. ```
  317. ### 🀝 **Contributing**
  318. Contributions are welcome! Please feel free to submit a Pull Request.
  319. ---
  320. ### πŸ“œ **License**
  321. [MIT License](LICENSE)
  322. ### 🌐 **Translations**
  323. - [繁體中文](README_zh.md)
  324. - [ζ—₯本θͺž](README_ja.md)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.