📌Overview

Purpose: To provide powerful source code analysis capabilities for Unreal Engine codebases, facilitating deep understanding and manipulation of the code for AI assistants and developers.

Overview: The Unreal Engine Code Analyzer MCP server leverages the Model Context Protocol to offer an extensive suite of tools for analyzing C++ code within Unreal Engine projects. It enables users to extract detailed information about classes, understand hierarchies, and implement best practices specifically tailored to game development.

Key Features:

Class Analysis: Delivers in-depth information about C++ classes, including attributes, methods, and inheritance structures, helping users understand the code's architecture.
Hierarchy Mapping: Provides a visual representation of class inheritance, enhancing comprehension of relationships between different code components.
Code Search: Enables context-aware searching within the code, allowing for efficient identification of relevant snippets and references.
Reference Finding: Locates all occurrences of classes, functions, or variables across the project, streamlining code navigation.
Subsystem Analysis: Analyzes essential Unreal Engine subsystems (e.g., Rendering, Physics) to give insights into their functionalities and usage patterns.
Pattern Detection & Learning: Identifies common coding patterns used in Unreal Engine and supplies resources for learning and applying best practices.
Custom Codebase Support: Empowers users to analyze their own Unreal Engine projects or other C++ applications, broadening the tool's applicability beyond Unreal Engine itself.

Unreal Engine Code Analyzer MCP Server

A Model Context Protocol (MCP) server that provides powerful source code analysis capabilities for Unreal Engine codebases. This tool enables AI assistants like Claude and Cline to deeply understand and analyze Unreal Engine source code.

Features

Class Analysis: Get detailed information about C++ classes including methods, properties, and inheritance
Hierarchy Mapping: Visualize and understand class inheritance hierarchies
Code Search: Search through code with context-aware results
Reference Finding: Locate all references to classes, functions, or variables
Subsystem Analysis: Analyze major Unreal Engine subsystems like Rendering, Physics, etc.
Game Genre Knowledge: Built-in knowledge base of game genres, features, and implementation patterns
Pattern Detection & Learning: Identifies common Unreal Engine patterns and provides learning resources
Custom Codebase Support: Analyze your own Unreal Engine project codebase

Quick Start

Installation

Clone this repository:

git clone https://github.com/ayeletstudioindia/unreal-analyzer-mcp
cd unreal-analyzer-mcp

Install dependencies:

npm install

Build the project:

npm run build

Configuration

For Claude Desktop App

Add the following to your Claude desktop configuration file (%APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "unreal-analyzer": {
      "command": "node",
      "args": ["path/to/unreal-analyzer/build/index.js"],
      "env": {}
    }
  }
}

For Cline

Add the following to your Cline MCP settings file (%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json on Windows):

{
  "mcpServers": {
    "unreal-analyzer": {
      "command": "node",
      "args": ["path/to/unreal-analyzer/build/index.js"],
      "env": {}
    }
  }
}

Technical Details

The analyzer is built using:

TypeScript for type-safe code
Tree-sitter for robust C++ parsing
Model Context Protocol SDK for AI assistant integration
Glob for file pattern matching

Key dependencies:

@modelcontextprotocol/create-server: ^0.1.0
tree-sitter: ^0.20.1
tree-sitter-cpp: ^0.20.0
glob: ^8.1.0

Usage

Before using any analysis tools, set either the Unreal Engine source path or a custom codebase path.

Setting Up Analysis

For Unreal Engine Source Code

{
  "name": "set_unreal_path",
  "arguments": {
    "path": "/path/to/UnrealEngine/Source"
  }
}

For Custom C++ Codebases

{
  "name": "set_custom_codebase",
  "arguments": {
    "path": "/path/to/your/codebase"
  }
}

The custom codebase feature allows analyzing any C++ project such as game engines (Unity, Godot, custom engines), graphics libraries (OpenGL, Vulkan, DirectX), frameworks (Qt, Boost, SFML), or any C++ application or library.

Available Tools

1. Class Analysis

// Get detailed information about the AActor class
{
  "name": "analyze_class",
  "arguments": {
    "className": "AActor"
  }
}

Example output:

{
  "name": "AActor",
  "properties": [
    {
      "name": "RootComponent",
      "type": "USceneComponent*",
      "access": "protected"
    }
  ],
  "methods": [
    {
      "name": "BeginPlay",
      "returnType": "void",
      "access": "protected",
      "virtual": true
    }
  ]
}

2. Class Hierarchy Analysis

// Get the inheritance hierarchy for ACharacter
{
  "name": "find_class_hierarchy",
  "arguments": {
    "className": "ACharacter",
    "includeImplementedInterfaces": true
  }
}

Example output:

{
  "class": "ACharacter",
  "inheritsFrom": "APawn",
  "interfaces": ["IMovementModeInterface"],
  "hierarchy": [
    "ACharacter",
    "APawn",
    "AActor",
    "UObject"
  ]
}

