Code Atlas (Aryan Saini26)

代码图集

    

一个开源MCP服务器，构建任何存储库的实时代码知识图，并将其暴露给人工智能编码代理，如Claude code和Cursor，以及同一图上的CLI、HTTP API和React web UI。

问题

人工智能编码代理在做实际工作之前，浪费了60-80%的上下文窗口在代码库中定位自己。CodeAtlas为他们提供了预先构建的结构和语义知识，这样他们就可以从第一个标记开始智能导航。

为什么选择CodeAtlas

• 持久SQLite+FTS5图 --缩放超过1M符号，增量更新；不是公寓 graph.json 每次运行都重新序列化。
• 基于真正嵌入的语义搜索 --FAISS+句子转换，而不仅仅是关键字匹配。混合模式通过互易秩融合来混合FTS5+矢量。
• PageRank中心性 --呼叫者加权重要性，而不是基于程度的“上帝节点”启发式方法。加上标签传播社区、git流失热点和覆盖缺口。
• 29个MCP工具，27个CLI子命令，6种导出格式 --该类别中最宽的试剂和终端表面。
• 完整的React web用户界面 --交互式力图、搜索、符号详细信息、分析选项卡——所有这些都由FastAPI层支持。只需一个命令即可启动： codeatlas ui.
• 26种语言通过树保姆 --Python、Types/TSX、Go、Rust、Java、C、C++、C#、Ruby、JavaScript、Kotlin、PHP、Scala、Bash、Lua、Elixir、Swift、Haskell、SQL、Zig、OCaml、Julia、PowerShell、Svelte。

特性

• 多语言解析 --26种语言的树型AST解析（如上所列）。
• 知识图谱 --SQLite+FTS5，具有递归CTE图遍历（零基础设施）。
• 语义搜索 --使用句子变换器进行自然语言代码查询的FAISS向量搜索。
• 混合搜索 --将关键字（FTS5）和向量（FAISS）结果进行交互排名融合。
• 图分析 --PageRank、社区检测、循环检测、死代码、热点、覆盖缺口、最短路径、文件耦合。
• 交互式可视化 --React+反应力图web UI，以及独立的D3.js HTML导出。
• HTTP/JSON API --FastAPI层位于图形之上，用于定制前端和工具。
• 实时同步 --监视器文件监视器和GitHub webhook处理程序，用于增量更新。
• 变更影响分析 --Git感知差异分析，显示哪些符号和文件受到影响。
• MCP服务器 --通过模型上下文协议公开了29个用于AI代理消费的工具。
• 图形导出 --DOT（Graphviz）、JSON（D3.js）、Mermaid、GraphML、CSV和Cypher格式。
• 配置文件 --可选 codeatlas.toml 用于每个repo设置。

快速开始

pip install codeatlas

# Initialize a config file (optional)
codeatlas init

# Index a repository
codeatlas index /path/to/repo

# View graph statistics
codeatlas stats

# Search by keyword
codeatlas query "authentication"

# Search by natural language (requires sentence-transformers)
codeatlas query "where do we handle login errors" --semantic

# Inspect a specific symbol
codeatlas show UserService

# Run code quality audit (cycles, dead code, complexity)
codeatlas audit

# Visualize the graph in your browser
codeatlas viz --open

# Watch for file changes
codeatlas watch /path/to/repo

# Export the graph
codeatlas export --format dot -o graph.dot
codeatlas export --format json -o graph.json
codeatlas export --format mermaid -o diagram.md

# Launch the web UI (API + React frontend, one command)
codeatlas ui

Web用户界面

CodeAtlas附带了基于Vite、Tailwind和反作用力图构建的React+TypeScript前端。它与同一图形存储上的FastAPI层进行通信，因此CLI、MCP服务器和web UI都看到了相同的数据。

# Build the frontend once
cd frontend && npm install && npm run build && cd ..

# Serve API + UI on localhost:8080
codeatlas ui

# Or run them separately during development
codeatlas server --port 8080              # API only
cd frontend && npm run dev                # Vite dev server with /api proxy

UI表面：

• 仪表盘 --按PageRank、文件热点、语言和符号细分、统计数据列出的顶级符号
• 搜索 --全文+语义搜索，结果详细信息窗格显示签名、文档字符串、传入/传出引用
• 分析 --标签式界面，具有PageRank排名、热点识别、社区检测、覆盖差距分析
• 图 --具有种类/社区着色、图例和文件过滤的交互式力量导向可视化
• 符号 --详细的符号页面，包括签名、文件、文件位置、进出参考卡
• 差异 --比较两个git引用之间的符号（添加/删除/修改的列）
• 设置 -配置API凭据，触发增量/完整重新索引，查看版本信息

安装

# Core (parsing + graph + CLI)
pip install codeatlas

# With MCP server
pip install codeatlas[mcp]

# With semantic search
pip install codeatlas[search]

# Everything
pip install codeatlas[all]

支持的语言

配置

CodeAtlas可以配置为 codeatlas.toml 存储库根目录中的文件。生成一个：

