code-atlas

code-atlas

多语言代码智能 MCP 服务——为 Claude Code（以及任何 MCP 客户端）提供结构化代码库视图，而非原始文本：符号搜索、文件大纲、AST 模式查询、跨文件引用、调用/类型层级、导入关系图、变更影响分析（含受影响测试检测）、Web 框架路由映射（Express/NestJS/Fastify/FastAPI/Flask/Django）、Mermaid 图表、由 LSP 支持的精准答案、本地嵌入语义搜索，以及游戏引擎资源理解（Godot、Unity、Unreal）。支持索引 25 种语言。

无需 grep 并阅读整个文件，模型可以提出 “绘制这个仓库的映射”、“列出这个文件的大纲”、“谁调用了 parseConfig？”、“请求处理程序如何到达 DB 层？”、“这个文件变更时会影响什么？” 等问题，并获得由持久化 tree-sitter 索引支持的精简、节省令牌的答案。

每个答案都有预算：工具接受 max_tokens 上限；如果响应被截断，会返回一个游标，你可以传回该游标以继续获取内容，而不必重新提问并提高预算。

状态：已发布（npm @lusiem/code-atlas，MCP registry io.github.lusiem/code-atlas）。支持 25 种语言、32 个工具，提供带结构化基础保障的 LSP 精确答案、引擎适配器，以及为节省令牌而构建的 Agent 工作流层（repo_map、context_pack、verify_changes）。已通过 19k 个文件 / 6.3M LOC 的验证。

工作原理

your repo ──scan (gitignore-aware)──> tree-sitter parse ──> SQLite index (symbols, imports,
                                                             occurrences, call/type edges, FTS5)
                                                                   │
Claude Code ◄──────────── MCP tools over stdio ────────────────────┘

• 持久化索引位于 <repo>/.code-atlas/index.db（自动加入 git 忽略），按内容哈希增量刷新。
• 实时更新——支持 gitignore 的文件监视器会在防抖间隔后重新索引保存内容，并且只重新解析受影响的文件（使用 --no-watch 或 "watch": false 可禁用）。
• 零配置——指定仓库根目录即可使用。也可选用 code-atlas.json 调整包含/排除规则。
• 完全本地运行——你的代码绝不会离开本机。

在 Claude Code 中安装和使用

claude mcp add code-atlas -- npx -y @lusiem/code-atlas serve

也可以从克隆的仓库运行：

git clone https://github.com/lusiem/code-atlas && cd code-atlas
npm install && npm run build
claude mcp add code-atlas -- node /path/to/code-atlas/dist/index.js serve

服务会索引当前工作目录；传入 --root <path> 可覆盖该目录。

CLI

node dist/index.js index [--root <path>]              # one-shot index build (debugging / warm-up)
node dist/index.js serve [--root <path>] [--no-watch] [--no-lsp] [--no-embeddings] [--no-download]
                                                      # MCP server on stdio

工具

完整参考（含输出示例）：docs/tools.md。

