Code Index MCP

Code Index MCP

概述

Code Index MCP 是一个 Model Context Protocol 服务，弥合了 AI 模型与复杂代码库之间的鸿沟。它提供智能索引、高级搜索功能和详细的代码分析，帮助 AI 助手有效理解和浏览项目。

适用于： 代码审查、重构、文档生成、调试辅助和架构分析。

快速开始

🚀 推荐配置（适合大多数用户）

使用任何兼容 MCP 的应用开始上手的最简单方式：

前置要求： Python 3.10+ 和 uv

1. 添加到 MCP 配置中（例如，claude_desktop_config.json 或 ~/.claude.json）：

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

   可选：将 --project-path /absolute/path/to/repo 附加到 args 数组，这样服务就会自动以该仓库初始化（等同于启动后调用 set_project_path）。

2. 重启应用 – uvx 会自动处理安装和运行

3. 开始使用（将以下提示词发送给 AI 助手）：

   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
   

   如果使用 --project-path 启动，可以跳过上面的第一个命令——服务已经知道项目位置。

Codex CLI 配置

如果使用 Anthropic 的 Codex CLI，请将服务添加到 ~/.codex/config.toml。 在 Windows 上，文件位于 C:\Users\<you>\.codex\config.toml：

[mcp_servers.code-index]
type = "stdio"
command = "uvx"
args = ["code-index-mcp"]

可以将 --project-path C:/absolute/path/to/repo 附加到 args 列表，以便在启动时自动设置项目（效果等同于运行 set_project_path 工具）。

在 Windows 上，uvx 需要标准配置文件目录存在。 请在同一个代码块中保留环境变量覆盖，以确保 MCP 稳定运行：

env = {
  HOME = "C:\\Users\\<you>",
  APPDATA = "C:\\Users\\<you>\\AppData\\Roaming",
  LOCALAPPDATA = "C:\\Users\\<you>\\AppData\\Local",
  SystemRoot = "C:\\Windows"
}

Linux 和 macOS 已经提供所需的 XDG 路径和 HOME，因此通常可以省略其中的 env 表。 只有在受限容器中运行 CLI 时，才需要添加覆盖项。

FastMCP 与发现清单

• 运行 fastmcp run fastmcp.json，通过 FastMCP 启动服务，并使用正确的源入口和依赖元数据。传入 --project-path（或在启动后调用 set_project_path 工具），以便为正确的仓库启动索引。
• 提供或复制 .well-known/mcp.json，以共享符合标准的 MCP 清单。支持 .well-known 约定的客户端（例如 Claude Desktop、Codex CLI）可以直接导入此文件，无需手动编写配置。
• 如果要公开更丰富的 LLM Feed 元数据，请发布 .well-known/mcp.llmfeed.json。它引用同一个 code-index 服务定义以及文档和源代码链接，有助于注册表自动展示描述、标签和功能。

分享清单时，请提醒使用者提供 --project-path（或调用 set_project_path），以便服务为目标仓库建立索引。

典型用例

代码审查：“找出所有使用旧 API 的位置”
重构帮助：“这个函数在哪里调用？”
学习项目：“展示这个 React 项目的主要组件”
调试：“搜索所有与错误处理相关的代码”

主要功能

🔍 智能搜索与分析

• 双策略架构：针对 10 种核心语言进行专门的 tree-sitter 解析，为 50 多种文件类型提供回退策略
• 直接集成 Tree-sitter：专用语言不使用正则表达式回退机制；遇到问题时立即失败并提供清晰的错误信息
• 高级搜索：自动检测并使用最佳可用工具（ugrep、ripgrep、ag 或 grep）
• 通用文件支持：全面覆盖从高级 AST 解析到基础文件索引的各种需求
• 文件分析：运行 build_deep_index 后，可深入了解结构、导入项、类、方法和复杂度指标

🗂️ 多语言支持

