Godot MCP Gateway

English | 简体中文

하나의 Godot 에디터, 여러 AI 코딩 에이전트.

Godot MCP Gateway는 Codex, Claude Code, OpenCode, Pi 및 기타 MCP 클라이언트가 하나의 Godot 에디터를 안전하게 공유할 수 있게 해주는 로컬 컨트롤 플레인입니다. 각 클라이언트는 독립적인 MCP 세션을 유지하며, 시스템 전체의 단일 Gateway가 에디터 검색, 요청 라우팅, 쓰기 스케줄링, 플레이테스트 접근, Godot LSP 연결 및 재연결을 담당합니다.

프로젝트 상태: 초기 개발 단계입니다. v1 Gateway 토폴로지, 이기종 배치 실행, 에디터 활동 UI가 구현되어 있지만, 아직 안정적인 릴리스는 공개되지 않았습니다.

왜 Gateway인가?

대부분의 Godot MCP 통합은 AI 클라이언트마다 서버 하나를 시작하고 에디터 포트 하나를 점유합니다. 이 모델은 여러 에이전트가 같은 프로젝트에서 작업할 때 취약해집니다. 이 프로젝트는 에이전트 세션을 에디터 연결과 분리합니다:

Codex -------- stdio shim --\
Claude Code -- stdio shim ---+-- local IPC -- Gateway -- WebSocket -- Godot Editor
OpenCode ----- stdio shim ---/                   |-- Playtest Runtime
Pi ----------- stdio shim --/                    `-- Godot LSP

Godot 플러그인은 Gateway에 아웃바운드로 연결됩니다. 에이전트는 Godot 포트 풀을 점유하거나 에디터에 직접 연결하지 않습니다.

Related MCP server: agent-bus-mcp

주요 기능

• 다중 에이전트 세션: 모든 MCP 클라이언트는 고유한 ID, 수명 주기, 활동 스트림을 가집니다.

• 단일 에디터 연결: Gateway가 에디터, 런타임, LSP 라우팅을 담당합니다.

• 순서가 보장된 쓰기: 서로 다른 에이전트의 에디터 변경은 FIFO로 스케줄링됩니다.

• 크로스 도구 배치: batch는 이기종 MCP 도구를 순차적으로 실행하고, 실패 시 중단하며, 다른 에이전트의 쓰기가 끼어들지 못하게 합니다.

• 작업 가시성: Godot Dock에 연결된 에이전트, 대기 중 및 실행 중인 작업, 배치 진행률, 최근 결과가 표시됩니다.

• 에디터 포커스: 성공적인 변경은 영향을 받은 노드를 선택하고 포커스할 수 있습니다.

• 전체 툴킷 기반: 업스트림 Godot 도구 카탈로그가 Gateway 아키텍처를 통해 그대로 사용 가능합니다.

요구 사항

• Godot 4.2 이상

• Node.js 22 이상

• npm

소스에서 실행

저장소를 클론하고 빌드합니다:

git clone https://github.com/di404/godot-mcp-gateway.git
cd godot-mcp-gateway
npm install
npm run build

addons/godot_mcp_gateway/를 Godot 프로젝트의 addons/ 디렉터리에 복사한 다음, Project Settings → Plugins에서 Godot MCP Gateway를 활성화합니다.

터미널에서 시스템 전체 Gateway를 시작하고 계속 실행 상태로 둡니다:

npm run start:gateway

각 MCP 클라이언트가 자체 stdio shim을 실행하도록 구성합니다. /absolute/path/to/godot-mcp-gateway를 클론한 저장소의 절대 경로로 바꿉니다:

{
  "mcpServers": {
    "godot-mcp-gateway": {
      "command": "node",
      "args": [
        "/absolute/path/to/godot-mcp-gateway/packages/server/dist/index.js",
        "stdio"
      ],
      "env": {
        "GODOT_MCP_PROJECT_PATH": "/absolute/path/to/your-godot-project"
      }
    }
  }
}

MCP 클라이언트가 Godot 프로젝트 루트에서 시작하는 경우 GODOT_MCP_PROJECT_PATH는 생략할 수 있습니다. GODOT_MCP_AGENT_NAME을 설정하면 Dock에 표시되는 에이전트 라벨을 재정의할 수 있습니다.

배치 예제

batch 도구는 일반적인 등록된 도구 호출을 받습니다:

{
  "calls": [
    {
      "tool": "scene_get_tree",
      "arguments": { "max_depth": 1 }
    },
    {
      "tool": "project_get_settings",
      "arguments": { "prefix": "application/" }
    }
  ]
}

호출은 일반적인 검증 및 도구 파이프라인을 통해 순서대로 실행됩니다. 실행은 첫 번째 실패 또는 취소된 단계에서 중지되며, 나머지 단계는 skipped로 표시됩니다. v1에서는 중첩 배치와 출력 참조가 지원되지 않습니다.

저장소 구조

• addons/godot_mcp_gateway/ — Godot 에디터 플러그인, 도구 핸들러, Dock.

• packages/server/ — Gateway 프로세스, stdio MCP 인터페이스, IPC, 도구 카탈로그, 스케줄링, 런타임 라우팅, LSP 소유권.

• docs/ — 아키텍처, 프로토콜, 기여자, 호환성, 로컬 테스트 문서.

저장소 루트는 플러그인을 개발하고 테스트하기 위한 작은 Godot 프로젝트이기도 합니다. 더 자세한 가이드는 문서 인덱스에서 시작하세요.

현재 v1 범위

• 하나의 Gateway는 하나의 Godot 에디터와 하나의 활성 플레이테스트 런타임을 허용합니다.

• Gateway는 수동으로 시작되며 포그라운드에서 실행됩니다.

• 배치는 실패 시 중단(failure-stop) 방식이며, 각 변경은 자체 Undo 단계를 유지합니다.

• 중첩 배치와 단계 출력 참조는 의도적으로 보류되었습니다.

저작자 표시 및 라이선스

이 프로젝트는 NPGameDev의 Godot MCP Toolkit 및 Godot MCP Server의 활발한 포크입니다. 이들의 성숙한 도구 카탈로그와 에디터 통합이 기능 기반을 이루며, 이 포크는 그 주변의 연결 토폴로지를 변경합니다.

소스 코드는 MIT License에 따라 제공됩니다. 보존된 업스트림 고지 사항 및 타사 저작권 표기는 ATTRIBUTIONS.md를 참조하세요. 상속된 업스트림 아트워크는 개발 자료이며 이 포크의 독립 브랜드 자산으로 라이선스되지 않습니다. 브랜드 릴리스를 배포하기 전에 이를 교체하세요.