Codindex

本地代码索引服务：用 MCP 把代码库结构交给 AI。

tree-sitter 解析 AST，把函数、调用图、模块依赖图、控制流图存进单个 SQLite 文件， 通过 32 个 MCP 工具供 AI 查询。让 AI 不必 grep、不必逐文件 Read， 就知道仓库里有什么、谁调用了谁、改一处会波及哪里。

• 本地优先 — 不调 LLM API、不上传源码、无遥测

• 结构化 — 调用边由 AST 解析得出，不是正则猜的

• 快 — 自扫描 38 文件 / 145 函数 / 7,570 调用边，3.4 秒

以 MCP server 接入 Claude Code、Cursor、VS Code、Windsurf、Codex 及任何支持 Model Context Protocol 的 client。代码搜索与代码导航（code navigation）走 SQLite FTS5， 语义簇走调用图 BFS，产物是一张可查询的代码图（code graph）。

agentic coding 的关键瓶颈不是模型能力，而是给它看什么：整仓塞进上下文会爆，靠 grep 又只能拿到碎片。Codindex 把仓库索引成一份可复用的 repo index，让 AI 按需取结构化 code context——而不是把几万行源码反复喂进去。

它能回答哪些问题

在 CodeGraph 仓库（146 个 TS 文件）上实测：AST 统计到 1,926 个函数， 让 Agent 用 grep 手工统计只得到约 951 个——差一倍，且 grep 拿不到调用关系。

Related MCP server: weavatrix-js

快速开始

需要 Node.js ≥ 22.5（依赖内置 node:sqlite）。

npm i -g codindex

装好后：

codindex --version   # 确认版本
codindex --mcp       # MCP stdio 模式，交给编辑器挂载
codindex             # Web UI → http://localhost:3100

从源码安装（想改代码或跑测试时）：

git clone https://github.com/Bencibr/codindex.git codindex && cd codindex
npm install && npm run build
npm pack && npm i -g ./codindex-*.tgz

仓库根 .npmrc 已声明 legacy-peer-deps=true（tree-sitter 语法包的 peer 范围互相冲突）， npm install 无需额外参数。开发用 npm run dev 起服务，npm test 跑测试（325 个用例）。

安装时若出现 npm warn allow-scripts tree-sitter-* (install: node-gyp-build)， 属正常提示：语法包自带预编译产物，跳过 install 脚本不影响使用。 想消除提示可执行 npm approve-scripts --allow-scripts-pending。

扫描项目

任选其一：

# Web UI：打开 http://localhost:3100，填名称和路径，点「添加」→「扫描」

# API
curl -X POST http://localhost:3100/api/projects \
  -H "Content-Type: application/json" \
  -d '{"name":"My Project","path":"/path/to/your/project"}'
curl -X POST http://localhost:3100/api/projects/{id}/scan

// MCP
add_project { name: "My Project", path: "/path/to/your/project" }
scan_project { project_id: "xxx" }

跑通一次完整链路

装完不确定有没有生效，按下面四步走一遍（以扫描本仓库为例）：

1. 起服务

codindex          # Web UI → http://localhost:3100

2. 注册项目 —— 返回体里的 id 就是后续所有接口要用的 project_id

curl -X POST http://localhost:3100/api/projects \
  -H "Content-Type: application/json" \
  -d '{"name":"Codindex","path":"/path/to/codindex"}'
# → {"id":"bace225b-...","name":"Codindex","status":"pending", ...}

3. 扫描 —— 同步执行，返回即完成

curl -X POST http://localhost:3100/api/projects/bace225b-.../scan
# → {"status":"complete","files":38,"functions":145,"calls":7572,"types":31,"cycles":0}

4. 验证能查

curl http://localhost:3100/api/projects/bace225b-.../overview
# → {"name":"Codindex","status":"ready","lastScanned":1794213971, ...}

或者走 MCP：add_project → scan_project → get_project_summary， 最后一步会返回 {files: 38, functions: 145, types: 31, calls: 7568, modules: 9}。

看到 status: "ready" 且函数数不为 0，就说明整条链路通了。

MCP 配置

Claude Code — 全局装好后直接用 codindex 命令（最省事）：

{
  "mcpServers": {
    "codindex": {
      "command": "codindex",
      "args": ["--mcp"],
      "env": { "CODINDEX_DB": "/absolute/path/to/codindex.db" }
    }
  }
}

或用命令：claude mcp add codindex -- codindex --mcp

不想全局安装，也可以直接跑克隆下来的源码（需要该 clone 已 npm install）：

{
  "mcpServers": {
    "codindex": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/codindex/src/index.ts", "--mcp"]
    }
  }
}

Cursor / VS Code — 把同样的内容写进 .cursor/mcp.json 或 .vscode/mcp.json， 外层键改成 "servers"。

CODINDEX_DB 必须是绝对路径，否则 MCP 子进程可能找不到数据库。

32 个工具

完整清单（参数、返回值、解析规则）见 docs/TOOLS.md。

最常用的 get_smart_context 按 purpose 返回不同深度，避免为一点信息整段读源码：

除了工具，MCP 还提供 4 个 Resource（codindex://projects 及 codindex://projects/{id}/{overview,functions,features}）供客户端直接挂载， 以及 1 个 Prompt（codindex-guide）用于注入使用指引。见 docs/TOOLS.md。

性能

扫描：优化后综合耗时 ~9s → ~3.5s（批量事务、批量 UPDATE、Map 索引替代嵌套循环）。 本仓库自扫描 3.4s，含进程启动。

AI 效率：我们跑了两轮，结论不一致，两个都放上来。

能可靠省下来的是单次回答的数据量：结构化查询返回几万字符，而不是几十万字符的源码。 这一点两轮都成立。 不能承诺的是调用次数一定下降——这取决于 Agent 是否真的信任并优先使用这些工具， 受提示词、模型版本影响。第一轮的 −53% 没能复现。完整记录在 src/tests/bench/。

常见问题

它是向量检索 / RAG 吗？ 不是。没有 embedding、没有向量库、不调模型 API。search_semantic 这个名字容易误解， 它实际是基于调用图做 BFS：找到种子函数后把调用邻居一并返回，结果可复现、可审计。

需要联网或上传代码吗？ 不需要。数据落在单个 SQLite 文件（默认 data/codindex.db）。

和 LSP / IDE 跳转有什么不同？ LSP 面向编辑器里的即时导航；Codindex 面向「把整个仓库结构一次性交给 AI」—— 批量、可查询、可跨会话复用，还能算影响面、复用分和死代码。两者不冲突。

数据会过期吗？ start_watching 后文件变更 3 秒内同步。所有响应带 lastModified，可比对判断新鲜度。

装不上 / 跑不起来

.npmrc 那条最容易踩：它只在仓库根目录执行 npm install 时生效， 在子目录或别的目录装会重新触发 ERESOLVE。

支持的语言

单文件上限 1MB。未列出的语言不会被索引——宁可少支持，也不做「文件数统计上了、 函数却一个都解析不出来」的虚假覆盖。

技术栈

Node.js ≥ 22.5 + TypeScript (ESM) · Tree-sitter · SQLite（内置 node:sqlite， 可选 better-sqlite3）+ Drizzle ORM + FTS5 · Hono · React 18 + MUI 5（CDN 直出，无前端构建） · @modelcontextprotocol/sdk · chokidar · Vitest

文档

开发常用命令：

npm run dev        # tsx 直跑，改代码即生效
npx tsc --noEmit   # 完整类型检查
npm test           # 14 files / 325 tests（用临时库，不碰 data/）
npm run build      # 产物在 dist/
codindex --help    # CLI 用法

License

MIT