CodeGraphContext

🏗️ CodeGraphContext（CGC）

将代码仓库转化为可供 AI Agent 查询的图。

🌐 语言：

• 🇬🇧 English
• 🇨🇳 中文
• 🇰🇷 한국어
• 🇺🇦 Українська
• 🇷🇺 Русский
• 🇯🇵 日本語
• 🇮🇳 தமிழ்
• 🇪🇸 Español（即将推出）

🌍 欢迎通过在 GitHub Issues 提交 issue 和 PR，帮助将 CodeGraphContext 翻译成您的语言！

弥合深层代码图与 AI 上下文之间的鸿沟。

这是一款功能强大的 MCP 服务和 命令行工具套件，可将本地代码编入图数据库，为 AI 助手和开发者提供上下文。您可以将它作为独立命令行工具，用于全面的代码分析；也可以通过 MCP 将它连接到您喜爱的 AI IDE，借助 AI 理解代码。

---

📍 快速导航

• 🚀 快速开始
• 📋 前置条件
• 🏃 如何在本地运行项目
• 🌐 支持的编程语言
• 🛠️ CLI 工具包
• 🤖 MCP 服务
• 🗄️ 数据库选项
• 🔬 SCIP 索引（可选）

---

✨ 体验 CGC

👨🏻‍💻 安装和 CLI

通过 pip 几秒内完成安装，解锁强大的代码图分析 CLI。

🛠️ 几秒内完成索引

CLI 会智能解析 tree-sitter 节点来构建图。

🤖 为 AI 助手赋能

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

---

为什么选择 CodeGraphContext？

CodeGraphContext 专为纯文本搜索不再够用的场景打造。它会将代码仓库转换为由文件、符号、调用、继承、导入和关系构成的图，让你无需在不同工具间来回切换，就能从“这里定义在哪里？”深入了解“这些代码实际上是如何关联的”。

flowchart LR
  A[Source code] --> B[Tree-sitter and SCIP indexers]
  B --> C[Graph database]
  C --> D[CLI queries]
  C --> E[MCP server]
  D --> F[Direct analysis]
  E --> G[AI assistants with repo context]

一目了然的对比

方式	最适合	权衡
grep / 文件搜索	精确字符串查找	无法发现关系和代码结构
对代码块使用 RAG	自然语言检索	可能会丢失符号级精度
CodeGraphContext	仓库级推理	需要执行索引步骤

常见使用场景

• 跨文件和包追踪调用链。
• 理解类层次结构、导入和模块边界。
• 查找无用代码、热点和意外依赖。
• 为 AI 助手提供维护者会使用的同等结构化上下文。

常见问题

• 我需要远程服务吗？ 不需要。CGC 可通过嵌入式后端在本地运行，也可按需使用外部图数据库。
• 它只支持一种语言吗？ 不。它支持多种主流语言，并且还在持续扩展。
• 我可以将它与 AI 助手搭配使用吗？ 可以。这是创建 MCP 服务的主要原因之一。

---

项目详情

• 版本： 0.5.1
• 作者： Shashank Shekhar Singh [email protected]
• 许可证： MIT License（详情请参阅 LICENSE）
• 网站： CodeGraphContext

---

👨‍💻 维护者

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

Shashank Shekhar Singh

• 📧 邮箱：[email protected]
• 🐙 GitHub：@Shashankss1205
• 🔗 LinkedIn：Shashank Shekhar Singh
• 🌐 网站：codegraphcontext.vercel.app

欢迎随时贡献和反馈！如有问题、建议或合作机会，欢迎联系我们。

---

Star 历史

Star 历史图表 ↗

---

功能

• 代码索引： 分析代码并构建其组件的知识图谱。
• 关系分析： 查询调用者、被调用者、类层次结构、调用链等。
• 预索引包： 使用 .cgc 包即时加载知名代码库——无需索引！(了解详情)
• 实时文件监视： 监视目录中的更改，并自动实时更新图谱（cgc watch）。
• 交互式设置： 用户友好的命令行向导，让设置更加简单。
• 双模式： 既可作为面向开发者的独立 CLI 工具包，也可作为面向 AI Agent 的 MCP 服务。
• 多语言支持： 全面支持 23 种编程语言。
• 灵活的数据库后端： FalkorDB Lite（默认）、KuzuDB、LadybugDB、FalkorDB Remote、Nornic DB 或 Neo4j（所有平台均可通过 Docker／原生方式使用）。

