Godot Forge

Godot Forge

Godot 4 用の MCP サーバーです。テストランナー、API ドキュメント、スクリプト分析などを提供します。

AI コーディングアシスタントは、構造的に GDScript を苦手としています。Godot 3 に偏ったデータでトレーニングされたモデルは、非推奨 API を誤って生成します（await ではなく yield、CharacterBody3D ではなく KinematicBody、@export var ではなく export var）。Godot Forge がこの問題を解決します。

ツールは 8 個。設定不要。MCP 対応 IDE ならどれでも動作します。

インストール

npx -y godot-forge

以上です。Godot Forge は Godot の実行ファイル（Steam、Homebrew、直接ダウンロード）を自動検出し、project.godot も自動的に見つけます。

IDE への追加

claude mcp add godot-forge -- npx -y godot-forge

{
  "mcpServers": {
    "godot-forge": {
      "command": "npx",
      "args": ["-y", "godot-forge"]
    }
  }
}

{
  "servers": {
    "godot-forge": {
      "command": "npx",
      "args": ["-y", "godot-forge"]
    }
  }
}

{
  "mcpServers": {
    "godot-forge": {
      "command": "npx",
      "args": ["-y", "godot-forge"]
    }
  }
}

{
  "context_servers": {
    "godot-forge": {
      "command": {
        "path": "npx",
        "args": ["-y", "godot-forge"]
      }
    }
  }
}

{
  "mcpServers": {
    "godot-forge": {
      "command": "npx",
      "args": ["-y", "godot-forge"]
    }
  }
}

ツール

ヒント

8 個のツールのうち 6 個は、Godot をインストールしていなくても動作します。テストの実行、プロジェクトの起動、スクリーンショットの取得にのみ実行ファイルが必要です。

機能

テストランナー

GUT と GdUnit4 を自動検出します。合否件数と、ファイルパスおよび行番号を含む失敗の詳細を、構造化された JSON で返します。スクリプト、メソッド、内部クラスによる絞り込みに対応しています。

Ask your AI: "Run the water profile tests"
→ { total: 5, passed: 5, failed: 0, duration_ms: 462 }

Godot 3→4 移行マッピング

AI が壊れた GDScript を書く最大の原因です。AI が非推奨 API を照会すると、Godot 4 での正しい代替 API をすぐに取得できます（クラス、メソッド、構文、定数を網羅した 30 以上のマッピング）。

Query: "KinematicBody"  →  "Renamed to CharacterBody3D in Godot 4"
Query: "yield"          →  "yield(obj, 'signal') → await obj.signal"
Query: "instance()"     →  "instance() → instantiate()"

スクリプト解析：10 の落とし穴

実際のゲーム開発で見つかったすべての落とし穴を検出します。

シーン解析

.tscn と .tres ファイルを解析します。深いネスト（8 レベル超）、大きすぎるシーン（100 ノード超）、スクリプト参照の欠落、.tres 内の preload()、整数のリソース ID などを検出します。

LSP 診断

Godot に組み込まれた言語サーバーに接続します（エディターが開いていると自動的に実行されます）。実際のコンパイラーエラーと警告を返します（推測は不要です）。

メモ

プロジェクトを開いた状態で Godot エディターを実行している必要があります。それ以外のツールはエディターなしで動作します。

スクリーンショットのキャプチャ

ゲームのビューポートを PNG 画像としてキャプチャします。プロジェクトのメインシーン（または指定したシーン）を読み込み、レンダリングを待ってから、AI が確認できるようスクリーンショットを base64 形式で返します。

設定

Godot バイナリ

次の順序で自動検出されます。

1. GODOT_PATH 環境変数
2. PATH 内の godot / godot4
3. Steam のインストール先（macOS、Windows、Linux）
4. プラットフォームの標準パス（/Applications/Godot.app、Homebrew、Scoop、Flatpak、Snap など）

手動で上書きする場合：

export GODOT_PATH="/path/to/godot"

検索対象パスの一覧は、Godot の検出を参照してください。

プロジェクトディレクトリ

現在のディレクトリから上位へたどり、project.godot を見つけて自動検出します。上書きする場合：

npx godot-forge --project /path/to/godot/project

要件

• Node.js 18+：npx で実行するために必要です
• Godot 4.x：自動検出されます（8 つのツールのうち 6 つでは省略可能です）
• MCP 互換 IDE：Claude Code、Cursor、VS Code、Windsurf、Zed、その他 多数

設計原則

• 操作ではなく成果：各ツールは生の API ラッパーではなく、完全な結果を提供します
• 厳選した 8 つのツール：93 個のツールによるコンテキストの肥大化を避けます（これが重要な理由）
• 段階的な情報開示：まず概要を示し、詳細は要求に応じて提供します
• exec() ではなく spawn()：コマンドインジェクションや Windows の引用符処理の不具合はありません
• 実行可能なエラー：すべてのエラーに、AI が実行できる提案が含まれます
• クロスプラットフォーム：macOS、Windows、Linux に対応。Steam 経由、非 Steam 経由のインストールに対応します。

貢献

貢献を歓迎します！ガイドラインについては CONTRIBUTING.md を参照してください。

• バグ報告：Issue を作成
• 機能リクエスト：ディスカッションを開始
• プルリクエスト：フォークし、ブランチを作成してテストし、PR を送ってください

開発

git clone https://github.com/gregario/godot-forge.git
cd godot-forge
npm install
npm run build
npm test        # 74 tests across 12 test files

ローカルでの実行

# Point your IDE at the local build
claude mcp add godot-forge-dev -- node /path/to/godot-forge/dist/index.js

ロードマップ

予定されている機能については ROADMAP.md を参照してください。

フェーズ 2：入力シミュレーション、実行時のシーンツリー検査、パフォーマンスプロファイリング、シェーダー検証、エクスポート／CI パイプライン。

ライセンス

MIT