GodotLens: GDScript를 위한 AI 우선 코드 분석

Godot의 내장 언어 서버를 기반으로 GDScript를 위한 15가지 의미론적 분석 도구를 제공하는 MCP 서버입니다.

AI 에이전트를 위해 구축됨

AI 코딩 에이전트는 텍스트 파일로 작업하지만 GDScript에 대한 의미론적 이해가 부족합니다. 에이전트가 grep을 사용하여 함수의 사용처를 찾을 때, 함수 호출과 동일한 이름이 포함된 주석, 신호 선언과 신호 방출, 또는 재정의된 메서드와 관련 없는 함수를 구분할 수 없습니다.

GodotLens는 Godot의 내장 언어 서버를 MCP(Model Context Protocol)를 통해 노출함으로써 이 격차를 해소합니다. 이를 통해 AI 에이전트는 정의로 이동, 참조 찾기, 진단, 이름 변경 등 GDScript에 대한 컴파일러 수준의 정확한 코드 인텔리전스를 얻을 수 있습니다.

예시: _on_player_hit의 모든 사용처 찾기:

접근 방식	결과
`grep "_on_player_hit"`	주석, 문자열, 유사한 이름의 함수를 포함한 12개의 일치 항목
`gdscript_references`	`_on_player_hit`이 호출되는 정확히 4개의 호출 지점

사전 요구 사항

Godot 4.x 에디터가 프로젝트를 연 상태로 실행 중이어야 합니다. Godot의 LSP 서버는 에디터가 프로젝트를 열면 자동으로 시작됩니다.
Python 3.10+ (pip 설치용) 또는 Node.js 16+ (npx용)

빠른 시작

옵션 A: npx (MCP 클라이언트에 권장)

MCP 구성(예: Claude Code의 경우 .mcp.json)에 추가하세요:

{
  "mcpServers": {
    "godotlens": {
      "command": "npx",
      "args": ["-y", "godotlens-mcp"]
    }
  }
}

npm 패키지는 전체 서버(~20 KB의 Python)를 번들로 제공합니다. 외부 Python 의존성이 없습니다.

옵션 B: pip

pip install godotlens-mcp

{
  "mcpServers": {
    "godotlens": {
      "command": "godotlens-mcp"
    }
  }
}

구성

환경 변수	기본값	설명
`GODOT_LSP_HOST`	`127.0.0.1`	Godot LSP 서버 호스트
`GODOT_LSP_PORT`	`6005`	Godot LSP 서버 포트

도구

상태(Health)

도구	설명
`gdscript_status`	Godot LSP 연결을 확인합니다. 다른 도구를 사용하기 전에 에디터가 실행 중인지 확인하는 데 사용하세요.

탐색(6개 도구)

도구	설명
`gdscript_definition`	심볼이 정의된 곳으로 이동합니다. 파일 경로와 줄 번호를 반환합니다.
`gdscript_declaration`	심볼의 선언 위치로 이동합니다.
`gdscript_references`	프로젝트 전체에서 심볼에 대한 모든 참조를 찾습니다. 리팩토링 전 영향 분석에 필수적입니다.
`gdscript_hover`	심볼에 대한 타입 정보와 문서를 가져옵니다. 타입과 반환 값을 이해하는 데 사용하세요.
`gdscript_symbols`	파일 내의 모든 심볼(클래스, 함수, 변수, 신호)을 나열합니다. 파일 구조를 탐색하는 데 사용하세요.
`gdscript_signature_help`	호출 지점에서 함수 시그니처와 매개변수 정보를 가져옵니다.

리팩토링

도구	설명
`gdscript_rename`	모든 파일에서 심볼의 이름을 변경합니다. 워크플로우: 참조를 통해 영향 미리보기, 이름 변경, 동기화 순으로 진행하세요.

동기화(3개 도구)

도구	설명
`gdscript_sync_file`	수정된 파일을 LSP와 동기화하고 업데이트된 진단 정보를 가져옵니다. .gd 파일 편집 후 호출하세요.
`gdscript_sync_files`	수정된 여러 파일을 일괄 동기화합니다. 개별적으로 동기화하는 것보다 효율적입니다.
`gdscript_delete_file`	파일이 삭제되었음을 LSP에 알립니다. 오래된 진단 정보를 지웁니다.

일괄 작업(3개 도구)

도구	설명
`gdscript_symbols_batch`	한 번의 호출로 여러 파일에서 심볼을 가져옵니다.
`gdscript_definitions_batch`	한 번의 호출로 여러 위치에 대한 정의를 가져옵니다.
`gdscript_references_batch`	한 번의 호출로 여러 심볼에 대한 참조를 찾습니다. 대규모 영향 분석에 사용하세요.

진단

도구	설명
`gdscript_diagnostics`	컴파일러 오류와 경고를 가져옵니다. 워크플로우: 편집, 동기화, 진단 확인 순으로 진행하세요.

아키텍처

┌──────────────┐         ┌────────────────────┐         ┌───────────────────┐
│   AI Agent   │  stdio  │  GodotLens (MCP)   │   TCP   │  Godot Editor     │
│ (Claude, etc)├────────►│  JSON-RPC 2.0      ├────────►│  Built-in LSP     │
│              │◄────────┤  Python 3.10+      │◄────────┤  Port 6005        │
└──────────────┘         └────────────────────┘         └───────────────────┘

GodotLens는 AI 에이전트와 Godot의 내장 언어 서버 사이의 가교 역할을 합니다. AI 에이전트는 MCP(stdio를 통한 JSON-RPC)를 통해 GodotLens와 통신합니다. GodotLens는 MCP 도구 호출을 LSP 요청으로 변환하여 TCP를 통해 Godot 에디터로 보냅니다. 응답은 효율적인 AI 소비를 위해 압축됩니다.

의존성 제로 — 서버는 Python 표준 라이브러리만 사용합니다. MCP 및 LSP 프로토콜은 직접 구현되어 서버를 가볍고 독립적으로 유지합니다.

중요: 파일 동기화

Godot의 LSP는 에디터 외부에서 이루어진 파일 변경 사항을 자동으로 감지하지 않습니다. AI 에이전트가 .gd 파일을 수정하면 gdscript_sync_file 또는 gdscript_sync_files를 호출하여 LSP가 변경된 코드를 다시 분석하도록 해야 합니다. 그렇지 않으면 진단 및 탐색 결과가 오래된 상태일 수 있습니다.

권장 워크플로우:

GodotLens 도구를 사용하여 코드 분석
파일에 변경 사항 작성
gdscript_sync_file을 호출하여 LSP 상태 새로 고침
GodotLens 도구를 사용하여 변경 사항 확인

좌표계

모든 줄 및 문자 매개변수는 LSP 사양에 맞춰 **0부터 시작(0-indexed)**합니다:

0번째 줄, 0번째 문자 = 파일의 첫 번째 문자

라이선스

MIT 라이선스 — 자세한 내용은 LICENSE를 참조하세요.

godotlens-mcp