用途
mcp-codebase-index 是一个结构化代码库索引器，同时提供 MCP（Model Context Protocol）服务器，用于 AI 辅助开发场景，帮助 AI 以结构化方式导航代码库。它的核心目标不是回答“某个函数在哪”，而是回答“改动它会发生什么”。
主要能力
- 将源代码解析为结构化元数据：函数、类、导入、依赖图、跨文件调用链。
- 通过 MCP 暴露 18 个查询工具，供 Claude Code 及其他 MCP 客户端调用，避免读取整个文件。
- 零运行时依赖：Python 分析使用 Python 的 ast 模块，TypeScript/JS、Go、Rust、C# 使用基于正则的解析。要求 Python 3.11+。
- 自动增量重索引：在 git 仓库中，每次查询前检查 git diff 与 git status（约 1-2ms），若文件有变化，仅重新解析变更文件并重建依赖图，无需手动 reindex。
- 持久化磁盘缓存：每次构建后索引保存到 pickle 缓存文件 .codebase-index-cache.pkl；后续启动时与当前 git HEAD 校验，ref 匹配则瞬时启动；变更文件 ≤20 个时加载缓存并增量更新，而非全量重建。
- 内置 token 预算控制：如 max_results、max_lines 等参数，响应大小随答案而非代码库规模增长。
使用方式
安装（包含 MCP 服务器依赖）：使用带 [mcp] extra 的安装命令；若只需程序化 API 可省略该 extra。开发时也可从本地克隆安装。PROJECT_ROOT 指定要索引的目录，默认为当前工作目录。
持久化缓存行为：缓存命中（精确匹配）时，若缓存 git ref 与当前 HEAD 一致，直接从磁盘加载；缓存命中（小变更集）时，若变更 ≤20 个文件，加载缓存并在首次查询时增量更新；缓存未命中时进行全量重建并保存新缓存。建议将 .codebase-index-cache.pkl 加入 .gitignore。
与 OpenClaw 配置：在运行 OpenClaw 的机器上安装该包，将 MCP 服务器加入 OpenClaw 的 openclaw.json，重启后验证连接，即可使用全部 18 个工具。注意：OpenClaw 默认通过 mcporter 的 MCP 集成会为每次工具调用新建服务器进程，丢弃内存中的索引并强制重建；持久缓存可显著加快这种冷启动。若需持久连接，可使用 openclaw-mcp-adapter 插件。
与 Claude Code 配置：在项目的 .mcp.json 中添加配置，或直接使用 Python 模块（适用于安装在 virtualenv 中的情况）。Claude Code 默认倾向于使用内置的 Glob/Grep/Read 工具；除 CLAUDE.md 说明外，可添加在每次提示时触发的 hooks 来强化行为（SessionStart 在启动、恢复和上下文压缩时触发，UserPromptSubmit 每轮触发）。
重要提示：默认情况下 AI 助手会忽略索引工具并回退到整文件读取；应使用强制性的措辞而非“prefer”这类软性表述，并给出明确的回退条件。
适用场景
适用于 AI 辅助的代码库导航与重构分析，例如查询符号、类、导入关系，评估某符号变更的直接与传递影响（get_change_impact 在 CPython 上找到 154 个直接依赖与 492 个传递依赖，耗时 0.45ms），以及在大型代码库中控制 AI 的 token 消耗。
性能
针对四个真实项目在 M 系列 MacBook Pro 上测试，涵盖小型项目到 110 万行的 CPython。多个针对性查询在 CPython 上仍为亚毫秒级返回；find_symbol 无论项目是 7K 行还是 110 万行，返回 54-67 个字符。可使用 max_direct、max_transitive 限制输出。持久缓存下，CPython 缓存命中可在 1 秒内恢复完整索引，而非 56 秒。基准测试可通过 python benchmarks/benchmark.py 运行。
与 LSP 的区别
LSP 回答“这个函数在哪”，mcp-codebase-index 回答“改动它会发生什么”。LSP 是点查询：一个符号、一个文件、一个位置；无法直接回答“重构某符号后传递性影响什么”。本工具可在单次调用中返回直接与传递影响（示例：11 个直接依赖、31 个传递影响、204 个字符）。LSP 还需为每种语言安装单独的语言服务器（如 pyright、vtsls、gopls），而本工具零依赖，开箱支持 Python、TypeScript/JS、Go、Rust、C#、Markdown，且每个响应都有内置 token 预算控制。
限制
要求 Python 3.11+。对 TypeScript/JS、Go、Rust、C# 使用基于正则的解析。缓存文件为本地构建产物，建议加入 .gitignore。若嵌入专有产品或作为托管服务提供，需要商业许可。
许可与来源
该项目采用双重许可：开源使用为 AGPL-3.0（见 LICENSE），专有使用为商业许可（见 COMMERCIAL-LICENSE.md）。作为独立 MCP 服务器用于开发时适用 AGPL-3.0，无费用。结构化索引器最初作为 RMLPlus 项目（Recursive Language Models 框架的实现）的一部分开发。
