CodeGraphContext/CodeGraphContext

코드 저장소를 AI 에이전트를 위한 쿼리 가능한 그래프로 변환합니다.

🌐 언어:

• 🇬🇧 English (영어)
• 🇨🇳 中文 (중국어)
• 🇰🇷 한국어
• 🇺🇦 Українська (우크라이나어)
• 🇷🇺 Русский (러시아어)
• 🇯🇵 日本語 (일본어) (곧 출시 예정)
• 🇪🇸 Español (스페인어) (곧 출시 예정)

🌍 https://github.com/Shashankss1205/CodeGraphContext/issues 에 이슈(Issue) 및 PR을 제출하여 CodeGraphContext를 여러분의 언어로 번역하는 데 도움을 주세요!

심층적인 코드 그래프와 AI 컨텍스트 사이의 간극을 메웁니다.

로컬 코드를 그래프 데이터베이스(Graph Database)로 인덱싱하여 AI 어시스턴트와 개발자에게 컨텍스트를 제공하는 강력한 MCP 서버 (MCP server) 및 **CLI 툴킷 (CLI toolkit)**입니다. 포괄적인 코드 분석을 위한 독립형 CLI로 사용하거나, MCP를 통해 선호하는 AI IDE에 연결하여 AI 기반의 코드 이해 기능을 활용할 수 있습니다.

• 🚀 빠른 시작 (Quick Start)
• 🌐 지원되는 프로그래밍 언어 (Supported Programming Languages)
• 🛠️ CLI 툴킷 (CLI Toolkit)
• 🤖 MCP 서버 (MCP Server)
• 🗄️ 데이터베이스 옵션 (Database Options)
• 🔬 SCIP 인덱싱 (SCIP indexing) (선택 사항)

버전: 0.4.10
저자: 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

기여와 피드백은 언제나 환영합니다! 질문, 제안 또는 협업 기회에 대해 언제든지 연락해 주세요.

코드 인덱싱 (Code Indexing): 코드를 분석하고 구성 요소의 지식 그래프(Knowledge Graph)를 구축합니다.
관계 분석 (Relationship Analysis): 호출자(Callers), 피호출자(Callees), 클래스 계층 구조(Class Hierarchies), 호출 체인(Call Chains) 등을 쿼리합니다.
사전 인덱싱된 번들 (Pre-indexed Bundles): .cgc 번들을 사용하여 유명한 저장소를 인덱싱 없이 즉시 로드합니다. (자세히 알아보기)
라이브 파일 워칭 (Live File Watching): 디렉토리의 변경 사항을 감시하고 실시간으로 그래프를 자동으로 업데이트합니다 (codegraphcontext watch)

).대화형 설정 (Interactive Setup): 쉬운 설정을 위한 사용자 친화적인 명령줄 위저드(command-line wizard).
이중 모드 (Dual Mode): 개발자를 위한 독립형 CLI 툴킷 (CLI toolkit) 및 AI 에이전트를 위한 **MCP 서버 (MCP server)**로 작동.
다중 언어 지원 (Multi-Language Support): 20개의 프로그래밍 언어에 대한 완전한 지원.
유연한 데이터베이스 백엔드 (Flexible Database Backend): KuzuDB (기본값), LadybugDB, FalkorDB Lite (전형적인 Unix 기본값), FalkorDB Remote, Nornic DB, 또는 Neo4j (Docker/네이티브를 통한 모든 플랫폼 지원).

CodeGraphContext는 다음 언어들에 대해 포괄적인 파싱 (parsing) 및 분석 (analysis)을 제공합니다:

언어	언어	언어
🐍	Python
📜	JavaScript
🔷	TypeScript
☕	Java
🏗️	C / C++
#️⃣	C#
🐹	Go
🦀	Rust
💎	Ruby
🐘	PHP
🍎	Swift
🎨	Kotlin
🎯	Dart
🐪	Perl
🌙	Lua
🚀	Scala
λ	Haskell
💧	Elixir
⚛️	TSX

각 언어 파서 (parser)는 함수 (functions), 클래스 (classes), 메서드 (methods), 매개변수 (parameters), 상속 관계 (inheritance relationships), 함수 호출 (function calls), 그리고 임포트 (imports)를 추출하여 포괄적인 코드 그래프 (code graph)를 구축합니다.

CodeGraphContext는 사용자의 환경에 맞게 여러 그래프 데이터베이스 백엔드를 지원합니다:

