v0.1.10：Client 連線自動從 game_settings.csv 讀取 ENet port

v0.1.10 — Client 連線 ENet port 自動解析

Fixed

• Client 連線 ENet port 自動解析：client role 啟動時，args.connect_to 帶的 port 原本是 MCP WS port（例如 127.0.0.1:7070），但遊戲需要連的是 ENet port（例如 8910）。現在自動從 Data/CSV/game_settings.csv 讀取 network,default_port 的值，取代 connect_to 的 port，讓遊戲連到正確的 ENet 伺服器。若 game_settings.csv 不存在或無對應 row，則沿用原 connect_to（遊戲內建預設 port）。

Tests

• 新增 3 個測試：_read_enet_port 找到 port、檔案不存在回 None、row 不存在回 None。

完整測試套件：62 passed

v0.1.9：遊戲實體路由——runtime 工具自動導向獨立遊戲行程

v0.1.9 — 遊戲實體路由（Game Instance Routing）

Added

• 遊戲實體路由：當透過 godot_network switch 切換到獨立遊戲行程時，runtime 類工具（godot_exec、godot_game、godot_game_time、godot_input、godot_runtime_state、godot_screenshot、godot_profiler、godot_log）自動路由到該遊戲行程，而非編輯器的 PIE。編輯器專屬工具（godot_editor_read、godot_scene、godot_node_read、godot_script、godot_project）仍走編輯器 bridge，互不干擾。明確指定 instance_id 時優先於 active instance。
• godot_network switch 支援 editor：傳入 instance_id="editor"（或空字串）可清除 active game instance，讓 runtime 工具回退到編輯器。
• GameInstanceManager.clear_active()：新增 API 清除 active game instance。
• Runtime autoload 新增 play / stop / status 方法：standalone runtime 可回報 runtime_ready、is_playing、runtime_connected、fps，並支援停止行程。

Tests

• 新增 tests/test_game_instance_routing.py（8 個測試，全綠）：涵蓋 runtime 工具集定義、路由到 active game instance、編輯器工具不路由、無 game instance 時回退編輯器、明確 instance_id 覆寫、clear_active() 行為、switch editor 清除 active。

完整測試套件：59 passed

v0.1.8：Dock 極窄裁切根因修正 + .gitignore 補充

修正 Dock 極窄裁切 + .gitignore 補充 + README 更新

修正

Dock 極窄時文字被裁切（根因修正）

CheckButton/Button 的文字有不可壓縮的最小寬度。長文字如「視覺（看圖，base64 直傳）」強迫 VBox 至其最小寬度，dock 縮到最窄時右邊被裁掉約一個中文字元。

修法：_ready() 遞迴設所有 Button/CheckButton/OptionButton 的 text_overrun_behavior = OVERRUN_TRIM_ELLIPSIS，允許按鈕縮到文字寬度以下並顯示「…」而非硬裁切。

截圖清理區排列改善

從 HBoxContainer（Label + SpinBox 同行）改為 VBoxContainer（Label 在上、SpinBox 在下），SpinBox 取得完整列寬，不再跟 Label 搶水平空間。

變更

• .gitignore 補充：新增 coverage/profiling、Jupyter、type stubs、Poetry/Pipfile lock、Windows shortcuts、Godot export temp 等開源專案常見排除項
• README 更新：版號至 0.1.8，新增截圖清理 UI、專案級設定檔功能說明

更新方式

open-godot-mcp --shutdown-all
uv sync

重開 Godot 即可。

v0.1.7：修正 Dock 縮窄裁切

修正 Dock 縮窄裁切

v0.1.6 新增的截圖清理區把 4 個元件（2 Label + 2 SpinBox）塞在同一行，dock 寬度縮小時右側被裁切。

修正內容

• 拆成兩行：每行只有 1 Label + 1 SpinBox，最小寬度減半
• Label 加 autowrap_mode = 3 + size_flags_horizontal = 3（expand fill），縮窄時文字自動換行不溢出
• mcp_dock.gd 的 @onready 路徑同步更新（ScreenshotRow → ScreenshotRow1 / ScreenshotRow2）

v0.1.6：Dock 面板三大改善

Dock 面板三大改善

1. 截圖自動清理 UI

Dock 面板新增截圖清理設定區（兩個 SpinBox）：

• 最大保留數（預設 50）：超過此數自動刪最舊的
• 最大保留時數（預設 24h）：超過此時數自動刪除

