unreal-engine-mcp-server 0.2.1

package/.dockerignore

@@ -0,0 +1,57 @@
+# Git
+.git
+.gitignore
+
+# Node modules
+node_modules
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# TypeScript build output (will be built in Docker)
+dist
+
+# Development files
+.env
+.env.local
+.env.development
+.env.test
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+*.swn
+.DS_Store
+
+# Testing
+coverage
+.nyc_output
+*.test.ts
+*.spec.ts
+
+# Documentation
+README.md
+CONTRIBUTING.md
+CHANGELOG.md
+LICENSE
+
+# Docker
+Dockerfile
+.dockerignore
+docker-compose*.yml
+
+# CI/CD
+.github
+.gitlab-ci.yml
+.travis.yml
+
+# Logs
+logs
+*.log
+
+# Temporary files
+tmp
+temp
+*.tmp

package/.env.production

@@ -0,0 +1,25 @@
+# Production Configuration for Unreal Engine MCP Server
+
+# Unreal Engine Remote Control Settings
+UE_HOST=127.0.0.1
+UE_RC_HTTP_PORT=30010
+UE_RC_WS_PORT=30020
+
+# Tool Mode Configuration
+# Set to 'false' to use individual tools (36+), 'true' or unset for consolidated (10)
+USE_CONSOLIDATED_TOOLS=true
+
+# Logging Level
+LOG_LEVEL=info
+
+# Server Settings
+SERVER_NAME=unreal-engine-mcp
+SERVER_VERSION=1.0.0
+
+# Connection Settings
+MAX_RETRY_ATTEMPTS=3
+RETRY_DELAY_MS=2000
+
+# Performance Settings
+REQUEST_TIMEOUT_MS=30000
+WEBSOCKET_KEEPALIVE_MS=30000

package/.eslintrc.json

@@ -0,0 +1,54 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2022,
+    "sourceType": "module",
+    "project": "./tsconfig.json"
+  },
+  "plugins": [
+    "@typescript-eslint"
+  ],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "env": {
+    "node": true,
+    "es2022": true
+  },
+  "rules": {
+    "@typescript-eslint/no-unused-vars": [
+      "warn",
+      {
+        "args": "all",
+        "argsIgnorePattern": "^_",
+        "caughtErrors": "all",
+        "caughtErrorsIgnorePattern": "^_",
+        "destructuredArrayIgnorePattern": "^_",
+        "varsIgnorePattern": "^_",
+        "ignoreRestSiblings": true
+      }
+    ],
+    "@typescript-eslint/no-explicit-any": "off",
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "@typescript-eslint/no-non-null-assertion": "warn",
+    "no-console": "off",
+    "semi": ["error", "always"],
+    "quotes": ["error", "single", { "avoidEscape": true }],
+    "no-empty": ["error", { "allowEmptyCatch": true }],
+    "no-useless-escape": "warn",
+    "no-case-declarations": "off",
+    "prefer-const": "warn",
+    "no-unused-vars": "off"
+  },
+  "ignorePatterns": [
+    "dist/",
+    "node_modules/",
+    "*.js",
+    "*.d.ts",
+    "*.cjs",
+    "vitest.config.ts",
+    "test-*.js"
+  ]
+}

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

