🏗️ CodeGraphContext (CGC)

June 1, 2026 · View on GitHub

将代码仓库转换为 AI 智能体可查询的图图谱。

🌐 语言 (Languages):

🇬🇧 English
🇨🇳 中文
🇰🇷 한국어
🇺🇦 Українська
🇷🇺 Русский
🇯🇵 日本語
🇪🇸 Español (即将推出)

🌍 帮助我们将 CodeGraphContext 翻译成您的语言！

连接深层代码图与 AI 上下文。

这是一个强大的 MCP 服务端 和 CLI 工具包，它将本地代码索引到图数据库中，为 AI 助手和开发者提供上下文信息。你可以将其作为独立的 CLI 进行全面的代码分析，或者通过 MCP 将其连接到你最喜欢的 AI IDE，实现 AI 驱动的代码理解。

✨ 体验 CGC

👨🏻‍💻 安装与 CLI

使用 pip 在几秒钟内完成安装，解锁强大的代码图分析 CLI。

🛠️ 秒级索引

CLI 智能解析 tree-sitter 节点以构建代码图。

🤖 赋能你的 AI 助手

使用自然语言通过 MCP 查询复杂的调用链。

项目详情

版本: 0.4.13
作者: Shashank Shekhar Singh shashankshekharsingh1205@gmail.com
许可证: MIT License (详见 LICENSE)
网站: CodeGraphContext

👨‍💻 维护者

CodeGraphContext 由以下人员创建并积极维护：

Shashank Shekhar Singh

📧 邮箱: shashankshekharsingh1205@gmail.com
🐙 GitHub: @Shashankss1205
🔗 LinkedIn: Shashank Shekhar Singh
🌐 网站: codegraphcontext.vercel.app

非常欢迎贡献和反馈！如有任何疑问、建议或合作机会，请随时联系。

Star 历史

功能特性

代码索引: 分析代码并构建其组件的知识图谱。
关系分析: 查询调用者、被调用者、类层次结构、调用链等。
预索引包: 使用 .cgc 包即时加载知名仓库 - 无需索引！(了解更多)
实时文件监控: 监控目录更改并实时自动更新代码图 (cgc watch)。
交互式设置: 用户友好的命令行向导，轻松完成设置。
双重模式: 既可以作为开发者的独立 CLI 工具包，也可以作为 AI 智能体的 MCP 服务端。
多语言支持: 全面支持 14 种编程语言。
灵活的数据库后端: KùzuDB（默认，所有平台零配置）、FalkorDB Lite（仅限 Unix）、FalkorDB Remote 或 Neo4j（通过 Docker/原生支持所有平台）。

支持的编程语言

CodeGraphContext 为以下语言提供全面的解析和分析：

	语言		语言		语言
🐍	Python	📜	JavaScript	🔷	TypeScript
☕	Java	🏗️	C / C++	#️⃣	C#
🐹	Go	🦀	Rust	💎	Ruby
🐘	PHP	🍎	Swift	🎨	Kotlin
🎯	Dart	🐪	Perl

每个语言解析器都会提取函数、类、方法、参数、继承关系、函数调用和导入，以构建全面的代码图。

数据库选项

CodeGraphContext 支持多种图数据库后端以适应你的环境：

特性	KùzuDB (默认)	FalkorDB Lite	Neo4j
设置	零配置 / 嵌入式	零配置 / 进程内	Docker / 外部
平台	所有 (Windows 原生, macOS, Linux)	仅限 Unix (Linux/macOS/WSL)	所有平台
用例	桌面、IDE、本地开发	专门的 Unix 开发	企业、大规模图调研
要求	`pip install kuzu`	`pip install falkordblite`	Neo4j 服务端 / Docker
速度	⚡ 极快	⚡ 快速	🚀 可扩展
持久化	是 (保存至磁盘)	是 (保存至磁盘)	是 (保存至磁盘)

谁在用

CodeGraphContext 已经吸引了开发者和项目在以下方面的探索：

AI 助手中的静态代码分析
项目的图化可视化
死代码和复杂度检测

如果你正在项目中使用 CodeGraphContext，欢迎提交 PR 并添加到这里！ 🚀

依赖

neo4j>=5.15.0
watchdog>=3.0.0
stdlibs>=2023.11.18
typer>=0.9.0
rich>=13.7.0
inquirerpy>=0.3.7
python-dotenv>=1.0.0
tree-sitter>=0.21.0（Python 3.13 不安装）
tree-sitter-language-pack>=0.6.0（Python 3.13 不安装）
pyyaml
pytest
nbformat
nbconvert>=7.16.6
pathspec>=0.12.1

