Mcp Codebase Index

mcp-codebase-index

一款结构化代码库索引工具，提供用于 AI 辅助开发的 MCP 服务。运行时零依赖——使用 Python 的 ast 模块分析 Python，并通过基于正则表达式的解析来分析 TypeScript/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 进行验证——如果引用匹配，启动即可瞬间完成。如果只有少量文件发生变化（≤20），系统会加载缓存索引并进行增量更新，而不是从头开始重建。这消除了重启 Claude Code 会话、重启 MCP 服务或上下文压缩后恢复工作时的冷启动延迟。

语言支持

语言	方法	提取内容
Python（.py）	AST 解析	函数、类、方法、导入、依赖关系图
TypeScript/JS（.ts、.tsx、.js、.jsx）	基于正则表达式	函数、箭头函数、类、接口、类型别名、导入
Go（.go）	基于正则表达式	函数、方法（基于接收者）、结构体、接口、类型别名、导入、文档注释
Rust（.rs）	基于正则表达式	函数（pub/async/const/unsafe）、结构体、枚举、trait、impl 块、use 语句、属性、文档注释、macro_rules
C#（.cs）	基于正则表达式	类、接口、结构体、枚举、记录、方法、构造函数、using 指令、[Attributes]、/// XML 文档注释
Markdown/文本（.md、.txt、.rst）	标题检测	章节（# 标题、下划线、编号标题、全大写标题）
其他	通用	仅统计行数

安装

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

[mcp] extra 包含 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. 缓存命中（变更较少）： 如果自缓存的 ref 以来变更的文件数 ≤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 Agent 配置（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

你的 Agent 将可以使用全部 18 个工具。

性能说明： 服务会在每次查询前通过 git diff 自动检测文件变更（约 1–2ms），并仅对变更部分进行增量重新索引。不过，OpenClaw 默认通过 mcporter 集成 MCP，每次调用工具都会启动一个新的服务进程，因此会丢弃内存中的索引，并在每次调用时强制完整重建（小型项目约 1–2 秒，大型项目则更久）。借助持久化缓存，现在冷启动会快很多——服务会从磁盘缓存加载，而不是重新解析整个代码库。若要建立持久连接（甚至避免加载缓存的开销），请使用 openclaw-mcp-adapter 插件。它会在启动时连接一次，并让服务持续运行：

pip install openclaw-mcp-adapter

使用 Claude Code 配置

将以下内容添加到项目的 .mcp.json 中：

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

也可以直接使用 Python 模块（适用于安装在虚拟环境中的情况）：

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

使用 Hooks 强化工具使用

即使 codebase-index 可用，Claude Code 通常仍会默认使用内置的 Glob/Grep/Read 工具。除了在 CLAUDE.md 中添加说明（见下文）之外，你还可以添加 Hooks，在每次提示词提交时触发，以强化这一行为。将以下内容添加到 .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 的标准输出会作为上下文注入，供 Claude 在回复前查看。SessionStart 会在启动、恢复会话和上下文压缩时触发。UserPromptSubmit 会在每轮对话中触发。

重要：确保 AI 确实使用已索引的工具

默认情况下，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 仓库会自动增量更新）
get_usage_stats	会话效率统计：工具调用次数、返回字符数与源码总字符数、估算节省的 token 数

基准测试

在配备 M 系列芯片的 MacBook Pro 上，对四个真实项目进行了测试，项目规模从小型项目到 CPython 本身（110 万行）：

索引构建性能

项目	文件数	行数	函数数	类数	索引时间	峰值内存
RMLPlus	36	7,762	237	55	0.9s	2.4 MB
FastAPI	2,556	332,160	4,139	617	5.7s	55 MB
Django	3,714	707,493	29,995	7,371	36.2s	126 MB
CPython	2,464	1,115,334	59,620	9,037	55.9s	197 MB

启用持久缓存后，后续启动时无需再次完整构建。与解析相比，加载缓存所需时间微不足道——在 CPython 上命中缓存后，不到 1 秒即可恢复完整索引，而不是等待 56s。

查询响应大小与源码总量对比

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

查询	响应	源码总量	缩减比例
find_symbol("TestCase")	67 个字符	41,077,561 个字符	99.9998%
get_dependencies("compile")	115 个字符	41,077,561 个字符	99.9997%
get_change_impact("TestCase")	16,812 个字符	41,077,561 个字符	99.96%
get_function_source("compile")	4,531 个字符	41,077,561 个字符	99.99%
get_function_source("run_unittest")	439 个字符	41,077,561 个字符	99.999%

无论项目规模是 7K 行还是 110 万行，find_symbol 都只返回 54-67 个字符。响应大小取决于答案，而非代码库规模。

在 CPython 上，get_change_impact("TestCase") 在 0.45ms 内找到了 154 个直接依赖项和 492 个传递依赖项——没有依赖关系图，这类查询根本无法完成。使用 max_direct 和 max_transitive 将输出限制在 token 预算内。

查询响应时间

即使面对 CPython 的 110 万行代码，所有定向查询的返回时间都不到 1ms：

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

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

这与 LSP 有何不同？

LSP 回答“这个函数在哪里？”——mcp-codebase-index 回答“如果我修改它，会发生什么？”LSP 执行的是点查询：一个符号、一个文件、一个位置。它可以告诉你 LLMClient 的定义位置，以及哪些代码引用了它。但如果问“重构 LLMClient 会造成哪些传递性破坏？”，LSP 就无能为力了。这个工具只需一次调用，就能返回 11 个直接依赖项和 31 个传递性影响——仅 204 个字符。若要通过 LSP 得到相同答案，AI 必须递归地串联数十次查找引用调用，并在每一步读取文件，耗费数千个 token，才能重建依赖图早已掌握的信息。

LSP 还要求你为项目中的每种语言分别安装语言服务器——Python 用 pyright，TypeScript 用 vtsls，Go 用 gopls。每个语言服务器都是一个重量级二进制文件，各自有依赖项和配置。mcp-codebase-index 零依赖，开箱即用，支持 Python、TypeScript/JS、Go、Rust、C# 和 Markdown，并且每个响应都内置 token 预算控制（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 项目的一部分开发的，该项目是 Recursive Language Models 框架的一种实现。

许可证

本项目采用双重许可：

• AGPL-3.0，适用于开源用途——请参阅 LICENSE
• 商业许可证，适用于专有用途——请参阅 COMMERCIAL-LICENSE.md

如果你将 mcp-codebase-index 用作独立的 MCP 服务进行开发，可免费遵循 AGPL-3.0 许可证。如果你将它嵌入专有产品，或将其作为托管服务的一部分提供，则需要商业许可证。详情请参阅 COMMERCIAL-LICENSE.md。