---

🏗️ 架构与工作流

CodeGraphContext 会解析源代码并构建全面的知识图谱。你可以通过 CLI 工具包直接查询此图谱，也可以通过 MCP 服务将其提供给 AI 助手。

flowchart TD
    A[Code Repository] -->|Parsed by| B[Tree-sitter / SCIP Indexing]
    B -->|Generates| C[Knowledge Graph]
    C -->|Stored in| D[(Graph Database)]
    D -->|Queried via| E[CLI Toolkit]
    D -->|Served by| F[MCP Server]
    F -->|Provides context to| G[🤖 AI Assistant]

    classDef default fill:#1f2937,stroke:#8b5cf6,stroke-width:2px,color:#fff;
    classDef db fill:#0f172a,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef ai fill:#312e81,stroke:#a855f7,stroke-width:2px,color:#fff;
    
    D:::db
    G:::ai

---

支持的编程语言

CodeGraphContext 可全面解析和分析以下语言：

	语言		语言		语言
🐍	Python	📜	JavaScript	🔷	TypeScript
☕	Java	🔵	C	➕	C++
#️⃣	C#	🐹	Go	🦀	Rust
💎	Ruby	🐘	PHP	🍎	Swift
🎨	Kotlin	🎯	Dart	🐪	Perl
🌙	Lua	🚀	Scala	λ	Haskell
💧	Elixir	📜	Emacs Lisp (elisp)	🌐	HTML
🎨	CSS	⚛️	TSX	⛓️	Solidity
🏗️	HCL (Terraform/Terragrunt)

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

HCL 说明： .tf、.tfvars 和 .hcl 文件涵盖 Terraform、OpenTofu 和 Terragrunt。HCL 用于声明而非调用，因此会贡献代码块、变量和跨配置导入，但不会产生函数调用。参见 docs/docs/contributing_languages.md § HCL。

Solidity 说明： .sol 文件通过 tree-sitter-language-pack 使用 Tree-sitter（不使用 SCIP）。支持 Foundry 重映射、修饰符调用、using Lib for T，以及作为 CALLS 的 emit／自定义错误 revert。参见 docs/docs/contributing_languages.md § Solidity。

Kotlin 说明： 函数和类上的注解会记录为 decorators，并保留其参数（@Preview(showBackground = true)）。因此，find_dead_code 的 exclude_decorated_with 可用于 Kotlin 和 Android 代码库，例如排除 Composable、Preview、Test 和 Provides。该筛选器匹配函数，因此类级别的注解不会影响它。目前尚未记录接口、对象、构造函数、参数和属性上的注解。

---

数据库选项

CodeGraphContext 支持多个图数据库后端，以适应不同的环境：

功能	KuzuDB	LadybugDB	FalkorDB Lite	Neo4j / Nornic DB
典型默认选项	FalkorDB Lite 不可用时的跨平台备用方案	可选的嵌入式后端	Unix 上的默认选项（Python 3.12+，已安装 falkordblite 时）	通过 cgc config db 显式配置时使用
设置方式	零配置 / 嵌入式	零配置 / 嵌入式	零配置 / 进程内	Docker / 外部
平台	全部平台（Windows Native、macOS、Linux）	全部平台（Windows Native、macOS、Linux）	仅限 Unix（Linux/macOS/WSL）	所有平台
使用场景	桌面应用、IDE、本地开发	自定义研究项目	专用 Unix 开发	企业级、大型图
要求	pip install kuzu	pip install ladybug	pip install falkordblite	Neo4j Server / Docker / Nornic Cloud
速度	⚡ 极快	⚡ 快	🚀 可扩展	🌐 取决于网络
持久化	是（写入磁盘）	是（写入磁盘）	是（写入磁盘）	是（服务端）

