gopeak

GoPeak

🌐 言語：English | 한국어 | 日本語 | Deutsch | Português | 简体中文

GoPeak は、AI アシスタントが実際のプロジェクトを最初から最後まで実行、調査、変更、デバッグできる Godot 向け MCP サーバーです。

英語版が正式な原本です。各言語版の README は概要をまとめたものであり、README.md より更新が遅れる場合があります。

招待リンクの更新中のため、Discord コミュニティチャットは一時的にご利用いただけません。その間は GitHub Discussions をご利用ください：https://github.com/HaD0Yun/Gopeak-godot-mcp/discussions

---

クイックスタート（3 分）

要件

• Godot 4.x
• Node.js 18+
• MCP 対応クライアント（Claude Desktop、Cursor、Cline、OpenCode など）

1) GoPeak を実行する

npx -y gopeak

または、グローバルにインストールします：

npm install -g gopeak
gopeak

更新通知用のシェルフックは、オプトイン方式になりました：

gopeak setup

gopeak setup は、明示的に実行した場合にのみ、対応する bash/zsh の rc ファイルを変更します。npm install によってシェルフックが自動でインストールされることはなくなりました。

2) MCP クライアントの設定を追加する

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "gopeak"],
      "env": {
        "GODOT_PATH": "/path/to/godot",
        "GOPEAK_TOOL_PROFILE": "compact"
      }
    }
  }
}

GOPEAK_TOOL_PROFILE=compact がデフォルトです。オンデマンドで有効になる動的なツールグループを備えた、信頼できるコア機能を公開します。これにより、実験的または環境に依存する機能を明示しながら、トークン使用量を抑えられます。

3) 最初に試すプロンプト

• 「/your/projects 内の Godot プロジェクトを一覧表示して、プロジェクト情報を表示してください。」
• 「CharacterBody2D をルートとする scenes/Player.tscn を作成し、移動スクリプトを追加してください。」
• 「プロジェクトを実行してデバッグ出力を取得し、最初のエラーを修正してください。」

---

GoPeak を選ぶ理由

• 実際のプロジェクトを使ったフィードバックループ：ゲームを実行してログを調査し、その場で修正できます。
• 信頼できる Godot 4 ワークフローツール：プロジェクトの検出、シーン／スクリプト／リソースの編集、ランタイム／LSP／DAP 連携、テスト、アセットのワークフローに対応しています。
• デフォルトでトークン効率に優れています：コンパクトなコア機能と動的なツールグループを備えています。従来の機能一式を読み込む代わりに、必要な機能群だけを有効にできます。
• 成熟度ラベルを明示した動的なツールグループ：tool.catalog で検索すると、一致するグループが自動的に有効になります。または、tool.groups で手動で有効にできます。
• セットアップ要件を明示した深い Godot 連携：ClassDB のクエリ、ランタイムの調査、デバッガーフック、ブリッジを使ったシーン／リソースの編集では、アドオン、エディター、LSP、DAP、ランタイムの要件を明確に示します。

特におすすめの用途

• AI の支援を受けながら迅速に開発を進める、個人／インディー開発者
• 実際のプロジェクトやランタイムの状態に基づいた AI を必要とするチーム
• デバッグ中心のワークフロー（ブレークポイント、スタックトレース、ライブランタイムチェック）

---

ツール公開モデル（重要）

GoPeak は、3 つの公開プロファイルに対応しています。

• compact（デフォルト）：信頼できるコアツールに加え、必要に応じて有効化される動的なツールグループを公開します。
• full：互換性と監査作業のため、従来のツールリスト全体を公開します。
• legacy：古い設定向けに、full と同じ動作でツールを公開します。

次のいずれかを使用して設定します。

• GOPEAK_TOOL_PROFILE
• MCP_TOOL_PROFILE（フォールバック用エイリアス）

動的ツールグループ（コンパクトモード）

compact モードでは、追加のツールが動的グループに整理され、必要に応じて自動的に有効になります。各グループについて Godot 4 のフィクスチャによる証拠が得られるまでは、成熟度ラベルを意図的に保守的に設定しています。