• 10 种支持 Tree-sitter AST 解析的语言：Python、JavaScript、TypeScript、Java、Kotlin、C#、Go、Objective-C、Zig、Rust
• 50 多种采用回退策略的文件类型：C/C++、Ruby、PHP 及所有其他编程语言
• 文档与配置文件：Markdown、JSON、YAML、XML，并进行相应处理
• Web 前端：Vue、React、Svelte、HTML、CSS、SCSS
• Java Web 与构建：JSP/Tag 文件（.jsp、.jspx、.jspf、.tag、.tagx）、Grails/GSP（.gsp）、Gradle 与 Groovy 构建文件（.gradle、.groovy）、.properties 和 Protocol Buffers（.proto）
• 数据库：SQL 变体、NoSQL、存储过程、迁移
• 配置：JSON、YAML、XML、Markdown
• 查看完整列表

⚡ 实时监控与自动刷新

• 文件监视器：文件发生变化时自动更新索引
• 跨平台：原生操作系统文件系统监控
• 智能处理：批量处理快速发生的更改，避免过度重建
• 浅层索引刷新：监视文件更改并保持文件列表最新；需要符号元数据时，请运行深度重建

⚡ 性能与效率

• Tree-sitter AST 解析：原生语法解析，准确提取符号
• 持久化缓存：存储索引，让后续访问快如闪电
• 智能过滤：智能排除构建目录和临时文件
• 节省内存：针对大型代码库进行优化
• 直接依赖：不使用回退机制；遇到问题时立即失败并提供清晰的错误信息

支持的文件类型

🛠️ 开发环境设置

用于贡献或本地开发：

1. 克隆并安装：

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

2. 配置本地开发环境：

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

3. 使用 MCP Inspector 调试：

   npx @modelcontextprotocol/inspector uv run code-index-mcp
   

pip install code-index-mcp

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

可用工具

🏗️ 项目管理

需要符号级数据时运行 build_deep_index；默认的浅层索引用于快速发现文件。

🔍 搜索与发现

🔄 监控与自动刷新

🛠️ 系统与维护

使用示例

🎯 快速入门工作流

1. 初始化项目

Set the project path to /Users/dev/my-react-app

自动为代码库编制索引并创建可搜索缓存

2. 探索项目结构

Find all TypeScript component files in src/components

使用：find_files，模式为 src/components/**/*.tsx

3. 分析关键文件

Give me a summary of src/api/userService.ts

使用：get_file_summary 显示函数、导入内容和复杂度 提示：如果收到 needs_deep_index 响应，请先运行 build_deep_index。

🔍 高级搜索示例

Search for all function calls matching "get.*Data" using `regex=True`

Find authentication-related functions with fuzzy search for 'authUser'

Search for "API_ENDPOINT" only in Python files

Configure automatic index updates when files change

I added new components, please refresh the project index

故障排除

🔄 自动刷新无法正常工作

如果文件更改时索引没有自动更新，请尝试：

• pip install watchdog（可能解决环境隔离问题）
• 手动刷新：更改文件后调用 refresh_index 工具
• 检查文件监视器状态：使用 get_file_watcher_status 确认监控已启用

macOS 文件监视器选项

默认的 FSEvents 观察器适用于大多数项目。如果遇到问题，可以通过 configure_file_watcher 切换到其他观察器：

• "auto"（默认）：平台默认选项（macOS 上为 FSEvents）
• "kqueue"：Kqueue 观察器（macOS/BSD）
• "fsevents"：强制使用 FSEvents（仅限 macOS）
• "polling"：跨平台轮询回退方案

注意：Kqueue 会为每个受监视文件打开一个文件描述符。对于使用 kqueue 的大型项目，可能需要提高限制：ulimit -n 10240

开发与贡献

🔧 从源代码构建

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

🐛 调试

npx @modelcontextprotocol/inspector uvx code-index-mcp

🤝 贡献

欢迎贡献！欢迎提交 Pull Request。

📜 许可证

MIT 许可证

🌐 翻译

• 繁體中文
• 日本語