GodotLens: AIファーストなGDScriptコード分析

Godotの組み込み言語サーバーを活用し、GDScript向けの15種類のセマンティック分析ツールを提供するMCPサーバー。

AIエージェント向けに構築

AIコーディングエージェントはテキストファイルを扱いますが、GDScriptのセマンティック（意味論的）な理解が不足しています。エージェントが grep を使用して関数の使用箇所を検索する場合、関数呼び出しと、同じ名前を含むコメント、シグナル宣言とシグナル発信、あるいはオーバーライドされたメソッドと無関係な関数を区別できません。

GodotLensは、Godotの組み込み言語サーバーをModel Context Protocol (MCP) を通じて公開することで、このギャップを埋めます。これにより、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サーバーのポート

ツール

ヘルスチェック

ツール	説明
`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`	1回の呼び出しで複数のファイルからシンボルを取得します。
`gdscript_definitions_batch`	1回の呼び出しで複数の位置の定義を取得します。
`gdscript_references_batch`	1回の呼び出しで複数のシンボルの参照を検索します。一括影響分析に使用します。

診断

ツール	説明
`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 ファイルを変更した場合は、LSPが変更されたコードを再分析できるように gdscript_sync_file または gdscript_sync_files を呼び出す必要があります。これを行わないと、診断結果やナビゲーション結果が古くなる可能性があります。

推奨ワークフロー:

GodotLensツールを使用してコードを分析する
ファイルに変更を書き込む
gdscript_sync_file を呼び出してLSPの状態を更新する
GodotLensツールを使用して変更を確認する

座標系

すべての行および文字パラメータは 0から始まるインデックス であり、LSP仕様に準拠しています:

行0、文字0 = ファイルの最初の文字

ライセンス

MITライセンス — 詳細は LICENSE を参照してください。

godotlens-mcp