🏗️ CodeGraphContext (CGC)

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

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

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

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

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

---

📍 快速导航

• 🚀 快速入门
• 🌐 支持的编程语言
• 🛠️ CLI 工具包模式
• 🤖 MCP 服务端模式
• 🗄️ 数据库选项

---

✨ 体验 CGC

👨🏻‍💻 安装与 CLI

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

🛠️ 秒级索引

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

🤖 赋能你的 AI 助手

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

---

项目详情

• 版本: 0.4.7
• 作者: 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 real_ladybug	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 助手。

安装 (两种模式通用)

1. 安装: pip install codegraphcontext

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

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

**Linux/Mac:**
```bash
# 下载修复脚本
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):**
```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
```

1. 数据库设置 (自动)

   • KùzuDB (默认): 在 Windows、macOS 和 Linux 上原生运行，无需任何设置。只需 pip install real_ladybug 即可！
   • 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： 1. 设置: 运行 MCP 设置向导来配置你的 IDE/AI 助手：

```bash
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`）。

1. 启动: 启动 MCP 服务端：
   bash cgc mcp start

2. 使用: 现在可以通过自然语言与你的 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 的未来。