gopeak 2.1.0 → 2.2.0

package/README.md

@@ -14,108 +14,149 @@
 
 **GoPeak is an MCP server for Godot that lets AI assistants run, inspect, modify, and debug real projects end-to-end.**
 
-> Includes Auto Reload: when MCP edits scenes/scripts, the Godot editor refreshes automatically.
+---
+
+## Quick Start (3 Minutes)
+
+### Requirements
+
+- Godot 4.x
+- Node.js 18+
+- MCP-compatible client (Claude Desktop, Cursor, Cline, OpenCode, etc.)
+
+### 1) Run GoPeak
+
+```bash
+npx -y gopeak
+```
+
+or install globally:
+
+```bash
+npm install -g gopeak
+gopeak
+```
+
+### 2) Add MCP client config
+
+```json
+{
+  "mcpServers": {
+    "godot": {
+      "command": "npx",
+      "args": ["-y", "gopeak"],
+      "env": {
+        "GODOT_PATH": "/path/to/godot",
+        "GOPEAK_TOOL_PROFILE": "compact"
+      }
+    }
+  }
+}
+```
+
+> `GOPEAK_TOOL_PROFILE=compact` is the default. It keeps prompt/tool-list token usage low while preserving access to the full toolset via catalog discovery.
+
+### 3) First prompts to try
+
+- "List Godot projects in `/your/projects` and show project info."
+- "Create `scenes/Player.tscn` with `CharacterBody2D` root and add a movement script."
+- "Run project, get debug output, then fix top error."
 
 ---
 
-## Why GoPeak (Short Version)
+## Why GoPeak
 
-- **Real project feedback loop**: run the game, read logs, fix issues in-context.
-- **95+ tools** across scene, script, resource, runtime, LSP, DAP, input, and assets.
-- **Deep Godot integration**: ClassDB introspection, runtime inspection, debugger hooks.
-- **Faster iteration**: less copy-paste, more direct implementation/testing.
+- **Real project feedback loop**: run the game, inspect logs, and fix in-context.
+- **95+ tools available** across scene/script/resource/runtime/LSP/DAP/input/assets.
+- **Token-efficient by default**: compact tool surface for lower context overhead.
+- **Discoverability built-in**: use `tool.catalog` (alias of `tool_catalog`) to find hidden or legacy tools by keyword.
+- **Deep Godot integration**: ClassDB queries, runtime inspection, debugger hooks, bridge-based scene/resource edits.
 
 ### Best For
 
-- Solo/indie developers building quickly with AI assistance
-- Teams that want AI to inspect real project state, not just generate snippets
-- Debug-heavy workflows where runtime introspection and breakpoints matter
+- Solo/indie developers moving quickly with AI assistance
+- Teams that need AI grounded in actual project/runtime state
+- Debug-heavy workflows (breakpoints, stack traces, live runtime checks)
 
 ---
 
-## GoPeak vs Upstream (Coding-Solo/godot-mcp)
+## Tool Surface Model (Important)
 
-| Capability | Upstream | GoPeak |
-|---|---|---|
-| GDScript LSP tools | Not available in README tool list | ✅ `lsp_get_diagnostics`, `lsp_get_completions`, `lsp_get_hover`, `lsp_get_symbols` |
-| DAP debugging tools | Not available in README tool list | ✅ breakpoints, step/continue/pause, stack trace, debug output |
-| Input injection tools | Not available in README tool list | ✅ `inject_action`, `inject_key`, `inject_mouse_click`, `inject_mouse_motion` |
-| Screenshot capture tools | Not available in README tool list | ✅ `capture_screenshot`, `capture_viewport` |
-| Auto Reload editor plugin | Not available | ✅ included `auto_reload` addon |
-| Tool coverage scale | Smaller documented scope | ✅ 95+ MCP tools |
+GoPeak supports three exposure profiles:
 
----
+- `compact` (default): exposes a curated alias set (about 20 core tools)
+- `full`: exposes full legacy tool list (95+)
+- `legacy`: same exposed behavior as `full`
 
-## Requirements
+Configure with either:
 
