# MCPBridge Server

Companion MCP server for the **MCP Bridge** Unreal Engine 4.27 editor plugin.
It translates [Model Context Protocol](https://modelcontextprotocol.io) tool
calls from AI coding agents (Claude Code, Codex, Cursor, or any MCP client)
into HTTP commands for the listener that the plugin runs inside the Unreal
editor.

```
AI agent (MCP client) --stdio--> this server --HTTP localhost:8080--> UE4.27 editor (MCP Bridge plugin)
```

All communication stays on your machine: the server talks only to
`localhost:8080`, where the plugin's in-editor listener accepts connections
from the local machine only.

## Requirements

- Node.js 18 or newer
- The MCP Bridge plugin installed and enabled in a UE 4.27 project
  (available on Fab; the plugin's Quick Start covers editor setup)

## Setup

```bash
npm install
npm run build
```

Then register the server with your MCP client. For Claude Code, add this to
your project's `.mcp.json` (adjust the path to where you cloned this repo):

```json
{
  "mcpServers": {
    "unreal-bridge": {
      "command": "node",
      "args": ["<path-to-this-repo>/dist/index.js"]
    }
  }
}
```

Start your UE 4.27 project with the plugin enabled, then ask your agent to
run `test_connection`. A healthy reply includes the engine version and
project paths.

## What the tools cover

150+ tools across: actor and level editing, Blueprint creation and
compilation, Blueprint member/graph editing with schema-validated pin
connections, gameplay framework generation (GameMode/Character/controller/HUD
with class defaults wired), input mappings and control-scheme presets, camera
rig presets, Blackboards and Behavior Trees built from JSON, C++ class
generation and UnrealBuildTool compilation as background jobs with structured
error reporting, materials and material instances, DataTables, audio
components, map creation, viewport control and screenshots, and a searchable
project intelligence index.

Every editor mutation runs in a UE4 transaction (undo works), compiles and
saves the affected asset, and reports failure explicitly - a broken Blueprint
is never reported as success.

## Tests

```bash
npm test              # unit tests against a mock listener; no Unreal needed
npm run test:integration  # requires UE 4.27 running with the plugin listener
```

The registry-consistency test cross-checks this server's tools against the
plugin's Python command router; it runs in the plugin's development
repository and skips automatically here.

## Versioning

Server and plugin versions track each other (this is v0.4.0, matching plugin
v0.4.0). When updating one, update the other.

## License

MIT - see [LICENSE](LICENSE).