@@ -0,0 +1,75 @@
+name: Publish to MCP Registry
+
+on:
+  push:
+    tags: ["v*"]  # Triggers on version tags like v1.2.0
+  workflow_dispatch:  # Allow manual triggering
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Required for OIDC authentication
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm run test
+        continue-on-error: true
+
+      - name: Run linting
+        run: npm run lint
+
+      - name: Build package
+        run: npm run build
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          if [[ ${{ github.event_name }} == "push" && ${{ github.ref }} == refs/tags/* ]]; then
+            VERSION=${GITHUB_REF#refs/tags/v}
+          else
+            VERSION=$(node -p "require('./package.json').version")
+          fi
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Publishing version: $VERSION"
+
+      - name: Update server.json version
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+          jq --arg v "$VERSION" '.version = $v | .packages[] |= if .registry_type == "npm" then .version = $v else . end' server.json > tmp && mv tmp server.json
+          echo "Updated server.json:"
+          cat server.json
+
+      - name: Publish to npm
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Install MCP Publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+
+      - name: Login to MCP Registry
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish to MCP Registry
+        run: ./mcp-publisher publish
+
+      - name: Verify publication
+        run: |
+          echo "Waiting for registry to update..."
+          sleep 30
+          curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.ChiR24/unreal-engine-mcp" | jq '.'

package/Dockerfile

@@ -0,0 +1,54 @@
+# Multi-stage build for efficient image size
+FROM node:20-alpine AS builder
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install ALL dependencies (including dev) for building - skip prepare script
+RUN npm ci --ignore-scripts
+
+# Copy TypeScript config and source files
+COPY tsconfig.json ./
+COPY src ./src
+
+# Build the TypeScript project
+RUN npm run build
+
+# Production stage
+FROM node:20-alpine
+
+# Install dumb-init for proper signal handling
+RUN apk add --no-cache dumb-init
+
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nodejs -u 1001
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install production dependencies only (skip prepare script)
+RUN npm ci --only=production --ignore-scripts && \
+    npm cache clean --force
+
+# Copy built application from builder stage
+COPY --from=builder /app/dist ./dist
+
+# Change ownership to nodejs user
+RUN chown -R nodejs:nodejs /app
+
+# Switch to non-root user
+USER nodejs
+
+# MCP servers use stdio, no port exposure needed
+# Use dumb-init to handle signals properly
+ENTRYPOINT ["dumb-init", "--"]
+
+# Run the MCP server
+CMD ["node", "dist/cli.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Unreal Engine MCP Server Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,209 @@
+# Unreal Engine MCP Server
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![NPM Package](https://img.shields.io/npm/v/unreal-engine-mcp-server)](https://www.npmjs.com/package/unreal-engine-mcp-server)
+[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-TypeScript-blue)](https://github.com/modelcontextprotocol/sdk)
+[![Unreal Engine](https://img.shields.io/badge/Unreal%20Engine-5.0--5.6-orange)](https://www.unrealengine.com/)
+
+A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal Engine via Remote Control API. Built with TypeScript and designed for game development automation.
+
+## Features
+
+### Core Capabilities
+- **Asset Management** - Browse, import, and create materials
+- **Actor Control** - Spawn, delete, and manipulate actors with physics
+- **Editor Control** - PIE sessions, camera, and viewport management
+- **Level Management** - Load/save levels, lighting, and environment building
+- **Animation & Physics** - Blueprints, state machines, ragdolls, constraints
+- **Visual Effects** - Niagara particles, GPU simulations, procedural effects
+- **Sequencer** - Cinematics, camera animations, and timeline control
+- **Console Commands** - Safe execution with dangerous command filtering
+
+## Quick Start
+
+### Prerequisites
+- Node.js 18+
+- Unreal Engine 5.0-5.6
+- Required UE Plugins:
+  - Remote Control
+  - Web Remote Control
+  - Python Script Plugin
+  - Editor Scripting Utilities
+
+### Installation
+
+#### Option 1: NPM Package (Recommended)
+
+```bash
+# Install globally
+npm install -g unreal-engine-mcp-server
+
+# Or install locally in your project
+npm install unreal-engine-mcp-server
+```
+
+#### Option 2: Clone and Build
+
+```bash
+# Clone the repository
+git clone https://github.com/ChiR24/Unreal_mcp.git
+cd Unreal_mcp
+
+# Install dependencies and build
+npm install
+npm run build
+
+# Run directly
+node dist/cli.js
+```
+
+### Unreal Engine Configuration
+
+Add to your project's `Config/DefaultEngine.ini`:
+
+```ini
+[/Script/PythonScriptPlugin.PythonScriptPluginSettings]
+bRemoteExecution=True
+bAllowRemotePythonExecution=True
+
+[/Script/RemoteControl.RemoteControlSettings]
+bAllowRemoteExecutionOfConsoleCommands=True
+bEnableRemoteExecution=True
+bAllowPythonExecution=True
+```
+
+Then enable Python execution in: Edit > Project Settings > Plugins > Remote Control
+
+## MCP Client Configuration
+
+### Claude Desktop / Cursor
+
+#### For NPM Installation (Global)
+
+```json
+{
+  "mcpServers": {
+    "unreal-engine": {
+      "command": "unreal-engine-mcp-server",
+      "env": {
+        "UE_HOST": "127.0.0.1",
+        "UE_RC_HTTP_PORT": "30010",
+        "UE_RC_WS_PORT": "30020"
+      }
+    }
+  }
+}
+```
+
+#### For NPM Installation (Local)
+
+```json
+{
+  "mcpServers": {
+    "unreal-engine": {
+      "command": "npx",
+      "args": ["unreal-engine-mcp-server"],
+      "env": {
+        "UE_HOST": "127.0.0.1",
+        "UE_RC_HTTP_PORT": "30010",
+        "UE_RC_WS_PORT": "30020"
+      }
+    }
+  }
+}
+```
+
+#### For Clone/Build Installation
+
+```json
+{
+  "mcpServers": {
+    "unreal-engine": {
+      "command": "node",
+      "args": ["path/to/Unreal_mcp/dist/cli.js"],
+      "env": {
+        "UE_HOST": "127.0.0.1",
+        "UE_RC_HTTP_PORT": "30010",
+        "UE_RC_WS_PORT": "30020"
+      }
+    }
+  }
+}
+```
+
+## Available Tools (13 Consolidated)
+
+| Tool | Description |
+|------|-------------|
+| `manage_asset` | List, create materials, import assets |
+| `control_actor` | Spawn, delete actors, apply physics |
+| `control_editor` | PIE control, camera, view modes |
+| `manage_level` | Load/save levels, lighting |
+| `animation_physics` | Animation blueprints, ragdolls |
+| `create_effect` | Particles, Niagara, debug shapes |
+| `manage_blueprint` | Create blueprints, add components |
+| `build_environment` | Landscapes, terrain, foliage |
+| `system_control` | Profiling, quality, UI, screenshots |
+| `console_command` | Direct console command execution |
+| `manage_rc` | Remote Control presets |
+| `manage_sequence` | Sequencer/cinematics |
+| `inspect` | Object introspection |
+
+## Key Features
+
+- **Graceful Degradation** - Server starts even without UE connection
+- **Auto-Reconnection** - Attempts reconnection every 10 seconds
+- **Connection Timeout** - 5-second timeout with configurable retries
+- **Non-Intrusive Health Checks** - Uses echo commands every 30 seconds
+- **Command Safety** - Blocks dangerous console commands
+- **Input Flexibility** - Vectors/rotators accept object or array format
+- **Asset Caching** - 10-second TTL for improved performance
+
+## Supported Asset Types
+
+Blueprints, Materials, Textures, Static/Skeletal Meshes, Levels, Sounds, Particles, Niagara Systems
+
+## Example Console Commands
+
+- **Statistics**: `stat fps`, `stat gpu`, `stat memory`
+- **View Modes**: `viewmode wireframe`, `viewmode unlit`
+- **Gameplay**: `slomo 0.5`, `god`, `fly`
+- **Rendering**: `r.screenpercentage 50`, `r.vsync 0`
+
+## Configuration
+
+### Environment Variables
+
+```env
+UE_HOST=127.0.0.1              # Unreal Engine host
+UE_RC_HTTP_PORT=30010          # Remote Control HTTP port
+UE_RC_WS_PORT=30020            # Remote Control WebSocket port
+USE_CONSOLIDATED_TOOLS=true    # Use 13 consolidated tools (false = 37 individual)
+LOG_LEVEL=info                 # debug | info | warn | error
+```
+
+### Docker
+
+```bash
+docker build -t unreal-mcp .
+docker run -it --rm unreal-mcp
+```
+
+## Development
+
+```bash
+npm run build          # Build TypeScript
+npm run lint           # Run ESLint
+npm run lint:fix       # Fix linting issues
+```
+
+## Contributing
+
+Contributions welcome! Please:
+- Include reproduction steps for bugs
+- Keep PRs focused and small
+- Follow existing code style
+
+## License
+
+MIT - See [LICENSE](LICENSE) file

package/claude_desktop_config_example.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "unreal-engine": {
+      "command": "node",
+      "args": ["PathToMCP\\UnrealMCP\\unreal-engine-mcp-server\\dist\\cli.js"],
+      "env": {
+        "UE_HOST": "127.0.0.1",
+        "UE_RC_WS_PORT": "30020",
+        "UE_RC_HTTP_PORT": "30010"
+      }
+    }
+  }
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { startStdioServer } from './index.js';
+startStdioServer().catch((err) => {
+    console.error('Failed to start server:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import 'dotenv/config';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { UnrealBridge } from './unreal-bridge.js';
+export declare function createServer(): Promise<{
+    server: Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    }>;
+    bridge: UnrealBridge;
+}>;
+export declare function startStdioServer(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map