emptysock-mcp

EmptySock ゲームエンジン用の Model Context Protocol サーバー。エンジンのシステム — NavMesh、Physics、Scene、Save、Actor — を MCP ツールとして公開し、Claude Desktop、AI エージェント、Claude API から利用できます。

要件

• 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

設定

サンプルの env ファイルをコピーし、必要な値を入カしてください:

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 の設定ファイル (~/Library/Application Support/Claude/claude_desktop_config.json、macOS の場合) にサーバーを追加します:

{
  "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 内にサンドボッス化されます。パストラバーサル (..、絶対パス) はスキーマ層と解決時の両方で拒否されます。

例 — 書き込み:

{
  "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() を呼び出す前に各アクターの受信箱を空にします。フレーム N の間に送信されたメッセージは、フレーム N の更新ロジックが実行される前に完全に処理されます。

開発

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

テストは src/tests/ にあります。入力検証、ツールディスパッチ、セキュリティ不変条件 (パストラバーサル、シェルメタキャラクターインジェクション、未知のツール名) をカバーしています。

ツールの追加

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) — 失敗時に McpError(InvalidParams) をスローする Zod パース

• SafeRelPath, SafeId, Vec2, Vec3, GameNum — 再利用可能な Zod スキーマ

• textResponse(data) — 標準の MCP テキストコンテンツレスポンスを構築する

• wrapError(err) — stderr にログを記録し、McpError(InternalError) として再スローする

セキュリティモデル