工具	能回答什么问题
repo_map	这个代码仓库是什么？我该从哪里开始？ 标注了导入扇入／扇出的目录树（层次结构一目了然）、入口点、按重要性排序并说明排序原因的关键符号，以及第三方依赖清单——一次有预算控制的调用即可完成，无需全面 grep 搜索。使用 path_prefix/depth 缩小范围。
project_overview	简版概览：语言、规模、布局、索引新鲜度。
search_symbols	X 定义在哪里？对名称和文档注释进行 FTS + 模糊搜索，并可按类型／语言／路径筛选。
search_content	这段文本出现在哪里？字符串字面量、错误消息、环境变量、配置键、TODO——以及唯一能搜索非代码文件的工具（md/json/yaml/toml/sql/Dockerfile/CI）。索引提供候选项，磁盘负责验证，因此命中结果永远不会过时。
semantic_search	“重试退避逻辑在哪里实现？”——自然语言搜索，采用关键词 + 嵌入的混合排序，完全在本地运行。
get_file_outline	这个文件里有什么？无需阅读源代码即可查看层次化签名——超出预算时，会减少嵌套深度而不是截掉末尾行，因此所有顶层符号都会保留。传入一个目录，即可通过一次调用查看一个包的公共 API 概况。
get_symbol_info	获取一个符号的所有信息（可按 id、位置或名称查询），包括文档和源代码。
context_pack	一次调用即可获取有关某个符号的简报，并控制 token 预算：源代码、概要、调用者／被调用者、类型、路由、相关测试——无需分六次查询。会列出超出预算而无法纳入的部分。
batch_symbols	一次调用即可将最多 50 个 #id 解析为简洁的单行信息。
ast_query	原始 tree-sitter S 表达式查询——可执行结构化搜索，这是正则表达式做不到的。
find_references	哪些代码使用了这个符号？有 LSP 时采用精确匹配；否则优先显示已解析的用法，再将名称匹配项作为候选。
go_to_definition	跳转到指定位置标识符的定义。有 LSP 时采用精确结果，未启用时回退到索引。
call_hierarchy	以树形结构查看谁调用了它／它调用了什么。语言服务器运行时，边会标记为 [lsp 1.00]。
type_hierarchy	沿着 extends/implements 关系查看超类型和子类型。
get_dependencies	文件导入关系图，包含两个方向（导入／被导入）。
trace_path	两个符号之间的最短调用链。
change_impact	变更影响范围：传递调用者 + 导入可达性，优先列出受影响的测试文件。目标可以是一个符号、文件列表，或不指定目标——不带参数时会分析未提交的 git diff（按代码块级别分析：只有你实际修改过的符号才会作为遍历起点）。受影响的路由处理程序会标记为 [ROUTE GET /users/:id]。
verify_changes	编辑后对照 git HEAD 进行结构检查：不再能解析的导入、其他文件仍在引用的已移除导出、仍有调用者的签名变更。change_impact 用于预测；此工具用于确认。
tests_for_symbol	哪些测试会执行这个符号？反向遍历关系图查找测试文件，并标明测试用例；仅通过导入链找到的结果会作为较弱的信号报告。
find_similar_code	“这个辅助函数是否已经存在？”——使用本地嵌入向量搜索近似重复代码，在覆盖率构建期间则回退到文本相似度搜索。
find_dead_code	排除入口点／路由／生命周期后，找出引用数为零的符号，并谨慎标注置信度（任何位置存在同名用法时标记为 possibly dead）；未使用的导出会单独列出。
hotspots	根据变更频率 × 代码规模对风险进行排序，结果取自缓存的提交历史。
change_coupling	哪些文件过去常与此文件一同变更——这是结构索引无法发现的耦合（配置、固定数据、文档、基于字符串键的分发）。提供方向性置信度，并标记没有导入关系的文件。
symbol_history	这个符号为何会如此编写，该向谁询问？使用 git log -L 查看符号所在行的历史：sha、日期、作者、主题。
list_routes	列出工作区内 Web 框架的路由——包括 Express、Fastify、NestJS、FastAPI、Flask、Django，以及 Next.js、SvelteKit、Nuxt 和 Remix 的基于文件的路由——每条路由都关联到其处理程序符号。
find_route	“哪段代码处理 GET /api/users/7？”——根据已索引的路由模式匹配具体 URL（:id、{id}、<int:pk> 均视为通配符），并返回处理程序。
generate_diagram	生成上述关系图的 Mermaid 图表：导入关系图（文件或目录级别）、围绕某个符号的调用图、类型层次结构、调用路径——可直接粘贴到 GitHub Markdown 或文档中。
get_scene_structure	Godot 场景节点树，包含附加脚本、实例化子场景和信号连接（处理程序已解析为符号）。
find_asset_references	哪些场景／预制件／Blueprint 使用了此脚本、资源或处理程序？跨 Godot res:// 路径、Unity GUID（通过 .meta）以及 Unreal 模块和 /Game/ Blueprint 路径进行反向查找。
search_reflection	查找工作区中所有 UPROPERTY(Replicated)、[SerializeField]、@export 变量和信号——即引擎反射标记。
index_status / reindex	查看索引状态并手动刷新。
跨文件回答采用LSP 优先并设有结构分析兜底：当语言服务器可用时（在 PATH 中找到或自动获取到每用户缓存目录），引用/定义/悬停/调用层级均为精确结果，并标记为 lsp；其他情况下，启发式导入/名称解析会为每条边给出置信度分数。支持的服务器：typescript-language-server + pyright（npm）、gopls（go install）、rust-analyzer + clangd（固定版本、经 SHA-256 验证的发布二进制文件）、用于 Java 的 Eclipse JDT LS（需要 Java 21+ 运行时，可通过 PATH/JAVA_HOME 检测）、kotlin-language-server（需要任意 JRE），以及用于 C# 的 csharp-ls（需要 .NET SDK；作为 dotnet 工具安装——特意不使用 Microsoft 的 Roslyn LSP，因为其许可证仅适用于 VS）。只要 Godot 编辑器打开了项目，GDScript 就会连接到编辑器内置的语言服务器（TCP 127.0.0.1:6005，可用 CODE_ATLAS_GODOT_LSP_PORT 覆盖）；关闭编辑器后，回答会回退到结构分析；重新打开后，下次查询时会重新连接。缺少运行时会使对应语言降级为结构分析，并在 index_status 中如实报告。首次获取（下载 + 启动）绝不会阻塞查询：工具最多等待 8 s，之后会先进行结构分析并作答，同时服务器继续启动。
使用 --no-lsp 禁用；使用 --no-download 禁用自动下载。

