Arenula

nyx000.github.io/arenula-mcp

MCP-Server-Suite für die s&box-Spielengine. Verbindet KI-Coding-Assistenten mit dem s&box-Editor — Szenen auslesen, Objekte erstellen, Code kompilieren, Assets verwalten und mehr.

Entwickelt nach Anthropics MCP-Best Practices: Omnibus-Tools mit Aktions-Enums, ausführlichen Beschreibungen mit negativer Führung, reduzierten Antworten und umsetzbaren Fehlern.

Arenula — Lateinisch für „Sandkorn“. Ein Korn in der Sandbox.

Antwort-Envelope

Mutations-Tools geben JSON mit diesen Feldern zurück:

• message — kurze, menschenlesbare Bestätigung.

• verified — (optional) Rückschreiben des Zustands nach der Mutation, damit Aufrufer bestätigen können, dass die Änderung tatsächlich übernommen wurde. Z. B. nach component.add: { "component_exists": true, "component_type": "ModelRenderer" }. Nach terrain.configure_clutter: { "clutter_assigned": "volcano_ground", "seed": 42, "mode": "Infinite" }. Wenn dieses Feld fehlt, sollte der Aufrufer davon ausgehen, dass die Mutation nicht verifiziert ist.

• warnings — (optional) Array mit feldbezogenen Hinweisen auf teilweisen Erfolg, jeweils { field, message, suggestion? }. Wird verwendet, wenn die Hauptoperation erfolgreich war, aber ein Unterschritt übersprungen wurde — z. B. liefert networking.add_helper mit einer Mischung aus gültigen und ungültigen Spawnpunkt-IDs den Helfer verbunden und eine Warnung pro ungültiger ID.

Fehler geben weiterhin den Standard-{ error, action, suggestion }-Body mit isError: true zurück. Jeder benutzersichtige Wert, der nicht in eine reale Engine-Ressource aufgelöst werden kann, führt nun zu einem Fehler mit einem umsetzbaren Vorschlag, anstatt stillschweigend ohne Wirkung zu bleiben.

Related MCP server: sbox-mcp-documentation

Server

Einrichtung

1. Arenula-MCP klonen

Klonen oder laden Sie dieses Repository auf Ihren Rechner herunter. Hier befinden sich die API- und Docs-Server – sie müssen nicht in Ihrem s&box-Projekt liegen.

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

Kopieren Sie editor/ in den Libraries-Ordner Ihres s&box-Projekts:

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

Starten Sie s&box — Arenula wird automatisch kompiliert und startet den MCP-Server auf Port 8098.

3. API & Docs erstellen

Installieren und erstellen Sie vom Arenula-MCP-Stammverzeichnis aus beide Node.js-Server:

npm run setup        # installs dependencies and builds both servers

Dadurch werden api/dist/index.js und docs/dist/index.js erstellt – diese Dateien wird Ihr KI-Client referenzieren.

4. Konfigurieren Sie Ihren KI-Client

Fügen Sie eine .mcp.json-Datei im Stammverzeichnis Ihres s&box-Projekts hinzu (oder kopieren Sie .mcp.json.example). Aktualisieren Sie die Pfade zu dem Ort, an dem Sie Arenula-MCP geklont haben:

{
  "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"]
    }
  }
}

Ersetzen Sie C:/Projects/Arenula-MCP durch das Verzeichnis, in das Sie das Repository geklont haben. Holen Sie die neueste API-Schema-URL von sbox.game/api/schema (klicken Sie auf Download, kopieren Sie die URL).

Die Werkzeuge erscheinen als mcp__editor__*, mcp__api__*, mcp__docs__* in Ihrem KI-Client.

Editor-Werkzeuge

23 Omnibus-Werkzeuge, 182 Aktionen. Jedes Werkzeug akzeptiert einen erforderlichen action-Parameter.

Architektur

33 C#-Quelldateien — 9 Kerninfrastruktur, 24 Handler pro Werkzeug (inkl. ConsoleHandler).

Quellenangabe

• Editor basiert auf Ozmium MCP Server von ozmium7 (GPL-3.0)

• API basiert auf sbox-api-mcp von sofianebel (MIT)

• Docs basiert auf sbox-docs-mcp von sofianebel (MIT)

Lizenz

GPL-3.0 (Editor) · MIT (API, Docs, schemagen) — siehe LICENSE für die Begründung der Aufteilung und welche Lizenz für kopierten Code gilt.