嵌入式 KuzuDB/LadybugDB 默认使用 4 GiB 缓冲池（CGC_EMBEDDED_BUFFER_POOL_MB）。将该环境变量设为其他 MiB 值，或设为 0 以使用库的默认值（约占系统 RAM 的 80%）。

---

SCIP 索引（可选）

当 CGC 配置（~/.codegraphcontext/.env）中的 SCIP_INDEXER=true 时，某些语言会使用外部 SCIP 索引器，以获得比单独使用 Tree-sitter 启发式分析更准确的调用关系和继承关系。

C 和 C++ 使用 scip-clang，这需要 compile_commands.json 文件（JSON 编译数据库）：每个翻译单元对应一条记录，其中包含实际的编译器命令（包含路径、-D 定义、-std 等）。没有该文件，scip-clang 就无法运行；CGC 会记录警告，并为该仓库回退到 Tree-sitter。生成该文件的常见方式：使用 CMake 并添加 -DCMAKE_EXPORT_COMPILE_COMMANDS=ON，或使用 Bear 包装实际构建命令（例如 bear -- make）。CGC 也会在 build/ 和 cmake-build-*/ 下查找该文件。

C# 使用 scip-dotnet（Roslyn）；你需要常规的 .csproj / .sln 文件，并且还原操作必须成功——无需 compile_commands.json。

SCIP 独立于所用的图数据库（Kuzu、Neo4j 等）；同一标志适用于所有后端。

---

使用者

开发者和项目已开始探索在以下场景中使用 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.4
• python-dotenv>=1.0.0
• tree-sitter>=0.24.0,<0.26.0
• tree-sitter-language-pack>=1.6,<2.0
• pyyaml
• pathspec>=0.12.1
• falkordb>=1.0,<1.6
• falkordblite>=0.7,<0.10（仅限 Unix，Python 3.12+）
• kuzu（KuzuDB 引擎）
• fastapi>=0.100.0
• uvicorn>=0.22.0
• requests>=2.28.0
• protobuf>=3.20,<3.21

**注意：**支持 Python 3.10-3.14。

---

🚀 安装与快速入门

1. 安装工具包：

   pip install codegraphcontext
   

2. 故障排除（找不到命令）： 如果找不到 codegraphcontext 命令，请运行以下单行修复命令：

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

3. 数据库设置（自动）： CodeGraphContext 默认使用嵌入式图数据库。

   • **FalkorDB Lite：**默认后端。
   • **KuzuDB：**跨平台嵌入式后端。
   • **Neo4j：**运行 codegraphcontext neo4j setup 以使用外部服务。

🧪 本地开发设置

如果你想从本地克隆的仓库运行 CodeGraphContext 并贡献更改，请使用可编辑安装：

git clone https://github.com/CodeGraphContext/CodeGraphContext.git
cd CodeGraphContext
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

然后验证安装并尝试本地命令：

cgc --help
cgc doctor
cgc index .
cgc analyze callers main

如果要开发 MCP 服务，请通过以下命令完成设置：

cgc mcp setup
cgc mcp start

如果你只想安装已发布的软件包，执行 pip install codegraphcontext 即可。如果你正在开发依赖解析功能的特性，并且也需要可选的解析扩展，请使用 pip install -e ".[dev,parsing]" 安装。

---

🐳 Docker（无需 Python）

无需安装 Python 即可运行 CodeGraphContext——拉取镜像并开始索引：

快速开始

# Pull the latest image
docker pull codegraphcontext/codegraphcontext:latest

# Index your current directory
docker run --rm -v "$(pwd):/workspace" codegraphcontext/codegraphcontext cgc index .

# List indexed repos
docker run --rm -v cgc-data:/home/cgc/.codegraphcontext \
    codegraphcontext/codegraphcontext cgc list

# Interactive shell
docker run -it --rm -v "$(pwd):/workspace" \
    -v cgc-data:/home/cgc/.codegraphcontext \
    codegraphcontext/codegraphcontext bash

Docker Compose