语义搜索使用针对代码调优的本地模型 jinaai/jina-embeddings-v2-base-code（量化 ONNX）为每个函数/类（签名 + 文档 + 函数体）生成嵌入向量，并将余弦相似度与 BM25 关键词排名融合。所有内容都保留在你的设备上。ONNX 运行时（约 220 MB）和模型（约 150 MB）不属于此软件包：它们会在你首次调用 semantic_search 时下载到每用户缓存目录，不会在安装时下载；结构分析工具也不会等待它们。覆盖率完成前，结果会侧重关键词权重，并对此作出说明。为包含 60k 个符号的代码库生成嵌入向量约需 15 分钟后台处理时间，且只需执行一次；之后只会重新生成已编辑符号的嵌入向量。"embeddings": {"model": "fast"} 可切换为速度快 4 倍的通用模型；--no-embeddings 可关闭此层。

语言

当前支持索引的语言（25 种）： TypeScript、TSX、JavaScript、Python、C、C++、Rust、Go、Java、Kotlin、C#、 GDScript、PHP、Ruby、Lua、Solidity、Zig、Nix、Swift、Scala、Dart、Terraform/HCL、Pascal/Delphi、 Vue、Svelte。

Vue 和 Svelte 单文件组件会按其真实文件行号索引 <script> 块（包括所有 <script setup>）； 组件导入可以解析，因此 .vue/.svelte 依赖图可用于 get_dependencies 和 change_impact。Terraform 会将块映射为符号（resource "aws_s3_bucket" "logs" 可通过任一标签搜索），并将本地 module 源解析为导入。超出 LSP 覆盖核心范围的语言也能以结构化方式作答，并提供置信度评分的边—— 与其他语言遵循相同的契约。

测试文件感知： 每个索引文件都会依据各语言的路径约定进行分类 （*.test.ts、test_*.py、*_test.go、src/test/、*_spec.rb、Foundry .t.sol 等）——这 为 change_impact 提供受影响测试的报告功能。内联测试块（Rust #[cfg(test)]、Zig test）无法按路径分类，因此按设计不会显示。

游戏引擎： 引擎资源会与代码一并索引——Godot .tscn/.tres 场景（节点树、 脚本附件、信号连接、自动加载；根据 project.godot 解析 res://，也支持包含多个项目的单体仓库）， Unity .unity/.prefab/.asset + .meta GUID 映射（MonoBehaviour → C# 类链接、序列化引用），以及 Unreal .uproject/.uplugin/Build.cs 模块图 和已索引的反射宏：UCLASS/USTRUCT/UFUNCTION/UPROPERTY 限定符会关联到其注解的 符号（可搜索，并显示在 get_symbol_info 中）；dllexport 宏 （class MYGAME_API AMyActor）也不再影响 C++ 类提取。

Unreal Blueprints（.uasset/.umap）： 原生解析二进制编辑器包（包 概要、名称/导入/导出表、资源注册表标签，以及有界的带标签属性读取——无需安装 Unreal）。Blueprint 会将其函数、事件分发器和成员 变量作为可搜索符号呈现（search_symbols kind:event_dispatcher、lang:uasset），每个资源都提供 一个 get_file_outline，图节点注释可进行全文搜索；在 find_asset_references 中可查询资源//Game/ 路径 + 父类 + 被调用函数引用（包括通过 handles_event 查询“谁处理 ReceiveBeginPlay”）。Blueprint→C++ 链接（通过 Unreal 的 A/U/F 命名规则识别父类，以及被调用的 UFUNCTION）会生成带置信度评分的 provenance: engine 边，从而启用 type_hierarchy、call_hierarchy 和 change_impact。 目标为未烹制（编辑器）资源——已通过真实 UE 5.6 项目验证（1,763/1,764 个 资源可解析，保存版本涵盖 UE 4.25 至 5.6）；检测到已烹制/市场资源时会跳过，并记录原因。二进制资源的大小上限由 maxAssetFileBytes（默认 64 MB）设定，并按大小和修改时间进行变更门控，确保预热扫描不会重新读取这些文件。Godot 二进制 .scn 仍不在支持范围内。

