게임 코드베이스의 구조를 AI에게 매핑해주는 오픈소스 MCP 도구 'gdep' 개발기

실용적 조언

AI 코딩 도구 사용 시 프로젝트 루트에 AGENTS.md를 생성하여 컨텍스트를 관리하라
복잡한 의존성 추적이 필요할 때는 MCP 서버를 통해 구조화된 데이터를 주입하라

섹션별 상세

기존 AI 코딩 어시스턴트들이 대규모 게임 프로젝트에서 파일 단위로만 코드를 읽어 전체적인 의존성을 파악하지 못하고 환각(Hallucination)을 일으키는 문제를 해결하고자 했다. AI가 .uasset이나 Blueprint 참조를 추적하지 못해 수십 개의 메시지를 주고받으며 시간을 낭비하는 상황을 개선하기 위해 전체 구조를 매핑하는 접근 방식을 선택했다.

gdep은 CLI 도구이자 MCP 서버로 작동하며, UE5 및 Unity 프로젝트를 0.5초 이내에 스캔하여 클래스 의존성, C++와 Blueprint 간의 호출 흐름, GAS(Gameplay Ability System) 체인 등을 분석한다. 이를 통해 AI에게 개별 파일이 아닌 프로젝트 전체의 '전술 지도'를 제공하여 탐색 효율성을 극대화한다.

동일한 Lyra 기반 UE5 프로젝트에서 수행한 비교 테스트 결과, gdep을 사용하지 않았을 때는 2분 10초가 소요되었으나 사용 시에는 56초로 약 2.3배 빠른 분석 속도를 보였다. 특히 에셋 스캔 성공률 100%를 달성하며 구체적인 태그 분포와 부모 클래스 매핑 정보를 구조화된 데이터로 제공하는 성과를 확인했다.

Claude Code가 gdeep mcp 없이 분석을 시도하는 터미널 화면 — ScreenshotAI가 프로젝트의 전체 구조를 파악하지 못한 상태에서 개별 파일을 하나씩 읽으며 분석을 진행하는 대조군 실험 과정을 보여준다.

Claude Code가 gdeep mcp를 사용하여 분석을 진행하는 터미널 화면 — ScreenshotMCP 도구를 통해 구조화된 컨텍스트를 주입받아 분석 속도와 정확도가 향상된 실험군 결과를 시연한다.

단순한 코드 분석을 넘어 게임 엔진에 특화된 19가지 린트(Lint) 규칙을 적용하여 Update() 내 GetComponent 호출이나 Tick() 내 SpawnActor 사용 같은 성능 저하 요인을 감지한다. 또한 AGENTS.md 파일을 생성하여 MCP 호환 AI가 시작 시 프로젝트 컨텍스트를 자동으로 읽어 들일 수 있도록 설계했다.

용어 해설

모델 컨텍스트 프로토콜(MCP): — Anthropic이 제안한 개방형 표준으로, AI 모델이 로컬 데이터 소스나 도구에 안전하고 표준화된 방식으로 접근할 수 있게 해주는 프로토콜이다. 이를 통해 개발자는 자신의 코드베이스나 데이터베이스를 AI 어시스턴트와 쉽게 연결할 수 있다.
게임플레이 어빌리티 시스템(GAS): — Unreal Engine에서 캐릭터의 능력, 상태 효과, 속성을 모듈식으로 관리하기 위해 제공하는 프레임워크이다. 복잡한 멀티플레이어 게임 로직을 체계적으로 구현하는 데 필수적이다.
블루프린트(Blueprint): — Unreal Engine의 노드 기반 비주얼 스크립팅 시스템으로, 코드를 작성하지 않고도 노드를 연결해 게임 로직을 시각적으로 설계할 수 있게 해준다. 대규모 프로젝트에서는 C++와 블루프린트 간의 상호 참조가 빈번하게 발생한다.

코드 예제

bash

pip install gdep
npm install -g gdep-mcp

gdep CLI 및 MCP 서버 설치 명령어

언급된 도구

gdep추천

게임 프로젝트 의존성 분석 및 MCP 서버

Claude Code중립

Anthropic의 터미널 기반 AI 코딩 에이전트

Cursor중립

AI 기반 코드 에디터

언급된 리소스

GitHubgdep GitHub Repository