Unreal Engine Code Analyzer MCP Server

Unreal Engine Code Analyzer MCP Server

Unreal Engine のコードベースに強力なソースコード分析機能を提供する Model Context Protocol（MCP）サーバーです。このツールを使うと、Claude や Cline などの AI アシスタントが Unreal Engine のソースコードを深く理解し、分析できます。

機能

• クラス分析：メソッド、プロパティ、継承など、C++ クラスの詳細情報を取得します
• 階層マッピング：クラスの継承階層を可視化し、把握します
• コード検索：コンテキストを考慮した検索結果でコードを検索します
• 参照の検索：クラス、関数、変数へのすべての参照箇所を特定します
• サブシステム分析：レンダリング、物理など、Unreal Engine の主要なサブシステムを分析します
• ゲームジャンルの知識：ゲームジャンル、機能、実装パターンに関するナレッジベースを内蔵しています
• パターンの検出と学習：一般的な Unreal Engine のパターンを特定し、学習リソースを提供します
• カスタムコードベースのサポート：独自の Unreal Engine プロジェクトのコードベースを分析します

クイックスタート

インストール

1. このリポジトリをクローンします：

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

2. 依存関係をインストールします：

npm install

3. プロジェクトをビルドします：

npm run build

設定

Claude Desktop アプリの場合

Claude のデスクトップ設定ファイル（Windows の場合は %APPDATA%\Claude\claude_desktop_config.json）に以下を追加します：

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

Cline の場合

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++ 解析を実現する Tree-sitter
• AI アシスタントとの統合を実現する Model Context Protocol SDK
• ファイルパターンの照合に使う Glob

主な依存関係：

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

使用方法

分析ツールを使用する前に、Unreal Engine のソースパスまたはカスタムコードベースのパスを設定する必要があります：

分析の設定

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 のベストプラクティスを理解して実践するための強力なツールが2つ用意されています：

パターン検出

// 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：関数のリフレクションと Blueprint との統合
• コンポーネント：コンポーネントの作成と管理
• イベント：イベント処理とデリゲート
• レプリケーション：ネットワークレプリケーションの設定
• ブループリント：Blueprint と 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 ドキュメント作成機能が追加されました。

1. ドキュメントの自動生成

   • ソースコードのコメントからドキュメントを抽出します
   • クラスの構造と関係を分析します
   • クラスを種類やモジュールごとに分類します
   • 構文例と使用パターンを生成します

2. スマート検索

   • すべてのドキュメントを対象とした全文検索
   • 関連度に基づく検索結果の順位付け
   • カテゴリとモジュールによる絞り込み
   • コード例の掲載

3. ドキュメントのカテゴリ

   • オブジェクト：ベースオブジェクトクラス（UObject の派生クラス）
   • アクター：アクタークラス（AActor の派生クラス）
   • 構造体：データ構造と型
   • コンポーネント：コンポーネントクラス
   • その他：その他のクラスとユーティリティ

4. モジュールの構成

   • Core：エンジンの中核機能
   • RenderCore：レンダリングシステム
   • PhysicsCore：物理エンジン
   • その他のエンジンモジュール

5. 既存ツールとの連携

   • 詳細情報を得るためにクラス分析と連携します
   • ベストプラクティスを得るためにパターン検出と連携します
   • Unreal Engine の公式ドキュメントを参照します
   • 学習リソースと例を提供します

ベストプラクティス

1. 分析ツールを使用する前に、Unreal Engine のパスまたはカスタムコードベースのパスを必ず設定してください
2. 分析時には、具体的なクラス名を使用してください（例：「Class」だけでなく「MyClass」）
3. search_code のファイルパターンパラメーターを活用して、検索結果を絞り込んでください
4. クラス階層を分析する際は、全体像を把握できるよう、実装されているインターフェースも含めてください
5. 特定のクラスを詳しく調べる前に、サブシステム分析ツールを使用して概要を把握してください（Unreal Engine のみ）

エラー処理

アナライザーは、次の場合に明確なエラーメッセージを出力します。

• コードベースのパス（Unreal Engine またはカスタム）が設定されていない
• 指定されたパスが存在しない、またはアクセスできない
• コードベース内でクラスまたはシンボルが見つからない
• 無効なファイルパターンが指定されている
• 検索クエリまたは C++ コードに構文エラーがある
• ソースファイルへのアクセスが制限されている
• C++ ファイルの Tree-sitter による解析に失敗する

パフォーマンスに関する考慮事項

• 大規模なコードベースは、分析に時間がかかる場合があります
• 複雑なクラス階層の処理には、より多くの時間がかかる場合があります
• 範囲の広い検索パターンでは、多数の一致が見つかる可能性があります
• より速く結果を得るには、より具体的なクエリを使用してください

テスト

このプロジェクトでは、主要なすべてのコンポーネントを対象に、包括的なテストカバレッジを用意しています。

テストカバレッジ

• アナライザーテスト：UnrealCodeAnalyzer クラスの中核機能テスト

  • 初期化とパスの検証
  • クラスの分析と解析
  • 参照の検索
  • コード検索
  • サブシステム分析
  • キャッシュ管理

• ゲームジャンルテスト：ゲームジャンルのナレッジベースの検証

  • データ構造の検証
  • ジャンル固有の機能の検証
  • コンポーネントの命名規則
  • データの完全性チェック

• MCP サーバーテスト：MCP サーバー実装のテスト

  • サーバーの初期化
  • ツールの登録と処理
  • リクエストとレスポンスの検証
  • エラー処理
  • ツール固有の機能テスト

テストの実行

すべてのテストを実行します。

npm test

ウォッチモードでテストを実行します（開発中に便利です）。

npm run test:watch

テストの作成

新機能を追加する際は、以下を確認してください。

1. 新たに追加した機能に対応するテストカバレッジを用意する
2. テストを src/__tests__ ディレクトリに整理する
3. 外部依存関係を適切にモックする
4. 一貫性を保つため、既存のテストパターンに従う

貢献

貢献を歓迎します。以下の改善に向けたプルリクエストをぜひお送りください。

• ソースコード解析機能
• 新しい分析機能
• パフォーマンスの最適化
• ドキュメントの改善
• テストカバレッジ

PR を提出する前に、以下を確認してください。

1. すべてのテストに合格すること（npm test）
2. 新機能のテストを追加すること
3. 必要に応じてドキュメントを更新すること