gopeak 2.1.0 → 2.2.1

package/README.md

@@ -14,108 +14,221 @@
 
 **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 exposes 33 core tools with 22 dynamic tool groups (78 additional tools) that activate on demand — keeping token usage low while preserving full capability.
+
+### 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.
+- **110+ tools available** across scene/script/resource/runtime/LSP/DAP/input/assets.
+- **Token-efficient by default**: compact tool surface (33 tools) + dynamic tool groups. Only activate what you need — no more 110-tool context bombs.
+- **Dynamic tool groups**: search with `tool.catalog` and matching groups auto-activate. Or manually activate with `tool.groups`.
+- **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): 33 core tools + **22 dynamic tool groups** (78 additional tools activated on demand)
+- `full`: exposes full legacy tool list (110+)
+- `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)
+
+### Dynamic Tool Groups (compact mode)
+
+In `compact` mode, 78 additional tools are organized into **22 groups** that activate automatically when needed:
+
+| Group | Tools | Description |
+|---|---|---|
+| `scene_advanced` | 3 | Duplicate, reparent nodes, load sprites |
+| `uid` | 2 | UID management for resources |
+| `import_export` | 5 | Import pipeline, reimport, validate project |
+| `autoload` | 4 | Autoload singletons, main scene |
+| `signal` | 2 | Disconnect signals, list connections |
+| `runtime` | 4 | Live scene inspection, runtime properties, metrics |
+| `resource` | 4 | Create/modify materials, shaders, resources |
+| `animation` | 5 | Animations, tracks, animation tree, state machine |
+| `plugin` | 3 | Enable/disable/list editor plugins |
+| `input` | 1 | Input action mapping |
+| `tilemap` | 2 | TileSet and TileMap cell painting |
+| `audio` | 4 | Audio buses, effects, volume |
+| `navigation` | 2 | Navigation regions and agents |
+| `theme_ui` | 3 | Theme colors, font sizes, shaders |
+| `asset_store` | 3 | Search/download CC0 assets |
+| `testing` | 6 | Screenshots, viewport capture, input injection |
+| `dx_tools` | 4 | Error log, project health, find usages, scaffold |
+| `intent_tracking` | 9 | Intent capture, decision logs, handoff briefs |
+| `class_advanced` | 1 | Class inheritance inspection |
+| `lsp` | 3 | GDScript completions, hover, symbols |
+| `dap` | 6 | Breakpoints, stepping, stack traces |
+| `version_gate` | 2 | Version validation, patch verification |
+
+**How it works:**
+
+1. **Auto-activation via catalog**: Search with `tool.catalog` and matching groups activate automatically.
+   > "Use `tool.catalog` with query `animation` and show relevant tools."
+
+2. **Manual activation**: Directly activate a group with `tool.groups`.
+   > "Use `tool.groups` to activate the `dap` group for debugging."
+
+3. **Deactivation**: Remove groups when done to reduce context.
+   > "Use `tool.groups` to reset all active groups."
+
+The server sends `notifications/tools/list_changed` so MCP clients (Claude Code, Claude Desktop) automatically refresh the tool list.
+
+### Don't worry about tokens
+
+GoPeak uses **cursor-based pagination** for `tools/list` — even in `full` profile, tools are delivered in pages (default 33) instead of dumping all 110+ definitions at once. Your AI client fetches the next page only when it needs more.
+
+Set page size with `GOPEAK_TOOLS_PAGE_SIZE`:
+
+```json
+{
+  "env": {
+    "GOPEAK_TOOLS_PAGE_SIZE": "25"
+  }
+}
+```
 
 ---
 
-## 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`)**
+## CI
 
-```json
-{
-  "mcpServers": {
-    "godot": {
-      "command": "gopeak",
-      "env": {
-        "GODOT_PATH": "/path/to/godot"
-      }
-    }
-  }
-}
+GitHub Actions runs on push/PR and executes:
+
+1. `npm run build`
+2. `npx tsc --noEmit`
+3. `npm run test:ci`
+
+Run the same checks locally:
+
+```bash
+npm run ci
 ```
 
-**B) No global install (npx mode)**
+---
 
-```json
-{
-  "mcpServers": {
-    "godot": {
-      "command": "npx",
-      "args": ["-y", "gopeak"],
-      "env": {
-        "GODOT_PATH": "/path/to/godot"
-      }
-    }
-  }
-}
+## Versioning & Release
+
+Use the built-in bump script to keep `package.json` and `server.json` in sync:
+
+```bash
+node scripts/bump-version.mjs patch
+node scripts/bump-version.mjs minor --dry-run
 ```
 