グループ	成熟度	説明／設定条件
scene_advanced	audit-required	ノードの複製や親の変更、スプライトの読み込みを行います。信頼できるものとして扱う前に、Godot 4 のフィクスチャでシーンの所有権と永続性を検証してください。
uid	audit-required	リソースの UID 管理を行います。Godot のバージョンとリソースの保存／読み込みの証拠に基づいて動作を制限してください。
import_export	audit-required	インポートパイプライン、再インポート、プロジェクトの検証を行います。インポート設定とエクスポートコマンドの構築について、フィクスチャでの確認が必要です。
autoload	audit-required	オートロードのシングルトンとメインシーンを扱います。プロジェクト設定の往復検証が必要です。
signal	audit-required	シグナルの切断と接続一覧の取得を行います。シグナルの往復検証が必要です。
runtime	optional-runtime	ライブシーンの検査、実行時プロパティ、メトリクスを扱います。ランタイムアドオン／ソケットが必要です。
resource	audit-required	マテリアル、シェーダー、リソースの作成／変更を行います。リソースの保存／読み込みについてフィクスチャでの確認が必要です。
animation	audit-required	アニメーション、トラック、アニメーションツリー、ステートマシンを扱います。保存済みのシーン／リソースによるフィクスチャ確認が必要です。
plugin	optional-editor	エディタープラグインの有効化／無効化／一覧表示を行います。エディタープラグインが利用可能である必要があります。
input	audit-required	入力アクションのマッピングを扱います。プロジェクト設定の往復検証が必要です。
tilemap	audit-required	TileSet と TileMap のセル描画を行います。有効化する前に、Godot 4.3 以降の TileMapLayer の動作を考慮する必要があります。
audio	audit-required	オーディオバス、エフェクト、音量を扱います。バスレイアウトについてフィクスチャでの確認が必要です。
navigation	audit-required	ナビゲーション領域とエージェントを扱います。保存済みのシーン／リソースによるフィクスチャ確認が必要です。
theme_ui	audit-required	テーマの色、フォントサイズ、シェーダーを扱います。リソースの保存／読み込みについてフィクスチャでの確認が必要です。
asset_store	optional-network	外部の CC0 アセットを検索／ダウンロードします。ネットワーク／プロバイダーが利用可能である必要があり、オプションのままにしてください。
testing	optional-runtime	スクリーンショット、ビューポートのキャプチャ、入力の注入を行います。ランタイムアドオン／エディターが利用可能である必要があります。
dx_tools	audit-required	エラーログ、プロジェクトの健全性、使用箇所の検索、ひな形作成を行います。決定論的な静的フィクスチャによる確認が必要です。
intent_tracking	workflow-layer	意図の記録、意思決定ログ、引き継ぎ概要を扱います。Godot エンジンのプリミティブではないため、オプトイン／ワークフローの範囲内にとどめてください。
class_advanced	trusted-static	クラスの継承を検査します。ClassDB／静的な証拠に照らして検証してください。
lsp	optional-lsp	GDScript の補完、ホバー、シンボルを扱います。ポート 6005 で Godot LSP が稼働している必要があります。
dap	optional-dap	ブレークポイント、ステップ実行、スタックトレースを扱います。ポート 6006 で Godot DAP が稼働している必要があります。
version_gate	audit-required	バージョンの検証とパッチの確認を行います。明示的なバージョンのフィクスチャ証拠が必要です。

仕組み：

1. カタログによる自動有効化：tool.catalog で検索すると、一致するグループが自動的に有効になります。

   "tool.catalog をクエリ animation で使用し、関連するツールを表示してください。"

2. 手動での有効化：tool.groups でグループを直接有効にします。

   "デバッグ用に tool.groups で dap グループを有効にしてください。"

3. 無効化：不要になったグループを解除して、コンテキストを減らします。

   "tool.groups を使って、有効なグループをすべてリセットしてください。"

サーバーは notifications/tools/list_changed を送信するため、MCP クライアント（Claude Code、Claude Desktop）はツール一覧を自動的に更新します。 MCP クライアントがツールを積極的にキャッシュし、有効化後に更新しない場合は、クライアントを再接続するか、新たに有効化したツールを一度直接呼び出して、最新の tools/list の往復を強制してください。

シーンツールの型付きプロパティ値

ブリッジ対応のシーンツール（add_node、set_node_properties）では、position や scale などの型付きプロパティに対して、{ "x": 100, "y": 200 } や [100, 200] のような一般的なベクターペイロードを変換できるようになりました。ツール間で安全に使うには、引き続きタグ付きの値が最適です。

{
  "position": { "type": "Vector2", "x": 100, "y": 200 },
  "scale": { "type": "Vector2", "x": 2, "y": 2 }
}

内部のヘッドレスシリアライザーでは _type を使用しますが、MCP クライアントがツール間で明示的な Godot 値タグを指定する場合は、type を使用してください。

トークンの心配は不要です

GoPeak は tools/list にカーソルベースのページネーションを使用します。full プロファイルでも、従来の定義セット全体を一度に出力するのではなく、ツールをページ単位（デフォルトは33件）で提供します。AI クライアントは、さらに必要になった場合にのみ次のページを取得します。

