Code Index

code-index

一个基于 SQLite 的本地代码索引，通过 MCP 提供给 Claude Code。它用定向检索取代盲目的 Read / Grep / Glob 探索——“parseAuthToken 定义在哪里”、“哪些代码调用了 Indexer.reindex_all”、“查找限流代码”——这些问题都能通过离线索引在几毫秒内得到解答。

无需 API 密钥。无需外部服务。嵌入模型在你的机器上本地运行。

工作原理（30 秒概览）

1. 使用 tree-sitter 解析你的代码库（Python、TypeScript/JavaScript、Go、Rust）。
2. 按符号对代码分块，并扩展标识符（getUserAuthToken → get user auth token），让搜索同时匹配这两种形式。
3. 通过 sentence-transformers 使用 jina-embeddings-v2-base-code（768 维）在本地为每个块生成嵌入。
4. 将符号、代码块、向量以及调用/导入关系存储在 .claude/index.db 中（SQLite + sqlite-vec + FTS5）。
5. 通过 MCP 提供 14 个检索工具 + 1 个管理工具（参见 工具）。
6. 通过可选的 PostToolUse 钩子保持索引最新，该钩子会对已修改的文件进行增量重新索引。

工具

检索

工具	用途
code_search	混合（向量 + FTS）搜索，适用于概念性查询（例如，“身份验证流程”、“我们在哪里解析 JSON”）。
symbol_lookup	按函数 / 类 / 方法 / 类型的确切名称查找。对于标识符，优先于 code_search。
file_outline	按源码顺序列出文件中的符号（含签名）。只需要了解结构时，用它代替 Read。
module_outline	一次调用即可列出目录子树中的符号。用它代替循环调用 file_outline。
where_am_i	给定 path + line，返回最内层符号及其完整的外层符号链。
get_symbol_body	获取来自 symbol_lookup / code_search / file_outline 的 symbol_id 对应的完整代码块。
get_symbol_bodies	get_symbol_body 的批量版本（每次调用最多 20 个 ID）。
callers	调用指定符号的符号。depth（1-5）可沿调用关系递归展开。
callees	指定符号调用的符号。depth（1-5）可沿调用关系递归展开。
references	非调用用法（子类、自由标识符引用）。与 callers / callees 配合使用。
trace	从入口符号构建调用图树；flat=true 会返回节点/边，便于 LLM 快速扫描。
file_imports	此文件导入的文件（direction=imports），或导入此文件的文件（direction=imported_by）。
recent_changes	最近 N 次 git 提交中修改过的文件。
propose_rename	v1：同文件重命名。返回由 Agent 使用自己的 Edit 工具应用的编辑列表；发生冲突时拒绝执行。

管理

工具 / 操作	用途
admin op=init	构建或刷新索引。默认采用增量方式；force=true 会从头重建。
admin op=setup_check	诊断钩子配置、嵌入模型和主机。对钩子进行端到端往返测试。
admin op=install_hook	将自动重新索引的 PostToolUse 钩子接入 .claude/settings.json。可重复执行。
admin op=stats	只读：按语言统计文件数、符号总数、嵌入模型指纹和上次索引时间。
admin op=verify	完整性检查：孤立行、解析失败的文件、悬空边。

embed_query_debug 是仅供开发使用的排名诊断工具；除非设置了 CODE_INDEX_DEBUG=1，否则不会显示在 list_tools 中。

所有工具都返回有界 JSON；对于较大的正文，请使用 get_symbol_body， 而不是内联整个文件。

要求

• Python 3.10+，并支持加载 SQLite 扩展（sqlite-vec 必需）。
  • Python 3.13 默认启用此功能。
  • 对于 3.10–3.12，请通过 python.org 安装程序安装，或使用 pyenv，并执行 PYTHON_CONFIGURE_OPTS=--enable-loadable-sqlite-extensions pyenv install 3.12.x。
  • Homebrew Python 通常不包含扩展钩子 — 请改用上述两种方法之一。
