unreal-engine-mcp-server 0.4.7 → 0.5.0

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

@@ -2,31 +2,32 @@ name: Publish to MCP Registry
 
 on:
   push:
-    tags: ["v*"]  # Triggers on version tags like v1.2.0
-  workflow_dispatch:  # Allow manual triggering
+    tags: ["v*"]
+  workflow_dispatch:
 
 jobs:
   publish:
     runs-on: ubuntu-latest
     permissions:
-      id-token: write  # Required for OIDC authentication
+      id-token: write
       contents: read
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:
           node-version: "20"
           registry-url: "https://registry.npmjs.org"
+          cache: 'npm'
 
       - name: Install dependencies
         run: npm ci
 
-      - name: Run tests
-        run: npm run test
+      - name: Run smoke tests
+        run: npm run test:smoke
         continue-on-error: true
 
       - name: Run linting
@@ -59,17 +60,21 @@ jobs:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
       - name: Install MCP Publisher
+        if: ${{ success() }}
         run: |
           curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.1.0/mcp-publisher_1.1.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
           chmod +x mcp-publisher
 
       - name: Login to MCP Registry
+        if: ${{ success() }}
         run: ./mcp-publisher login github-oidc
 
       - name: Publish to MCP Registry
+        if: ${{ success() }}
         run: ./mcp-publisher publish
 
       - name: Verify publication
+        if: ${{ always() }}
         run: |
           echo "Waiting for registry to update..."
           sleep 30

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

@@ -0,0 +1,23 @@
+name: Release Drafter
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  update_release_draft:
+    permissions:
+      contents: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: release-drafter/release-drafter@v6.1.0 # v6.1.0
+        with:
+          config-name: release-drafter.yml
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/release.yml

