CU-MCP-Bridge

BepInEx mod + Python MCP server that lets AI assistants control Casualties Unknown gameplay in real time over a local HTTP link.

Requirements

• Windows, Linux, or macOS — the game may run natively or under Proton/Wine; a 127.0.0.1 HTTP socket bridges the two either way

• Casualties Unknown (Steam)

• Python 3.10+ (standard library only — no pywin32)

• .NET SDK (for building the mod)

• BepInEx installed in the game

Related MCP server: Unity-MCP

Quick start

1. Install the mod

Copy the two DLLs from mod/ into your game's BepInEx/plugins/ folder:

<game directory>/BepInEx/plugins/CU-MCP-Mod.dll
<game directory>/BepInEx/plugins/Newtonsoft.Json.dll

2. Install Python dependencies

With uv (recommended — pyproject.toml + uv.lock are checked in):

uv sync

or with pip:

pip install -r requirements.txt

Standard library only otherwise — no pywin32, no native transport dependency.

3. Configure your AI client

Add to your MCP configuration (e.g. opencode.json):

{
  "mcp": {
    "servers": {
      "cu-mcp-bridge": {
        "type": "stdio",
        "command": "python",
        "args": ["src/bridge_server/server.py"],
        "cwd": "/path/to/CU-MCP-Bridge"
      }
    }
  }
}

4. Play

1. Start the game, enter a level

2. Start the Python server: python src/bridge_server/server.py (usually launched for you by the MCP client via the config above)

3. Ask your AI assistant to control the player

Start order no longer matters: the mod keeps polling until the server is up, and the server queues anything it wants to send until the mod connects.

Configuration

The mod and server rendezvous on http://127.0.0.1:8765 by default.

• Server: set CU_MCP_HTTP_HOST / CU_MCP_HTTP_PORT before launching server.py.

• Mod: set "http_url" in cu_mcp_config.json (next to the game executable), e.g. { "http_url": "http://127.0.0.1:8765" }.

Both must point at the same host/port.

Building from source

# Build the C# mod
dotnet build BepInEx/CU-MCP-Mod.csproj -c Release

# Deploy to game (kills the game process, rebuilds, copies DLL)
.\deploy.ps1 -Action deploy

Output: BepInEx/bin/Release/net472/CU-MCP-Mod.dll

Architecture

AI Client (opencode)
        |
    stdio (JSON-RPC)
        |
Python FastMCP Server (src/bridge_server/)   <-- HTTP server on 127.0.0.1:8765
        |
    Local HTTP (newline-delimited JSON Message bodies)
        |
C# BepInEx Mod (BepInEx/, inside Unity game) <-- HTTP client (poll + post)
        |
    Unity Game (Casualties Unknown)

Communication

The mod drives both directions against the server:

• GET /poll?timeout=<sec> — long-poll for the next AI -> Game message (order / query / contingency); 204 means "nothing yet, poll again".

• POST /message — Game -> AI player state, query/search results, order results, acks, interrupts (newline-delimited JSON; batches allowed).

• GET /health — liveness / connected flag.

Message payloads are byte-for-byte the same newline-delimited JSON Message objects the previous named-pipe transport used. Each order still blocks on the MCP side until the mod reports completion (success/failure/timeout).

Project structure

CU-MCP-Bridge/
├── BepInEx/                # C# mod source (BepInEx plugin)
│   ├── Executor/           # Order execution, pathfinding, movement
│   ├── Collector/          # Game state collection (player, environment)
│   ├── Contingency/        # Local condition-action rules
│   ├── Transport/          # HTTP bridge client + wire protocol
│   ├── AIPlayerManager.cs  # AI companion creation/destruction
│   ├── BridgePlugin.cs     # Entry point, tick loop
│   └── DebugGUI.cs         # F6 debug panel
├── src/bridge_server/      # Python MCP server
│   ├── server.py           # MCP tool definitions
│   ├── state_manager.py    # inbound reader, state cache
│   ├── order_manager.py    # Order queue
│   ├── transport.py        # HTTP bridge server (stdlib http.server)
│   ├── pipe_server.py      # back-compat shim -> transport.py
│   └── contingency.py      # Contingency rule manager
├── tests/                  # Unit & integration tests
├── deploy.ps1              # Build + deploy script
└── requirements.txt        # Python dependencies

MCP Tools

Known issues

• Skin mod compatibility: Installing third-party skin mods (e.g. "Skin Sync") may cause the AI companion to display a duplicate tail that mirrors the human player's tail. This is a skin mod compatibility issue and does not occur in the vanilla game.

License

MIT