Godot용 실시간 MCP 서버를 구축한 방법

Godot에서 MCP 서버에 ‘실시간’이 중요한 이유

대부분의 MCP 데모는 REST 형태의 세계에서 작동합니다. 모델이 질문하고, 도구가 JSON을 반환하며, 왕복에 2초가 걸려도 아무도 신경 쓰지 않습니다. Godot는 다릅니다. 에디터는 라이브 씬 트리, 리소스 가져오기, 플레이 모드 루프를 소유합니다. MCP 서버가 메인 스레드를 차단하거나 프로젝트의 오래된 덤프만 보게 되면 AI 클라이언트는 공동 조종사처럼 느껴지지 않고 추가 단계가 있는 원격 파일 편집기처럼 느껴집니다.

VberAI용 Godot MCP를 설계할 때 요구 사항은 명확했습니다.

• AI 어시스턴트(Cursor, Claude, Windsurf 및 유사한 MCP 클라이언트)는 디스크에서 .gd 파일을 읽는 것뿐만 아니라 에디터를 조작해야 합니다.
• 노드 생성, 이름 변경, 스크립트 연결, 선택 항목 쿼리와 같은 작업은 에디터가 응답하는 동안 완료되어야 합니다.
• 플레이 모드와 편집 모드 컨텍스트는 정직해야 합니다. 플레이 중에 안전하지 않은 작업은 도구가 크게 실패해야 합니다.

이 글은 엔지니어링 이야기입니다. 프로젝트를 정적 저장소로 취급하는 대신 Godot 옆에 있는 실시간 MCP 서버를 구축한 방법입니다.

엔진을 위한 ‘파일 전용’ MCP의 문제점

순진한 접근 방식이 매력적입니다.

1. MCP 서버를 프로젝트 폴더에 연결합니다.
2. read_file / write_file / list_dir을 노출합니다.
3. 모델이 GDScript를 생성하고 에디터가 잘 다시 로드되기를 기대합니다.

문서 사이트에는 효과가 있습니다. 엔진 작업에는 실패합니다. 왜냐하면:

• 씬 소유권은 메모리에 있습니다. 저장되지 않은 .tscn 차이, 열린 씬, 에디터 선택 항목은 디스크에 보이지 않습니다.
• 가져오기 파이프라인은 상태를 유지합니다. PNG를 쓰는 것은 ‘올바른 가져오기 설정으로 리소스 준비’와 같지 않습니다.
• 시그널과 노드 경로는 그래프 데이터입니다. 문자열 편집은 조용히 연결을 끊습니다.
• 지연 시간이 누적됩니다. ‘노드가 나타났나요?’ 확인할 때마다 전체 파일 시스템 스캔이 됩니다.

인간이 Godot 독에서 이미 보는 것, 즉 계층 구조, 인스펙터 형태의 속성, 리소스 핸들을 반영하는 MCP 표면이 필요했습니다. 경로 문자열만이 아니라요.

아키텍처 개요

높은 수준에서 Godot MCP는 세 개의 협력 계층입니다.

MCP 클라이언트(Cursor / Claude / …)
        │  stdio 또는 로컬 전송을 통한 JSON-RPC
        ▼
MCP 서버(VberAI Godot 브리지 프로세스)
        │  명령 큐 + 결과 봉투
        ▼
Godot 에디터 플러그인(GDExtension / 에디터 플러그인)
        │  메인 스레드에서 지연 호출
        ▼
에디터 씬 트리 / ResourceDB / 스크립트 에디터

계층 1 — MCP 도구 표면

도구는 의도적으로 작고 동사 형태입니다.

• godot_get_scene_tree — 편집 중인 씬의 스냅샷(노드 유형 및 경로 포함)
• godot_create_node / godot_set_property
• godot_attach_script / godot_run_script_snippet(보호됨)
• godot_list_resources / godot_get_selection

하나의 거대한 do_anything 도구는 피합니다. 작은 도구는 검증하기 쉽고, 로그하기 쉽고, 모델이 무한 패치로 남용하기 어렵습니다.