• uv / uvx（安装）— 推荐的运行器。如果更喜欢永久安装，也可以使用 pip。
• 约 600 MB 可用磁盘空间，用于首次初始化时下载嵌入模型。

快速开始（Claude Code）

一条命令，无需 API 密钥：

claude mcp add-json -s user code-index "$(cat <<'JSON'
{
  "type": "stdio",
  "command": "uvx",
  "args": ["--refresh", "--from", "mcp-code-index", "code-index-mcp"]
}
JSON
)"

然后在任意代码仓库中打开 Claude Code 并询问：

“为此代码仓库构建代码索引。”

Claude 会调用 init MCP 工具，将 .claude/index.db 写入磁盘。之后， 你可以询问 “parseAuthToken 定义在哪里？” 或 “哪些内容会调用 Indexer.reindex_all？” 之类的问题 — Claude 会通过 symbol_lookup / callers / code_search 来处理，而不是使用 grep。

--refresh 的作用 — 每次启动 Claude Code 时都会获取最新的 PyPI 版本。在预览期间很方便；如果想固定版本，请移除它（可节省约 1 秒启动时间）。

仅安装到项目 — 移除 -s user，即可将服务注册到当前项目的 .claude/settings.json，而不是全局的 ~/.claude.json。

首次运行时下载模型 — 首次执行 init 时，会将 jina-embeddings-v2-base-code（约 600 MB）下载到 ~/.cache/huggingface， 并永久缓存。后续运行完全离线。如果网络无法访问 Hugging Face，请在可访问的机器上预先填充缓存。

已在未使用 --refresh 的情况下安装？ 请先运行 claude mcp remove code-index， 然后重新运行上述命令。

替代方案：永久安装（不使用 uvx）

pip install mcp-code-index
claude mcp add -s user code-index -- code-index-mcp

可选：编辑时保持索引实时更新

如果没有钩子，当文件在 Agent 之外发生变化（mv、 git checkout、IDE 保存）时，索引会逐渐过时，直到再次调用 init。启用钩子后， Claude 执行的每个 Edit / Write / MultiEdit 都会触发对所改文件的增量重新索引。

最简单的方法：询问 Claude。 在新项目中首次使用时，询问 “设置 code-index” — Claude 会依次调用 setup_check → install_hook → init。钩子 命令会根据 MCP 服务的启动方式生成（支持 uvx），因此会使用同一套 Python 工具链。 钩子输出会写入 .claude/code-index-hook.log，便于排查故障。

手动安装 — 将此代码块添加到项目的 .claude/settings.json 中的 hooks.PostToolUse 下（根据启动服务的方式，所需版本可能不同 — install_hook 会为你生成正确的版本）：

{
  "matcher": "Edit|Write|MultiEdit",
  "hooks": [
    {
      "type": "command",
      "command": "uvx --with 'sentence-transformers<5' --with 'numpy<2' --from mcp-code-index code-index-hook"
    }
  ]
}

其他兼容 MCP 的 Agent

该服务通过 stdio 使用标准 MCP 通信，因此任何支持 MCP 服务的客户端都可以使用（Cursor、Continue、Cody、Zed 等）。将客户端配置为启动 uvx --refresh --from mcp-code-index code-index-mcp（或者在 pip install mcp-code-index 后启动 code-index-mcp）。连接后，在客户端中调用 init 工具来初始化索引。若要固定使用稳定版本，而不是始终获取最新版本，请移除 --refresh。

从源代码构建（开发）

git clone https://github.com/achreftlili/code-index
cd code-index
pip install -e .
code-index init        # CLI alternative to the `init` MCP tool
code-index-mcp         # starts the MCP server on stdio (for manual wiring)

配置

所有设置均为可选项——默认设置开箱即用。可通过环境变量覆盖这些设置。在 Claude Code 中，在 ~/.claude.json 的 code-index 服务条目中的 env 块里设置这些变量（然后重新连接 MCP 服务）。