ページサイズは GOPEAK_TOOLS_PAGE_SIZE で設定します。

{
  "env": {
    "GOPEAK_TOOLS_PAGE_SIZE": "25"
  }
}

---

インストール方法

A）推奨：npx

npx -y gopeak

B）グローバルインストール

npm install -g gopeak
gopeak

更新通知用の任意のシェルフックも、以下から引き続き利用できます。

gopeak setup

C）ソースからインストール

git clone https://github.com/HaD0Yun/Gopeak-godot-mcp.git
cd godot-mcp
npm install
npm run build
node build/index.js

GoPeak では、次の2つの CLI バイナリ名も使用できます。

• gopeak
• godot-mcp

---

ドキュメント

• ドキュメント一覧
• アーキテクチャ
• プラットフォームのロードマップ
• Unity-MCP ベンチマーク計画
• リリースプロセス

CI

GitHub Actions は push/PR の際に実行され、次の処理を行います。

1. npm run build
2. npx tsc --noEmit
3. npm run smoke

PR を作成する前に、ローカルでも同じチェックを実行してください。

npm run ci
npm run test:dynamic-groups
npm run test:integration

---

バージョン管理とリリース

組み込みのバンプスクリプトを使用して、package.json と server.json のバージョンを同期させます。

node scripts/bump-version.mjs patch
node scripts/bump-version.mjs minor --dry-run

リリースチェックリストの全体については、docs/release-process.md を参照してください。

---

アドオン（推奨）

Auto Reload + Editor Bridge + Runtime Addon インストーラー

Godot プロジェクトフォルダーでインストールします。

curl -sL https://raw.githubusercontent.com/HaD0Yun/Gopeak-godot-mcp/main/install-addon.sh | bash

PowerShell：

iwr https://raw.githubusercontent.com/HaD0Yun/Gopeak-godot-mcp/main/install-addon.ps1 -UseBasicParsing | iex

その後、Project Settings → Plugins でプラグインを有効にします（特に、ブリッジ対応のシーン／リソースツールには godot_mcp_editor が必要です）。

---

主な機能

これらの機能は、ワークフロー上の用途ごとに分類されています。任意のランタイム／LSP／DAP／ネットワーク機能を使用するには、事前にセットアップが必要です。監査が必要な機能は、フィクスチャによる証拠を確認してから有効化してください。

• プロジェクト制御：エディターの起動、プロジェクトの実行／停止、デバッグ出力の取得
• シーン編集：シーンの作成、ノードの追加／削除／親の変更、プロパティの編集
• スクリプトのワークフロー：スクリプトの作成／変更、スクリプト構造の確認
• リソース：リソース、マテリアル、シェーダー、タイルセットの作成／変更
• シグナル／アニメーション：シグナルの接続、アニメーション／トラック／ステートマシンの構築
• ランタイムツール：実行中のツリーの確認、プロパティの設定、メソッドの呼び出し、メトリクスの取得（ランタイムアドオン／ソケットが必要）
• LSP + DAP：診断／補完／ホバー、およびブレークポイント／ステップ実行／スタックトレース（Godot の LSP／DAP ポートが必要）
• 入力 + スクリーンショット：キーボード／マウス／アクションの入力とビューポートのキャプチャ（ランタイム／エディターブリッジのセットアップが必要）
• アセットライブラリ：CC0 アセットの検索／取得（任意のネットワーク／プロバイダーを使用するワークフロー）

ツールの種類（例）

領域	例
プロジェクト	project.list、project.info、editor.run
シーン／ノード	scene.create、scene.node.add、set_node_properties
スクリプト	script.create、script.modify、script.info
ランタイム	runtime.status、inspect_runtime_tree、call_runtime_method
LSP/DAP	lsp.diagnostics、lsp_get_hover、dap_set_breakpoint、dap.output
入力／ビジュアル	inject_key、inject_mouse_click、capture_screenshot

---

プロジェクトビジュアライザー

visualizer.map（旧名 map_project）を使用して、プロジェクト全体のアーキテクチャを視覚化できます。スクリプトはフォルダー構成に基づいて、色分けされたカテゴリに分類されます。

---

プロンプトの例

ビルド

• 「CharacterBody2D、Sprite2D、CollisionShape2D と基本的な移動スクリプトを含む Player シーンを作成してください。」
• 「敵のスポーナーシーンを追加し、スポーンシグナルを GameManager に接続してください。」

デバッグ

• 「プロジェクトを実行してエラーを収集し、重大度の高い上位3件の問題を自動的に修正してください。」
• 「scripts/player.gd:42 にブレークポイントを設定して実行を続け、ヒットしたらスタックトレースを表示してください。」

ランタイムテスト