-- Godot 4.x
-- Node.js 18+
-- MCP-compatible client (Claude Desktop, Cursor, Cline, OpenCode, etc.)
+- `GOPEAK_TOOL_PROFILE`
+- `MCP_TOOL_PROFILE` (fallback alias)
+
+### How to discover hidden tools in compact mode
+
+Call:
+
+- `tool.catalog` (compact alias)
+- `tool_catalog` (legacy name)
+
+Example intent:
+
+> "Use `tool.catalog` with query `animation` and show relevant tools."
+
+This lets assistants start with a small, efficient default surface but still find and use the full capability set when needed.
 
 ---
 
-## Installation
+## Installation Options
 
-### 1) Fastest (recommended)
+### A) Recommended: npx
 
 ```bash
-npx gopeak
+npx -y gopeak
 ```
 
-or
+### B) Global install
 
 ```bash
 npm install -g gopeak
 gopeak
 ```
 
-### 2) Manual (from source)
+### C) From source
 
 ```bash
 git clone https://github.com/HaD0Yun/godot-mcp.git
 cd godot-mcp
 npm install
 npm run build
+node build/index.js
 ```
 
-Set `GODOT_PATH` if Godot is not auto-detected.
+GoPeak also exposes two CLI bin names:
 
-### MCP Client Config (practical examples)
+- `gopeak`
+- `godot-mcp`
 
-Use one of these depending on your client.
+---
 
-**A) Global install (`npm install -g gopeak`)**
+## Addons (Recommended)
 
-```json
-{
-  "mcpServers": {
-    "godot": {
-      "command": "gopeak",
-      "env": {
-        "GODOT_PATH": "/path/to/godot"
-      }
-    }
-  }
-}
+### Auto Reload + Runtime Addon installer
+
+Install in your Godot project folder:
+
+```bash
+curl -sL https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install-addon.sh | bash
 ```
 
-**B) No global install (npx mode)**
+PowerShell:
 
-```json
-{
-  "mcpServers": {
-    "godot": {
-      "command": "npx",
-      "args": ["-y", "gopeak"],
-      "env": {
-        "GODOT_PATH": "/path/to/godot"
-      }
-    }
-  }
-}
+```powershell
+iwr https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install-addon.ps1 -UseBasicParsing | iex
 ```
 
-> Tip: If your client uses `args` array style only, use `"command": "npx"` + `"args": ["-y", "gopeak"]`.
+Then enable plugin in **Project Settings → Plugins**.
 
 ---
 
@@ -131,18 +172,27 @@ Use one of these depending on your client.
 - **Input + screenshots**: keyboard/mouse/action injection and viewport capture
 - **Asset library**: search/fetch CC0 assets (Poly Haven, AmbientCG, Kenney)
 
-### Tool Coverage at a Glance
+### Tool families (examples)
 
 | Area | Examples |
 |---|---|
-| Scene/Node | `create_scene`, `add_node`, `set_node_properties` |
-| Script | `create_script`, `modify_script`, `get_script_info` |
-| Runtime | `inspect_runtime_tree`, `call_runtime_method` |
-| LSP/DAP | `lsp_get_diagnostics`, `dap_set_breakpoint` |
+| Project | `project.list`, `project.info`, `editor.run` |
+| Scene/Node | `scene.create`, `scene.node.add`, `set_node_properties` |
+| Script | `script.create`, `script.modify`, `script.info` |
+| Runtime | `runtime.status`, `inspect_runtime_tree`, `call_runtime_method` |
+| LSP/DAP | `lsp.diagnostics`, `lsp_get_hover`, `dap_set_breakpoint`, `dap.output` |
 | Input/Visual | `inject_key`, `inject_mouse_click`, `capture_screenshot` |
 
 ---
 
+## Project Visualizer
+
+Visualize your entire project architecture with `visualizer.map` (`map_project` legacy). Scripts are grouped by folder structure into color-coded categories.
+
+![Project Visualizer — AI-generated architecture map](assets/visualizer-category-map.png)
+
+---
+
 ## Quick Prompt Examples
 
 ### Build
@@ -151,27 +201,44 @@ Use one of these depending on your client.
 
 ### Debug
 - "Run the project, collect errors, and fix the top 3 issues automatically."
