emptysock-mcp

EmptySock 게임 엔진용 Model Context Protocol 서버입니다. 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

구성

예제 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. 두 항목을 모들 src/tools/index.ts에서 buildRegistry()의 register() 호출을 통해 등록합니다.

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)로 다시 던집니다

보안 모델