기능	KuzuDB	LadybugDB	FalkorDB Lite	Neo4j / Nornic DB
전형적인 기본값	표준 기본값 (임베디드, KuzuDB 기반)	특화된 임베디드 (Kuzu와 유사)	Unix (Python 3.12 이상, falkordblite 작동 시)	명시적으로 구성된 경우
설정	설정 불필요 / 임베디드 (Zero-config / Embedded)	설정 불필요 / 임베디드 (Zero-config / Embedded)	설정 불필요 / 인프로세스 (Zero-config / In-process)	Docker / 외부 (External)
플랫폼	모든 플랫폼 (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
속도	⚡ 매우 빠름 (Extremely Fast)	⚡ 빠름 (Fast)	🚀 확장 가능 (Scalable)
지속성 (Persistence)	예 (디스크에 저장)	예 (디스크에 저장)	예 (디스크에 저장)

SCIP_INDEXER=true일 때

CGC 설정(~/.codegraphcontext/.env)에서 SCIP_INDEXER=true일 때, 일부 언어는 Tree-sitter 휴리스틱(heuristics)만 사용하는 것보다 더 정확한 호출(calls) 및 상속(inheritance) 정보를 얻기 위해 외부 SCIP 인덱서(indexers)를 사용합니다.

**C 및 C++**은 scip-clang을 사용하며, 이는 compile_commands.json 파일(JSON 컴파일 데이터베이스)을 필요로 합니다. 이 파일에는 실제 컴파일러 명령(include 경로, -D 정의, -std 등)이 포함된 번역 단위(translation unit)당 하나의 항목이 있어야 합니다. 이 파일이 없으면 scip-clang을 실행할 수 없으며, CGC는 경고를 기록하고 해당 저장소에 대해 **Tree-sitter로 폴백(falls back)**합니다. 파일을 생성하는 일반적인 방법은 다음과 같습니다:

• -DCMAKE_EXPORT_COMPILE_COMMANDS=ON 옵션을 사용하는 CMake
• 또는 실제 빌드를 Bear로 감싸기 (예: bear -- make)

CGC는 또한 build/ 및 cmake-build-*/ 디렉토리에서 해당 파일명을 찾습니다. **C#**은 scip-dotnet (Roslyn)을 사용하며, 일반적인 .csproj / .sln 파일과 성공적인 복원(restore) 과정이 필요합니다. compile_commands.json은 필요하지 않습니다. SCIP는 사용 중인 그래프 데이터베이스(graph database)(Kuzu, Neo4j 등)와 무관하며, 동일한 플래그가 모든 백엔드에 적용됩니다.

CodeGraphContext는 이미 개발자들과 프로젝트들에 의해 다음과 같은 용도로 탐색되고 있습니다:

• AI 어시스턴트에서의 정적 코드 분석 (Static code analysis)
• 프로젝트의 그래프 기반 시각화 (Graph-based visualization)
• 데드 코드(Dead code) 및 복잡도 탐지

프로젝트에서 CodeGraphContext를 사용 중이라면, 언제든지 PR(Pull Request)을 열어 여기에 추가해 주세요! 🚀

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.21.0 (Python 3.13에는 설치되지 않음)
tree-sitter-language-pack>=0.6.0 (Python 3.13에는 설치되지 않음)
pyyaml
pathspec>=0.12.1
falkordb>=0.1.0
falkordblite>=0.1.0 (Unix 전용)
kuzu (KuzuDB 엔진)
fastapi>=0.100.0
uvicorn>=0.22.0
requests>=2.28.0
protobuf>=3.20,<3.21

참고: Python 3.10-3.14를 지원합니다.

툴킷 설치: pip install codegraphcontext

문제 해결 (Command not found): 만약 codegraphcontext 명령어를 찾을 수 없다면...

명령어를 찾을 수 없다면, 다음 한 줄 해결책을 실행하세요:
curl -sSL https://raw.githubusercontent.com/CodeGraphContext/CodeGraphContext/main/scripts/post_install_fix.sh | bash

데이터베이스 설정 (자동): CodeGraphContext는 기본적으로 임베디드 그래프 데이터베이스 (embedded graph database)를 사용합니다.
KuzuDB: 모든 플랫폼의 기본값입니다.
FalkorDB Lite: 사용 가능한 경우 Unix/macOS에서 권장됩니다.
Neo4j: 외부 서버를 사용하려면 codegraphcontext neo4j setup을 실행하세요.

CLI 명령어로 즉시 사용 시작하기:

# 현재 디렉토리 인덱싱
codegraphcontext index .
# 인덱싱된 모든 리포지토리 목록 표시
...

사용 가능한 모든 명령어와 사용 시나리오에 대해서는 전체 CLI 명령어 가이드를 참조하세요.

CodeGraphContext는 코드에 대한 멋지고 인터랙티브한 지식 그래프 (knowledge graphs)를 생성할 수 있습니다. 정적인 다이어그램과 달리, 이는 프리미엄 웹 기반 탐색기입니다:

프리미엄 미학 (Premium Aesthetics): 다크 모드 (Dark mode), 글래스모피즘 (glassmorphism), 그리고 현대적인 타이포그래피 (Outfit/JetBrains Mono).
인터랙티브 검사 (Interactive Inspection): 노드를 클릭하면 심볼 (symbol) 정보, 파일 경로 및 컨텍스트가 포함된 상세 사이드 패널이 열립니다.
빠른 검색 (Quick Search): 그래프를 통해 실시간 검색을 수행하여 특정 심볼을 즉시 찾을 수 있습니다.
지능형 레이아웃 (Intelligent Layouts): 복잡한 관계를 읽기 쉽게 만드는 힘 지향 (Force-directed) 및 계층적 (hierarchical) 레이아웃.
의존성 없는 보기 (Zero-Dependency Viewing): 모든 현대적인 브라우저에서 작동하는 독립형 HTML 파일.

# 함수 호출 시각화
codegraphcontext analyze calls my_function --viz
# 클래스 계층 구조 탐색
...

AI 어시스턴트가 CodeGraphContext를 사용하도록 설정하기:

설정: IDE/AI 어시스턴트를 구성하려면 MCP 설정 마법사를 실행하세요:
codegraphcontext mcp setup

마법사는 다음 항목들을 자동으로 감지하고 구성할 수 있습니다:

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

설정이 성공적으로 완료되면,

codegraphcontext mcp setup은 필요한 설정 파일들을 생성하여 배치합니다:

• mcp.json 파일을 생성합니다.

참조를 위해 현재 디렉토리에 mcp.json 파일을 생성합니다. - 데이터베이스 자격 증명(credentials)을 ~/.codegraphcontext/.env에 안전하게 저장합니다.

• 선택한 IDE/CLI의 설정 파일(예: .claude.json 또는 VS Code의 settings.json)을 업데이트합니다.

시작 (Start): MCP 서버를 실행합니다: codegraphcontext mcp start

사용 (Use): 이제 자연어(natural language)를 사용하여 AI 어시스턴트를 통해 코드베이스와 상호작용하세요! 아래 예시를 참조하십시오.

프로젝트 루트에 .cgcignore 파일을 생성하여 CodeGraphContext가 특정 파일과 디렉토리를 무시하도록 설정할 수 있습니다. 이 파일은 .gitignore와 동일한 구문(syntax)을 사용합니다.

.cgcignore 파일 예시:

# 빌드 결과물(build artifacts) 무시
/build/
/dist/
...

codegraphcontext mcp setup 명령은 IDE/CLI를 자동으로 구성하려고 시도합니다. 자동 설정을 사용하지 않기로 선택하거나 사용 중인 도구가 지원되지 않는 경우, 수동으로 구성할 수 있습니다.

클라이언트의 설정 파일(예: VS Code의 settings.json 또는 .claude.json)에 다음 서버 구성을 추가하십시오:

{
"mcpServers": {
"CodeGraphContext": {
...

pipx를 사용하여 CodeGraphContext를 설치한 경우, 대신 다음 구성을 사용하십시오:

{
"mcpServers": {
"CodeGraphContext": {
...

서버가 실행되면 일반적인 영어를 사용하여 AI 어시스턴트를 통해 서버와 상호작용할 수 있습니다. 다음과 같은 요청 예시가 있습니다:

새 프로젝트를 인덱싱(index)하려면:

• "/path/to/my-project 디렉토리의 코드를 인덱싱해 주세요." 또는

• "~/dev/my-other-project에 있는 프로젝트를 코드 그래프(code graph)에 추가해 주세요."

디렉토리의 실시간 변경 사항을 감시(watch)하려면:

• "/path/to/my-active-project 디렉토리의 변경 사항을 감시해 주세요." 또는
• "내가 ~/dev/main-app에서 작업 중인 프로젝트의 코드 그래프를 최신 상태로 유지해 주세요."

디렉토리 감시를 요청하면 시스템은 두 가지 작업을 동시에 수행합니다:

• 해당 디렉토리의 모든 코드를 인덱싱하기 위해 전체 스캔(full scan)을 시작합니다. 이 프로세스는 백그라운드에서 실행되며, job_id를 받게 됩니다.

진행 상황을 추적하기 위해 사용됩니다. - 이후 그래프를 실시간으로 업데이트하기 위해 파일 변경 사항을 감지하도록 디렉토리를 감시(watching)하기 시작합니다.

이는 단순히 시스템에 특정 디렉토리를 감시하도록 명령하는 것만으로도, 초기 인덱싱(indexing)과 지속적인 업데이트를 모두 자동으로 처리할 수 있음을 의미합니다.

• "감시(Watch)를..."

코드가 정의된 위치 찾기:- "process_payment 함수는 어디에 있나요?" - "User 클래스를 찾아주세요." - "'데이터베이스 연결(database connection)'과 관련된 모든 코드를 보여주세요."

• "어디에..."

관계 및 영향 분석:- "get_user_by_id 함수를 호출하는 다른 함수는 무엇인가요?" - "만약 제가 calculate_tax 함수를 변경하면, 코드의 다른 어떤 부분들이 영향을 받게 될까요?" - "BaseController 클래스의 상속 계층 구조(inheritance hierarchy)를 보여주세요." - "Order 클래스는 어떤 메서드(methods)를 가지고 있나요?"

• "다른 어떤 함수가..."

의존성 탐색:- "requests 라이브러리를 임포트(import)하는 파일은 무엇인가요?" - "render 메서드의 모든 구현체(implementations)를 찾아주세요."

• "어떤 파일들이..."

**고급 호출 체인 및 의존성 추적 (수백 개의 파일에 걸쳐 수행):**CodeGraphContext는 방대한 코드베이스 전반에 걸쳐 복잡한 실행 흐름과 의존성을 추적하는 데 탁월합니다. 그래프 데이터베이스(graph databases)의 강력한 기능을 활용하여, 함수가 여러 추상화 계층을 거치거나 수많은 파일에 걸쳐 호출되더라도 직접적 및 간접적 호출자(callers)와 피호출자(callees)를 식별할 수 있습니다. 이는 다음과 같은 작업에 매우 유용합니다:

영향 분석 (Impact Analysis): 핵심 함수에 대한 변경이 미치는 전체적인 파급 효과를 이해합니다. -
**디버깅 (Debugging):**진입점(entry point)부터 특정 버그까지의 실행 경로를 추적합니다. -
**코드 이해 (Code Comprehension):**대규모 시스템의 서로 다른 부분들이 어떻게 상호작용하는지 파악합니다. -

"main 함수부터 process_data까지의 전체 호출 체인(call chain)을 보여주세요." -
"validate_input을 직접적 또는 간접적으로 호출하는 모든 함수를 찾아주세요." -
"initialize_system이 최종적으로 호출하게 되는 모든 함수는 무엇인가요?" -
"DatabaseManager 모듈의 의존성을 추적해 주세요."

코드 품질 및 유지보수 (Code Quality and Maintenance):

• "이 프로젝트에 데드 코드 (dead code)나 사용되지 않는 코드가 있나요?"

• "src/utils.py에 있는 process_data 함수의 순환 복잡도 (cyclomatic complexity)를 계산해 주세요."

• "코드베이스에서 가장 복잡한 함수 5개를 찾아주세요."

저장소 관리 (Repository Management):

• "현재 인덱싱된 모든 저장소 (repositories)를 나열해 주세요."
• "/path/to/old-project에 있는 인덱싱된 저장소를 삭제해 주세요."

기여를 환영합니다! 🎉

자세한 가이드라인은 CONTRIBUTING.md를 참조해 주세요.
새로운 기능, 통합 (integrations) 또는 개선 사항에 대한 아이디어가 있다면, 이슈 (issue)를 생성하거나 풀 리퀘스트 (Pull Request)를 제출해 주세요.

토론에 참여하여 CodeGraphContext의 미래를 함께 만들어 가세요.