直接在 Godot 編輯器內調整，存於 ProjectSettings（per-project），不再需要手動改設定檔。

2. 專案級設定檔

Dock 面板新增「設定檔位置」區，含「使用專案級設定檔」勾選框：

• 未勾選（預設）：設定檔存於 ~/.open_godot_mcp/config.json（使用者家目錄，全域共用）
• 勾選：設定檔存於 <專案根目錄>/.open_godot_mcp/config.json（per-project，不同專案可用不同 API key）

Dock 透過 agnes_config_changed 事件將路徑傳給 Python server，server 動態切換讀取位置。勾選時會顯示 git 安全警告（提醒加入 .gitignore）。

3. Dock Tab 重命名

McpDock → OpenGodot，更直觀、更符合品牌名。

更新方式

open-godot-mcp --shutdown-all
uv sync

重開 Godot 即可看到新的 Dock 面板。

v0.1.5：行程生命週期管理 + 版號單一真相來源

行程生命週期管理 + 版號單一真相來源

解決的問題

Windows 上 MCP server 孤兒行程無限累積——每次 AI client（Devin、Cursor、Windsurf 等）crash 或重啟，就漏一個 open-godot-mcp.exe 行程永遠活著，像病毒一樣越開越多。更新時 .exe 被 Windows 鎖定，uv sync 失敗，只能手動工作管理員殺行程或重開電腦。

新增

• Parent watchdog：server 啟動時起 daemon thread，每 5 秒檢查 parent 行程是否存活。parent 死了 → 立即 self-exit。Linux/macOS 靠 stdin EOF 自然退出，Windows 的 inherited handle 不會關閉，需要這個 watchdog。
• --shutdown-all CLI：open-godot-mcp --shutdown-all 終止所有執行中的 server 行程（不含自己）。更新前跑一次即可解鎖 .exe。
• 新增 lifecycle.py：跨平台 parent 存活檢查 + watchdog thread + shutdown_all_instances()。

變更

• 版號單一真相來源：__init__.py 用 importlib.metadata.version() 從 pyproject.toml 讀取，__main__.py、context.py、bridge.py 全部引用 __version__。不再需要手動同步 4 個檔案。
• .gitignore 補完開源專案常見排除。
• README.md / README_EN.md 新增行程生命週期管理區段。

更新方式

# 1. 一鍵清場（殺所有殘留 server 行程，解鎖 .exe）
open-godot-mcp --shutdown-all
# 2. 更新
uv sync
# 3. MCP client 重啟後自動拉起新版 server

v0.1.4 — 截圖自動清理

v0.1.4 — 截圖自動清理

新增

• 截圖自動清理：解決截圖無限累積導致專案垃圾檔越來越多的問題。截圖存到 user://mcp_screenshots/ 後從不清理，burst 一次產生 10+ 個檔案，長期使用垃圾檔不斷堆積。新增三層清理機制：
  • 自動輪轉：每次 game / editor / region / burst 存檔後，自動刪除最舊截圖，只保留最近 N 張（預設 50，可設定）
  • 過期淘汰：刪除超過指定時長的舊截圖（預設 24 小時，依檔案修改時間）
  • 手動 cleanup action：godot_screenshot cleanup 可隨時主動清理，支援 max_count / max_age_hours 參數覆蓋預設
  • 兩個 ProjectSettings 設定項可在 Godot 專案設定介面調整：
    • open_godot_mcp/screenshot_max_count（預設 50，設 0 關閉輪轉）
    • open_godot_mcp/screenshot_max_age_hours（預設 24，設 0 關閉過期淘汰）
  • 新增共用工具 addons/open_godot_mcp/utils/screenshot_cleanup.gd，editor handler 和 runtime autoload 共用

變更

• .gitignore 補完 Python 工具 cache 和 build artifact 排除規則（.pytest_cache/、.ruff_cache/、.mypy_cache/、*.egg-info/、build/、dist/）
• README.md 更新：Token 效率區塊加入截圖自動清理說明、工具清單截圖欄加「自動清理」
• 進版 0.1.3 → 0.1.4

測試

• 4 個 GDScript 檔案語法驗證全通過（screenshot_cleanup.gd、screenshot_handler.gd、runtime_autoload.gd、plugin.gd）
• 51 tests passed
• Godot 連線健康檢查通過

完整變更紀錄見 CHANGELOG.md。

v0.1.3 — Agnes/NVIDIA API 整合 + 5xx 自動重試

v0.1.3 — Agnes/NVIDIA API 整合 + 5xx 自動重試 + 清理 AHD harness 檔案