# Clone the repo and start with Docker Compose
git clone https://github.com/CodeGraphContext/CodeGraphContext.git
cd CodeGraphContext

# Start with embedded DB
docker compose run --rm cgc index .

# Start with external FalkorDB
docker compose --profile falkordb up -d

# Start with visualization server
docker compose --profile viz up -d
# Open http://localhost:8080

可用的 Docker 标签

标签	描述
latest	最新稳定版本
edge	main 分支的最新版本（可能不稳定）
0.4.19	指定版本
0.4	0.4.x 中最新的补丁版本

如需了解更高级的 Docker 用法，包括运行 MCP Server 或连接外部数据库，请参阅我们的全面 Docker 指南。

---

📋 前提条件

安装 CodeGraphContext 前，请确保你已准备好：

• Python 3.10 或更高版本
• pip 包管理器
• Git（可选，用于克隆代码仓库）

验证 Python 安装：

python --version

---

🚀 分步设置指南

第 1 步：安装 CodeGraphContext

pip install codegraphcontext  # Installs CodeGraphContext and required dependencies

此命令会安装 CodeGraphContext 及其所有必需的依赖项。

第 2 步：验证安装

codegraphcontext --help

如果命令显示可用的 CLI 命令，则表示安装成功。

第 3 步：数据库设置

CodeGraphContext 默认会自动使用嵌入式数据库，因此大多数用户无需进行额外配置。

---

🏃 如何在本地运行项目

索引代码仓库

codegraphcontext index .  # Scans current directory and builds code graph

此操作会扫描当前项目并创建可搜索的代码图谱。

查看已索引的代码仓库

codegraphcontext list

显示 CodeGraphContext 当前已索引的所有代码仓库。

分析代码

codegraphcontext analyze dead-code

在已索引的代码仓库中查找可能未使用的代码。

---

✅ 验证一切正常

索引代码仓库后，运行：

codegraphcontext list  # Shows all indexed repositories in the system

如果命令成功执行并显示已索引的代码仓库，则表示设置已完成，CodeGraphContext 已可使用。

CLI 工具包模式

立即开始使用 CLI 命令：

# Index your current directory
codegraphcontext index .

# List all indexed repositories
codegraphcontext list

# Analyze who calls a function
codegraphcontext analyze callers my_function

# Find complex code
codegraphcontext analyze complexity --threshold 10

# Find dead code
codegraphcontext analyze dead-code

# Watch for live changes (optional)
codegraphcontext watch .

# See all commands
codegraphcontext help

如需查看所有可用命令和使用场景，请参阅完整的 CLI 命令指南。

🎨 高级交互式可视化

CodeGraphContext 可以为你的代码生成精美的交互式知识图谱。与静态图表不同，这些是高级 Web 可视化工具：

• 高级美学设计：深色模式、玻璃拟态和现代字体（Outfit/JetBrains Mono）。
• 交互式检查：点击任意节点，即可打开详细的侧边栏，其中包含符号信息、文件路径和上下文。
• 快速搜索：在图谱中实时搜索，立即查找特定符号。
• 智能布局：力导向和分层布局，让复杂关系一目了然。
• 无需依赖即可查看：独立 HTML 文件，可在任何现代浏览器中使用。

# Visualize function calls
codegraphcontext analyze calls my_function --viz

# Explore class hierarchies
codegraphcontext analyze tree MyClass --viz

# Visualize search results
codegraphcontext find pattern "Auth" --viz

---

🤖 MCP 服务模式

配置 AI 助手以使用 CodeGraphContext：

1. 设置： 运行 MCP 设置向导，配置 IDE/AI 助手：

   codegraphcontext mcp setup
   

   向导可以自动检测并配置：

   • VS Code
   • Cursor
   • Windsurf
   • Zed
   • Claude
   • Gemini CLI
   • ChatGPT Codex
   • Cline
   • RooCode
   • Amazon Q Developer
   • Kiro
   • Goose
   • OpenCode

   配置成功后，codegraphcontext mcp setup 将生成并放置所需的配置文件：

   • 在当前目录中创建 mcp.json 文件供参考。
   • 将数据库凭据安全地存储在 ~/.codegraphcontext/.env 中。
   • 更新所选 IDE/CLI 的设置文件（例如 .claude.json 或 VS Code 的 settings.json）。

