AI导哈

代码库索引工具

一个结构化的代码库索引器，通过解析源代码文件生成元数据，并提供18种查询工具，支持AI辅助开发。

  • by MikeRecognex
  • Python
  • 本地部署
  • 63 星标
  • 更新于
在 GitHub 查看 MikeRecognex/mcp-codebase-index

使用说明

mcp代码库索引

一个结构化代码库索引器 主控程序 用于人工智能辅助开发的服务器。零运行时依赖关系——使用Python ast 用于Python分析和基于正则表达式的Types/JS、Go、Rust和C#解析的模块。需要Python 3.11+。

它的作用

通过将源文件解析为结构化元数据（函数、类、导入、依赖图和跨文件调用链）对代码库进行索引，然后通过模型上下文协议公开18个查询工具，使Claude Code和其他MCP客户端能够高效地导航代码库，而无需读取整个文件。

自动增量重新索引： 在git存储库中，索引会自动保持最新。在每次查询之前，服务器都会进行检查 git diff 和 git status （~1-2ms）。如果文件发生更改，则只会重新解析这些文件并重建依赖关系图。无需手动呼叫 reindex 编辑、分支切换或拉取后。

持久磁盘缓存： 索引被保存到pickle缓存文件中(.codebase-index-cache.pkl)每次建造之后。在后续的服务器启动时，缓存将被加载并根据当前的git HEAD进行验证——如果ref匹配，则启动是即时的。如果少量文件发生更改（≤20），则加载缓存索引并增量更新，而不是从头开始重建。这消除了重新启动Claude Code会话、重新启动MCP服务器或在上下文压缩后恢复工作时的冷启动惩罚。

语言支持

语言 方法 摘录
python.py) AST解析 函数、类、方法、导入、依赖关系图
Types/JS(.ts, .tsx, .js, .jsx) 基于正则表达式 函数、箭头函数、类、接口、类型别名、导入
去吧(.go) 基于正则表达式 函数、方法（基于接收器）、结构、接口、类型别名、导入、文档注释
生锈(.rs) 基于正则表达式 函数(pub/async/const/unsafe)、结构体、枚举、特征、impl块、use语句、属性、文档注释、宏规则
C.cs) 基于正则表达式 类、接口、结构、枚举、记录、方法、构造函数、使用指令、， [Attributes], /// XML文档注释
Markdown/文本(.md, .txt, .rst) 标题检测 章节（#标题、下划线、编号、ALL-CAPS）
其他 通用 仅限行数

安装

pip install "mcp-codebase-index[mcp]"

这 [mcp] 额外包括MCP服务器依赖性。如果您只需要程序化的API，请省略它。

对于开发（从本地克隆）：

pip install -e ".[dev,mcp]"

MCP服务器

跑步

# As a console script
PROJECT_ROOT=/path/to/project mcp-codebase-index

# As a Python module
PROJECT_ROOT=/path/to/project python -m mcp_codebase_index.server

PROJECT_ROOT 指定要索引的目录。默认为当前工作目录。

持久缓存

在git存储库中，服务器会自动将索引缓存到 .codebase-index-cache.pkl 在项目根中。启动时：

  1. 缓存命中（完全匹配）： 如果缓存的git ref与当前HEAD匹配，则索引会立即从磁盘加载——无需解析，也无需文件遍历。
  2. 缓存命中（小变更集）： 如果自缓存引用以来更改了≤20个文件，则缓存索引将在第一次查询时加载并增量更新。
  3. 缓存未命中： 如果变更集很大或不存在缓存，则会运行完全重建并保存新的缓存。

添加 .codebase-index-cache.pkl 到你的 .gitignore --这是一个仅限本地构建的工件。

使用OpenClaw进行配置

在运行OpenClaw的计算机上安装该软件包：

# Local install
pip install "mcp-codebase-index[mcp]"

# Or inside a Docker container / remote VPS
docker exec -it openclaw bash
pip install "mcp-codebase-index[mcp]"

将MCP服务器添加到您的OpenClaw代理配置中(openclaw.json):

{
  "agents": {
    "list": [{
      "id": "main",
      "mcp": {
        "servers": [
          {
            "name": "codebase-index",
            "command": "mcp-codebase-index",
            "env": {
              "PROJECT_ROOT": "/path/to/project"
            }
          }
        ]
      }
    }]
  }
}