-> Tip: If your client uses `args` array style only, use `"command": "npx"` + `"args": ["-y", "gopeak"]`.
+Full release checklist: [`docs/release-process.md`](docs/release-process.md).
+
+---
+
+## Addons (Recommended)
+
+### Auto Reload + Editor Bridge + Runtime Addon installer
+
+Install in your Godot project folder:
+
+```bash
+curl -sL https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install-addon.sh | bash
+```
+
+PowerShell:
+
+```powershell
+iwr https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install-addon.ps1 -UseBasicParsing | iex
+```
+
+Then enable plugins in **Project Settings → Plugins** (especially `godot_mcp_editor` for bridge-backed scene/resource tools).
 
 ---
 
@@ -131,18 +244,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 +273,50 @@ 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 & dynamic groups
+- "Use `tool.catalog` with query `tilemap` and list the most relevant tools."
+- "Activate the `dap` tool group for breakpoint debugging with `tool.groups`."
+- "Find import pipeline tools with `tool.catalog` query `import` and run the best one for texture settings."
+- "Reset all active tool groups with `tool.groups` to reduce context."
 
 ---
 
-## 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 |
+| `GODOT_BRIDGE_PORT` | Bridge/Visualizer HTTP+WS port override (aliases: `MCP_BRIDGE_PORT`, `GOPEAK_BRIDGE_PORT`) | `6505` |
+| `DEBUG` | Enable server debug logs (`true`/`false`) | `false` |
+| `LOG_MODE` | Recording mode: `lite` or `full` | `lite` |
+| `GOPEAK_TOOLS_PAGE_SIZE` | Number of tools per `tools/list` page (pagination) | `33` |
+| `GOPEAK_BRIDGE_PORT` | Port for unified bridge/visualizer server | `6505` |
+| `GOPEAK_BRIDGE_HOST` | Bind host for bridge/visualizer server | `127.0.0.1` |
+
+### Ports
+
+| Port | Service |
+|---|---|
+| `6505` (default) | Unified Godot Bridge + Visualizer server (+ `/health`, `/mcp`) on loopback by default |
+| `6005` | Godot LSP |
+| `6006` | Godot DAP |
+| `7777` | Runtime addon command socket (only needed for runtime tools) |
+
+### Minimal port profiles
 
-Then enable plugin in **Project Settings → Plugins**.
+- **Core editing only**: bridge port (`GODOT_BRIDGE_PORT`, default `6505`)
+- **Core + runtime actions (screenshots/input/runtime inspect)**: bridge port + `7777`
+- **Full debugging + diagnostics**: bridge port + `6005` + `6006` + `7777`
 
 ---
 
@@ -180,12 +325,15 @@ 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` to search and auto-activate matching groups, or use `tool.groups` to activate a specific group
 
 ---
 
 ## Docs & Project Links
 
+- [Architecture (MCP Platform Direction)](docs/architecture.md)
+- [Platform Roadmap (P1/P2/P3)](docs/platform-roadmap.md)
 - [CHANGELOG](CHANGELOG.md)
 - [ROADMAP](ROADMAP.md)
 - [CONTRIBUTING](CONTRIBUTING.md)
@@ -200,3 +348,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,178 @@
+@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 = "") -> void:
+	server_url = _resolve_server_url(url)
+	_should_reconnect = true
+	_current_reconnect_delay = RECONNECT_DELAY
+	_attempt_connection()
+
+
+func _resolve_server_url(explicit_url: String) -> String:
+	if explicit_url != "":
+		return explicit_url
+
+	var env_keys := ["GODOT_BRIDGE_PORT", "MCP_BRIDGE_PORT", "GOPEAK_BRIDGE_PORT"]
+	for key in env_keys:
+		var raw := OS.get_environment(key)
+		if raw == "":
+			continue
+		if raw.is_valid_int():
+			var port := int(raw)
+			if port >= 1 and port <= 65535:
+				return "ws://127.0.0.1:%d/godot" % port
+
+	return DEFAULT_URL
+
+
+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")))