新增

• Agnes / NVIDIA AI API 整合（5 個動態註冊工具，預設關閉）
  • agnes_vision — Agnes 2.0 Flash 視覺（URL-only，本地檔自動上傳 uguu.se）
  • agnes_image_generate — Agnes Image 2.0 Flash 文生圖/圖生圖（免費）
  • agnes_video_generate — Agnes Video V2.0 產影片（非同步任務，免費）
  • nvidia_vision — NVIDIA NIM VLM 視覺（base64 直傳，免上傳）
  • nvidia_image_generate — NVIDIA FLUX.2-klein-4b 產圖（免費）
  • Config 存於 ~/.open_godot_mcp/config.json（user home，不在 git repo 內）
  • API key 輪換：api_keys 支援多 key（陣列）。429/402/401 時自動換下一個 key 重試，所有 key 耗盡才 backoff。向後相容舊 api_key（單字串）。
  • 熱重載：dock 存檔 → bridge event agnes_config_changed → MCP server 動態 add_tool/remove_tool
  • 5xx 自動重試：500/502/503/504/524 歸類為 SERVER_ERROR，backoff [2,4,8]s 重試最多 3 次（依 Agnes 官方文檔 §503「Retry later」建議）
  • git 安全檢查：config 路徑在 git repo 內且未被 .gitignore 排除時，dock 顯示橘色警告
• Dock i18n：20 種語言選擇器（對齊 README 翻譯清單）
• 新錯誤碼：SERVER_ERROR、QUOTA_EXHAUSTED、AUTH_FAILED、UPLOAD_FAILED

變更

• Dock 面板重構：新增 Agnes/NVIDIA API 區塊、語言選擇器、git 安全警告、MCP 未連線提示
• 清理 git repo：移除 ~500 個 AHD（Agent Harness Deploy）harness 檔案（.agents/、.devin/、.codex/、.hermes/、.windsurf/、AGENTS.md）和 plans/ 內部規劃文件。這些是個人 AI 工具鏈設定，非開源產品一部分。
• .gitignore 新增 AHD 排除 + secrets 排除（**/config.json、**/api_keys.json）
• README.md 更新：加入 Agnes/NVIDIA 整合說明、工具數 ~30 → ~35、FAQ 新增
• 進版 0.1.2 → 0.1.3

測試

• 51 tests passed
• MCP 端對端測試：agnes_vision ✅、agnes_image_generate ✅（含 503 retry 驗證）、agnes_video_generate ✅、nvidia_vision ✅、nvidia_image_generate ✅

完整變更紀錄見 CHANGELOG.md。

v0.1.1 — 自動更新通知 + UI 修復

Open Godot MCP v0.1.1 — 自動更新通知 + UI 修復

新增功能

🔔 自動更新通知

像 godot-ai 一樣，安裝了 Open Godot MCP 的使用者會在 MCP 面板看到新版通知：

• 啟動時自動查詢 GitHub Releases API
• 比較 plugin.cfg 中的版本號
• 偵測到新版時顯示 「Update available: vX.Y.Z」 通知 banner
• 提供 Update 按鈕（一鍵更新）和 Release notes 連結

⬆️ 一鍵更新

點擊 Update 按鈕後全自動完成：

1. 下載 open-godot-mcp-plugin.zip（從 GitHub Release asset）
2. SHA-256 checksum 驗證
3. 停用舊插件
4. 解壓新檔案到 addons/open_godot_mcp/（含備份 + 回滾機制）
5. 檔案系統掃描
6. 重新啟用插件

🛡️ 安全設計

• URL 信任驗證：只從 github.com/masteryee-labs/Open-Godot-MCP/releases/download/ 下載
• 路徑安全檢查：拒絕 zip slip、目錄穿越攻擊
• 備份 + 回滾：安裝失敗時自動回滾到前一版本
• 混合狀態偵測：如果回滾也失敗，保持插件停用狀態並提示手動修復

修復

🖥️ MCP 面板 UI 溢出修復

視窗縮小時文字和按鈕不再超出框框：

• 加入 ScrollContainer 包裹所有內容（支援垂直捲動）
• Label 加入 autowrap_mode（自動換行）
• Button 加入 size_flags_horizontal = SIZE_EXPAND_FILL（填滿寬度）
• 關閉水平捲軸（只允許垂直捲動）

新增檔案