계층 2 — 실시간 브리지

브리지는 ‘실시간’이 실제로 사는 곳입니다.

• MCP 프로세스와 에디터 플러그인 사이의 양방향 채널(개발 중에는 로컬 소켓 또는 명명된 파이프, 제품 빌드는 VberAI 데스크톱 헬퍼 뒤에 래핑할 수 있음)
• 두 개의 겹치는 도구 호출이 씬 트리에서 경쟁하지 않도록 변형을 직렬화하는 명령 큐
• MCP 클라이언트가 파일 시스템을 폴링하지 않고 ‘적용됨’을 기다릴 수 있도록 하는 요청 ID + 확인
• 클라이언트가 세션 중간에 Godot가 종료되었는지 알 수 있도록 하는 하트비트 / 에디터 활성 상태

계층 3 — Godot에서 메인 스레드 안전성

Godot의 UI 및 씬 API는 자유 스레드가 아닙니다. 플러그인은 MCP I/O 스레드에서 노드를 변경하지 않습니다. 대신:

1. MCP 명령이 브리지 스레드에 도착합니다.
2. 페이로드가 큐에 추가됩니다.
3. 에디터 지연 콜백이 메인 스레드에서 실행됩니다(call_deferred / 유휴 프레임 훅).
4. 결과 봉투가 성공, 구조화된 오류 또는 ‘플레이 모드 종료 후 재시도’를 반환합니다.

이 패턴은 의도적으로 지루합니다. 지루함이 ‘실시간’을 ‘무작위 에디터 프리즈’로 만들지 않습니다.

실시간처럼 느끼게 만들기(지연 시간에 대해 거짓말하지 않고)

여기서 ‘실시간’은 마법 같은 제로 지연 시간을 의미하지 않습니다. 피드백 루프가 인간이 에디터에서 작업하는 방식과 일치한다는 것을 의미합니다.

스냅샷 vs 스트림

초기 프로토타입은 호출할 때마다 전체 씬 트리를 반환했습니다. 큰 오픈 월드 설정에서 무너졌습니다. 다음과 같이 전환했습니다.

• 기본적으로 얕은 스냅샷(루트 + 한 수준 또는 선택 중심)
• 모델이 이미 하위 트리를 알고 있을 때 경로 범위 읽기
• 선택적 변경 토큰을 통해 후속 호출이 모든 것을 다시 직렬화하는 대신 ‘X 이후 무엇이 변경되었나요?‘를 물을 수 있습니다.

Diff 친화적 결과

도구 결과에는 다음이 포함됩니다.

• 표준 NodePath 문자열
• 유형 이름(CharacterBody2D, Control, …)
• 인스펙터 필드에 깔끔하게 매핑되는 속성 키
• 쓰기가 적용되었지만 씬이 여전히 더티/저장되지 않은 경우 명시적 경고

결과가 자유 형식 텍스트의 블로그 게시물처럼 보이지 않고 UI 상태처럼 보이면 모델이 더 빠르게 반복합니다.

제한된 플레이 모드 동작

플레이 모드는 ‘AI가 내 프로젝트를 망쳤다’ 티켓의 절반이 시작되는 곳입니다. 우리의 규칙 세트:

모드	허용	차단 또는 게이트
편집	씬 변경, 리소스 쿼리	확인 없는 파괴적 프로젝트 삭제
플레이	주로 런타임 노드 읽기/쿼리	편집 중인 씬에 대한 구조적 편집
전환	대기/재시도 힌트	자동 실패 없음

명확한 오류가 영리함보다 낫습니다. 플레이 중에 모델이 편집할 수 없으면 MCP 응답이 구조화된 형태로 말합니다. 클라이언트가 사용자에게 플레이를 중지하고 재시도하라고 알릴 수 있습니다.

우리가 겪은 어려운 문제들(그리고 유지한 것들)

1. 에디터는 데이터베이스가 아닙니다.