注意: 支持 Python 3.10-3.14。

快速入门

安装核心工具包

pip install codegraphcontext

如果找不到 'cgc' 命令，请运行我们的一键修复：

curl -sSL https://raw.githubusercontent.com/CodeGraphContext/CodeGraphContext/main/scripts/post_install_fix.sh | bash

入门指南

📋 了解 CodeGraphContext 模式

CodeGraphContext 以 两种模式 运行，你可以使用其中一种或同时使用：

🛠️ 模式 1：CLI 工具包 (独立使用)

将 CodeGraphContext 作为强大的命令行工具包进行代码分析：

直接从终端索引和分析代码库
查询代码关系，查找死代码，分析复杂度
可视化代码图和依赖关系
非常适合希望通过 CLI 命令直接控制的开发者

🤖 模式 2：MCP 服务端 (AI 驱动)

将 CodeGraphContext 作为 AI 助手的 MCP 服务端 使用：

连接到 AI IDE（VS Code, Cursor, Windsurf, Claude, Kiro 等）
让 AI 智能体使用自然语言查询你的代码库
自动进行代码理解和关系分析
非常适合 AI 辅助开发工作流

你可以同时使用这两种模式！ 安装一次后，既可以直接使用 CLI 命令，也可以连接到你的 AI 助手。

安装 (两种模式通用)

安装: pip install codegraphcontext

⚙️ 故障排除: 如果找不到 cgc 命令

如果在安装后遇到 "cgc: command not found"，请运行 PATH 修复脚本：

Linux/Mac:

# 下载修复脚本
curl -O https://raw.githubusercontent.com/CodeGraphContext/CodeGraphContext/main/scripts/post_install_fix.sh

# 添加可执行权限
chmod +x post_install_fix.sh

# 运行脚本
./post_install_fix.sh

# 重启终端或重新加载 shell 配置
source ~/.bashrc  # 或对于 zsh 用户 source ~/.zshrc

Windows (PowerShell):

# 下载修复脚本
curl -O https://raw.githubusercontent.com/CodeGraphContext/CodeGraphContext/main/scripts/post_install_fix.sh

# 使用 bash 运行 (需要 Git Bash 或 WSL)
bash post_install_fix.sh

# 重启 PowerShell 或重新加载配置文件
. $PROFILE

数据库设置 (自动)
- KùzuDB (默认): 在 Windows、macOS 和 Linux 上原生运行，无需任何设置。只需 pip install kuzu 即可！
- FalkorDB Lite (替代方案): 支持 Unix/macOS/WSL 上的 Python 3.12+。
- Neo4j (替代方案): 如果你想使用 Neo4j，或者倾向于基于服务端的方案，请运行：cgc neo4j setup

CLI 工具包模式

立即开始使用 CLI 命令：

# 索引当前目录
cgc index .

# 列出所有已索引的仓库
cgc list

# 分析谁调用了某个函数
cgc analyze callers my_function

# 查找复杂代码
cgc analyze complexity --threshold 10

# 查找死代码
cgc analyze dead-code

# 监控实时更改 (可选)
cgc watch .

# 查看所有命令
cgc help

查看完整的 CLI 命令指南以获取所有可用命令和使用场景。

🎨 高级交互式可视化

CodeGraphContext 可以为你的代码生成精美的交互式知识图谱。不同于静态图表，这些是高级的基于 Web 的浏览器：

精美美学: 暗黑模式、毛玻璃效果和现代字体 (Outfit/JetBrains Mono)。
交互式检查: 点击任何节点即可打开包含符号信息、文件路径和上下文的详细侧边栏。
快速搜索: 通过实时搜索即时查找图中的特定符号。
智能布局: 力导向和分层布局，使复杂的关系清晰易读。
零依赖查看: 独立的 HTML 文件，可在任何现代浏览器中运行。

# 可视化函数调用
cgc analyze calls my_function --viz

# 探索类层次结构
cgc analyze tree MyClass --viz

# 可视化搜索结果
cgc find pattern "Auth" --viz

🤖 MCP 服务端模式

配置你的 AI 助手使用 CodeGraphContext：

