Code Index MCP

Code Index MCP

Code Index MCP 是一个 Model Context Protocol 服务，可让大模型（LLM）为项目目录中的代码建立索引、进行搜索和分析。

功能

• 为项目文件结构建立索引并进行导航
• 搜索代码中的特定模式
• 获取详细的文件摘要
• 分析代码结构和复杂度
• 支持多种编程语言
• 持久化存储项目设置

安装

本项目使用 uv 管理环境和安装依赖。

1. 确保已安装 Python 3.10 或更高版本

2. 安装 uv（推荐）：

   # Windows
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   # macOS/Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. 获取代码：

   # Clone the repository
   git clone https://github.com/your-username/code-index-mcp.git
   

使用方法

直接运行服务

# Run directly with uv - no additional dependency installation needed
uv run run.py

UV 将根据项目配置自动处理所有依赖项的安装。

与 Claude Desktop 集成

你可以轻松将 Code Index MCP 与 Claude Desktop 集成：

1. 确保已安装 UV（参见上方的安装部分）

2. 找到或创建 Claude Desktop 配置文件：

   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • macOS/Linux：~/Library/Application Support/Claude/claude_desktop_config.json

3. 添加以下配置（替换为实际路径）：

   Windows 配置：

   {
     "mcpServers": {
       "code-indexer": {
         "command": "uv",
         "args": [
            "--directory",
            "C:\\Users\\username\\path\\to\\code-index-mcp",
            "run",
            "run.py"
          ]
       }
     }
   }
   

   macOS/Linux 配置：

   {
     "mcpServers": {
       "code-indexer": {
         "command": "uv",
         "args": [
            "--directory",
            "/home/username/path/to/code-index-mcp",
            "run",
            "run.py"
          ]
       }
     }
   }
   

   注意：--directory 选项很重要，可确保 uv 在正确的项目目录中运行，并正确加载所有依赖项。

4. 重启 Claude Desktop，即可使用 Code Indexer 分析代码项目

无需手动安装依赖项——运行服务时，UV 会自动处理所有依赖项。

基本工作流

1. 设置项目路径（必需的第一步）：

   • 首次使用时，必须设置要分析的项目路径
   • 通过 Claude 命令：「我需要分析一个项目，请帮我设置项目路径」
   • 提供完整的项目目录路径

2. 代码搜索：

   • 搜索特定关键字或模式：「在项目中搜索 'function name'」
   • 按文件类型筛选：「在所有 .py 文件中搜索 'import'」

3. 文件分析：

   • 分析特定文件：「分析文件 src/main.py」
   • 获取文件摘要：「列出 utils/helpers.js 中的函数」

4. 项目导航：

   • 查看项目结构：「显示此项目的结构」
   • 查找符合特定模式的文件：「查找所有 test_*.py 文件」

技术详情

持久化存储

所有索引和设置数据都存储在项目目录中的 .code_indexer 文件夹内：

• config.json：项目配置信息
• file_index.pickle：文件索引数据
• content_cache.pickle：文件内容缓存

这样可以避免每次使用时都重新为整个项目建立索引。

使用 UV 管理依赖项

Code Index MCP 使用 UV 管理依赖项，具有以下优势：

• 根据项目需求自动解析依赖项
• 更快地安装软件包和设置环境
• 通过锁定文件确保依赖项版本一致

支持的文件类型

目前支持为以下文件类型建立索引和进行分析：

• Python（.py）
• JavaScript/TypeScript（.js、.ts、.jsx、.tsx）
• Java（.java）
• C/C++（.c、.cpp、.h、.hpp）
• C#（.cs）
• Go（.go）
• Ruby（.rb）
• PHP（.php）
• Swift（.swift）
• Kotlin（.kt）
• Rust（.rs）
• Scala（.scala）
• Shell（.sh、.bash）
• HTML/CSS（.html、.css、.scss）
• Markdown（.md）
• JSON（.json）
• XML（.xml）
• YAML（.yml、.yaml）

安全注意事项

• 文件路径验证可防止目录遍历攻击
• 不允许访问绝对路径
• 必须显式设置项目路径，不提供默认值
• .code_indexer 文件夹包含 .gitignore 文件，可防止索引数据被提交

贡献

欢迎通过提交 issue 或 pull request 来添加新功能或修复错误。

---

如需查看中文文档，请参阅 README_zh.md。