emptysock-mcp

Model Context Protocol-Server für die EmptySock-Spiel-Engine. Stellt die Engine-Systeme — NavMesh, Physics, Scene, Save und Actor — als MCP-Tools bereit, die von Claude Desktop, KI-Agenten und der Claude-API genutzt werden können.

Voraussetzungen

• Node.js 20+

• npm 9+

Related MCP server: Hayba

Installation

git clone https://github.com/eleferrets/emptysock-mcp.git
cd emptysock-mcp
npm install
npm run build

Konfiguration

Kopiere die Beispiel-Umgebungsdatei und fülle alle benötigten Werte aus:

cp .env.example .env

Commite .env niemals — es ist in der .gitignore enthalten. Speichere Geheimnisse in deinem CI/CD-Secret-Manager auf, nicht im Repository.

Den Server starten

stdio (empfohlen für die lokale Verwendung und Claude Desktop)

npm run dev          # development — tsx, no build step
# or after building:
node dist/server.js

Der Server kommuniziert über stdin/stdout. Es gibt keinen Netzwerkport und keine Authentisierungsschnittstelle.

Claude Desktop

Füge den Server zu deiner Claude-Desktop-Konfiguration hinzu (~/Library/Application Support/Claude/claude_desktop_config.json unter macOS):

{
  "mcpServers": {
    "emptysock": {
      "command": "node",
      "args": ["/absolute/path/to/emptysock-mcp/dist/server.js"],
      "env": {
        "SAVE_BASE_DIR": "/absolute/path/to/your/saves"
      }
    }
  }
}

Starte Claude Desktop neu. Die EmptySock-Tools erscheinen dann in der Tool-Auswahl.

Verfügbare Tools

NavMesh

Beispiel — Pfad finden:

{
  "from": { "x": 0, "y": 0 },
  "to":   { "x": 100, "y": 50 },
  "mapId": "level1"
}

Physics

Beispiel — Kreisüberlappung:

{
  "center": { "x": 50, "y": 50 },
  "radius": 20,
  "layerMask": 3
}

Scene

Beispiel — Komponente abrufen:

{
  "sceneId": "gameplay",
  "entityId": "player-001",
  "componentType": "Transform"
}

Save

Alle Speicher-Tools sind per Sandbox auf SAVE_BASE_DIR beschränkt. Pfad-Traversal (.., absolute Pfade) wird bereits auf Schema-Ebene und erneut beim Auflösen abgelehnt.

Beispiel — Schreiben:

{
  "slot": "autosave",
  "data": { "level": 3, "score": 4200, "checkpoint": "bridge" }
}

Slotnamen dürfen nur alphanumerische Zeichen, Bindestriche und Unterstriche enthalten (z. B. slot1, autosave, new-game-plus).

Actor

Beispiel — Nachricht senden:

{
  "actorId": "enemy-spawner",
  "message": { "type": "SPAWN_WAVE", "payload": { "wave": 3 } }
}

Hinweis zur Reihenfolge: ActorSystem leert den Posteingang jedes Actors, bevor update() aufgerufen wird. Nachrichten, die während Frame N gesendet werden, werden vollständig verarbeitet, bevor die Update-Logik von Frame N ausgeführt wird.

Entwicklung

npm run lint        # TypeScript type-check (no emit)
npm test            # run Vitest suite
npm run test:watch  # watch mode

Die Tests befinden sich in src/tests/. Sie decken Eingabevalidierung, Tool-Dispatch und Sicherheitsinvarianen ab (Pfad-Traversal, Shell-Metazeichen-Injektion, unbekannte Toolnamen).

Ein Tool hinzufügen

1. Erstelle src/tools/<domain>.ts — exportiere einen toolDef-Array-Eintrag und eine handler- Funktion.

2. Registriere beide in src/tools/index.ts über den register()- Aufruf in buildRegistry().

3. Füge einen Eintrag zu api-reference.json in emptysock-engine hinzu.

4. Füge eine Skill-Datei zu eleferrets/emptysock-ai-skills hinzu.

Verwende die gemeinsamen Helfer in src/lib/:

• parse(schema, raw) — Zod-Parse, der bei einem Fehler McpError(InvalidParams) wirft

• SafeRelPath, SafeId, Vec2, Vec3, GameNum — wiederverwendbare Zod-Schemas

• textResponse(data) — erstellt die standardmäßige MCP-Textinhalts-Antwort

• wrapError(err) — protokolliert auf stderr und wirft ihn als McpError(InternalError) erneut

Sicherheitsmodell