emptysock-mcp

Servidor de Model Context Protocol para el motor de juegos EmptySock. Expone los sistemas del motor — NavMesh, Physics, Scene, Save y Actor — como herramientas MCP consumibles por Claude Desktop, agentes de IA y la API de Claude.

Requisitos

• Node.js 20+

• npm 9+

Related MCP server: Hayba

Instalación

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

Configuración

Copia el archivo de entorno de ejemplo y completa los valores que necesites:

cp .env.example .env

Nunca hagas commit de .env — está en gitignore. Guarda los secretos en el gestor de secretos de tu CI/CD, no en el repositorio.

Ejecutar el servidor

stdio (recomendado para uso local y Claude Desktop)

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

El servidor se comunica a través de stdin/stdout. No hay ningún puerto de red ni superficie de autenticación.

Claude Desktop

Añade el servidor a la configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

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

Reinicia Claude Desktop. Las herramientas de EmptySock aparecerán en el selector de herramientas.

Herramientas disponibles

NavMesh

Ejemplo — encontrar ruta:

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

Physics

Ejemplo — solapamiento de círculo:

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

Scene

Ejemplo — obtener componente:

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

Save

Todas las herramientas de guardado están restringidas a SAVE_BASE_DIR. El path traversal (.., rutas absolutas) se rechaza en la capa de esquema y de nuevo en el momento de la resolución.

Ejemplo — escribir:

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

Los nombres de las ranuras solo pueden contener caracteres alfanuméricos, guiones y guiones bajos (p. ej. slot1, autosave, new-game-plus).

Actor

Ejemplo — enviar mensaje:

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

Nota sobre el orden: ActorSystem vacía la bandeja de entrada de todos los actores antes de llamar a update(). Los mensajes enviados durante el frame N se procesan antes de que se ejecute la lógica de actualización del frame N.

Desarrollo

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

Los tests se encuentran en src/tests/. Cubren la validación de entrada, el despacho de herramientas y los invariantes de seguridad (path traversal, inyección de metacaracteres de shell, nombres de herramientas desconocidos).

Cómo añadir una herramienta

1. Crea src/tools/<domain>.ts — exporta una entrada de array toolDef y una función handler.

2. Registra ambas en src/tools/index.ts mediante la llamada a register() en buildRegistry().

3. Añade una entrada a api-reference.json en emptysock-engine.

4. Añade un archivo de skill a eleferrets/emptysock-ai-skills.

Usa los helpers compartidos en src/lib/:

• parse(schema, raw) — parse de Zod que lanza McpError(InvalidParams) al fallar

• SafeRelPath, SafeId, Vec2, Vec3, GameNum — esquemas Zod reutilizables

• textResponse(data) — construye la respuesta estándar de contenido de texto de MCP

• wrapError(err) — escribe en stderr y vuelve a lanzar como McpError(InternalError)

Modelo de seguridad