路线图

1. 结构核心：扫描器、SQLite+FTS5 索引、TS/JS/Python 提取器、首批 6 个工具 ✅
2. 全部 11 种语言的提取器、跨文件导入解析、调用图（find_references、call_hierarchy、trace_path） ✅
3. 文件监视器 + 增量重新索引（限定范围的重新解析、架构迁移） ✅
4. LSP 层（自动获取 ts-ls/pyright/gopls；校验和固定的 rust-analyzer/clangd 二进制文件；支持 JRE/.NET 检测的 JDT LS/kotlin-language-server/csharp-ls；提供精确的引用/定义/悬停/调用层级，并在必要时平稳回退） ✅
5. 本地嵌入语义搜索（semantic_search、BM25+向量倒数排名融合、按需下载模型、增量重新嵌入） ✅
6. 游戏引擎适配器：GDScript 语法（随附的 wasm 构建）、Godot 场景/自动加载、Unity 预制件/GUID、Unreal 模块图 + 反射搜索、连接 Godot 编辑器 LSP（TCP 6005，已针对真实编辑器进行夜间测试） ✅
7. 文档、CI 中的基准测试（冷索引 157k LOC ≈ 5 s，热查询 p95 < 10 ms）、跨平台 CI、npm pack 冒烟测试 ✅ — npm 发布 + MCP 注册表提交待处理
8. 竞争力提升：change_impact（影响范围 + 受影响的测试，支持 git-diff 模式）、Web 框架路由索引（list_routes/find_route）、新增 13 种语言，包括 Vue/Svelte SFC ✅
9. Agent 工作流版本（0.4.0）：context_pack（按 token 预算生成的一次调用简报）、verify_changes（根据 git HEAD 进行编辑后检查）、tests_for_symbol、find_similar_code、find_dead_code + hotspots、batch_symbols、所有列表类工具均支持 max_tokens、基于文件的路由（Next.js/SvelteKit/Nuxt/Remix）、PHP PSR-4 / C# 命名空间 / Swift SPM 导入解析、可选的 LSP 边提升、sqlite-vec vec0 KNN ✅
10. 代码库导览版本（0.5.0）：repo_map（带注释的架构图、重要性排名、入口点、依赖清单）、可恢复的游标 + 重新校准的 token 估算器、深度折叠的大纲和目录大纲、基于持久化提交缓存的 change_coupling + symbol_history、支持百万符号代码库的流式解析 ✅
11. Token 诚实度和文本版本（0.6.0）：不再低估高熵输出的估算器（base64 的计费仅为实际成本的四分之一，因此可能超出 max_tokens）、每个答案只注明一次来源信息，而非每一行都注明、基于无内容 FTS 索引并通过磁盘验证的 search_content、首次将非代码文件（md/json/yaml/Dockerfile/CI）纳入索引 ✅

性能（vuejs/core，157k LOC，536 个文件，含 .vue SFC）：冷索引 3.8 s，完整 MCP 往返中的热工具调用 p95 ≤ 6 ms。scripts/bench.mjs 会在 CI 中运行。

规模（Unreal Engine Engine/Source/Runtime，19,097 个文件、6.3M LOC、622k 个符号、502k 条边）： 冷索引需 413 s，热结构查询 p95 ≤ 18 ms，而 repo_map 可在 p95 126 ms 内、以 2,500-token 预算返回完整架构。对全部 19k 个文件进行文本搜索需 p50 69 ms，内容索引仅占 45.6 MB — 数据库的 4%，因为它不存储文件文本：索引只提供候选项，再由磁盘进行验证。

开发

npm install        # also copies grammar wasm files into grammars/
npm test           # vitest: extractor golden tests, store, scanner, MCP end-to-end
npm run lint
npm run dev serve  # run from source via tsx

位置约定：行号从 1 开始，列号从 0 开始，路径相对于根目录且使用正斜杠。 有关如何添加语言、服务和语法，请参阅 CONTRIBUTING.md。

许可证

MIT