emptysock-mcp

Model Context Protocol 服务器，用于 EmptySock 游戏引擎。将引擎系统 — NavMesh、Physics、Scene、Save 和 Actor — 暴露为可由 Claude Desktop、AI 代理和 Claude API 使用的 MCP 工具。

环境要求

• Node.js 20+

• npm 9+

Related MCP server: Hayba

安装

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

配置

复制示例环境变量文件，并填写你需要的任何值：

cp .env.example .env

切勿提交 .env — 它已被 gitignore。将密钥存放在 CI/CD 的密钥管理器中，而不是仓库中。

运行服务器

stdio（推荐用于本地使用和 Claude Desktop）

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

服务器通过 stdin/stdout 通信。没有网络端口，也没有身份验证暴露面。

Claude Desktop

将服务器添加到你的 Claude Desktop 配置中（在 macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

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

重启 Claude Desktop。EmptySock 工具将出现在工具选择器中。

可用工具

NavMesh

示例 — 查找路径：

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

Physics

示例 — 圆形重叠：

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

Scene

示例 — 获取组件：

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

Save

所有存档工具均被沙箱限制在 SAVE_BASE_DIR 内。路径穿越（..、绝对路径）会在 schema 层被拒绝，并在解析时再次被拒绝。

示例 — 写入：

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

存档槽名称仅由字母数字和连字符/下划线组成（例如 slot1、autosave、new-game-plus）。

Actor

示例 — 发送消息：

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

顺序说明： ActorSystem 会在调用 update() 之前清空每个 actor 的邮箱。在第 N 帧期间发送的消息会在第 N 帧的更新逻辑运行之前全部处理完毕。

开发

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

测试位于 src/tests/。它们涵盖输入验证、工具分发和安全不变量（路径穿越、shell 元字符注入、未知工具名）。

添加工具

1. 创建 src/tools/<domain>.ts — 导出 toolDef 数组条目和一个 handler 函数。

2. 通过 buildRegistry() 中的 register() 调用，将两者注册到 src/tools/index.ts。

3. 在 emptysock-engine 中的 api-reference.json 中添加一个条目。

4. 向 eleferrets/emptysock-ai-skills 添加一个技能文件。

使用 src/lib/ 中共享的辅助工具：

• parse(schema, raw) — Zod 解析，失败时抛出 McpError(InvalidParams)

• SafeRelPath、SafeId、Vec2、Vec3、GameNum — 可复用的 Zod schema

• textResponse(data) — 构建标准 MCP 文本内容响应

• wrapError(err) — 记录到 stderr，并以 McpError(InternalError) 重新抛出

安全模型