언리얼 엔진 코드 분석기 MCP 서버
언리얼 엔진 코드베이스에 강력한 소스 코드 분석 기능을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 도구를 사용하면 클로드와 클라인과 같은 AI 비서가 언리얼 엔진 소스 코드를 심층적으로 이해하고 분석할 수 있습니다.
특징
- 클래스 분석 : 메서드, 속성, 상속을 포함한 C++ 클래스에 대한 자세한 정보를 얻으세요
- 계층 매핑 : 클래스 상속 계층을 시각화하고 이해합니다.
- 코드 검색 : 컨텍스트 인식 결과를 사용하여 코드 검색
- 참조 찾기 : 클래스, 함수 또는 변수에 대한 모든 참조를 찾습니다.
- 서브시스템 분석 : 렌더링, 물리 등 주요 Unreal Engine 서브시스템을 분석합니다.
- 게임 장르 지식 : 게임 장르, 기능 및 구현 패턴에 대한 내장 지식 기반
- 패턴 감지 및 학습 : 일반적인 Unreal Engine 패턴을 식별하고 학습 리소스를 제공합니다.
- 사용자 정의 코드베이스 지원 : Unreal Engine 프로젝트 코드베이스를 직접 분석하세요
빠른 시작
설치
- 이 저장소를 복제하세요:
지엑스피1
- 종속성 설치:
- 프로젝트를 빌드하세요:
구성
Claude 데스크톱 앱용
Claude 데스크톱 구성 파일(Windows의 경우 %APPDATA%\Claude\claude_desktop_config.json )에 다음을 추가합니다.
{
"mcpServers": {
"unreal-analyzer": {
"command": "node",
"args": ["path/to/unreal-analyzer/build/index.js"],
"env": {}
}
}
}
클라인을 위해
Cline MCP 설정 파일에 다음을 추가합니다(Windows의 경우 %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json ):
{
"mcpServers": {
"unreal-analyzer": {
"command": "node",
"args": ["path/to/unreal-analyzer/build/index.js"],
"env": {}
}
}
}
기술적 세부 사항
분석기는 다음을 사용하여 구축되었습니다.
- 유형 안전 코드를 위한 TypeScript
- 강력한 C++ 구문 분석을 위한 트리시터
- AI 어시스턴트 통합을 위한 모델 컨텍스트 프로토콜 SDK
- 파일 패턴 매칭을 위한 Glob
주요 종속성:
- @modelcontextprotocol/create-server: ^0.1.0
- 나무 시터: ^0.20.1
- 트리시터 cpp: ^0.20.0
- 글로브: ^8.1.0
용법
분석 도구를 사용하기 전에 먼저 Unreal Engine 소스 경로나 사용자 정의 코드베이스 경로를 설정해야 합니다.
분석 설정
언리얼 엔진 소스 코드
{
"name": "set_unreal_path",
"arguments": {
"path": "/path/to/UnrealEngine/Source"
}
}
사용자 정의 C++ 코드베이스의 경우
{
"name": "set_custom_codebase",
"arguments": {
"path": "/path/to/your/codebase"
}
}
사용자 지정 코드베이스 기능을 사용하면 모든 C++ 프로젝트를 분석할 수 있습니다. 예:
- 게임 엔진(Unity, Godot, 커스텀 엔진)
- 그래픽 라이브러리(OpenGL, Vulkan, DirectX)
- 프레임워크(Qt, Boost, SFML)
- 모든 C++ 애플리케이션 또는 라이브러리
사용자 지정 게임 엔진 분석 예:
// Initialize with custom codebase
{
"name": "set_custom_codebase",
"arguments": {
"path": "/path/to/game-engine"
}
}
// Analyze engine's renderer class
{
"name": "analyze_class",
"arguments": {
"className": "Renderer"
}
}
// Find all shader-related code
{
"name": "search_code",
"arguments": {
"query": "shader|glsl|hlsl",
"filePattern": "*.{h,cpp,hpp}"
}
}
// Get render system class hierarchy
{
"name": "find_class_hierarchy",
"arguments": {
"className": "RenderSystem",
"includeImplementedInterfaces": true
}
}
Qt 애플리케이션 분석 예:
// Initialize with Qt project
{
"name": "set_custom_codebase",
"arguments": {
"path": "/path/to/qt-app"
}
}
// Find widget class definitions
{
"name": "search_code",
"arguments": {
"query": "class.*:.*public.*QWidget",
"filePattern": "*.h"
}
}
// Analyze main window class
{
"name": "analyze_class",
"arguments": {
"className": "MainWindow"
}
}
// Find signal/slot connections
{
"name": "find_references",
"arguments": {
"identifier": "connect",
"type": "function"
}
}
사용 가능한 도구
1. 클래스 분석
// Get detailed information about the AActor class
{
"name": "analyze_class",
"arguments": {
"className": "AActor"
}
}
출력 예:
{
"name": "AActor",
"properties": [
{
"name": "RootComponent",
"type": "USceneComponent*",
"access": "protected"
}
// ... other properties
],
"methods": [
{
"name": "BeginPlay",
"returnType": "void",
"access": "protected",
"virtual": true
}
// ... other methods
]
}
2. 클래스 계층 분석
// Get the inheritance hierarchy for ACharacter
{
"name": "find_class_hierarchy",
"arguments": {
"className": "ACharacter",
"includeImplementedInterfaces": true
}
}
출력 예:
{
"class": "ACharacter",
"inheritsFrom": "APawn",
"interfaces": ["IMovementModeInterface"],
"hierarchy": [
"ACharacter",
"APawn",
"AActor",
"UObject"
]
}
3. 참고문헌 찾기
// Find all references to the BeginPlay function
{
"name": "find_references",
"arguments": {
"identifier": "BeginPlay",
"type": "function"
}
}
출력 예:
{
"references": [
{
"file": "Actor.cpp",
"line": 245,
"context": "void AActor::BeginPlay() { ... }"
},
{
"file": "Character.cpp",
"line": 178,
"context": "Super::BeginPlay();"
}
]
}
4. 코드 검색
// Search for physics-related code
{
"name": "search_code",
"arguments": {
"query": "PhysicsHandle",
"filePattern": "*.h",
"includeComments": true
}
}
출력 예:
{
"matches": [
{
"file": "PhysicsEngine/PhysicsHandleComponent.h",
"line": 15,
"context": "class UPhysicsHandleComponent : public UActorComponent",
"snippet": "// Component used for grabbing and moving physics objects"
}
]
}
5. 패턴 감지 및 모범 사례
분석기는 Unreal Engine 모범 사례를 이해하고 따르기 위한 두 가지 강력한 도구를 제공합니다.
패턴 감지
// Detect patterns in a file
{
"name": "detect_patterns",
"arguments": {
"filePath": "Source/MyGame/MyActor.h"
}
}
출력 예:
{
"patterns": [
{
"pattern": "UPROPERTY Macro",
"description": "Property declaration for Unreal reflection system",
"location": "Source/MyGame/MyActor.h:15",
"context": "UPROPERTY(EditAnywhere, BlueprintReadWrite)\nfloat Health;",
"improvements": "Consider adding a Category specifier for better organization\nConsider adding Meta tags for validation",
"documentation": "https://docs.unrealengine.com/5.0/en-US/unreal-engine-uproperty-specifier-reference/",
"bestPractices": "Use appropriate specifiers (EditAnywhere, BlueprintReadWrite)\nConsider replication needs (Replicated, ReplicatedUsing)\nGroup related properties with categories",
"examples": "UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = \"Combat\")\nfloat Health;\nUPROPERTY(Replicated, Meta = (ClampMin = \"0.0\"))\nfloat Speed;"
}
]
}
모범 사례 가이드
// Get best practices for specific Unreal concepts
{
"name": "get_best_practices",
"arguments": {
"concept": "UPROPERTY" // or UFUNCTION, Components, Events, Replication, Blueprints
}
}
출력 예:
{
"description": "Property declaration for Unreal reflection system",
"bestPractices": [
"Use appropriate specifiers (EditAnywhere, BlueprintReadWrite)",
"Consider replication needs (Replicated, ReplicatedUsing)",
"Group related properties with categories",
"Use Meta tags for validation and UI customization"
],
"examples": [
"UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = \"Combat\")\nfloat Health;",
"UPROPERTY(Replicated, Meta = (ClampMin = \"0.0\"))\nfloat Speed;"
],
"documentation": "https://docs.unrealengine.com/5.0/en-US/unreal-engine-uproperty-specifier-reference/"
}
모범 사례 가이드에서는 Unreal Engine의 주요 개념을 다룹니다.
- UPROPERTY: 부동산 반영 및 노출
- UFUNCTION: 함수 리플렉션 및 블루프린트 통합
- 구성 요소: 구성 요소 생성 및 관리
- 이벤트: 이벤트 처리 및 위임
- 복제: 네트워크 복제 설정
- 블루프린트: 블루프린트/C++ 상호 작용 패턴
6. API 문서 쿼리
// Search the API documentation
{
"name": "query_api",
"arguments": {
"query": "Actor",
"category": "Object",
"module": "Core",
"includeExamples": true,
"maxResults": 10
}
}
출력 예:
{
"results": [
{
"class": "AActor",
"description": "Base class for all actors in the game",
"module": "Core",
"category": "Object",
"syntax": "class AActor : public UObject",
"examples": [
"// Create a new actor\nAActor* MyActor = GetWorld()->SpawnActor<AActor>();"
],
"remarks": [
"Actors are the base building blocks of the game",
"Can be placed in levels or spawned dynamically"
],
"documentation": "https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Core/AActor",
"relevance": 100
}
]
}
API 문서 쿼리 도구는 다음을 제공합니다.
- 클래스 문서 전체에서 전체 텍스트 검색
- 카테고리 및 모듈별 필터링
- 코드 예제 및 사용 패턴
- 관련성 기반 결과 정렬
- 공식 문서 링크
7. 하위 시스템 분석
// Analyze the Physics subsystem
{
"name": "analyze_subsystem",
"arguments": {
"subsystem": "Physics"
}
}
출력 예:
{
"name": "Physics",
"coreClasses": [
"UPhysicsEngine",
"FPhysScene",
"UBodySetup"
],
"keyFeatures": [
"PhysX integration",
"Collision detection",
"Physical materials"
],
"commonUseCases": [
"Character movement",
"Vehicle simulation",
"Destructible environments"
]
}
API 문서
이제 분석기에 포괄적인 API 문서화 기능이 포함되었습니다.
- 자동 문서 생성
- 소스 코드 주석에서 문서를 추출합니다.
- 클래스 구조와 관계를 분석합니다
- 클래스를 유형 및 모듈별로 분류합니다.
- 구문 예제와 사용 패턴을 생성합니다.
- 스마트 검색
- 모든 문서에 대한 전체 텍스트 검색
- 관련성 기반 결과 순위
- 카테고리 및 모듈 필터링
- 코드 예제 포함
- 문서 범주
- 객체: 기본 객체 클래스(UObject 파생 클래스)
- Actor: Actor 클래스(AActor 파생 클래스)
- 구조: 데이터 구조 및 유형
- 구성 요소: 구성 요소 클래스
- 기타: 기타 클래스 및 유틸리티
- 모듈 구성
- 핵심: 핵심 엔진 기능
- RenderCore: 렌더링 시스템
- PhysicsCore: 물리 엔진
- 그리고 다른 엔진 모듈
- 기존 도구와의 통합
- 자세한 정보를 위한 클래스 분석 링크
- 모범 사례를 위한 패턴 감지에 연결
- 참조: 공식 Unreal Engine 문서
- 학습 리소스와 예제를 제공합니다
모범 사례
- 분석 도구를 사용하기 전에 항상 Unreal Engine 경로 또는 사용자 정의 코드베이스 경로를 설정하세요.
- 분석할 때 특정 클래스 이름을 사용하세요(예: "Class" 대신 "MyClass")
search_code 에서 파일 패턴 매개변수를 활용하여 결과를 좁힙니다.- 완전한 이해를 위해 클래스 계층을 분석할 때 구현된 인터페이스를 포함합니다.
- 특정 클래스에 들어가기 전에 하위 시스템 분석 도구를 사용하여 전반적인 개요를 파악하세요(Unreal Engine에만 해당)
오류 처리
분석기는 다음과 같은 경우 명확한 오류 메시지를 표시합니다.
- 코드베이스 경로가 설정되지 않았습니다(Unreal Engine 또는 사용자 정의)
- 제공된 경로가 존재하지 않거나 접근할 수 없습니다.
- 코드베이스에서 클래스 또는 심볼을 찾을 수 없습니다.
- 잘못된 파일 패턴이 제공되었습니다.
- 검색 쿼리 또는 C++ 코드의 구문 오류
- 소스 파일에 대한 액세스가 제한됩니다.
- C++ 파일에 대한 트리시터 구문 분석이 실패합니다.
성능 고려 사항
- 대규모 코드베이스는 분석하는 데 시간이 더 오래 걸릴 수 있습니다.
- 복잡한 클래스 계층 구조에는 더 많은 처리 시간이 필요할 수 있습니다.
- 광범위한 검색 패턴으로 인해 많은 일치 항목이 생성될 수 있습니다.
- 더 빠른 결과를 위해 더 구체적인 쿼리를 사용하는 것을 고려하세요
테스트
이 프로젝트에는 모든 주요 구성 요소에 대한 포괄적인 테스트 범위가 포함됩니다.
테스트 범위
- 분석기 테스트 : UnrealCodeAnalyzer 클래스에 대한 핵심 기능 테스트
- 초기화 및 경로 검증
- 클래스 분석 및 구문 분석
- 참고문헌 찾기
- 코드 검색
- 하위 시스템 분석
- 캐시 관리
- 게임 장르 테스트 : 게임 장르 지식 기반 검증
- 데이터 구조 검증
- 장르별 기능 검증
- 구성 요소 명명 규칙
- 데이터 완전성 검사
- MCP 서버 테스트 : MCP 서버 구현 테스트
- 서버 초기화
- 도구 등록 및 취급
- 요청/응답 검증
- 오류 처리
- 도구별 기능 테스트
테스트 실행
모든 테스트를 실행합니다.
개발 중에 유용할 수 있는 감시 모드에서 테스트 실행:
쓰기 시험
새로운 기능을 제공할 때 다음 사항을 확인하세요.
- 모든 새로운 기능에는 해당 테스트 범위가 있습니다.
- 테스트는
src/__tests__ 디렉토리에 정리되어 있습니다. - 외부 종속성을 적절하게 모의합니다.
- 일관성을 위해 기존 테스트 패턴을 따르세요
기여하다
기여를 환영합니다! 다음 항목에 대한 개선 사항을 포함하여 풀 리퀘스트를 제출해 주세요.
- 소스 코드 파싱 기능
- 새로운 분석 기능
- 성능 최적화
- 문서 개선
- 테스트 범위
PR을 제출하기 전에:
- 모든 테스트가 통과되었는지 확인하세요(
npm test ) - 새로운 기능에 대한 테스트 추가
- 필요에 따라 문서를 업데이트하세요