@@ -0,0 +1,112 @@
+name: Create GitHub Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Create Release
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4 # v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4 # v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build package
+        run: npm run build
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+          echo "Releasing version: $VERSION"
+
+      - name: Extract changelog for this version
+        id: changelog
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+          
+          CHANGELOG=$(awk -v ver="$VERSION" '
+            $0 ~ "## .*\\[" ver "\\]" { found=1; next }
+            found && /^## .*\[/ { exit }
+            found { print }
+          ' CHANGELOG.md)
+          
+          if [ -z "$CHANGELOG" ]; then
+            CHANGELOG="Release ${{ steps.version.outputs.tag }}"
+          fi
+          
+          echo "$CHANGELOG" > release_notes.md
+          echo "Generated release notes:"
+          cat release_notes.md
+
+      - name: Create dist archive
+        run: |
+          mkdir -p release-artifacts
+          
+          tar -czvf release-artifacts/unreal-engine-mcp-server-${{ steps.version.outputs.version }}.tar.gz \
+            dist/ \
+            package.json \
+            README.md \
+            CHANGELOG.md \
+            LICENSE
+          
+          zip -r release-artifacts/unreal-engine-mcp-server-${{ steps.version.outputs.version }}.zip \
+            dist/ \
+            package.json \
+            README.md \
+            CHANGELOG.md \
+            LICENSE
+
+      - name: Create Plugin archive
+        run: |
+          if [ -d "plugins/McpAutomationBridge" ]; then
+            tar -czvf release-artifacts/McpAutomationBridge-plugin-${{ steps.version.outputs.version }}.tar.gz \
+              plugins/McpAutomationBridge/
+            
+            zip -r release-artifacts/McpAutomationBridge-plugin-${{ steps.version.outputs.version }}.zip \
+              plugins/McpAutomationBridge/
+            
+            echo "Plugin archive created"
+          else
+            echo "Plugin directory not found, skipping plugin archive"
+          fi
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@c062e08bd532815e2082a85e87e3ef29c3e6d191 # v2.0.8
+        with:
+          name: Release ${{ steps.version.outputs.tag }}
+          body_path: release_notes.md
+          draft: false
+          prerelease: ${{ contains(github.ref, 'alpha') || contains(github.ref, 'beta') || contains(github.ref, 'rc') }}
+          files: |
+            release-artifacts/*
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Release Summary
+        run: |
+          echo "## Release Created Successfully! 🎉" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Version:** ${{ steps.version.outputs.tag }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Artifacts:" >> $GITHUB_STEP_SUMMARY
+          ls -la release-artifacts/ >> $GITHUB_STEP_SUMMARY

package/.github/workflows/semantic-pull-request.yml

@@ -0,0 +1,35 @@
+name: "Semantic Pull Request"
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+permissions:
+  pull-requests: read
+  statuses: write
+
+jobs:
+  main:
+    name: Validate PR Title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            build
+            ci
+            chore
+            revert
+          requireScope: false

package/.github/workflows/smoke-test.yml

@@ -0,0 +1,36 @@
+name: Smoke Test (Mock Mode)
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  smoke-test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+    
+    - name: Use Node.js
+      uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+      with:
+        node-version: '20.x'
+        cache: 'npm'
+        
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Build
+      run: npm run build
+
+    - name: Run Smoke Test
+      run: npm run test:smoke
+      env:
+        MOCK_UNREAL_CONNECTION: "true"

package/.github/workflows/stale.yml

@@ -0,0 +1,28 @@
+name: '🏷️ Stale Issue and PR Management'
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@997185467fa4f803885201cee163a9f38240193d # v10.1.1
+        with:
+          stale-issue-message: 'This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 14 days if no further activity occurs. Thank you for your contributions!'
+          stale-pr-message: 'This pull request has been automatically marked as stale because it has not had recent activity. It will be closed in 14 days if no further activity occurs. Please update your PR or add a comment if you would like to keep it open.'
+          close-issue-message: 'This issue was closed because it has been stale for 14 days with no activity.'
+          close-pr-message: 'This pull request was closed because it has been stale for 14 days with no activity.'
+          days-before-stale: 60
+          days-before-close: 14
+          stale-issue-label: 'stale'
+          stale-pr-label: 'stale'
+          exempt-issue-labels: 'pinned,security,bug,enhancement'
+          exempt-pr-labels: 'pinned,security'
+          operations-per-run: 100

package/CHANGELOG.md

@@ -1,43 +1,279 @@
-# Changelog
+# 📋 Changelog
 
 All notable changes to this project will be documented in this file.
 
-## [0.4.7] - 2025-11-16
-### Added
-- Output Log reading via `system_control` tool with `read_log` action. Supports filtering by category (comma-separated or array), log level (Error, Warning, Log, Verbose, VeryVerbose, All), line count (up to 2000), specific log path, include prefixes, and exclude categories. Automatically resolves the latest project log under Saved/Logs.
-- New `src/tools/logs.ts` implementing robust log tailing, parsing (timestamp/category/level/message), and UE-specific internal entry filtering (e.g., excludes LogPython RESULT: blocks unless requested).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-### Changed
-- `system_control` tool schema: Added `read_log` action with full filter parameters to inputSchema; extended outputSchema with `logPath`, `entries` array, and `filteredCount`.
-- Updated `src/tools/consolidated-tool-handlers.ts` to route `read_log` to LogTools without requiring UE connection (file-based).
-- `src/index.ts`: Instantiates and passes LogTools to consolidated handler.
-- Version bumped to 0.4.7 in package.json, package-lock.json, server.json, .env.production, and runtime config.
+---
 
-## [0.4.6] - 2025-10-04
-### Fixed
-- Fixed duplicate response output issue where tool responses were being displayed twice in MCP content
-- Response validator now emits concise summaries in text content instead of duplicating full JSON payloads
-- Structured content is preserved for validation and tests while user-facing output is streamlined
+## 🏷️ [0.5.0] - 2025-12-16
 
-## [0.4.5] - 2025-10-03
-### Added
-- Expose `UE_PROJECT_PATH` environment variable across runtime config, Smithery manifest, and client example configs. This allows tools that need an absolute .uproject path (e.g., engine_start) to work without additional manual configuration.
-- Added `projectPath` to the runtime `configSchema` so Smithery's session UI can inject a project path into the server environment.
+> [!IMPORTANT]
+> ### 🔄 Major Architecture Migration
+> This release marks the **complete migration** from Unreal's built-in Remote Plugin to a native C++ **McpAutomationBridge** plugin. This provides:
+> - ⚡ Better performance
+> - 🔗 Tighter editor integration  
+> - 🚫 No dependency on Unreal's Remote API
+>
+> **BREAKING CHANGE:** Response format has been standardized across all automation tools. Clients should expect responses to follow the new `StandardActionResponse` format with `success`, `data`, `warnings`, and `error` fields.
 
-### Changed
-- Make `createServer` a synchronous factory (removed `async`) and updated `createServerDefault` and `startStdioServer` to use the synchronous factory. This aligns the exported default with Smithery’s expectations and prevents auto-start mismatches in the bundled output.
-- Provide a default for `ueHost` in the exported `configSchema` so the Smithery configuration dialog pre-fills the host input.
+### 🏗️ Architecture
 
-### Documentation
-- Updated `README.md`, `claude_desktop_config_example.json`, and `mcp-config-example.json` to include `UE_PROJECT_PATH` and usage notes.
-- Updated `smithery.yaml` and `server.json` manifest to declare `UE_PROJECT_PATH` and default values.
+| Change | Description |
+|--------|-------------|
+| 🆕 **Native C++ Plugin** | Introduced `McpAutomationBridge` - a native UE5 editor plugin replacing the Remote API |
+| 🔌 **Direct Editor Integration** | Commands execute directly in the editor context via automation bridge subsystem |
+| 🌐 **WebSocket Communication** | Implemented `McpBridgeWebSocket` for real-time bidirectional communication |
+| 🎯 **Bridge-First Architecture** | All operations route through the native C++ bridge (`fe65968`) |
+| 📐 **Standardized Responses** | All tools now return `StandardActionResponse` format (`0a8999b`) |
 
-### Build
-- Rebuilt the Smithery bundle and TypeScript output to ensure schema and defaults are exported in the distributed artifact.
+### ✨ Added
 
-### Fixes
-- Fixes Smithery UI blank ueHost field by defining a default in the runtime schema.
+<details>
+<summary><b>🎮 Engine Compatibility</b></summary>
 
+- **UE 5.7 Support** - Updated McpAutomationBridge with ControlRig dynamic loading and improved sequence handling (`ec5409b`)
 
-## [0.4.4] - 2025-09-30
-- Previous release notes retained in upstream repo.
+</details>
+
+<details>
+<summary><b>🔧 New APIs & Integrations</b></summary>
+
+- **GraphQL API** - Broadened automation bridge with GraphQL support, WASM integration, UI/editor integrations (`ffdd814`)
+- **WebAssembly Integration** - High-performance JSON parsing with 5-8x performance gains (`23f63c7`)
+
+</details>
+
+<details>
+<summary><b>🌉 Automation Bridge Features</b></summary>
+
+| Feature | Commit |
+|---------|--------|
+| Server mode on port `8091` | `267aa42` |
+| Client mode with enhanced connection handling | `bf0fa56` |
+| Heartbeat tracking and output capturing | `28242e1` |
+| Event handling and asset management | `d10e1e2` |
+
+</details>
+
+<details>
+<summary><b>🎛️ New Tool Systems (0a8999b, 0ac82ac)</b></summary>
+
+| Tool | Description |
+|------|-------------|
+| 🎮 **Input Management** | New `manage_input` tool with EnhancedInput support for Input Actions and Mapping Contexts |
+| 💡 **Lighting Manager** | Full lighting configuration via `manage_lighting` including spawn, GI setup, shadow config, build lighting |
+| 📊 **Performance Manager** | `manage_performance` with profiling (CPU/GPU/Memory), optimization, scalability, Nanite/Lumen config |
+| 🌳 **Behavior Tree Editing** | Full behavior tree creation and node editing via `manage_behavior_tree` |
+| 🎬 **Enhanced Sequencer** | Track operations (add/remove tracks, set muted/solo/locked), display rate, tick resolution |
+| 🌍 **World Partition** | Cell management, data layer toggling via `manage_level` |
+| 🖼️ **Widget Management** | UI widget creation, visibility controls, child widget adding |
+
+</details>
+
+<details>
+<summary><b>📊 Graph Editing Capabilities (0a8999b)</b></summary>
+
+- **Blueprint Graph** - Direct node manipulation with `manage_blueprint_graph` (create_node, delete_node, connect_pins, etc.)
+- **Material Graph** - Node operations via `manage_asset` (add_material_node, connect_material_pins, etc.)
+- **Niagara Graph** - Module and parameter editing (add_niagara_module, set_niagara_parameter, etc.)
+
+</details>
+
+<details>
+<summary><b>🛠️ New Handlers & Actions</b></summary>
+
+- Blueprint graph management and Niagara functionalities (`aff4d55`)
+- Physics simulation setup in AnimationTools (`83a6f5d`)
+- **New Asset Actions:**
+  - `generate_lods`, `add_material_parameter`, `list_instances`
+  - `reset_instance_parameters`, `get_material_stats`, `exists`
+  - `nanite_rebuild_mesh`
+- World partition and rendering tool handlers (`83a6f5d`)
+- Screenshot with base64 image encoding (`bb4f6a8`)
+
+</details>
+
+<details>
+<summary><b>🧪 Test Suites</b></summary>
+
+**50+ new test cases** covering:
+- Animation, Assets, Materials
+- Sequences, World Partition
+- Blueprints, Niagara, Behavior Trees
+- Audio, Input Actions
+- And more! (`31c6db9`, `85817c9`, `fc47839`, `02fd2af`)
+
+</details>
+
+### 🔄 Changed
+
+#### Core Refactors
+| Component | Change | Commit |
+|-----------|--------|--------|
+| `SequenceTools` | Migrated to Automation Bridge | `c2fb15a` |
+| `UnrealBridge` | Refactored for bridge connection | `7bd48d8` |
+| Automation Dispatch | Editor-native handlers modernization | `c9db1a4` |
+| Test Runner | Timeout expectations & content extraction | `c9766b0` |
+| UI Handlers | Improved readability and organization | `bb4f6a8` |
+| Connection Manager | Streamlined connection handling | `0ac82ac` |
+
+#### Tool Improvements
+- 🚗 **PhysicsTools** - Vehicle config logic updated, deprecated checks removed (`6dba9f7`)
+- 🎬 **AnimationTools** - Logging and response normalization (`7666c31`)
+- ⚠️ **Error Handling** - Utilities refactored, INI file reader added (`f5444e4`)
+- 📐 **Blueprint Actions** - Timeout handling enhancements (`65d2738`)
+- 🎨 **Materials** - Enhanced material graph editing capabilities (`0a8999b`)
+- 🔊 **Audio** - Improved sound component management (`0a8999b`)
+
+#### Other Changes
+- 📡 **Connection & Logging** - Improved error messages for clarity (`41350b3`)
+- 📚 **Documentation** - README updated with UE 5.7, WASM docs, architecture overview, 17 tools (`8d72f28`, `4d77b7e`)
+- 🔄 **Dependencies** - Updated to latest versions (`08eede5`)
+- 📝 **Type Definitions** - Enhanced tool interfaces and type coverage (`0a8999b`)
+
+### 🐛 Fixed
+
+- `McpAutomationBridgeSubsystem` - Header removal, logging category, heartbeat methods (`498f644`)
+- `McpBridgeWebSocket` - Reliable WebSocket communication (`861ad91`)
+- **AutomationBridge** - Heartbeat handling and server metadata retrieval (`0da54f7`)
+- **UI Handlers** - Missing payload and invalid widget path error handling (`bb4f6a8`)
+- **Screenshot** - Clearer error messages and flow (`bb4f6a8`)
+
+### 🗑️ Removed
+
+| Removed | Reason |
+|---------|--------|
+| 🔌 Remote API Dependency | Replaced by native C++ plugin |
+| 🐍 Python Fallbacks | Native C++ automation preferred (`fe65968`) |
+| 📦 Unused HTTP Client | Cleanup from error-handler (`f5444e4`) |
+
+---
+
+## 🏷️ [0.4.7] - 2025-11-16
+
+### ✨ Added
+- Output Log reading via `system_control` tool with `read_log` action. filtering by category, level, line count.
+- New `src/tools/logs.ts` implementing robust log tailing.
+- 🆕 Initial `McpAutomationBridge` plugin with foundational implementation (`30e62f9`)
+- 🧪 Comprehensive test suites for various Unreal Engine tools (`31c6db9`)
+
+### 🔄 Changed
+- `system_control` tool schema: Added `read_log` action.
+- Updated tool handlers to route `read_log` to LogTools.
+- Version bumped to 0.4.7.
+
+### 📚 Documentation
+- Updated README.md with initial bridge documentation (`a24dafd`)
+
+---
+
+## 🏷️ [0.4.6] - 2025-10-04
+
+### 🐛 Fixed
+- Fixed duplicate response output issue where tool responses were displayed twice in MCP content
+- Response validator now emits concise summaries instead of duplicating full JSON payloads
+- Structured content preserved for validation while user-facing output is streamlined
+
+---
+
+## 🏷️ [0.4.5] - 2025-10-03
+
+### ✨ Added
+- 🔧 Expose `UE_PROJECT_PATH` environment variable across runtime config, Smithery manifest, and client configs
+- 📁 Added `projectPath` to runtime `configSchema` for Smithery's session UI
+
+### 🔄 Changed
+- ⚡ Made `createServer` synchronous factory (removed `async`)
+- 🏠 Default for `ueHost` in exported `configSchema`
+
+### 📚 Documentation
+- Updated `README.md`, config examples to include `UE_PROJECT_PATH`
+- Updated `smithery.yaml` and `server.json` manifests
+
+### 🔨 Build
+- Rebuilt Smithery bundle and TypeScript output
+
+### 🐛 Fixed
+- Smithery UI blank `ueHost` field by defining default in runtime schema
+
+---
+
+## 🏷️ [0.4.4] - 2025-09-28
+
+### ✨ Improvements
+
+- 🤝 **Client Elicitation Helper** - Added support for Cursor, VS Code, Claude Desktop, and other MCP clients
+- 📊 **Consistent RESULT Parsing** - Handles JSON5 and legacy Python literals across all tools
+- 🔒 **Safe Output Stringification** - Robust handling of circular references and complex objects
+- 🔍 **Enhanced Logging** - Improved validation messages for easier debugging
+
+---
+
+## 🏷️ [0.4.0] - 2025-09-20
+
+> **Major Release** - Consolidated Tools Mode
+
+### ✨ Improvements
+
+- 🎯 **Consolidated Tools Mode Exclusively** - Removed legacy mode, all tools now use unified handler system
+- 🧹 **Simplified Tool Handlers** - Removed deprecated code paths and inline plugin validation
+- 📝 **Enhanced Error Handling** - Better error messages and recovery mechanisms
+
+### 🔧 Quality & Maintenance
+
+- ⚡ Reduced resource usage by optimizing tool handlers
+- 🧹 Cleanup of deprecated environment variables
+
+---
+
+## 🏷️ [0.3.1] - 2025-09-19
+
+> **BREAKING:** Connection behavior is now on-demand
+
+### 🏗️ Architecture
+
+- 🔄 **On-Demand Connection** - Shifted to intelligent on-demand connection model
+- 🚫 **No Background Processes** - Eliminated persistent background connections
+
+### ⚡ Performance
+
+- Reduced resource usage and eliminated background processes
+- Optimized connection state management
+
+### 🛡️ Reliability
+
+- Improved error handling and connection state management
+- Better recovery from connection failures
+
+---
+
+## 🏷️ [0.3.0] - 2025-09-17
+
+> 🎉 **Initial Public Release**
+
+### ✨ Features
+
+- 🎮 **13 Consolidated Tools** - Full suite of Unreal Engine automation tools
+- 📁 **Normalized Asset Listing** - Auto-map `/Content` and `/Game` paths
+- 🏔️ **Landscape Creation** - Returns real UE/Python response data
+- 📝 **Action-Oriented Descriptions** - Enhanced tool documentation with usage examples
+
+### 🔧 Quality & Maintenance
+
+- Server version 0.3.0 with clarified 13-tool mode
+- Comprehensive documentation and examples
+- Lint error fixes and code style cleanup
+
+---
+
+<div align="center">
+
+### 🔗 Links
+
+[![GitHub](https://img.shields.io/badge/GitHub-Repository-181717?style=for-the-badge&logo=github)](https://github.com/ChiR24/Unreal_mcp)
+[![npm](https://img.shields.io/badge/npm-Package-CB3837?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/unreal-engine-mcp-server)
+[![UE5](https://img.shields.io/badge/Unreal-5.6%20|%205.7-0E1128?style=for-the-badge&logo=unrealengine)](https://www.unrealengine.com/)
+
+</div>