内容
# mcp-code-indexer
**`code-graph-indexer`** 源代码仓库 — 一个代码智能引擎，可以将任何 TypeScript / React / Next.js 仓库转换为可查询的 **代码图**，并以五种方式提供服务：**CLI**、**MCP 服务器**、**HTTP + WebSocket API**、**带有内置聊天机器人的 3D 网页浏览器** 和 **本地语义搜索**。
> **直接使用？** 您不需要这个仓库。`npx code-graph-indexer ui --root .` 即可使用整个功能 — 参见 [软件包 README](packages/code-indexer-dist/README.md)。本仓库用于开发引擎本身。
```
┌──────────────┐ ts-morph AST ┌───────────────┐ serve ┌───────────────────────────────────────┐
│ 任意 TS/React │ ───────────────▶ │ 代码图 │ ─────────▶ │ CLI · MCP · HTTP/WS · 3D UI · 语义搜索 │
│ 仓库 │ 遍历 + 解析 │ 节点 + 边 │ │ （从任意地方消费） │
└──────────────┘ └───────────────┘ └───────────────────────────────────────┘
```
所有内容都基于 [`ts-morph`](https://ts-morph.com) 构建，因此边是由编译器解析的，而不是通过搜索 — 且保守：只有当边解析为真实的索引节点时，才会绘制边。索引器是 **通用** 的；它自己发现工作区形状，并处理 monorepos（pnpm / turbo / lerna）和独立的单包仓库。目标上没有任何内容是硬编码的。
---
## 为什么它能让开发更快、更便宜、更可靠
估计在具有代理读取文件与图查询的相同问题上的成本（典型的中型仓库）：
| 您询问的问题 | 仅代理（读取文件） | 使用代码图 | 您节省 |
| ------------------------------- | ----------------------------------- | ----------------------------- | --------------- |
| “什么调用了 `format()`？” | ~30k tokens · ~40s | ~0.4k tokens · <1s | **~99% tokens** |
| “如果我更改此内容，会有什么问题？” | ~50k tokens · ~60s _(遗漏边)_ | ~0.6k tokens · <1s _(精确)_ | **~99% tokens** |
| “在哪里可以找到执行 X 的代码？” | ~25k tokens · ~30s | ~0.3k tokens · ~2s | **~98% tokens** |
| “安全编辑此内容的上下文” | ~40k tokens · ~50s _(5 次读取)_ | ~0.8k tokens · <1s _(1 次调用)_ | **~98% tokens** |
| “是否存在任何死代码或循环？” | ~60k tokens · 手动审核 | ~0.5k tokens · 即时 | **~99% tokens** |
**更快**（内存查找，而不是重新读取）· **更便宜**（更少的 tokens = 更低的账单）· **更可靠**（编译器解析的边 — 没有虚构的调用者，没有错过的 impact）。
---
## 图模型
| 节点类型 | 边类型 |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `仓库` · `应用` · `软件包` · `文件夹` · `文件` · `组件` · `函数` · `外部` | `包含` · `导入` · `调用` · `渲染` · `引用` · `依赖于` |
每个节点都带有指标（`loc`、`exportsCount`）、一个 `状态` 块（类型/ lint / 构建健康）和 git 元数据 — 足以在上面构建代码库仪表盘、影响分析和 AI 代理导航。
---
## 快速入门（开发引擎）
```bash
pnpm install
pnpm build # turbo 构建核心 → _shared → 引擎 → 服务器 → 网页（拓扑顺序）
pnpm test # 引擎 + 模式软件包的单元测试
pnpm typecheck
pnpm lint
```
> 需要 Node ≥ 20.19 和 pnpm 10（通过 `packageManager` 固定；`corepack enable` 选择它）。在从源代码运行 CLI 或服务器之前需要 `pnpm build`。
在当前仓库（或任意路径）上运行完整的浏览器：
```bash
pnpm serve --root . # HTTP/WS 服务器在 :3002（也提供构建的 UI）
pnpm ui # 或：Vite 开发服务器在 :5182，带有 HMR，代理 /api + /ws → :3002
```
`pnpm serve` 提供预构建的网页包；`pnpm ui` 是用于开发 UI 本身的热重载开发服务器。
---
## 五个界面
所有接口都针对同一个引擎和目标仓库根目录进行解析。
### 1. 3D 浏览器 + 聊天机器人
[`apps/web/code-graph`](apps/web/code-graph) 前端 — 一个 [`react-force-graph-3d`](https://github.com/vasturiano/react-force-graph) 浏览器，带有文件夹钻取、类型/健康着色、悬停跟踪、爆炸半径高亮、2D 备用和聊天面板，基于图。 它是 HTTP/WS API 的纯消费者：它加载 `GET /api/graph`，然后在编辑文件时通过 `WS /ws` 应用实时的 `GraphPatch`。
### 2. MCP 服务器 — 14 种工具
通过 stdio 注册，以便 Claude Code / Cursor 可以直接调用它：
```bash
claude mcp add code-graph -- node "$(pwd)/tools/code-indexer/build/code-indexer/src/index.js"
```
工具：`index_repo`、`get_graph`、`get_node`、`who_renders`、`who_calls`、`find_references`、`blast_radius`、`find_cycles`、`find_orphans`、`search_nodes`、`get_context_pack`、`build_embeddings`、`semantic_search` 和 `open_explorer`（启动 3D UI 并返回其 URL）。完整描述请参见 [软件包 README](packages/code-indexer-dist/README.md#2-mcp-server--let-claude--cursor-query-your-code)。
### 3. CLI
```bash
node tools/code-indexer/build/code-indexer/src/cli.js index --root /path/to/repo
node tools/code-indexer/build/code-indexer/src/cli.js query blast-radius --id "fn:src/util.ts#format" --root /path/to/repo
```
### 4. HTTP + WebSocket API
```bash
pnpm serve --root /path/to/repo
curl localhost:3002/api/graph | jq '.meta'
# { "root": "/…", "nodeCount": 908, "edgeCount": 2138, "indexerVersion": "…" }
```
读取、反向查询、`POST /api/reindex`、`POST /api/chat` 和 `WS /ws` 用于实时补丁。仅绑定到 `127.0.0.1` — 端点是未经身份验证和可变的，因此请勿在主机上公开它。
### 5. 语义搜索
通过 transformers.js 进行本地 `Xenova/all-MiniLM-L6-v2` 嵌入 — 无需 API 密钥，数据不会离开机器。当模型未安装时，搜索会退回到词法搜索。
---
## 架构
> 更深入的原理 — 图模型、为什么使用 ts-morph、宏/微的分离以及诚实的取舍 — 请参见 [docs/DESIGN.md](docs/DESIGN.md)。
一个具有几个专注软件包的 Turborepo（以及共享配置）：
```
mcp-code-indexer/
├── packages/
│ ├── code-graph-core/ @repo/code-graph-core — Zod 模式：节点、边、快照、状态
│ └── code-indexer-dist/ code-graph-indexer — 已发布的 npm 软件包（tsup）+ 捆绑的网页 UI
├── tools/
│ ├── _shared/ @tools/shared — MCP 服务器基础（McpServerBase、ToolRegistry）、实用工具
│ └── code-indexer/ code-indexer-mcp — 引擎：ts-morph 分析、CLI、MCP 服务器
└── apps/
├── indexer-server/ indexer-server — Express + ws 运行时、文件监视器、REST/WS + 聊天
└── web/code-graph/ code-graph — React + three.js 3D 浏览器
```
依赖流（从叶子开始）：
```
code-graph-core ─┬─▶ code-indexer ─▶ indexer-server ─┐
_shared ──────┘ ├─▶ code-indexer-dist (npm 软件包)
web/code-graph ─────────────────────────────────┘
```
- **`code-graph-core`** — 契约。Zod 模式验证每个节点、边和快照，因此图形形状在端到端得到保证。纯粹且经过充分的单元测试。
- **`code-indexer`** — 分析引擎。`ts-morph` 解析加上工作区发现（monorepo 与独立）、增量快照到 `.code-graph/`。兼作 MCP 服务器。
- **`indexer-server`** — 用 Express + `ws` 包装引擎，在启动时索引，在后台丰富节点状态，监视文件以进行实时更新，并提供聊天端点（本地 `claude` CLI → API 密钥 → 启发式）。
- **`web/code-graph`** — 3D 浏览器，纯 API 消费者。
- **`code-indexer-dist`** — 将上述所有内容捆绑到单个 `code-graph-indexer` npm 软件包中，包括网页 UI。
---
## 脚本
| 命令 | 执行的操作 |
| -------------------------- | ---------------------------------------------------- |
| `pnpm build` | 构建每个软件包（通过 turbo 拓扑顺序） |
| `pnpm typecheck` | 跨每个软件包的 `tsc --noEmit` |
| `pnpm test` | 单元测试（模式 + 引擎） |
| `pnpm lint` | 跨所有软件包的 ESLint（共享平面配置） |
| `pnpm serve --root <path>` | 在 `:3002` 上针对任何仓库运行服务器（带有 UI） |
| `pnpm ui` | 用于浏览器在 `:5182` 上的 Vite 开发服务器 |
## 技术
TypeScript（严格）· Turborepo · pnpm 工作区 · ts-morph · Zod · Express · ws · @parcel/watcher · React · three.js · 模型上下文协议 SDK · transformers.js · Vitest · tsup。
## 状态
`pnpm build` ✓ · `pnpm typecheck` ✓ · `pnpm lint` ✓ · `pnpm test` ✓。CI 在每次推送和 PR 时运行相同的门控（`build → typecheck → lint → test`）（`.github/workflows/ci.yml`）。