3. Reference Finding

// Find all references to the BeginPlay function
{
  "name": "find_references",
  "arguments": {
    "identifier": "BeginPlay",
    "type": "function"
  }
}

Example output:

{
  "references": [
    {
      "file": "Actor.cpp",
      "line": 245,
      "context": "void AActor::BeginPlay() { ... }"
    },
    {
      "file": "Character.cpp",
      "line": 178,
      "context": "Super::BeginPlay();"
    }
  ]
}

4. Code Search

// Search for physics-related code
{
  "name": "search_code",
  "arguments": {
    "query": "PhysicsHandle",
    "filePattern": "*.h",
    "includeComments": true
  }
}

Example output:

{
  "matches": [
    {
      "file": "PhysicsEngine/PhysicsHandleComponent.h",
      "line": 15,
      "context": "class UPhysicsHandleComponent : public UActorComponent",
      "snippet": "// Component used for grabbing and moving physics objects"
    }
  ]
}

5. Pattern Detection & Best Practices

The analyzer offers tools for understanding and following Unreal Engine best practices.

Pattern Detection

// Detect patterns in a file
{
  "name": "detect_patterns",
  "arguments": {
    "filePath": "Source/MyGame/MyActor.h"
  }
}

Example output:

{
  "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;"
    }
  ]
}

Best Practices Guide

// Get best practices for specific Unreal concepts
{
  "name": "get_best_practices",
  "arguments": {
    "concept": "UPROPERTY"  // or UFUNCTION, Components, Events, Replication, Blueprints
  }
}

Example output:

{
  "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/"
}

The best practices guide covers key Unreal Engine concepts:

UPROPERTY: Property reflection and exposure
UFUNCTION: Function reflection and Blueprint integration
Components: Component creation and management
Events: Event handling and delegation
Replication: Network replication setup
Blueprints: Blueprint/C++ interaction patterns

6. API Documentation Query

// Search the API documentation
{
  "name": "query_api",
  "arguments": {
    "query": "Actor",
    "category": "Object",
    "module": "Core",
    "includeExamples": true,
    "maxResults": 10
  }
}

Example output:

{
  "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
    }
  ]
}

The API documentation query provides:

Full-text search across class documentation
Filtering by category and module
Code examples and usage patterns
Relevance-based sorting of results
Links to official documentation

7. Subsystem Analysis

// Analyze the Physics subsystem
{
  "name": "analyze_subsystem",
  "arguments": {
    "subsystem": "Physics"
  }
}

Example output:

{
  "name": "Physics",
  "coreClasses": [
    "UPhysicsEngine",
    "FPhysScene",
    "UBodySetup"
  ],
  "keyFeatures": [
    "PhysX integration",
    "Collision detection",
    "Physical materials"
  ],
  "commonUseCases": [
    "Character movement",
    "Vehicle simulation",
    "Destructible environments"
  ]
}

API Documentation Features

Automatic extraction and generation from source code comments
Class structure and relationship analysis
Syntax examples and usage patterns
Full-text smart search with filters and relevance ranking
Categorization into Object, Actor, Structure, Component, Miscellaneous
Organized by Engine modules like Core, RenderCore, PhysicsCore
Integration with class analysis, pattern detection, official docs, and learning resources

Best Practices

Always set either Unreal Engine path or custom codebase path before using analysis tools
Use specific class names when analyzing
Utilize file pattern parameters in code searches to narrow results
Include implemented interfaces when analyzing class hierarchies
Use subsystem analysis for a high-level overview before detailed class exploration

Error Handling

The analyzer provides clear errors for:

Missing codebase path
Invalid or inaccessible paths
Class or symbol not found
Invalid file patterns
Syntax errors in queries or C++ code
Access restrictions on source files
Tree-sitter parsing failures

Performance Considerations

Large codebases may require more time to analyze
Complex hierarchies increase processing time
Broad search queries may slow performance
Using specific queries improves speed and relevance

Testing

Test Coverage

Analyzer Tests: Core functionality, including initialization, class and reference analysis, searching, subsystem analysis, and cache management
Game Genres Tests: Verification of game genre knowledge base, feature validation, and data completeness
MCP Server Tests: Server initialization, tool registration, request/response handling, error handling, and functionality testing

Running Tests

Run all tests:

npm test

Run tests in watch mode (for development):

npm run test:watch

Writing Tests

For new features:

Provide corresponding tests
Organize tests in src/__tests__
Mock external dependencies as needed
Follow existing test patterns

Contributing

Contributions are welcome! Please submit pull requests for:

Parsing improvements
New analysis features
Performance optimizations
Documentation enhancements
Additional test coverage

Before submitting a PR:

Ensure all tests pass (npm test)
Add new tests as required
Update documentation as needed