unreal-engine-mcp-server 0.5.0 → 0.5.1

package/.env.example

@@ -6,7 +6,7 @@ MCP_ROUTE_STDOUT_LOGS=true
 # Unreal Engine Settings
 UE_PROJECT_PATH="C:/Users/YourName/Documents/Unreal Projects/YourProject/YourProject.uproject"
 # UE_EDITOR_EXE="C:/Program Files/Epic Games/UE_5.7/Engine/Binaries/Win64/UnrealEditor.exe"
-# UE_SCREENSHOT_DIR="C:/Users/YourName/Documents/Unreal Projects/YourProject/Saved/Screenshots"
+
 
 # Automation Bridge Connection (Node -> Unreal)
 MCP_AUTOMATION_HOST=127.0.0.1

package/.github/release-drafter-config.yml

@@ -0,0 +1,51 @@
+name-template: 'v$NEXT_PATCH_VERSION'
+tag-template: 'v$NEXT_PATCH_VERSION'
+categories:
+  - title: '🚀 Features'
+    labels:
+      - 'type/enhancement'
+      - 'feature'
+      - 'enhancement'
+  - title: '🐛 Bug Fixes'
+    labels:
+      - 'type/bug'
+      - 'bug'
+      - 'fix'
+  - title: '📚 Documentation'
+    labels:
+      - 'area/docs'
+      - 'documentation'
+  - title: '🧰 Tools'
+    labels:
+      - 'area/tools'
+      - 'tooling'
+  - title: '🔌 Plugin'
+    labels:
+      - 'area/plugin'
+  - title: '🧪 Testing'
+    labels:
+      - 'area/testing'
+      - 'test'
+  - title: '📦 Maintenance'
+    labels:
+      - 'chore'
+      - 'maintenance'
+change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
+change-title-escapes: '\<*_&'
+version-resolver:
+  major:
+    labels:
+      - 'major'
+  minor:
+    labels:
+      - 'minor'
+  patch:
+    labels:
+      - 'patch'
+      - 'type/bug'
+      - 'bug'
+  default: patch
+template: |
+  ## Changes in this Release
+
+  $CHANGES

package/.github/workflows/greetings.yml

@@ -1,6 +1,10 @@
 name: Greetings
 
-on: [pull_request_target, issues]
+on:
+  pull_request_target:
+    types: [opened]
+  issues:
+    types: [opened]
 
 permissions:
   issues: write

package/.github/workflows/labeler.yml

@@ -1,6 +1,7 @@
 name: "Pull Request Labeler"
 on:
-  - pull_request_target
+  pull_request_target:
+    types: [opened, synchronize, reopened]
 
 permissions:
   contents: read

package/.github/workflows/publish-mcp.yml

@@ -56,6 +56,7 @@ jobs:
 
       - name: Publish to npm
         run: npm publish
+        continue-on-error: true
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 

package/.github/workflows/release-drafter.yml

@@ -18,6 +18,6 @@ jobs:
     steps:
       - uses: release-drafter/release-drafter@v6.1.0 # v6.1.0
         with:
-          config-name: release-drafter.yml
+          config-name: release-drafter-config.yml
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/release.yml

@@ -15,12 +15,12 @@ jobs:
     
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4 # v4
+        uses: actions/checkout@v6 # v4
         with:
           fetch-depth: 0
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4 # v4
+        uses: actions/setup-node@v6 # v4
         with:
           node-version: '20'
           cache: 'npm'
@@ -91,7 +91,7 @@ jobs:
           fi
 
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@c062e08bd532815e2082a85e87e3ef29c3e6d191 # v2.0.8
+        uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2.5.0
         with:
           name: Release ${{ steps.version.outputs.tag }}
           body_path: release_notes.md

package/CHANGELOG.md