常用选项（大多数用户通常只会调整这些）：

Var	Default	When to set it
CODE_INDEX_EMBED_DEVICE	自动	强制指定 torch 设备：cpu、mps 或 cuda。如果在 Apple Silicon 上运行 init 时出现 MPS 内存不足，请设为 cpu。
CODE_INDEX_EMBED_BATCH	32	编码批次大小。调低（例如设为 8 或 4）可在使用 mps/cuda 时降低 GPU 峰值内存占用。
CODE_INDEX_DB	.claude/index.db	覆盖 SQLite 索引路径（例如，用于在同级工作树之间共享索引）。

高级选项（很少需要调整）：

Var	Default	Notes
CODE_INDEX_EMBEDDER	jina	目前仅支持 jina（本地 sentence-transformers）；此变量是为未来扩展预留的。
CODE_INDEX_EMBED_MODEL	jinaai/jina-embeddings-v2-base-code	HuggingFace 模型 ID。仅当你确认模型的维度兼容（768d）时才覆盖此设置。
CODE_INDEX_EMBED_DIM	768	必须与嵌入模型的输出维度一致。

故障排除

**在 Apple Silicon 上，init 因 MPS backend out of memory 而失败。**某个大文件生成的分块批次超过了 GPU 的可用 VRAM。最快的解决方法是重新在 CPU 上运行（速度较慢，但非常可靠）：

"env": {
  "CODE_INDEX_EMBED_DEVICE": "cpu"
}

若要继续使用 GPU，可改为缩小批次大小："CODE_INDEX_EMBED_BATCH": "8"。 重新连接 MCP 服务（/mcp → 重新连接，或重启 Claude Code），使新的环境变量生效。init 支持增量处理——重试时会跳过已完成嵌入的文件。

**首次运行时，init 因 Hugging Face 网络错误而失败。**你的网络阻止了模型下载。请在可以访问网络的机器上预先填充缓存：

huggingface-cli download jinaai/jina-embeddings-v2-base-code
# then copy ~/.cache/huggingface/ to the offline machine

出现 sqlite3.OperationalError: not authorized，或 sqlite-vec 加载失败。 你的 Python 构建不支持加载 SQLite 扩展。请参阅 要求——通过 python.org 安装，或使用带有 PYTHON_CONFIGURE_OPTS=--enable-loadable-sqlite-extensions 的 pyenv 构建版本。

**重构或切换分支后，code_search / symbol_lookup 返回的路径已过时。**自动重新索引钩子仅会在 Claude 执行 Edit / Write / MultiEdit 时触发。在 Agent 外部批量移动文件后（mv、 git checkout、IDE 重命名），请重新运行 init（该操作支持增量处理）。或者配置 钩子，让索引在 Agent 自动编辑时保持更新。

目录结构

src/code_index/
  db.py           SQLite schema, connection, sqlite-vec loading
  parser.py       Tree-sitter wrapper, symbol + edge extraction
  imports.py      Per-language import target → file path resolution
  chunker.py      Per-symbol chunks, identifier expansion
  embedder.py     Local Jina (sentence-transformers) backend
  indexer.py      Pipeline: walk → parse → chunk → embed → write
  reindexer.py    Per-root engine cache; one entry point for "reindex one file"
  retriever.py    Hybrid search (vector + FTS5) with RRF
  watcher.py      File watcher (watchdog)
  admin.py        setup_check / install_hook / init logic (pure, no MCP state)
  mcp_server.py   MCP wiring, shared helpers, schema fragments
  tool_registry.py  Shared `@_tool` decorator + `_TOOLS` registry
  tools/          Per-domain MCP handlers (graph, paths, refactor, …)
  hook.py         `code-index-hook` console script — the PostToolUse entry point
  cli.py          init / reindex / watch / stats