-- "Set a breakpoint at `scripts/player.gd:42`, continue execution, and show the stack trace when hit."
+- "Set a breakpoint at `scripts/player.gd:42`, continue execution, and show stack trace when hit."
 
-### Runtime Testing
+### Runtime testing
 - "Press `ui_accept`, move mouse to (400, 300), click, then capture a screenshot."
-- "Inspect the live scene tree and report nodes with missing scripts or invalid references."
+- "Inspect live scene tree and report nodes with missing scripts or invalid references."
 
-### Refactor / Maintenance
-- "Find all TODO/FIXME comments and group them by file with a priority suggestion."
-- "Analyze project health and list quick wins to improve stability before release."
+### Discovery in compact mode
+- "Use `tool.catalog` with query `tilemap` and list the most relevant tools."
+- "Find import pipeline tools with `tool.catalog` query `import` and run the best one for texture settings."
 
 ---
 
-## Auto Reload Addon (Recommended)
+## Technical Reference
 
-Install in your Godot project folder:
+### Environment variables
 
-```bash
-curl -sL https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install-addon.sh | bash
-```
+| Name | Purpose | Default |
+|---|---|---|
+| `GOPEAK_TOOL_PROFILE` | Tool exposure profile: `compact`, `full`, `legacy` | `compact` |
+| `MCP_TOOL_PROFILE` | Fallback profile env alias | `compact` |
+| `GODOT_PATH` | Explicit Godot executable path | auto-detect |
+| `DEBUG` | Enable server debug logs (`true`/`false`) | `false` |
+| `LOG_MODE` | Recording mode: `lite` or `full` | `lite` |
 
-Then enable plugin in **Project Settings → Plugins**.
+### Ports
+
+| Port | Service |
+|---|---|
+| `6505` | Unified Godot Bridge + Visualizer server (+ `/health`, `/mcp`) |
+| `6005` | Godot LSP |
+| `6006` | Godot DAP |
+| `7777` | Runtime addon command socket (only needed for runtime tools) |
+
+### Minimal port profiles
+
+- **Core editing only**: `6505`
+- **Core + runtime actions (screenshots/input/runtime inspect)**: `6505` + `7777`
+- **Full debugging + diagnostics**: `6505` + `6005` + `6006` + `7777`
 
 ---
 
@@ -180,7 +247,8 @@ Then enable plugin in **Project Settings → Plugins**.
 - **Godot not found** → set `GODOT_PATH`
 - **No MCP tools visible** → restart your MCP client
 - **Project path invalid** → confirm `project.godot` exists
-- **Runtime tools not working** → install/enable runtime addon
+- **Runtime tools not working** → install/enable runtime addon plugin
+- **Need a tool that is not visible** → run `tool.catalog` and search by capability keyword
 
 ---
 
