Arenula

nyx000.github.io/arenula-mcp

MCP server suite for the s&box game engine. Connects AI coding assistants to the s&box editor — reading scenes, creating objects, compiling code, managing assets, and more.

Designed following Anthropic's MCP best practices: omnibus tools with action enums, rich descriptions with negative guidance, trimmed responses, actionable errors.

Arenula — Latin for "grain of sand". One grain in the sandbox.

Response envelope

Mutation tools return JSON with these fields:

• message — short human-readable confirmation.

• verified — (optional) read-back of state after the mutation, so callers can confirm the change actually stuck. E.g. after component.add: { "component_exists": true, "component_type": "ModelRenderer" }. After terrain.configure_clutter: { "clutter_assigned": "volcano_ground", "seed": 42, "mode": "Infinite" }. When this field is missing the caller should assume the mutation is unverified.

• warnings — (optional) array of per-field partial-success notes, each { field, message, suggestion? }. Used where the main operation succeeded but some sub-step was skipped — e.g. networking.add_helper with a mix of valid and invalid spawn-point IDs will return the helper wired up and a warning per bad ID.

Errors still return the standard { error, action, suggestion } body with isError: true. Any user-facing value that can't be resolved to a real engine resource now errors with an actionable suggestion rather than silently no-op'ing.

Related MCP server: sbox-mcp-documentation

Servers

Setup

1. Clone Arenula-MCP

Clone or download this repo somewhere on your machine. This is where the API and Docs servers will live — they don't need to be inside your s&box project.

C:\Projects\Arenula-MCP\       <-- can be anywhere you like
  editor/                      goes into your s&box project (step 2)
  api/                         stays here, runs from here
  docs/                        stays here, runs from here

2. Editor plugin

Copy editor/ into your s&box project's Libraries folder:

YourProject/
  Libraries/
    arenula_mcp/               <-- copy the contents of editor/ here
      Editor/
        Core/
        Handlers/
      sbox_mcp.sbproj

Open s&box — Arenula compiles automatically and starts the MCP server on port 8098.

3. Build API & Docs

From the Arenula-MCP root, install and build both Node.js servers:

npm run setup        # installs dependencies and builds both servers

This builds api/dist/index.js and docs/dist/index.js — those are the files your AI client will point to.

4. Configure your AI client

Add a .mcp.json file to your s&box project root (or copy .mcp.json.example). Update the paths to where you cloned Arenula-MCP:

{
  "mcpServers": {
    "editor": {
      "type": "sse",
      "url": "http://localhost:8098/sse"
    },
    "api": {
      "command": "node",
      "args": ["C:/Projects/Arenula-MCP/api/dist/index.js"],
      "env": {
        "SBOX_API_URL": "https://cdn.sbox.game/releases/..."
      }
    },
    "docs": {
      "command": "node",
      "args": ["C:/Projects/Arenula-MCP/docs/dist/index.js"]
    }
  }
}

Replace C:/Projects/Arenula-MCP with wherever you cloned the repo. Get the latest API schema URL from sbox.game/api/schema (click Download, copy URL).

Tools appear as mcp__editor__*, mcp__api__*, mcp__docs__* in your AI client.

Editor Tools

23 omnibus tools, 182 actions. Each tool takes a required action parameter.

Architecture

33 C# source files — 9 core infrastructure, 24 per-tool handlers (incl. ConsoleHandler).

Attribution

• Editor based on Ozmium MCP Server by ozmium7 (GPL-3.0)

• API based on sbox-api-mcp by sofianebel (MIT)

• Docs based on sbox-docs-mcp by sofianebel (MIT)

License

GPL-3.0 (Editor) · MIT (API, Docs, schemagen) — see LICENSE for why the split exists and which one applies to code you copy.