设置: 运行 MCP 设置向导来配置你的 IDE/AI 助手：
```
cgc mcp setup
```
该向导可以自动检测并配置：
- VS Code
- Cursor
- Windsurf
- Claude
- Gemini CLI
- ChatGPT Codex
- Cline
- RooCode
- Amazon Q Developer
- Kiro
配置成功后，cgc mcp setup 将生成并放置必要的配置文件：
- 在当前目录创建一个 mcp.json 文件供参考。
- 将你的数据库凭据安全地存储在 ~/.codegraphcontext/.env。
- 更新你选择的 IDE/CLI 的设置文件（例如 .claude.json 或 VS Code 的 settings.json）。
启动: 启动 MCP 服务端：
```
cgc mcp start
```
使用: 现在可以通过自然语言与你的 AI 助手交互来探索代码库了！请参阅下面的示例。

忽略文件 (`.cgcignore`)

你可以通过在项目根目录创建一个 .cgcignore 文件来告知 CodeGraphContext 忽略特定的文件和目录。该文件使用与 .gitignore 相同的语法。

.cgcignore 文件示例：

# 忽略构建产物
/build/
/dist/

# 忽略依赖
/node_modules/
/vendor/

# 忽略日志
*.log

MCP 客户端配置

cgc mcp setup 命令尝试自动配置你的 IDE/CLI。如果你选择不使用自动设置，或者你的工具不受支持，你可以进行手动配置。

将以下服务端配置添加到客户端的设置文件中（例如 VS Code 的 settings.json 或 .claude.json）：

{
  "mcpServers": {
    "CodeGraphContext": {
      "command": "cgc",
      "args": [
        "mcp",
        "start"
      ],
      "env": {
        "NEO4J_URI": "你的_NEO4J_URI",
        "NEO4J_USERNAME": "你的_NEO4J_用户名",
        "NEO4J_PASSWORD": "你的_NEO4J_密码"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

自然语言交互示例

服务端运行后，你可以使用普通的英语（或中文，取决于 AI 助手）与其交互。以下是一些交互示例：

索引和监控文件

索引新项目:
- "请索引 /path/to/my-project 目录中的代码。" 或
- "将位于 ~/dev/my-other-project 的项目添加到代码图中。"
开始监控目录的实时更改:
- "监控 /path/to/my-active-project 目录的更改。" 或
- "为我在 ~/dev/main-app 处理的项目保持代码图更新。"
当你要求监控一个目录时，系统会同时执行两个操作：
1. 启动全量扫描以索引该目录中的所有代码。此过程在后台运行，你会收到一个 job_id 来追踪进度。
2. 开始监控目录中的任何文件更改，以实时保持代码图更新。
这意味着你可以直接告诉系统监控一个目录，它会自动处理初始索引和持续更新。

查询和理解代码

查找代码定义位置:
- "process_payment 函数在哪里定义的？"
- "帮我找一下 User 类。"
- "显示任何与 'database connection' 相关的代码。"
分析关系和影响:
- "还有哪些函数调用了 get_user_by_id 函数？"
- "如果我修改了 calculate_tax 函数，代码的其他哪些部分会受到影响？"
- "显示 BaseController 类的继承层次结构。"
- "Order 类有哪些方法？"
探索依赖关系:
- "哪些文件导入了 requests 库？"
- "查找 render 方法的所有实现。"
高级调用链和依赖追踪（跨越数百个文件）: CodeGraphContext 擅长追踪庞大代码库中复杂的执行流和依赖关系。利用图数据库的力量，它可以识别直接和间接的调用者与被调用者，即使函数是通过多层抽象或跨越多层文件调用的。这对于以下方面非常有价值：
- 影响分析: 了解修改核心函数带来的完整涟漪效应。
- 调试: 追踪从入口点到特定 bug 的执行路径。
- 代码理解: 掌握大型系统中不同部分的交互方式。
- "显示从 main 函数到 process_data 的完整调用链。"
- "查找所有直接或间接调用 validate_input 的函数。"
- "列出 initialize_system 最终会调用的所有函数。"
- "追踪 DatabaseManager 模块的依赖关系。"
代码质量与维护:
- "这个项目中是否有任何死代码或未使用的代码？"
- "计算 src/utils.py 中 process_data 函数的圈复杂度。"
- "查找代码库中最复杂的 5 个函数。"
仓库管理:
- "列出所有当前已索引的仓库。"
- "删除位于 /path/to/old-project 的已索引仓库。"

贡献

欢迎贡献！ 🎉
请参阅我们的 CONTRIBUTING.md 以获取详细准则。如果你有新功能、集成或改进的想法，请开启 issue 或提交 Pull Request。

加入讨论，共同塑造 CodeGraphContext 的未来。