檔案	用途
addons/open_godot_mcp/utils/update_manager.gd	版本檢查 + HTTP 下載 + URL 信任驗證
addons/open_godot_mcp/utils/update_reload_runner.gd	ZIP 解壓 + 備份/回滾 + 插件重載
.github/workflows/release.yml	發布 release 時自動建構 ZIP + SHA256

下載

• PyPI: pip install open-godot-mcp
• 原始碼: https://github.com/masteryee-labs/Open-Godot-MCP
• 文件: https://github.com/masteryee-labs/Open-Godot-MCP/tree/main/Docs

從 v0.1.0 升級

如果你已安裝 v0.1.0：

1. 開啟 Godot 編輯器
2. 查看 MCP 面板（右下角 dock）
3. 看到「Update available: v0.1.1」通知
4. 點擊 Update 按鈕
5. 等待自動下載 + 安裝 + 重載完成

或手動更新：

pip install --upgrade open-godot-mcp

v0.1.0 — 首次發布：AI 自主 Godot 遊戲開發 MCP

Open Godot MCP v0.1.0 — 首次發布

這是什麼？

Open Godot MCP 是一個開源的 Model Context Protocol (MCP) server，讓 AI 程式助手（Claude、Cursor、Windsurf 等）自主開發、測試、除錯 Godot 遊戲。

核心功能

🎮 確定性 Playtesting

AI 不只寫程式，還能自己玩遊戲驗證修復：

• freeze 凍結遊戲時鐘
• step 精確推進時間
• step_until 等待條件達成
• JSON state digest 觀察狀態（不燒 vision token）

🌐 連線遊戲測試（獨有功能）

唯一支援連線遊戲測試的 Godot MCP：

• 多實例啟動（host + client）
• Peer 模擬
• 網路條件注入（延遲、封包遺失）
• 同步狀態驗證

🐛 DAP 除錯

• Breakpoint 設定/移除
• stack_trace — 呼叫堆疊
• variables — 變數檢查（local + member + global）
• evaluate — 表達式求值

📝 LSP 整合

• 靜態診斷
• 自動完成
• Go-to-definition

💰 Token 效率

• JSON state digest 取代截圖（省 90% token）
• Diff 回傳（只回傳變更部分）
• 截圖壓縮（JPEG/WebP + 存磁碟）
• Read/write 分離
• 批次操作

🔌 連線穩定

• 可配置 port（env > EditorSettings > 自動避讓）
• Windows Port Reservation 偵測
• 心跳機制
• 智慧重連（指數退避）

工具清單

~30 MCP tools，~130 actions：

領域	工具
編輯器	godot_editor_read/edit
場景/節點	godot_scene, godot_node_read/edit
腳本/資源	godot_script, godot_resource
遊戲控制	godot_game, godot_game_time, godot_input
狀態/注入	godot_runtime_state, godot_exec
除錯	godot_debugger (DAP)
程式碼	godot_lsp
效能	godot_profiler
測試	godot_test
連線	godot_network
其他	godot_screenshot, godot_filesystem, godot_batch, godot_export 等

規格

項目	值
Godot 版本	4.5+
Python 版本	3.11+
授權	MIT（100% 開源）
平台	Windows, macOS, Linux
AI 客戶端	Claude, Cursor, Windsurf, VS Code, Zed, 任何 MCP 相容客戶端
語言支援	20 語言 README

安裝

uv tool install open-godot-mcp
# 或
pip install open-godot-mcp

與現有 Godot MCP 比較

特性	其他 MCP	Open Godot MCP
編輯器操作	✅	✅
真實遊戲操作	⚠️ 部分	✅ 確定性+即時
連線遊戲測試	❌ 全缺	✅ 獨有
DAP 除錯	❌ 全缺	✅
LSP 整合	❌ 全缺	✅
Token 效率	⚠️ 部分	✅ 全面
連線穩定	⚠️	✅ 最穩
授權	部分付費	100% MIT 免費

致謝

本專案站在巨人的肩膀上，截優去短自以下專案：

• Coding-Solo/godot-mcp（4.8k stars）
• satelliteoflove/godot-mcp
• hi-godot/godot-ai
• tomyud1/godot-mcp
• rosskarchner/godot-mcp
• Erodenn/godot-mcp-runtime
• thediymaker/godot-mcp

下載

• PyPI: pip install open-godot-mcp
• 原始碼: https://github.com/masteryee-labs/Open-Godot-MCP
• 文件: https://github.com/masteryee-labs/Open-Godot-MCP/tree/main/Docs