2. 启动： 启动 MCP 服务：

   codegraphcontext mcp start
   

3. 使用： 现在可以通过 AI 助手使用自然语言与代码库交互了！请参阅下方示例。

---

忽略文件（.cgcignore）

你可以在项目根目录中创建 .cgcignore 文件，告知 CodeGraphContext 忽略特定文件和目录。此文件使用与 .gitignore 相同的语法。

.cgcignore 文件示例：

# Ignore build artifacts
/build/
/dist/

# Ignore dependencies
/node_modules/
/vendor/

# Ignore logs
*.log

---

MCP 客户端配置

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

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

{
  "mcpServers": {
    "CodeGraphContext": {
      "command": "codegraphcontext",
      "args": [
        "mcp",
        "start"
      ],
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

OpenCode 配置

有关如何通过 OpenCode 安装和配置 MCP 服务的说明，请参阅 OpenCode MCP 指南。

如果通过 pipx 安装

如果你使用 pipx 安装了 CodeGraphContext，请改用以下配置：

{
  "mcpServers": {
    "CodeGraphContext": {
      "command": "pipx",
      "args": [
        "run",
        "codegraphcontext",
        "mcp",
        "start"
      ],
      "env": {
        "NEO4J_URI": "YOUR_NEO4J_URI",
        "NEO4J_USERNAME": "YOUR_NEO4J_USERNAME",
        "NEO4J_PASSWORD": "YOUR_NEO4J_PASSWORD"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

---

Token 优化输出（GCF）

使用可选的 GCF 输出格式，可将工具响应的 Token 数量减少约 62%：

pip install gcf-python
CGC_OUTPUT_FORMAT=gcf codegraphcontext mcp start

或者将其添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "CodeGraphContext": {
      "command": "codegraphcontext",
      "args": ["mcp", "start"],
      "env": {
        "CGC_OUTPUT_FORMAT": "gcf"
      }
    }
  }
}

GCF 使用位置字段编码结构化数据（键只声明一次，值以竖线分隔）。代码图查询结果（符号、关系、调用方、复杂度）正是最能体现 GCF 优势的数据类型。所有前沿模型的 LLM 理解率均为 100%。如果未安装 gcf-python，则回退到 JSON。

---

自然语言交互示例

服务启动后，你可以使用日常英语通过 AI 助手与其交互。以下是一些你可以提出的请求示例：

索引和监视文件

• 索引新项目：

  • “请为 /path/to/my-project 目录中的代码建立索引。” 或
  • “将 ~/dev/my-other-project 中的项目添加到代码图中。”

• 开始监视目录的实时更改：

  • “监视 /path/to/my-active-project 目录中的更改。” 或
  • “持续更新我正在 ~/dev/main-app 中开发的项目的代码图。”

  当你要求监视目录时，系统会同时执行两项操作：

  1. 启动完整扫描，为该目录中的所有代码建立索引。此过程在后台运行，你会收到一个 job_id 用于跟踪进度。
  2. 开始监视目录中的文件更改，以实时更新代码图。

  这意味着你只需告诉系统监视某个目录，它就会自动处理初始索引和后续持续更新。

查询和理解代码

• 查找代码定义位置：

  • “process_payment 函数在哪里？”
  • “帮我查找 User 类。”
  • “显示所有与‘数据库连接’相关的代码。”

• 分析关系和影响：

  • “还有哪些函数调用了 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 的已索引仓库。”

---

故障排除

遇到锁错误、“索引始终无法完成”的循环，或功能无响应？ 请参阅 docs/TROUBLESHOOTING.md——每个条目都将实际报告的问题对应到其修复方法或变通方案。

---

贡献

欢迎贡献！🎉
详细指南请参阅 CONTRIBUTING.md。 如果你对新功能、集成或改进有想法，请提交 issue 或 Pull Request。

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