重新启动OpenClaw并验证连接：

openclaw mcp list

所有18个工具都将提供给您的代理。

性能说明： 服务器通过以下方式自动检测文件更改 git diff 在每次查询之前（约1-2ms），只对更改的内容进行增量重新索引。然而，OpenClaw通过mcporter进行的默认MCP集成会在每次工具调用时生成一个新的服务器进程，该进程会丢弃内存中的索引，并每次强制进行完全重建（小型项目约1-2s，大型项目较长）。有了持久缓存，这些冷启动现在要快得多——服务器从磁盘缓存加载，而不是重新解析整个代码库。对于持久连接（甚至避免缓存负载开销），使用 openclaw mcp适配器 插件，它在启动时连接一次并保持服务器运行：

pip install openclaw-mcp-adapter

使用Claude代码进行配置

添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "codebase-index": {
      "command": "mcp-codebase-index",
      "env": {
        "PROJECT_ROOT": "/path/to/project"
      }
    }
  }
}

或者直接使用Python模块（如果安装在virtualenv中则很有用）：

{
  "mcpServers": {
    "codebase-index": {
      "command": "/path/to/.venv/bin/python3",
      "args": ["-m", "mcp_codebase_index.server"],
      "env": {
        "PROJECT_ROOT": "/path/to/project"
      }
    }
  }
}

使用钩子加固工具

即使代码库索引可用，Claude Code也倾向于默认使用内置的Glob/Grep/Read工具。除了CLAUDE.md指令（见下文）外，您还可以添加在每个提示上触发的钩子来强化行为。将此添加到 .claude/settings.local.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'CRITICAL REMINDER: Use codebase-index MCP tools FIRST for ALL code navigation (find_symbol, get_function_source, search_codebase, get_dependencies, etc). Only fall back to Glob/Grep/Read for non-code files.'"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Use codebase-index MCP tools first for code navigation.'"
          }
        ]
      }
    ]
  }
}

Hook stdout被注入到Claude在响应之前看到的上下文中。 SessionStart 启动、恢复和上下文压缩时发生火灾。 UserPromptSubmit 每个转弯处都着火。

重要提示：让人工智能真正使用索引工具

默认情况下，AI助手将忽略索引工具，转而使用Glob/Grep/Read读取整个文件。像“偏好”这样的软语言被合理化了。将此添加到您的项目 CLAUDE.md （或等效的说明文件） 强制性的 语言：

## Codebase Navigation — MANDATORY

You MUST use codebase-index MCP tools FIRST when exploring or navigating the codebase. This is not optional.

- ALWAYS start with: get_project_summary, find_symbol, get_function_source, get_class_source,
  get_structure_summary, get_dependencies, get_dependents, get_change_impact, get_call_chain, search_codebase
- Only fall back to Read/Glob/Grep when codebase-index tools genuinely don't have what you need
  (e.g. reading non-code files, config, frontmatter)
- If you catch yourself reaching for Glob/Grep/Read to find or understand code, STOP and use
  codebase-index instead

“偏好”这个词太弱了——模型将其视为对熟悉工具的建议和默认。具有明确回退标准的强制性语言实际上改变了行为。

可用工具（18）

工具 说明
get_project_summary 文件数、包、顶级类/函数
list_files 使用可选的glob过滤器列出索引文件
get_structure_summary 文件或整个项目的结构
get_functions 列出带有名称、行、参数的函数
get_classes 列出具有名称、行、方法、基的类
get_imports 列出带有模块、名称和行的导入
get_function_source 函数/方法的完整来源
get_class_source 类的完整来源
find_symbol 查找定义符号的位置（文件、行、类型）
get_dependencies 符号调用/使用什么
get_dependents 什么调用/使用符号
get_change_impact 直接+可传递家属
get_call_chain 最短依赖路径（BFS）
get_file_dependencies 由给定文件导入的文件
get_file_dependents 从给定文件导入的文件
search_codebase 在所有文件中搜索正则表达式（最多100个结果）
reindex 强制完全重新索引（很少需要——增量更新在git repos中自动发生）
get_usage_stats 会话效率统计数据：工具调用、返回的字符与总源、估计的令牌节省

基准测试