codeatlas init

示例 codeatlas.toml:

[codeatlas]
exclude_dirs = [".git", ".venv", "node_modules", "__pycache__", "dist", "build"]

[codeatlas.parser]
max_file_size_kb = 500
include_extensions = [".py", ".ts", ".tsx", ".js", ".mjs", ".go", ".rs", ".java", ".kt", ".kts", ".cpp", ".cc", ".cxx", ".hpp", ".hxx", ".h", ".cs", ".rb", ".php", ".scala", ".sc", ".sh", ".bash", ".lua", ".ex", ".exs", ".swift", ".hs", ".lhs", ".sql", ".c", ".zig", ".ml", ".mli"]

[codeatlas.graph]
db_path = ".codeatlas/graph.db"

如果找不到配置文件，则使用合理的默认值。

忽略包含以下内容的文件 .gitignore / .codeatlas-ignore

CodeAtlas自动尊重回购 .gitignore （如果存在）。添加a .codeatlas-ignore 当你需要额外的规则或否定时，在repo根目录中 gitignore条目；其模式在gitignore规则和 可以覆盖它们。

地点a .codeatlas-ignore 存储库根目录中的文件以排除特定 从索引中删除文件或目录。语法镜像 .gitignore:

# Skip generated artifacts
dist/
build/
*.log

# Skip a specific file (but re-include one via negation)
src/generated/
!src/generated/manifest.ts

支持：评论(#)、空白线条、球形图案(*, **, ?), 仅目录模式(foo/)，和否定(!pattern).

关系信心

图中的每条边都标记了置信度，以便代理可以分辨 AST证明了除启发式猜测之外的事实：

codeatlas report 表面计数；原始统计数据也可通过以下方式获得 GraphStore.get_confidence_stats()导出的JSON边带有相同的标签： codeatlas export --format json 发射 {"source", "target", "kind", "confidence"}, 交互式可视化绘制了推断出的虚边和模糊边 点状排列，因此启发式猜测一目了然。

社区观点

通过 --communities 到 codeatlas export 或 codeatlas viz 运行标签 在图上传播，并包括 community_id 在每个节点上。在 交互式可视化，节点由社区和工具栏切换绘制 在社区着色和善良着色之间切换。

CLI命令

MCP服务器

启动MCP服务器，以便与Claude Code、Cursor或任何与MCP兼容的代理一起使用：

codeatlas serve

Claude代码配置

添加到您的Claude Code MCP设置中：

{
  "mcpServers": {
    "codeatlas": {
      "command": "codeatlas",
      "args": ["serve"]
    }
  }
}

可用的MCP工具（29）

图形可视化

生成代码库的交互式力导向图：

# Generate and open in browser
codeatlas viz --open

# Save to a specific file
codeatlas viz -o my-graph.html

# Filter to specific directory
codeatlas viz --file-filter src/core/

可视化功能：

• 使用D3.js进行强制布局
• 按符号类型（类、函数、接口等）对节点进行颜色编码
• 悬停以突出显示符号的直接连接
• 按名称筛选符号的搜索栏
• 用鼠标缩放和平移
• 拖动节点以重新排列

GitHub 网络钩子

对于推送时的自动图形更新：

codeatlas webhook /path/to/repo --port 9000 --secret YOUR_WEBHOOK_SECRET

然后将您的GitHub repo webhook配置为POST到 http://your-server:9000/webhook.

建筑

Source Files --> Tree-sitter AST --> Symbols + Relationships --> SQLite Graph
                                                                    |
                                                 +--------+---------+--------+
                                                 |        |         |        |
                                              FTS5     FAISS     Graph    D3.js
                                             Search   Vectors   Analysis   Viz
                                                 |        |         |        |
                                                 +--------+---------+--------+
                                                              |
                                                   CLI + MCP Server --> AI Agents

设计决策：

• SQLite over Neo4j：零基础设施，Python附带，FTS5用于关键字搜索，递归CTE用于图遍历
• pgvector上的FAISS：在没有数据库服务器的情况下本地运行
• 正则表达式上的树保姆：增量解析，处理所有边缘情况，跨语言一致性

发展

# Clone and set up
git clone https://github.com/AryanSaini26/CodeAtlas.git
cd CodeAtlas
python3.12 -m venv .venv
.venv/bin/pip install -e ".[all,dev]"

# Run tests with coverage (1038 tests, 92.2%)
.venv/bin/pytest -v --cov=codeatlas --cov-report=term-missing

# Lint / format
.venv/bin/ruff check src tests
.venv/bin/ruff format src tests

# Benchmarks (clones requests + click, runs timing/memory/token-savings)
python benchmarks/bench.py

释放

发布是通过GitHub Actions完全自动化的。要剪切新版本，请执行以下操作：

# Bump version, tag, and push — CI will build and publish to PyPI
make release VERSION=0.2.0

要求：

1. 在PyPI.org上为此回购配置了PyPI可信发布（不需要API令牌）
2. GITHUB_TOKEN 是自动的，不需要额外的秘密

许可证

麻省理工学院