Code Index MCP

Code Index MCP 是一个模型上下文协议服务器，它使大型语言模型 (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. 获取代码:

   # 克隆仓库
   git clone https://github.com/your-username/code-index-mcp.git
   

使用

直接运行服务器

# 使用 uv 直接运行 - 无需额外安装依赖
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。