• 「ui_accept を押し、マウスを (400, 300) に移動してクリックし、スクリーンショットを撮影してください。」
• 「ライブのシーンツリーを調べ、スクリプトが見つからないノードや無効な参照があるノードを報告してください。」

ツールの検索と動的グループ

• 「tool.catalog でクエリ tilemap を使い、関連性の高いツールを一覧表示してください。」
• 「ブレークポイントデバッグ用に tool.groups で dap ツールグループを有効にしてください。」
• 「tool.catalog のクエリ import でインポートパイプラインのツールを探し、テクスチャ設定に最適なツールを実行してください。」
• 「コンテキストを減らすため、tool.groups で有効なツールグループをすべてリセットしてください。」

---

移行と非推奨化のポリシー

GoPeak では、compact を安全なデフォルトとして扱い、full／legacy は互換性プロファイルとして扱います。今後、非表示化、削除、名前変更、または API 契約の変更を行う場合は、以下を含める必要があります。

1. 旧名称から新名称への対応表、または代替手段がないことの明記。
2. プロファイル（compact、full、legacy、またはオプトインのグループ）への影響。
3. エイリアスを引き続き提供するかどうか、および削除予定時期。
4. README／ドキュメントとリリースノートの更新。
5. tools/list での公開状況とエイリアスの動作を確認する検証コマンド。
6. 一般的な Godot ワークフロー向けの移行プロンプトの例。

現在の互換性方針：従来のツール名と compact エイリアスは引き続きサポートされます。外部要件が任意の動的グループ（runtime、testing、lsp、dap、asset_store）は、常に利用可能なコア機能としてではなく、オプトインまたはセットアップが必要な機能として説明してください。

技術リファレンス

環境変数

名前	用途	デフォルト
GOPEAK_TOOL_PROFILE	ツールの公開プロファイル：compact、full、legacy	compact
MCP_TOOL_PROFILE	フォールバック用のプロファイル環境変数エイリアス	compact
GODOT_PATH	Godot 実行ファイルの明示的なパス	自動検出
GODOT_BRIDGE_PORT	Bridge／Visualizer の HTTP+WS ポートの上書き（エイリアス：MCP_BRIDGE_PORT、GOPEAK_BRIDGE_PORT）	6505
DEBUG	サーバーのデバッグログを有効化（true／false）	false
LOG_MODE	記録モード：lite または full	lite
GOPEAK_TOOLS_PAGE_SIZE	tools/list の1ページあたりのツール数（ページネーション）	33
GOPEAK_BRIDGE_PORT	統合 Bridge／Visualizer サーバーのポート	6505
GOPEAK_BRIDGE_HOST	Bridge／Visualizer サーバーのバインド先ホスト	127.0.0.1

ポート

ポート	サービス
6505（デフォルト）	統合 Godot Bridge + Visualizer サーバー（デフォルトではループバック上で /health、/mcp を提供）
6005	Godot LSP
6006	Godot DAP
7777	ランタイムアドオンのコマンドソケット（ランタイムツールでのみ必要）

最小限のポート構成

• コアの編集のみ：Bridge ポート（GODOT_BRIDGE_PORT、デフォルトは 6505）
• コア + ランタイム操作（スクリーンショット／入力／ランタイムの調査）：Bridge ポート + 7777
• 完全なデバッグ + 診断：Bridge ポート + 6005 + 6006 + 7777

---

トラブルシューティング

• Godot が見つからない → GODOT_PATH を設定してください
• MCP ツールが表示されない → MCP クライアントを再起動してください
• プロジェクトパスが無効 → project.godot が存在することを確認してください
• ランタイムツールが動作しない → ランタイムアドオンプラグインをインストール／有効化してください
• 表示されていないツールが必要 → tool.catalog を実行してツールを検索し、該当するグループを自動的に有効化するか、tool.groups を使って特定のグループを有効化してください
• Godot エディターでは接続済みと表示されるのに、get_editor_status では未接続と表示される → 別の gopeak／MCP サーバーのインスタンスが Bridge ポート 6505 をすでに使用していないか確認してください。ステータスのペイロードには、起動エラーが報告され、重複するサーバーの停止が提案されるようになりました

---

ドキュメントとプロジェクトリンク

• アーキテクチャ（MCP プラットフォームの方向性）
• プラットフォームロードマップ（P1/P2/P3）
• 変更履歴
• ロードマップ
• コントリビューションガイド

---

ライセンス

MIT — LICENSE を参照してください。

クレジット

• オリジナルの MCP サーバー：Coding-Solo
• GoPeak による機能強化：HaD0Yun
• プロジェクトビジュアライザーの着想元：tomyud1/godot-mcp