@@ -7,6 +7,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## 🏷️ [0.5.1] - 2025-12-17
+
+> [!WARNING]
+> ### ⚠️ Breaking Changes
+> - **Standardized Return Types** - All tool methods now return `StandardActionResponse` type instead of generic objects. Consumers must update their code to handle the new response structure with `success`, `data`, `warnings`, and `error` fields. (`5e615c5`)
+> - **Test Suite Structure** - New test files added and existing tests enhanced with comprehensive coverage.
+
+### 🔄 Changed
+
+<details>
+<summary><b>🎯 Standardized Tool Interfaces</b> (<code>5e615c5</code>)</summary>
+
+| Component | Change |
+|-----------|--------|
+| Tool Methods | Updated all tool methods to return `StandardActionResponse` type for consistency |
+| Tool Interfaces | Modified interfaces (assets, blueprint, editor, environment, foliage, landscape, level, sequence) to use standardized response format |
+| Type System | Added proper type imports and exports for `StandardActionResponse` |
+| Handler Files | Updated to work with new standardized response types |
+| Response Structure | All implementations return correct structure with `success`/`error` fields |
+
+</details>
+
+### ✨ Added
+
+<details>
+<summary><b>🧪 Comprehensive Test Suite</b> (<a href="https://github.com/ChiR24/Unreal_mcp/pull/25">#25</a>)</summary>
+
+| Feature | Description |
+|---------|-------------|
+| **Test Coverage** | Added comprehensive test files with success, error, and edge cases |
+| **GraphQL DataLoader** | Implemented N+1 query optimization with batching and caching |
+| **Type-Safe Interfaces** | Added type-safe automation response interfaces for better error handling |
+| **Utility Tests** | Added tests for core utilities (normalize, safe-json, validation) |
+| **Real-World Scenarios** | Enhanced coverage with real-world scenarios and cleanup procedures |
+| **New Test Suites** | Audio, lighting, performance, input, and asset graph management |
+| **Enhanced Logging** | Improved diagnostic logging throughout tools |
+| **Documentation** | Updated supported Unreal Engine versions (5.0-5.7) in testing documentation |
+
+</details>
+
+### 🧹 Maintenance
+
+- 🗑️ **Prompts Module Cleanup** - Removed prompts module and related GraphQL prompt functionality ([#26](https://github.com/ChiR24/Unreal_mcp/pull/26))
+- 🔒 **Security Updates** - Removed unused dependencies (axios, json5, yargs) from package.json for security (`5e615c5`)
+- 📐 **Tool Interfaces** - Enhanced asset and level tools with security validation and timeout handling (`5e615c5`)
+
+### 📦 Dependencies
+
+<details>
+<summary><b>GitHub Actions Updates</b></summary>
+
+| Package | Update | PR | Commit |
+|---------|--------|-----|--------|
+| `actions/checkout` | v4 → v6 | [#23](https://github.com/ChiR24/Unreal_mcp/pull/23) | `4c6b3b5` |
+| `actions/setup-node` | v4 → v6 | [#22](https://github.com/ChiR24/Unreal_mcp/pull/22) | `71aa35c` |
+| `softprops/action-gh-release` | 2.0.8 → 2.5.0 | [#21](https://github.com/ChiR24/Unreal_mcp/pull/21) | `b6c8a46` |
+
+</details>
+
+<details>
+<summary><b>NPM Package Updates</b> (<a href="https://github.com/ChiR24/Unreal_mcp/pull/24">#24</a>, <code>5e615c5</code>)</summary>
+
+| Package | Update |
+|---------|--------|
+| `@modelcontextprotocol/sdk` | 1.25.0 → 1.25.1 |
+| `@types/node` | 25.0.2 → 25.0.3 |
+
+</details>
+
+---
+
 ## 🏷️ [0.5.0] - 2025-12-16
 
 > [!IMPORTANT]

package/CONTRIBUTING.md

@@ -26,7 +26,7 @@ Please be respectful and constructive in all interactions. We're building someth
 
 1. Fork and clone the repository:
    ```bash
-   git clone https://github.com/YOUR_USERNAME/unreal-engine-mcp-server.git
+   git clone https://github.com/ChiR24/Unreal_mcp.git
    cd unreal-engine-mcp-server
    ```
 

package/GEMINI.md

@@ -0,0 +1,115 @@
+# Unreal Engine MCP Server
+
+## Project Overview
+
+The **Unreal Engine MCP Server** (`unreal-engine-mcp-server`) is a comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal Engine via a native automation bridge. It facilitates bidirectional communication between an AI agent (running via MCP) and an active Unreal Engine Editor session.
+
+### Architecture
+
+The system is composed of three main components:
+
+1.  **MCP Server (Node.js/TypeScript):**
+    *   **Role:** The core server that implements the MCP protocol, handles client requests, and orchestrates communication.
+    *   **Location:** `src/`
+    *   **Key File:** `src/index.ts` (Entry point), `src/unreal-bridge.ts` (Connection management).
+    *   **Tools:** Defines MCP tools for Actor manipulation, Asset management, Blueprints, etc. (found in `src/tools/`).
+
+2.  **Unreal Engine Plugin (C++):**
+    *   **Role:** Acts as the receiver and executor within the Unreal Engine process. It runs a WebSocket server to listen for commands from the Node.js server.
+    *   **Location:** `Plugins/McpAutomationBridge/`
+    *   **Key Functionality:** Handles `execute_console_command`, `set_object_property`, and other engine-level operations on the Game Thread.
+    *   **Communication:** Listens on `ws://localhost:8091` (default).
+
+3.  **WebAssembly Module (Rust):**
+    *   **Role:** Provides high-performance utilities for the Node.js server, such as complex property parsing and vector math.
+    *   **Location:** `wasm/`
+    *   **Key File:** `wasm/src/lib.rs`.
+
+## Building and Running
+
+### Prerequisites
+*   Node.js (v18 or higher)
+*   Unreal Engine (5.0-5.7)
+*   Rust (optional, if modifying WASM components)
+
+### Setup
+
+1.  **Install Dependencies:**
+    ```bash
+    npm install
+    ```
+
+2.  **Build the Server:**
+    ```bash
+    npm run build
+    ```
+
+3.  **Build WebAssembly (Optional):**
+    If you are working on the Rust module:
+    ```bash
+    npm run build:wasm
+    ```
+
+4.  **Unreal Plugin Installation:**
+    *   Copy the `Plugins/McpAutomationBridge` folder into your Unreal Project's `Plugins` directory (e.g., `YourProject/Plugins/`).
+    *   Regenerate project files and recompile your Unreal project.
+    *   Enable the plugin in the Unreal Editor if it's not automatically enabled.
+    *   Ensure the plugin is running (it should log "MCP Automation Bridge listening" to the Output Log).
+
+### Running the Server
+To start the MCP server:
+```bash
+npm start
+```
+Or for development with `ts-node`:
+```bash
+npm run dev
+```
+
+### Testing
+The project includes a suite of integration tests located in the `tests/` directory. These scripts act as "fake" MCP clients to verify functionality.
+
+*   **Run All Tests:**
+    ```bash
+    npm test
+    ```
+*   **Run Specific Test:**
+    ```bash
+    npm run test:control_actor
+    npm run test:manage_asset
+    npm run test:wasm
+    ```
+
+## Development Conventions
+
+*   **Language:**
+    *   Server logic is written in **TypeScript**.
+    *   Unreal integration is written in **C++**.
+    *   Performance modules are written in **Rust**.
+*   **Safety:**
+    *   The `UnrealBridge` class (`src/unreal-bridge.ts`) includes safety mechanisms like command throttling and "Safe ViewMode" switching to prevent crashing the engine with invalid commands.
+    *   **Do not** bypass these safety checks when adding new functionality.
+*   **Linting:**
+    *   TypeScript: `npm run lint`
+    *   C++/C#: Scripts provided (`npm run lint:cpp`, `npm run lint:csharp`) rely on external tools like `cpplint` and `dotnet-format`.
+
+## Directory Structure
+
+*   `src/`: Source code for the Node.js MCP server.
+    *   `tools/`: Definitions for MCP tools (Actors, Assets, etc.).
+    *   `resources/`: Definitions for MCP resources.
+    *   `wasm/`: Compiled WebAssembly bindings.
+*   `Plugins/`: Source code for the Unreal Engine C++ plugin.
+*   `wasm/`: Source code for the Rust WebAssembly module.
+*   `tests/`: Integration tests and test runners.
+*   `scripts/`: Utility scripts for build and maintenance.
+
+# Project Rules Agent
+
+- The user explicitly wants real, working code only. I must never add mocks, placeholders, false-passed success code, or any non-functional code. All solutions should be directly applicable to a live editor and pass all relevant tests genuinely.
+- The user explicitly requires real, working code only. I must never add mocks, placeholders, false-passed success codes, or any non-functional code. All solutions must be directly applicable to a live editor and pass all relevant tests genuinely.
+- Always read full file content.
+- Engine path: X:\Unreal_Engine\UE_5.0\Engine
+- Engine path: X:\Unreal_Engine\UE_5.6\Engine
+- Engine path: X:\Unreal_Engine\UE_5.7\Engine
+- Before editing codes in plugin make sure to check before in engine's code so that all code are correct.