在M系列MacBook Pro上测试了四个真实世界的项目，从一个小项目到CPython本身（110万行）：

指数构建性能

项目 文件 行 函数 类 索引时间 峰值内存
RMLPlus 36 7762 237 55 0.9秒 2.4 MB
快速API 2556 332160 4139 617 5.7秒 55 MB
Django 3714 707493 29995 7371 36.2秒 126 MB
CPython 2,464 1,115,334 59,620 9,037 55.9秒 197 MB

通过持久缓存，后续的初创公司完全绕过了完整的构建。与解析相比，缓存加载时间可以忽略不计——CPython上的缓存命中会在不到一秒钟的时间内恢复完整索引，而不是56秒。

查询响应大小与总源

查询CPython——4100万个字符的源代码：

查询 响应 总来源 减少
find_symbol("TestCase") 67个字符 41077561个字符 99.9998%
get_dependencies("compile") 115个字符 41077561个字符 99.9997%
get_change_impact("TestCase") 16812个字符 41077561个字符 99.96%
get_function_source("compile") 4531个字符 41077561个字符 99.99%
get_function_source("run_unittest") 439个字符 41077561个字符 99.999%

find_symbol 返回54-67个字符，无论项目是7K行还是1.1M行。响应大小随答案而变化，而不是随代码库而变化。

get_change_impact("TestCase") 已找到CPython 154名直系亲属和492名传递性亲属 在0.45ms内——这种查询没有依赖图是不可能的。使用 max_direct 和 max_transitive 限制代币预算的产出。

查询响应时间

所有目标查询都会在亚毫秒的时间内返回，即使在CPython的110万行上也是如此：

查询 RMLPlus FastAPI Django CPython
find_symbol 0.01毫秒 0.01毫秒 0.03毫秒 0.08毫秒
get_dependencies 0.00ms 0.00ms 0.001ms 0.01ms
get_change_impact 0.02毫秒 0.00毫秒 2.81毫秒 0.45毫秒
get_function_source 0.01毫秒 0.02毫秒 0.03毫秒 0.10毫秒

自己运行基准测试： python benchmarks/benchmark.py

这与LSP有何不同？

LSP回答“这个函数在哪里？”--mcp代码库索引回答“如果我更改它会发生什么？”LSP是点查询：一个符号、一个文件、一个位置。它可以告诉你在哪里 LLMClient 是定义的，谁引用它。但要问“如果我重构，传递性中断是什么 LLMClient？”而LSP什么都没有。该工具在一次调用中返回11个直接依赖项和31个传递性影响——204个字符。为了从LSP中获得相同的答案，人工智能需要递归地链接数十个查找引用调用，在每一步读取文件，燃烧数千个令牌来重建依赖关系图已经知道的内容。

LSP还要求您为项目中的每种语言安装一个单独的语言服务器——Python为pyright，TypeScript为vtsls，Go为gopls。每个都是一个重量级的二进制文件，有自己的依赖关系和配置。mcp代码库索引是零依赖的，可以开箱即用地处理Python+TypeScript/JS+Go+Rust+C#+Markdown，每个响应都有内置的令牌预算控制(max_results, max_lines).LSP是为IDE构建的。这是为AI构建的。

程序化使用

from mcp_codebase_index.project_indexer import ProjectIndexer
from mcp_codebase_index.query_api import create_project_query_functions

indexer = ProjectIndexer("/path/to/project", include_patterns=["**/*.py"])
index = indexer.index()
query_funcs = create_project_query_functions(index)

# Use query functions
print(query_funcs["get_project_summary"]())
print(query_funcs["find_symbol"]("MyClass"))
print(query_funcs["get_change_impact"]("some_function"))

发展

pip install -e ".[dev,mcp]"
pytest tests/ -v
ruff check src/ tests/

参考文献

结构索引器最初是作为 RMLPlus 项目，实施 递归语言模型 框架。

许可证

该项目具有双重许可：

  • AGPL-3.0 关于开源使用，请参见 许可证
  • 商业许可证 对于专有用途，请参见 商业许可

如果您将mcp代码库索引用作独立的mcp服务器进行开发，则AGPL-3.0许可证免费适用。如果你将其嵌入到专有产品中或作为托管服务的一部分提供，你需要商业许可证。看 商业许可 了解详情。

相关 MCP