qFoldIT Toolbelt — UNIGINE 2 / UNIGINE 2 Sim

84 composite editor-automation tools for UNIGINE 2, exposed to AI agents via a companion MCP bridge that sits alongside UNIGINE's own official MCPBridge Plugin.

Built by qFoldIT — foundation release, 2026

What this is, and how it relates to UNIGINE's MCPBridge Plugin

UNIGINE already publishes an official MCPBridge Plugin on the Add-On
Store: a built-in MCP server that runs directly inside the Editor with 27
low-level tools (primitives, node templates, transforms, materials,
components, XML inspect/import, console commands). That plugin is the
foundation layer — it needs no external process and is the right place for
raw editor control.

qFoldIT Toolbelt is a companion, not a replacement. It adds a second
layer of higher-level, composite tools the same way
UEFN Toolbelt adds 355
named commands on top of UEFN's raw Python API instead of making an agent
write one-off scripts every call:

Instead of an agent issuing a dozen raw primitive-creation + transform
calls to lay out a competitive arena, it calls:

arena_generate(size="medium")
procedural_place(pattern="circle", count=12, radius=8, node_path="props/crate.node")
material_team_color_split(team_a_contains="RedSpawn", team_b_contains="BlueSpawn")

Why a separate external bridge (and not registered inside MCPBridge itself)

UNIGINE has not currently published a documented API for third parties to
register additional tools directly into MCPBridge's in-process MCP server.
So instead of guessing at an undocumented internal hook, this toolbelt uses
the same two-process pattern UEFN Toolbelt uses for exactly the same
reason (UEFN has no native MCP at all): an external mcp_server.py bridge
that any MCP client connects to over stdio, relaying calls over local HTTP
to a listener running inside the Editor.

Claude / any MCP client
    │  MCP protocol (stdio)
    ▼
mcp_server.py            (external, this repo)
    │  HTTP POST 127.0.0.1:8766
    ▼
UNIGINE 2 Editor process
    ├── MCPBridge Plugin (official, UNIGINE)  — 27 base tools, its own MCP server
    └── qFoldIT ToolbeltListener.cs (this repo) — 25 composite tools, HTTP listener

Both run side by side. If UNIGINE later documents a plugin-extension API
for MCPBridge, the tool logic here (in editor_plugin/Tools/*.cs) can be
re-registered directly into it — only the transport (mcp_server.py +
ToolbeltListener.cs) would need to change.

See ARCHITECTURE.md for the full design and
docs/TOOL_REFERENCE.md for every tool's signature.

⚠ Before you build

None of this repository's Unigine.* calls were compiled or run against a
live UNIGINE installation — this was written without access to the SDK.
Exact property vs. method access, primitive mesh asset paths, widget
constructor signatures, and physics/navigation type availability do vary
between SDK versions. Check each call against Help → API
Documentation in your SDK Browser (targeting 2.20/2.21, matching what
MCPBridge Plugin lists as supported) before relying on this in a real
project.

editor_plugin/UnigineCompat.cs holds the core node/material/transform
operations shared across every tool file. The expanded tool set added in
this release (Lighting, Physics, UI, Audio, Camera, Particles, Navigation,
Components, etc.) calls Unigine.* more directly where a shared helper
didn't make sense for a single-use API — each of those files carries its
own ⚠ comment block at the top calling out exactly which calls are most
likely to need adjusting.

Install

1. You already have MCPBridge Plugin (UNIGINE's official plugin)
   installed — confirmed by your Add-On Store purchase. Keep it enabled;
   qFoldIT Toolbelt runs alongside it, not instead of it.
2. Copy editor_plugin/ into your UNIGINE project (e.g. under
   source/qfoldit_toolbelt/) and add ToolbeltBootstrap as a world
   script / autostart WorldLogic component so it initializes with the
   Editor.
3. Install the Python bridge dependency:

   pip install mcp
   

4. Register the bridge with your MCP client. Example for Claude Code
   (.mcp.json):

   {
     "mcpServers": {
       "qfoldit-unigine-toolbelt": {
         "command": "python",
         "args": ["<ABSOLUTE_PATH>/qfoldit-unigine-toolbelt/mcp_server.py"]
       }
     }
   }
   

5. Open the Editor (so ToolbeltBootstrap.Init() starts the listener),
   then connect your MCP client. Call list_toolbelt_tools to confirm the
   handshake.

Tool categories (84 tools total)

Roadmap to parity

This release brings the toolbelt to 84 real tools across 23 categories
— still short of UEFN Toolbelt's 355 and well beyond MCPBridge's 27, but a
large step up from the initial 25-tool foundation release. More
importantly, this release adds the UAG Bridge (uag_validate /
uag_apply): the piece that actually connects UNIGINE-TOOLBELT to the
rest of the qFoldIT stack (SOS → SKG → SEM → UAG → UWI → MCP), mirroring
UEFN-TOOLBELT's unreal-world-builder skill and structured identically to
UNITY-TOOLBELT's own UAG Bridge — same schema, same validation rules, same
"call existing tools, report gaps explicitly" contract, so a single UAG
document is interchangeable between the two engine adapters. See
docs/UAG_BRIDGE.md for the exact contract and
mapping table, and tests/uag_validator/ + tests/uag_bridge_simulation/
for how its logic was verified without a live UNIGINE installation.

Categories most likely to need SDK-version adjustment before production
use (see the ⚠ notes at the top of each file): Physics, Navigation,
Animation-adjacent (Particles), UI (Widget API), and Components (C#
component system availability varies by SDK version).

License

AGPL-3.0, with an additional visible-attribution requirement — see LICENSE. Any tool built on this codebase must credit qFoldIT and link back to this repository (see LICENSE for the exact wording); network/hosted use requires publishing your modified source.