Skip to content

GEMINI.md

Latest commit

 

History

History
99 lines (78 loc) · 4.06 KB

GEMINI.md

File metadata and controls

99 lines (78 loc) · 4.06 KB
Raw

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).

Building and Running

Prerequisites

  • Node.js (v18 or higher)
  • Unreal Engine (5.0-5.7)

Setup

  1. Install Dependencies:

    npm install

  2. Build the Server:

    npm run build
    1. Unreal Plugin Installation:
    • 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:

npm start

Or for development with ts-node:

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: 
    npm test
  • Run Specific Test: 
    npm run test:control_actor
npm run test:manage_asset

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.
  • Plugins/: Source code for the Unreal Engine C++ plugin.
  • 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.