아래 코드를 복사해서 블로그나 개인 기술 문서(노션, 벨로그, 깃허브 등)에 바로 붙여넣어 사용하실 수 있습니다!
# [Windows & AI Agent] Graphify 최신 버전 완벽 가이드: 로컬 MCP 연동부터 지식 그래프 구축까지 (v0.9.42)
대규모 프로젝트의 코드베이스 구조와 클래스 간 의존 관계를 AI 에이전트(Gemini, Claude, Cursor 등)가 한눈에 파악하도록 도와주는 **Graphify(지식 그래프 분석 도구)**의 최신 버전 설치, MCP 연동, 그리고 윈도우(Windows) 환경에서의 실전 설정 가이드를 Step-by-Step으로 정리합니다.
---
## 📌 Graphify란?
**Graphify**는 소스코드(AST 파싱)를 분석하여 파일, 클래스, 함수 간의 호출 및 의존성을 **지식 그래프(Knowledge Graph)** 형태로 추출해 주는 도구입니다.
MCP(Model Context Protocol)를 통해 AI 에이전트와 연동하면, AI가 프로젝트 전체의 구조와 핵심 노드(God Class), 최단 호출 경로 등을 즉시 파악하고 탐색할 수 있습니다.
---
## 🚀 Step 1. MCP 서버 설정 (`mcp_config.json`)
Graphify는 외부 서버를 호출하는 방식이 아니라, **사용자 로컬 컴퓨터의 Python 가상환경에서 독립 프로세스**로 실행됩니다. `uv` 패키지 관리자를 사용하여 100% 로컬에서 동작합니다.
### 1) `mcp_config.json` 설정 파일 수정
`mcp_config.json` (또는 에이전트 설정 파일)에 아래 내용을 등록합니다.
```json
{
"mcpServers": {
"graphify": {
"command": "uv",
"args": [
"run",
"--refresh",
"--with",
"graphifyy",
"--with",
"mcp",
"-m",
"graphify.serve",
"D:/UnivEsGWSolution/graphify-out/graph.json"
],
"disabled": false
}
}
}
⚠️ 주의! @latest 문법 사용 금지 (uv 전용 이슈)
npm이나 pip과 달리 uv에서 graphifyy@latest처럼 @latest를 적으면, @를 로컬 디렉토리 경로(Direct Path)로 인식하여 file:///.../latest 경로를 찾는 오류(Distribution not found)가 발생합니다.
최신 버전 갱신은 graphifyy@latest 대신 "--refresh" 옵션을 사용해야 항상 최신 패키지로 갱신됩니다.
🔄 Step 2. 에이전트 스킬 최신화 (Version Sync)
Graphify를 실행할 때 아래와 같은 경고 메시지가 나올 수 있습니다.
warning: skill is from graphify 0.9.19, package is 0.9.42. Run 'graphify install' to update.
💡 경고 원인 및 해결 방법
- 원인: 프로젝트에 등록된 Graphify 규칙/스킬 템플릿(0.9.19)보다 최근 실행한 Graphify 패키지(0.9.42) 버전이 높기 때문입니다. (기능 실행에는 지장이 없는 단순 안내문입니다.)
- 해결: 터미널(PowerShell)에서 아래 명령어를 1회 실행하여 에이전트 스킬/규칙을 최신 버전으로 즉시 업데이트할 수 있습니다.
# Google Antigravity / Agent 환경 스킬 업데이트
uv run --with graphifyy graphify antigravity install
🧹 Step 3. 지식 그래프 완전 초기화 & 재생성
기존 그래프 데이터가 꼬였거나 완전히 깨끗한 상태에서 다시 스캔하고 싶다면 아래 순서로 진행합니다.
1) 기존 그래프 데이터 삭제 (PowerShell 기준)
# 기존 지식 그래프 폴더 및 파일 삭제
Remove-Item -Recurse -Force graphify-out -ErrorAction SilentlyContinue
Remove-Item -Force graph.json -ErrorAction SilentlyContinue
(CMD 기준: rmdir /s /q graphify-out)
2) 새 지식 그래프 추출 실행
# 순수 소스코드만 스캔하여 지식 그래프 생성 (--code-only 옵션)
uv run --with graphifyy --with mcp graphify extract . --code-only
🙈 Step 4. [꿀팁] 윈도우 환경 .graphifyignore 예외 처리 노하우
특정 대형 프로젝트 폴더(예: SharedProject/)를 스캔에서 제외하고 싶을 때, 단순히 SharedProject/ 하나만 적으면 윈도우 환경에서는 무시 패턴이 잘 적용되지 않을 수 있습니다.
❓ 왜 안 될까요?
파이썬 내부 경로 검사(fnmatch) 시 윈도우는 역슬래시(SharedProject\sub\file.cs) 경로를 사용하기 때문에 Unix 스타일 슬래시(/)만 작성 시 일치하지 않기 때문입니다.
🛠️ 해결책: .graphifyignore 파일 다각도 패턴 등록
프로젝트 루트 디렉토리에 .graphifyignore 파일을 생성하고 윈도우 경로 및 하위 와일드카드를 포함하여 작성합니다.
d:\UnivEsGWSolution\.graphifyignore 작성 예시:
# 특정 디렉토리 완전 제외 (윈도우 + 슬래시 패턴 예외 처리)
SharedProject
SharedProject/
SharedProject/*
SharedProject/**
**/SharedProject/**
SharedProject\*
# 기타 제외할 임시/빌드 파일 패턴
*.tmp
*.log
docs/old/
💡 참고: Graphify는 기본적으로 프로젝트의 .gitignore 파일도 자동으로 인식하여 빌드 출력물(bin/, obj/, node_modules/ 등)을 알아서 스캔 대상에서 제외합니다.
🤖 Step 5. AI 에이전트와 대화로 지식 그래프 활용하기
지식 그래프 생성이 완료되면, AI 채팅 창에서 자연어로 질문하여 코드베이스를 입체적으로 분석할 수 있습니다.
| AI 질문 예시 |
작동하는 MCP 도구 |
설명 |
| *"우리 프로젝트에서 가장 연결 결합도가 높은 God Node 들을 알려줘."* |
god_nodes |
핵심 아키텍처 허브 클래스/파일 탐색 |
| *"A 서비스 클래스와 B 리포지토리 간의 호출 경로(Shortest Path)를 찾아줘."* |
shortest_path |
두 노드 간 최단 연결 의존성 추적 |
| *"현재 지식 그래프의 전체 모듈(커뮤니티) 구조와 통계를 요약해 줘."* |
graph_stats, get_community |
프로젝트 도메인별 그룹 구조 파악 |
| *"UserControl.cs 파일과 직접 연결된 이웃 노드(참조 관계) 보여줘."* |
get_neighbors |
해당 파일의 상/하위 참조 관계 탐색 |
❓ 트러블슈팅 FAQ
Q1. uvx graphifyy . 실행 시 명령어를 찾을 수 없다고 나옵니다.
graphifyy 패키지의 실행 파일(exe) 이름은 graphify.exe입니다. uvx 사용 시 실행 파일명을 명시해 주어야 합니다:
uvx --from graphifyy graphify .
Q2. graphify update . 실행 중 No module named 'fcntl' 에러가 납니다.
fcntl은 리눅스/맥 전용 파이썬 파일 락 모듈로, 윈도우 환경에서 graphify update 실행 시 모듈 부재 오류가 발생할 수 있습니다.
윈도우 환경에서는 update 대신 uv run --with graphifyy --with mcp graphify extract . --code-only 명령을 통한 재생성을 권장합니다.
📝 요약 체크리스트
mcp_config.json에 --refresh 옵션으로 100% 로컬 MCP 서버 구동uv run --with graphifyy graphify antigravity install 로 스킬 최신화.graphifyignore에 윈도우 경로 패턴(SharedProject\*, SharedProject/**) 등록하여 불필요한 폴더 스캔 제외- AI 에이전트에게 "God Node 보여줘", "A와 B의 최단 경로 찾아줘" 라고 물어보고 스마트하게 코드 분석!
```