노드 순서, 소유자 관계, 패킹된 씬은 GIF에서 단순해 보이고 .tscn에서 지저분해 보이는 방식으로 상호 작용합니다. 우리는 Godot의 자체 API(Node, EditorInterface, 리소스 로더)에 의존했습니다. 표류할 병렬 씬 모델을 발명하는 대신에요.

2. 스크립트와 씬은 두 가지 진실의 원천입니다.

스크립트를 연결하는 것은 스크립트가 컴파일되고 클래스 이름이 해석되는지 확인하는 것과 같지 않습니다. 서버는 컴파일/연결 결과를 별도로 보고합니다. 이로 인해 ‘도구가 성공했다고 말했지만 인스펙터에 아무것도 표시되지 않음’ 실패 클래스가 중단되었습니다.

3. 다중 창 / 다중 프로젝트 세션

개발자는 둘 이상의 Godot 인스턴스를 엽니다. 브리지는 명시적 에디터 세션 ID에 바인딩되어 주말 동안 절전 + 다시 열기 후 도구 호출이 잘못된 프로젝트에 도달하지 않습니다.

4. 보안 경계

씬을 다시 쓸 수 있는 MCP 서버는 강력합니다. 로컬 우선 전송, 명시적 도구 허용 목록, 전체 프로젝트 트리의 조용한 클라우드 유출 금지는 협상 불가입니다. ‘AI 도우미’와 ‘게임 위의 원격 셸’은 별개의 제품 범주로 유지되어야 합니다.

AI Studio 및 VberAI의 나머지와 어떻게 맞는지

Godot MCP는 엔진 운영자입니다. 보완 요소:

• VberAI Studio(AI Studio) — Figma/PSD → Control 계층 구조에 대한 디자인-엔진 구조; MCP는 가져오기 후 버튼을 연결하고 노드 이름을 변경합니다.
• Unity MCP / Cocos MCP — 동일한 MCP 아이디어, 다른 에디터 호스트 및 안전 규칙.
• AI Super Matting — 텍스처가 MCP가 나중에 할당하는 엔진 리소스가 되기 전에 알파를 정리합니다.

공유된 테제: AI는 텍스트로서의 저장소뿐만 아니라 라이브 프로덕션 표면(에디터, 에셋, 씬)을 만져야 합니다.

자신만의 엔진 MCP를 구축하는 경우 실용적인 팁

1. 엔진 메인 스레드에서 변형을 큐에 넣으세요. 게임 엔진이 공유 없는 서버라고 가장하지 마세요.
2. 스키마가 있는 작은 도구를 선호하세요. 검증이 프롬프트 시보다 낫습니다.
3. NodePath와 유형을 반환하세요. 산문이 아니라요. 모델은 작동 가능한 핸들이 필요합니다.
4. 모든 응답에 편집/플레이 모드를 인코딩하세요. 여기서의 모호함은 신뢰를 파괴합니다.
5. ‘독에 보이는’ 왕복 시간을 측정하세요. JSON 인코딩 시간만이 아니라요.

MCP 프로세스만 최적화하고 에디터 브리지를 무시하면 빠른 환각 루프를 제공하게 됩니다.

결론

Godot용 실시간 MCP 서버를 구축한다는 것은 에디터를 라이브 협력자로 취급하는 것을 의미했습니다. 큐가 있는 메인 스레드 안전 브리지, 에디터 작업 형태의 도구, 플레이 모드 제한에 대한 정직함. 파일 전용 MCP는 더 쉽지만 씬 네이티브 작업에는 불완전합니다.

주말 프로토타입 대신 출시된 경로를 원하시나요? VberAI Godot MCP로 시작하여 선호하는 MCP 클라이언트를 연결하고 간단한 첫 도구 호출을 시도하세요. 현재 씬 트리를 나열한 다음 선택 항목 아래에 노드를 하나 만드세요. 이 단일 루프(쿼리 → 변경 → 독에서 보기)가 제품입니다. 나머지는 그 주변의 안정성 엔지니어링입니다.