@@ -200,3 +268,4 @@ MIT — see [LICENSE](LICENSE).
 
 - Original MCP server by [Coding-Solo](https://github.com/Coding-Solo/godot-mcp)
 - GoPeak enhancements by [HaD0Yun](https://github.com/HaD0Yun)
+- Project visualizer inspired by [tomyud1/godot-mcp](https://github.com/tomyud1/godot-mcp)

package/build/addon/godot_mcp_editor/mcp_client.gd

@@ -0,0 +1,161 @@
+@tool
+extends Node
+class_name MCPEditorClient
+
+signal connected
+signal disconnected
+signal tool_requested(request_id: String, tool_name: String, args: Dictionary)
+
+const DEFAULT_URL := "ws://127.0.0.1:6505/godot"
+const RECONNECT_DELAY := 3.0
+const MAX_RECONNECT_DELAY := 30.0
+
+var socket: WebSocketPeer = WebSocketPeer.new()
+var server_url: String = DEFAULT_URL
+var _is_connected := false
+var _reconnect_timer: Timer
+var _current_reconnect_delay := RECONNECT_DELAY
+var _should_reconnect := true
+var _project_path: String
+var _initialized := false
+
+
+func _ready() -> void:
+	_project_path = ProjectSettings.globalize_path("res://")
+
+	_reconnect_timer = Timer.new()
+	_reconnect_timer.one_shot = true
+	_reconnect_timer.timeout.connect(_on_reconnect_timer)
+	add_child(_reconnect_timer)
+
+	set_process(true)
+	_initialized = true
+
+
+func _process(_delta: float) -> void:
+	if not _initialized:
+		return
+
+	if socket.get_ready_state() == WebSocketPeer.STATE_CLOSED:
+		if _is_connected:
+			_handle_disconnect()
+		return
+
+	socket.poll()
+
+	match socket.get_ready_state():
+		WebSocketPeer.STATE_OPEN:
+			if not _is_connected:
+				_handle_connect()
+
+			while socket.get_available_packet_count() > 0:
+				var packet := socket.get_packet()
+				_handle_message(packet.get_string_from_utf8())
+
+		WebSocketPeer.STATE_CLOSING:
+			pass
+
+		WebSocketPeer.STATE_CLOSED:
+			if _is_connected:
+				_handle_disconnect()
+
+
+func connect_to_server(url: String = DEFAULT_URL) -> void:
+	server_url = url
+	_should_reconnect = true
+	_current_reconnect_delay = RECONNECT_DELAY
+	_attempt_connection()
+
+
+func disconnect_from_server() -> void:
+	_should_reconnect = false
+	if _reconnect_timer:
+		_reconnect_timer.stop()
+	if socket.get_ready_state() == WebSocketPeer.STATE_OPEN:
+		socket.close()
+	_is_connected = false
+
+
+func _attempt_connection() -> void:
+	if socket.get_ready_state() != WebSocketPeer.STATE_CLOSED:
+		socket.close()
+
+	var err := socket.connect_to_url(server_url)
+	if err != OK:
+		push_error("[MCP Editor] Failed to connect: %s" % err)
+		_schedule_reconnect()
+
+
+func _handle_connect() -> void:
+	_is_connected = true
+	_current_reconnect_delay = RECONNECT_DELAY
+
+	_send_message({
+		"type": "godot_ready",
+		"project_path": _project_path
+	})
+
+	connected.emit()
+
+
+func _handle_disconnect() -> void:
+	_is_connected = false
+	disconnected.emit()
+
+	if _should_reconnect:
+		_schedule_reconnect()
+
+
+func _schedule_reconnect() -> void:
+	if _reconnect_timer == null:
+		return
+	_reconnect_timer.start(_current_reconnect_delay)
+	_current_reconnect_delay = min(_current_reconnect_delay * 2.0, MAX_RECONNECT_DELAY)
+
+
+func _on_reconnect_timer() -> void:
+	_attempt_connection()
+
+
+func _handle_message(json_string: String) -> void:
+	var message = JSON.parse_string(json_string)
+	if message == null:
+		push_error("[MCP Editor] Failed to parse message: %s" % json_string)
+		return
+
+	match message.get("type", ""):
+		"ping":
+			_send_message({"type": "pong"})
+
+		"tool_invoke":
+			var request_id: String = message.get("id", "")
+			var tool_name: String = message.get("tool", "")
+			var args: Dictionary = message.get("args", {})
+			tool_requested.emit(request_id, tool_name, args)
+
+		_:
+			pass
+
+
+func send_tool_result(request_id: String, success: bool, result = null, error: String = "") -> void:
+	var response := {
+		"type": "tool_result",
+		"id": request_id,
+		"success": success
+	}
+
+	if success:
+		response["result"] = result
+	else:
+		response["error"] = error
+
+	_send_message(response)
+
+
+func _send_message(message: Dictionary) -> void:
+	if socket.get_ready_state() == WebSocketPeer.STATE_OPEN:
+		socket.send_text(JSON.stringify(message))
+
+
+func is_connected_to_server() -> bool:
+	return _is_connected

package/build/addon/godot_mcp_editor/plugin.cfg

@@ -0,0 +1,6 @@
+[plugin]
+name="Godot MCP Editor"
+description="MCP Editor Plugin - Scene manipulation via Godot API"
+author="HaD0Yun"
+version="1.0.0"
+script="plugin.gd"

package/build/addon/godot_mcp_editor/plugin.gd

@@ -0,0 +1,84 @@
+@tool
+extends EditorPlugin
+
+const MCPEditorClientScript = preload("mcp_client.gd")
+const MCPToolExecutorScript = preload("tool_executor.gd")
+
+var _mcp_client: Node
+var _tool_executor: Node
+var _status_label: Label
+
+
+func _enter_tree() -> void:
+	_mcp_client = MCPEditorClientScript.new()
+	_mcp_client.name = "MCPEditorClient"
+	add_child(_mcp_client)
+
+	_tool_executor = MCPToolExecutorScript.new()
+	_tool_executor.name = "MCPToolExecutor"
+	add_child(_tool_executor)
+	_tool_executor.set_editor_plugin(self)
+
+	_mcp_client.connected.connect(_on_connected)
+	_mcp_client.disconnected.connect(_on_disconnected)
+	_mcp_client.tool_requested.connect(_on_tool_requested)
+
+	_setup_status_indicator()
+	_mcp_client.connect_to_server()
+
+
+func _exit_tree() -> void:
+	if _mcp_client:
+		if _mcp_client.connected.is_connected(_on_connected):
+			_mcp_client.connected.disconnect(_on_connected)
+		if _mcp_client.disconnected.is_connected(_on_disconnected):
+			_mcp_client.disconnected.disconnect(_on_disconnected)
+		if _mcp_client.tool_requested.is_connected(_on_tool_requested):
+			_mcp_client.tool_requested.disconnect(_on_tool_requested)
+		_mcp_client.disconnect_from_server()
+		_mcp_client.queue_free()
+		_mcp_client = null
+
+	if _tool_executor:
+		_tool_executor.queue_free()
+		_tool_executor = null
+
+	if _status_label:
+		remove_control_from_container(CONTAINER_TOOLBAR, _status_label)
+		_status_label.queue_free()
+		_status_label = null
+
+
+func _setup_status_indicator() -> void:
+	_status_label = Label.new()
+	_status_label.text = "MCP: Connecting..."
+	_status_label.add_theme_color_override("font_color", Color.YELLOW)
+	_status_label.add_theme_font_size_override("font_size", 12)
+	add_control_to_container(CONTAINER_TOOLBAR, _status_label)
+
+
+func _on_connected() -> void:
+	if _status_label:
+		_status_label.text = "MCP: Connected"
+		_status_label.add_theme_color_override("font_color", Color.GREEN)
+
+
+func _on_disconnected() -> void:
+	if _status_label:
+		_status_label.text = "MCP: Disconnected"
+		_status_label.add_theme_color_override("font_color", Color.RED)
+
+
+func _on_tool_requested(request_id: String, tool_name: String, args: Dictionary) -> void:
+	if _tool_executor == null or _mcp_client == null:
+		return
+
+	var result: Dictionary = _tool_executor.execute_tool(tool_name, args)
+	var success: bool = result.get("ok", false)
+
+	if success:
+		var payload := result.duplicate(true)
+		payload.erase("ok")
+		_mcp_client.send_tool_result(request_id, true, payload, "")
+	else:
+		_mcp_client.send_tool_result(request_id, false, null, str(result.get("error", "Unknown error")))

package/build/addon/godot_mcp_editor/tool_executor.gd

@@ -0,0 +1,114 @@
+@tool
+extends Node
+class_name MCPToolExecutor
+
+var _editor_plugin: EditorPlugin = null
+
+var _scene_tools: Node = null
+var _resource_tools: Node = null
+var _animation_tools: Node = null
+
+var _tool_map: Dictionary = {}
+var _initialized := false
+
+
+func set_editor_plugin(plugin: EditorPlugin) -> void:
+	_editor_plugin = plugin
+	_init_tools()
+
+	if _scene_tools and _scene_tools.has_method("set_editor_plugin"):
+		_scene_tools.set_editor_plugin(plugin)
+	if _resource_tools and _resource_tools.has_method("set_editor_plugin"):
+		_resource_tools.set_editor_plugin(plugin)
+	if _animation_tools and _animation_tools.has_method("set_editor_plugin"):
+		_animation_tools.set_editor_plugin(plugin)
+
+
+func _init_tools() -> void:
+	if _initialized:
+		return
+	_initialized = true
+
+	var base_path: String = get_script().resource_path.get_base_dir()
+	var scene_tools_path := "%s/tools/scene_tools.gd" % base_path
+	var resource_tools_path := "%s/tools/resource_tools.gd" % base_path
+	var animation_tools_path := "%s/tools/animation_tools.gd" % base_path
+
+	if ResourceLoader.exists(scene_tools_path):
+		var scene_script: Script = load(scene_tools_path)
+		if scene_script:
+			_scene_tools = scene_script.new()
+			_scene_tools.name = "SceneTools"
+			add_child(_scene_tools)
+
+	if ResourceLoader.exists(resource_tools_path):
+		var resource_script: Script = load(resource_tools_path)
+		if resource_script:
+			_resource_tools = resource_script.new()
+			_resource_tools.name = "ResourceTools"
+			add_child(_resource_tools)
+
+	if ResourceLoader.exists(animation_tools_path):
+		var animation_script: Script = load(animation_tools_path)
+		if animation_script:
+			_animation_tools = animation_script.new()
+			_animation_tools.name = "AnimationTools"
+			add_child(_animation_tools)
+
+	_tool_map = {
+		# Scene tools
+		"create_scene": [_scene_tools, "create_scene"],
+		"list_scene_nodes": [_scene_tools, "list_scene_nodes"],
+		"add_node": [_scene_tools, "add_node"],
+		"delete_node": [_scene_tools, "delete_node"],
+		"duplicate_node": [_scene_tools, "duplicate_node"],
+		"reparent_node": [_scene_tools, "reparent_node"],
+		"set_node_properties": [_scene_tools, "set_node_properties"],
+		"get_node_properties": [_scene_tools, "get_node_properties"],
+		"load_sprite": [_scene_tools, "load_sprite"],
+		"save_scene": [_scene_tools, "save_scene"],
+		"connect_signal": [_scene_tools, "connect_signal"],
+		"disconnect_signal": [_scene_tools, "disconnect_signal"],
+		"list_connections": [_scene_tools, "list_connections"],
+
+		# Resource tools
+		"create_resource": [_resource_tools, "create_resource"],
+		"modify_resource": [_resource_tools, "modify_resource"],
+		"create_material": [_resource_tools, "create_material"],
+		"create_shader": [_resource_tools, "create_shader"],
+		"create_tileset": [_resource_tools, "create_tileset"],
+		"set_tilemap_cells": [_resource_tools, "set_tilemap_cells"],
+		"set_theme_color": [_resource_tools, "set_theme_color"],
+		"set_theme_font_size": [_resource_tools, "set_theme_font_size"],
+		"apply_theme_shader": [_resource_tools, "apply_theme_shader"],
+
+		# Animation tools
+		"create_animation": [_animation_tools, "create_animation"],
+		"add_animation_track": [_animation_tools, "add_animation_track"],
+		"create_animation_tree": [_animation_tools, "create_animation_tree"],
+		"add_animation_state": [_animation_tools, "add_animation_state"],
+		"connect_animation_states": [_animation_tools, "connect_animation_states"],
+		"create_navigation_region": [_animation_tools, "create_navigation_region"],
+		"create_navigation_agent": [_animation_tools, "create_navigation_agent"]
+	}
+
+
+func execute_tool(tool_name: String, args: Dictionary) -> Dictionary:
+	if not _tool_map.has(tool_name):
+		return {"ok": false, "error": "Unknown tool: " + tool_name}
+
+	var handler: Array = _tool_map[tool_name]
+	var node: Node = handler[0]
+	var method: String = handler[1]
+
+	if node == null:
+		return {"ok": false, "error": "Tool handler unavailable: " + tool_name}
+
+	if not node.has_method(method):
+		return {"ok": false, "error": "Tool method not found: %s.%s" % [node.name, method]}
+
+	var result = node.call(method, args)
+	if result is Dictionary:
+		return result
+
+	return {"ok": false, "error": "Invalid tool result from: " + tool_name}