代码索引 MCP

概述

代码索引 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"]
       }
     }
   }
   

   可选：在 args 数组中追加 --project-path /absolute/path/to/repo，使服务器自动初始化该仓库（等同于启动后调用 set_project_path）。

2. 重启您的应用程序 – uvx 会自动处理安装和执行

3. 开始使用（向您的 AI 助手提供以下提示）：

   将项目路径设置为 /Users/dev/my-react-app
   查找该项目中的所有 TypeScript 文件  
   搜索“authentication”函数
   分析主 App.tsx 文件
   

   如果您使用 --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"]

您可以在 args 列表中追加 --project-path C:/absolute/path/to/repo，以便在启动时自动设置项目（效果与运行 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. 初始化项目

将项目路径设置为 /Users/dev/my-react-app

自动索引您的代码库，并创建可搜索的缓存

2. 探索项目结构

查找 src/components 目录下的所有 TypeScript 组件文件

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

3. 分析关键文件

请给我 src/api/userService.ts 的概要信息

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

🔍 高级搜索示例

使用 `regex=True` 搜索所有匹配 "get.*Data" 的函数调用

通过模糊搜索查找与认证相关的函数 'authUser'

仅在 Python 文件中搜索 "API_ENDPOINT"

配置文件更改时自动更新索引

我添加了新组件，请刷新项目索引。

故障排除

🔄 自动刷新未生效

如果文件更改时自动索引更新未生效，请尝试：

• 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 许可证

🌐 翻译

• 繁體中文
• 日本語

Code Index MCP 快速上手指南

Code Index MCP 是一个基于模型上下文协议（MCP）的服务器工具，旨在帮助 AI 助手智能地索引、搜索和分析代码库。它支持多种编程语言的 AST 解析，让 AI 能更深入地理解你的项目结构。

环境准备

在开始之前，请确保满足以下系统要求：

• 操作系统：Windows, macOS, 或 Linux
• Python 版本：3.10 或更高版本
• 包管理工具：推荐安装 uv（比传统 pip 更快速、高效）
  • 安装 uv (官方脚本): curl -LsSf https://astral.sh/uv/install.sh | sh (Mac/Linux) 或 powershell -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows)

安装与配置

Code Index MCP 无需手动安装到全局环境，推荐通过 MCP 客户端配置文件直接调用 uvx 进行按需运行和自动安装。

1. 配置 MCP 客户端

根据你的 AI 客户端类型，将以下配置添加到对应的配置文件中。

方案 A：Claude Desktop / 通用 JSON 配置

编辑 claude_desktop_config.json 或 ~/.claude.json：

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

提示：若希望启动时自动锁定项目路径，可在 args 数组末尾添加 --project-path /绝对路径/到/你的/仓库。

方案 B：Anthropic Codex CLI (TOML 格式)

编辑 ~/.codex/config.toml (Windows 位于 C:\Users\<你>\.codex\config.toml)：

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

注意：在 Windows 上运行 Codex CLI 时，可能需要在同一配置块中补充环境变量（HOME, APPDATA 等）以确保 uvx 正常找到用户目录。

2. 重启应用

保存配置文件后，完全重启你的 AI 客户端应用程序。uvx 会在首次运行时自动下载并执行最新版本的 code-index-mcp。

基本使用

配置完成后，你可以直接在对话框中向 AI 助手发送指令来使用该项目。

第一步：设置项目路径（如未在启动参数中指定）

如果启动时未添加 --project-path，请先告诉 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
  

  (注：首次深度分析可能会触发 build_deep_index，稍作等待即可获得详细的类、方法和依赖关系分析)

• 架构理解：

  Show me the main components of this React project
  

核心工具说明

AI 会自动调用以下底层工具完成任务，你也可以显式要求：

• set_project_path: 初始化项目索引。
• build_deep_index: 构建完整的符号索引（用于深度代码分析）。
• search_code_advanced: 高级搜索（支持正则、模糊匹配）。
• get_file_summary: 获取单个文件的结构摘要。