gopeak 2.3.5 → 2.3.7

package/README.md

@@ -10,10 +10,14 @@
 [![](https://img.shields.io/github/forks/HaD0Yun/Gopeak-godot-mcp 'Forks')](https://github.com/HaD0Yun/Gopeak-godot-mcp/network/members)
 [![](https://img.shields.io/badge/License-MIT-red.svg 'MIT License')](https://opensource.org/licenses/MIT)
 
+🌐 **Languages**: **English** | [한국어](README-ko.md) | [日本語](README-ja.md) | [Deutsch](README-de.md) | [Português](README-pt_BR.md) | [简体中文](README-zh.md)
+
 ![GoPeak Hero](assets/gopeak-hero-v2.png)
 
 **GoPeak is an MCP server for Godot that lets AI assistants run, inspect, modify, and debug real projects end-to-end.**
 
+> English is the canonical source of truth. Localized READMEs are concise overviews and may lag behind `README.md`.
+
 > Discord community chat is temporarily unavailable while the invite link is refreshed. Please use GitHub Discussions in the meantime: https://github.com/HaD0Yun/Gopeak-godot-mcp/discussions
 
 ---
@@ -64,7 +68,7 @@ gopeak setup
 }
 ```
 
-> `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.
+> `GOPEAK_TOOL_PROFILE=compact` is the default. It exposes a trusted core surface with dynamic tool groups that activate on demand — keeping token usage low while making experimental or environment-dependent capabilities explicit.
 
 ### 3) First prompts to try
 
@@ -77,10 +81,10 @@ gopeak setup
 ## Why GoPeak
 
 - **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.
+- **Trusted Godot 4 workflow tools** across project discovery, scene/script/resource editing, runtime/LSP/DAP integrations, testing, and asset workflows.
+- **Token-efficient by default**: compact core surface + dynamic tool groups. Activate only the capability family you need instead of loading the full legacy surface.
+- **Dynamic tool groups with explicit maturity labels**: search with `tool.catalog` and matching groups auto-activate, or manually activate with `tool.groups`.
+- **Deep Godot integration with setup gates**: ClassDB queries, runtime inspection, debugger hooks, and bridge-based scene/resource edits clearly state addon, editor, LSP, DAP, or runtime requirements.
 
 ### Best For
 
@@ -94,9 +98,9 @@ gopeak setup
 
 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`
+- `compact` (default): trusted core tools plus dynamic tool groups activated on demand.
+- `full`: exposes the full legacy tool list for compatibility and audit work.
+- `legacy`: same exposed behavior as `full` for older configurations.
 
 Configure with either:
 
@@ -105,32 +109,32 @@ Configure with either:
 
 ### Dynamic Tool Groups (compact mode)
 
-In `compact` mode, 78 additional tools are organized into **22 groups** that activate automatically when needed:
+In `compact` mode, additional tools are organized into dynamic groups that activate automatically when needed. Maturity labels are intentionally conservative until each group has Godot 4 fixture evidence:
 
-| Group | Tools | Description |
+| Group | Maturity | Description / setup gate |
 |---|---|---|
-| `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 |
+| `scene_advanced` | audit-required | Duplicate, reparent nodes, load sprites; verify scene ownership/persistence in a Godot 4 fixture before treating as trusted. |
+| `uid` | audit-required | UID management for resources; gate behavior by Godot version and resource save/load evidence. |
+| `import_export` | audit-required | Import pipeline, reimport, validate project; requires fixture checks for import settings and export command construction. |
+| `autoload` | audit-required | Autoload singletons, main scene; requires project settings round-trip verification. |
+| `signal` | audit-required | Disconnect signals, list connections; requires signal round-trip verification. |
+| `runtime` | optional-runtime | Live scene inspection, runtime properties, metrics; requires the runtime addon/socket. |
+| `resource` | audit-required | Create/modify materials, shaders, resources; requires resource save/load fixture checks. |
+| `animation` | audit-required | Animations, tracks, animation tree, state machine; requires saved scene/resource fixture checks. |
+| `plugin` | optional-editor | Enable/disable/list editor plugins; requires editor plugin availability. |
+| `input` | audit-required | Input action mapping; requires project settings round-trip verification. |
+| `tilemap` | audit-required | TileSet and TileMap cell painting; must account for Godot 4.3+ `TileMapLayer` behavior before being promoted. |
+| `audio` | audit-required | Audio buses, effects, volume; requires bus layout fixture checks. |
+| `navigation` | audit-required | Navigation regions and agents; requires saved scene/resource fixture checks. |
+| `theme_ui` | audit-required | Theme colors, font sizes, shaders; requires resource save/load fixture checks. |
+| `asset_store` | optional-network | Search/download external CC0 assets; requires network/provider availability and should remain optional. |
+| `testing` | optional-runtime | Screenshots, viewport capture, input injection; requires runtime addon/editor availability. |
+| `dx_tools` | audit-required | Error log, project health, find usages, scaffold; requires deterministic static fixture checks. |
+| `intent_tracking` | workflow-layer | Intent capture, decision logs, handoff briefs; not a Godot engine primitive and should stay opt-in/workflow-scoped. |
+| `class_advanced` | trusted-static | Class inheritance inspection; validate against ClassDB/static evidence. |
+| `lsp` | optional-lsp | GDScript completions, hover, symbols; requires Godot LSP on port 6005. |
+| `dap` | optional-dap | Breakpoints, stepping, stack traces; requires Godot DAP on port 6006. |
+| `version_gate` | audit-required | Version validation and patch verification; requires explicit version fixture evidence. |
 
 **How it works:**
 
@@ -144,10 +148,24 @@ In `compact` mode, 78 additional tools are organized into **22 groups** that act
    > "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.
+If your MCP client caches tools aggressively and does not refresh after activation, reconnect the client or call the newly activated tool directly once to force a fresh `tools/list` round-trip.
+
+### Typed property values for scene tools
+
+Bridge-backed scene tools (`add_node`, `set_node_properties`) now coerce common vector payloads such as `{ "x": 100, "y": 200 }` and `[100, 200]` for typed properties like `position` and `scale`. Tagged values are still the safest cross-tool form:
+
+```json
+{
+  "position": { "type": "Vector2", "x": 100, "y": 200 },
+  "scale": { "type": "Vector2", "x": 2, "y": 2 }
+}
+```
+
+The internal headless serializer uses `_type`, but MCP callers should prefer `type` when they need an explicit cross-tool Godot value tag.
 
 ### 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.
+GoPeak uses **cursor-based pagination** for `tools/list` — even in `full` profile, tools are delivered in pages (default 33) instead of dumping the entire legacy definition set at once. Your AI client fetches the next page only when it needs more.
 
 Set page size with `GOPEAK_TOOLS_PAGE_SIZE`:
 
@@ -260,15 +278,17 @@ Then enable plugins in **Project Settings → Plugins** (especially `godot_mcp_e
 
 ## Core Capabilities
 
+These capabilities are grouped by workflow value. Optional-runtime/LSP/DAP/network groups require their setup gates before use; audit-required groups should be promoted only after fixture evidence.
+
 - **Project control**: launch editor, run/stop project, capture debug output
 - **Scene editing**: create scenes, add/delete/reparent nodes, edit properties
 - **Script workflows**: create/modify scripts, inspect script structure
 - **Resources**: create/modify resources, materials, shaders, tilesets
 - **Signals/animation**: connect signals, build animations/tracks/state machines
-- **Runtime tools**: inspect live tree, set properties, call methods, metrics
-- **LSP + DAP**: diagnostics/completion/hover + breakpoints/step/stack trace
-- **Input + screenshots**: keyboard/mouse/action injection and viewport capture
-- **Asset library**: search/fetch CC0 assets (Poly Haven, AmbientCG, Kenney)
+- **Runtime tools**: inspect live tree, set properties, call methods, metrics (requires runtime addon/socket)
+- **LSP + DAP**: diagnostics/completion/hover + breakpoints/step/stack trace (requires Godot LSP/DAP ports)
+- **Input + screenshots**: keyboard/mouse/action injection and viewport capture (requires runtime/editor bridge setup)
+- **Asset library**: search/fetch CC0 assets (optional network/provider workflow)
 
 ### Tool families (examples)
 
@@ -313,6 +333,19 @@ Visualize your entire project architecture with `visualizer.map` (`map_project`
 
 ---
 
+## Migration & Deprecation Policy
+
+GoPeak treats `compact` as the safe default and `full`/`legacy` as compatibility profiles. Any future hide, remove, rename, or API-contract change must include:
+
+1. an old → new mapping or an explicit no-replacement note;
+2. the profile impact (`compact`, `full`, `legacy`, or opt-in group);
+3. whether an alias remains and the planned removal window;
+4. README/docs and release-note updates;
+5. a verification command proving `tools/list` exposure and alias behavior;
+6. a migration prompt example for common Godot workflows.
+
+Current compatibility stance: legacy tool names and compact aliases remain supported. Dynamic groups with optional external requirements (`runtime`, `testing`, `lsp`, `dap`, `asset_store`) should be documented as opt-in/setup-gated rather than marketed as always-available core behavior.
+
 ## Technical Reference
 
 ### Environment variables
@@ -353,6 +386,7 @@ Visualize your entire project architecture with `visualizer.map` (`map_project`
 - **Project path invalid** → confirm `project.godot` exists
 - **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
+- **`get_editor_status` says disconnected while the Godot editor shows connected** → check whether another `gopeak`/MCP server instance already owns bridge port `6505`; the status payload now reports the startup error and suggests stopping duplicate servers
 
 ---
 

package/build/addon/godot_mcp_editor/tools/scene_tools.gd

@@ -81,49 +81,92 @@ func _find_node(root: Node, path: String) -> Node:
 	return root.get_node_or_null(path)
 
 
-func _parse_value(value):
-	if typeof(value) == TYPE_DICTIONARY and value.has("type"):
-		match value["type"]:
-			"Vector2":
-				return Vector2(value.get("x", 0), value.get("y", 0))
-			"Vector3":
-				return Vector3(value.get("x", 0), value.get("y", 0), value.get("z", 0))
-			"Color":
-				return Color(value.get("r", 1), value.get("g", 1), value.get("b", 1), value.get("a", 1))
-			"Vector2i":
-				return Vector2i(value.get("x", 0), value.get("y", 0))
-			"Vector3i":
-				return Vector3i(value.get("x", 0), value.get("y", 0), value.get("z", 0))
-			"Rect2":
-				return Rect2(value.get("x", 0), value.get("y", 0), value.get("width", 0), value.get("height", 0))
-			"Transform2D":
-				if value.has("x") and value.has("y") and value.has("origin"):
-					var xx: Dictionary = value["x"]
-					var yy: Dictionary = value["y"]
-					var oo: Dictionary = value["origin"]
-					return Transform2D(
-						Vector2(xx.get("x", 1), xx.get("y", 0)),
-						Vector2(yy.get("x", 0), yy.get("y", 1)),
-						Vector2(oo.get("x", 0), oo.get("y", 0))
-					)
-			"Transform3D":
-				if value.has("basis") and value.has("origin"):
-					var b: Dictionary = value["basis"]
-					var o: Dictionary = value["origin"]
-					var basis := Basis(
-						Vector3(b.get("x", {}).get("x", 1), b.get("x", {}).get("y", 0), b.get("x", {}).get("z", 0)),
-						Vector3(b.get("y", {}).get("x", 0), b.get("y", {}).get("y", 1), b.get("y", {}).get("z", 0)),
-						Vector3(b.get("z", {}).get("x", 0), b.get("z", {}).get("y", 0), b.get("z", {}).get("z", 1))
-					)
-					return Transform3D(basis, Vector3(o.get("x", 0), o.get("y", 0), o.get("z", 0)))
-			"NodePath":
-				return NodePath(value.get("path", ""))
-			"Resource":
-				var resource_path: String = str(value.get("path", ""))
-				if resource_path.is_empty():
-					return null
-				return load(resource_path)
+func _parse_value(value, expected_type: int = TYPE_NIL):
+	if typeof(value) == TYPE_DICTIONARY:
+		var type_tag := ""
+		if value.has("type"):
+			type_tag = str(value["type"])
+		elif value.has("_type"):
+			type_tag = str(value["_type"])
+
+		if not type_tag.is_empty():
+			match type_tag:
+				"Vector2":
+					return Vector2(value.get("x", 0), value.get("y", 0))
+				"Vector3":
+					return Vector3(value.get("x", 0), value.get("y", 0), value.get("z", 0))
+				"Color":
+					return Color(value.get("r", 1), value.get("g", 1), value.get("b", 1), value.get("a", 1))
+				"Vector2i":
+					return Vector2i(value.get("x", 0), value.get("y", 0))
+				"Vector3i":
+					return Vector3i(value.get("x", 0), value.get("y", 0), value.get("z", 0))
+				"Rect2":
+					return Rect2(value.get("x", 0), value.get("y", 0), value.get("width", 0), value.get("height", 0))
+				"Transform2D":
+					if value.has("x") and value.has("y") and value.has("origin"):
+						var xx: Dictionary = value["x"]
+						var yy: Dictionary = value["y"]
+						var oo: Dictionary = value["origin"]
+						return Transform2D(
+							Vector2(xx.get("x", 1), xx.get("y", 0)),
+							Vector2(yy.get("x", 0), yy.get("y", 1)),
+							Vector2(oo.get("x", 0), oo.get("y", 0))
+						)
+				"Transform3D":
+					if value.has("basis") and value.has("origin"):
+						var b: Dictionary = value["basis"]
+						var o: Dictionary = value["origin"]
+						var basis := Basis(
+							Vector3(b.get("x", {}).get("x", 1), b.get("x", {}).get("y", 0), b.get("x", {}).get("z", 0)),
+							Vector3(b.get("y", {}).get("x", 0), b.get("y", {}).get("y", 1), b.get("y", {}).get("z", 0)),
+							Vector3(b.get("z", {}).get("x", 0), b.get("z", {}).get("y", 0), b.get("z", {}).get("z", 1))
+						)
+						return Transform3D(basis, Vector3(o.get("x", 0), o.get("y", 0), o.get("z", 0)))
+				"NodePath":
+					return NodePath(value.get("path", ""))
+				"Resource":
+					var resource_path: String = str(value.get("path", ""))
+					if resource_path.is_empty():
+						return null
+					return load(resource_path)
+
+		match expected_type:
+			TYPE_VECTOR2:
+				if value.has("x") and value.has("y"):
+					return Vector2(value.get("x", 0), value.get("y", 0))
+			TYPE_VECTOR2I:
+				if value.has("x") and value.has("y"):
+					return Vector2i(value.get("x", 0), value.get("y", 0))
+			TYPE_VECTOR3:
+				if value.has("x") and value.has("y") and value.has("z"):
+					return Vector3(value.get("x", 0), value.get("y", 0), value.get("z", 0))
+			TYPE_VECTOR3I:
+				if value.has("x") and value.has("y") and value.has("z"):
+					return Vector3i(value.get("x", 0), value.get("y", 0), value.get("z", 0))
+			TYPE_COLOR:
+				if value.has("r") and value.has("g") and value.has("b"):
+					return Color(value.get("r", 1), value.get("g", 1), value.get("b", 1), value.get("a", 1))
+			TYPE_RECT2:
+				if value.has("x") and value.has("y") and value.has("width") and value.has("height"):
+					return Rect2(value.get("x", 0), value.get("y", 0), value.get("width", 0), value.get("height", 0))
+			TYPE_NODE_PATH:
+				if value.has("path"):
+					return NodePath(value.get("path", ""))
 	if typeof(value) == TYPE_ARRAY:
+		match expected_type:
+			TYPE_VECTOR2:
+				if value.size() >= 2:
+					return Vector2(value[0], value[1])
+			TYPE_VECTOR2I:
+				if value.size() >= 2:
+					return Vector2i(value[0], value[1])
+			TYPE_VECTOR3:
+				if value.size() >= 3:
+					return Vector3(value[0], value[1], value[2])
+			TYPE_VECTOR3I:
+				if value.size() >= 3:
+					return Vector3i(value[0], value[1], value[2])
 		var result: Array = []
 		for item in value:
 			result.append(_parse_value(item))
@@ -131,6 +174,13 @@ func _parse_value(value):
 	return value
 
 
+func _get_property_type(node: Node, prop_name: String) -> int:
+	for prop in node.get_property_list():
+		if str(prop.get("name", "")) == prop_name:
+			return int(prop.get("type", TYPE_NIL))
+	return TYPE_NIL
+
+
 func _serialize_value(value) -> Variant:
 	match typeof(value):
 		TYPE_VECTOR2:
@@ -174,7 +224,8 @@ func _serialize_value(value) -> Variant:
 
 func _set_node_properties(node: Node, properties: Dictionary) -> void:
 	for prop_name in properties:
-		var val = _parse_value(properties[prop_name])
+		var expected_type := _get_property_type(node, str(prop_name))
+		var val = _parse_value(properties[prop_name], expected_type)
 		node.set(prop_name, val)
 
 

package/build/addon/godot_mcp_runtime/mcp_runtime_autoload.gd

@@ -45,6 +45,9 @@ func _process(_delta: float) -> void:
 			continue
 		
 		client.poll()
+		if client.get_status() != StreamPeerTCP.STATUS_CONNECTED:
+			clients_to_remove.append(client)
+			continue
 		var available = client.get_available_bytes()
 		if available > 0:
 			var data = client.get_utf8_string(available)

package/build/godot-bridge.js

@@ -335,10 +335,13 @@ export class GodotBridge extends EventEmitter {
         nextSocket.on('close', (code, reasonBuffer) => {
             const reason = reasonBuffer.toString();
             this.log('warn', `Godot disconnected (code=${code}, reason=${reason || 'none'})`);
-            this.handleDisconnect(new Error('Godot disconnected during request'));
+            this.handleDisconnect(nextSocket, new Error('Godot disconnected during request'));
         });
         nextSocket.on('error', (error) => {
             this.log('error', `WebSocket error: ${error.message}`);
+            if (nextSocket.readyState === WebSocket.CLOSED || nextSocket.readyState === WebSocket.CLOSING) {
+                this.handleDisconnect(nextSocket, error);
+            }
         });
     }
     handleRawMessage(data) {
@@ -463,7 +466,11 @@ export class GodotBridge extends EventEmitter {
         clearInterval(this.pingInterval);
         this.pingInterval = null;
     }
-    handleDisconnect(reason) {
+    handleDisconnect(disconnectedSocket, reason) {
+        if (disconnectedSocket && this.socket && disconnectedSocket !== this.socket) {
+            this.log('debug', 'Ignoring stale Godot socket disconnect event');
+            return;
+        }
         this.stopKeepalive();
         this.socket = null;
         this.connectionInfo = null;

package/build/index.js

@@ -8,7 +8,8 @@
  */
 import { fileURLToPath } from 'url';
 import { join, dirname, basename, normalize } from 'path';
-import { existsSync, readdirSync, mkdirSync, readFileSync, appendFileSync, writeFileSync } from 'fs';
+import { existsSync, readdirSync, mkdirSync, readFileSync, appendFileSync, writeFileSync, mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
 import { spawn } from 'child_process';
 import { createConnection as createTcpConnection } from 'node:net';
 import { promisify } from 'util';
@@ -43,6 +44,7 @@ class GodotServer {
     godotDebugMode = GODOT_DEBUG_MODE_DEFAULT;
     lspClient = null;
     dapClient = null;
+    bridgeStartupError = null;
     lastProjectPath = null;
     recordingMode = (process.env.LOG_MODE === 'full' ? 'full' : 'lite');
     logQueue = [];
@@ -652,6 +654,87 @@ class GodotServer {
         }
         return compactTools;
     }
+    jsonTextResponse(payload) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(payload, null, 2),
+                }],
+        };
+    }
+    buildLegacyToCompactAliasMap() {
+        return new Map(Object.entries(this.compactAliasToLegacy).map(([compactName, legacyName]) => [legacyName, compactName]));
+    }
+    buildToolGroupLookup() {
+        const toolToGroup = new Map();
+        const registerGroups = (groups, type) => {
+            for (const [groupName, group] of Object.entries(groups)) {
+                for (const toolName of group.tools) {
+                    toolToGroup.set(toolName, { group: groupName, type });
+                }
+            }
+        };
+        registerGroups(CORE_TOOL_GROUPS, 'core');
+        registerGroups(TOOL_GROUPS, 'dynamic');
+        return toolToGroup;
+    }
+    getActivatedToolNames() {
+        const activatedToolNames = new Set();
+        for (const groupName of this.activeGroups) {
+            const group = TOOL_GROUPS[groupName];
+            if (!group) {
+                continue;
+            }
+            for (const toolName of group.tools) {
+                activatedToolNames.add(toolName);
+            }
+        }
+        return activatedToolNames;
+    }
+    getAvailableDynamicGroups() {
+        return Object.keys(TOOL_GROUPS);
+    }
+    getUnknownDynamicGroupError(groupName) {
+        return `Unknown group '${groupName}'. Available dynamic groups: ${this.getAvailableDynamicGroups().join(', ')}`;
+    }
+    notifyToolListChanged() {
+        this.cachedToolDefinitions = [];
+        this.server.sendToolListChanged().catch(() => { });
+    }
+    autoActivateMatchingGroups(query) {
+        if (!query || this.toolExposureProfile !== 'compact') {
+            return [];
+        }
+        const newlyActivated = [];
+        for (const [groupName, group] of Object.entries(TOOL_GROUPS)) {
+            if (this.activeGroups.has(groupName)) {
+                continue;
+            }
+            const hasMatchingKeyword = group.keywords.some((kw) => query.includes(kw) || kw.includes(query));
+            const hasMatchingToolName = group.tools.some((toolName) => toolName.toLowerCase().includes(query));
+            if (hasMatchingKeyword || hasMatchingToolName) {
+                this.activeGroups.add(groupName);
+                newlyActivated.push(groupName);
+            }
+        }
+        if (newlyActivated.length > 0) {
+            this.notifyToolListChanged();
+        }
+        return newlyActivated;
+    }
+    setDynamicGroupActivation(groupName, active) {
+        const wasActive = this.activeGroups.has(groupName);
+        if (active) {
+            this.activeGroups.add(groupName);
+        }
+        else {
+            this.activeGroups.delete(groupName);
+        }
+        if (wasActive !== active) {
+            this.notifyToolListChanged();
+        }
+        return wasActive;
+    }
     sanitizeToolsForList(tools) {
         const seenNames = new Map();
         return tools.map((tool) => {
@@ -680,15 +763,7 @@ class GodotServer {
         const exposed = this.buildCompactTools(allTools);
         // Add dynamically activated group tools (using their legacy names)
         if (this.activeGroups.size > 0) {
-            const activatedToolNames = new Set();
-            for (const groupName of this.activeGroups) {
-                const group = TOOL_GROUPS[groupName];
-                if (!group)
-                    continue;
-                for (const toolName of group.tools) {
-                    activatedToolNames.add(toolName);
-                }
-            }
+            const activatedToolNames = this.getActivatedToolNames();
             for (const tool of allTools) {
                 if (activatedToolNames.has(tool.name)) {
                     exposed.push({
@@ -750,22 +825,8 @@ class GodotServer {
         const rawLimit = typeof normalizedArgs.limit === 'number' ? normalizedArgs.limit : 30;
         const limit = Math.max(1, Math.min(100, rawLimit));
         const tools = this.getAllToolDefinitions();
-        const reverseAlias = new Map();
-        for (const [compactName, legacyName] of Object.entries(this.compactAliasToLegacy)) {
-            reverseAlias.set(legacyName, compactName);
-        }
-        // Build tool → group reverse map (core + dynamic)
-        const toolToGroup = new Map();
-        for (const [groupName, group] of Object.entries(CORE_TOOL_GROUPS)) {
-            for (const toolName of group.tools) {
-                toolToGroup.set(toolName, { group: groupName, type: 'core' });
-            }
-        }
-        for (const [groupName, group] of Object.entries(TOOL_GROUPS)) {
-            for (const toolName of group.tools) {
-                toolToGroup.set(toolName, { group: groupName, type: 'dynamic' });
-            }
-        }
+        const reverseAlias = this.buildLegacyToCompactAliasMap();
+        const toolToGroup = this.buildToolGroupLookup();
         const filtered = tools.filter((tool) => {
             if (!query)
                 return true;
@@ -785,40 +846,16 @@ class GodotServer {
         // Auto-activate matching tool groups when query matches their keywords
         // or when the query directly matches a group's tool NAME (not description).
         // This prevents over-activation from incidental description matches.
-        const newlyActivated = [];
-        if (query && this.toolExposureProfile === 'compact') {
-            for (const [groupName, group] of Object.entries(TOOL_GROUPS)) {
-                if (this.activeGroups.has(groupName))
-                    continue;
-                // Activate if query matches a group keyword
-                const hasMatchingKeyword = group.keywords.some((kw) => query.includes(kw) || kw.includes(query));
-                // Or if query matches a tool NAME in the group (strict name-only match)
-                const hasMatchingToolName = group.tools.some((t) => t.toLowerCase().includes(query));
-                if (hasMatchingKeyword || hasMatchingToolName) {
-                    this.activeGroups.add(groupName);
-                    newlyActivated.push(groupName);
-                }
-            }
-            // Notify clients that tool list changed so they re-fetch
-            if (newlyActivated.length > 0) {
-                this.cachedToolDefinitions = []; // Clear cache to force rebuild
-                this.server.sendToolListChanged().catch(() => { });
-            }
-        }
-        return {
-            content: [{
-                    type: 'text',
-                    text: JSON.stringify({
-                        profile: this.toolExposureProfile,
-                        totalTools: tools.length,
-                        query: query || null,
-                        returned: items.length,
-                        activeGroups: Array.from(this.activeGroups),
-                        newlyActivated: newlyActivated.length > 0 ? newlyActivated : undefined,
-                        tools: items,
-                    }, null, 2),
-                }],
-        };
+        const newlyActivated = this.autoActivateMatchingGroups(query);
+        return this.jsonTextResponse({
+            profile: this.toolExposureProfile,
+            totalTools: tools.length,
+            query: query || null,
+            returned: items.length,
+            activeGroups: Array.from(this.activeGroups),
+            newlyActivated: newlyActivated.length > 0 ? newlyActivated : undefined,
+            tools: items,
+        });
     }
     async handleManageToolGroups(args) {
         const normalizedArgs = this.normalizeParameters(args || {});
@@ -845,102 +882,55 @@ class GodotServer {
                 const allGroups = [...coreGroups, ...dynamicGroups];
                 const totalCoreTools = coreGroups.reduce((sum, g) => sum + g.toolCount, 0);
                 const totalDynTools = dynamicGroups.reduce((sum, g) => sum + g.toolCount, 0);
-                return {
-                    content: [{
-                            type: 'text',
-                            text: JSON.stringify({
-                                totalGroups: allGroups.length,
-                                coreGroups: coreGroups.length,
-                                dynamicGroups: dynamicGroups.length,
-                                coreTools: totalCoreTools,
-                                dynamicTools: totalDynTools,
-                                groups: allGroups,
-                            }, null, 2),
-                        }],
-                };
+                return this.jsonTextResponse({
+                    totalGroups: allGroups.length,
+                    coreGroups: coreGroups.length,
+                    dynamicGroups: dynamicGroups.length,
+                    coreTools: totalCoreTools,
+                    dynamicTools: totalDynTools,
+                    groups: allGroups,
+                });
             }
             case 'activate': {
                 if (groupName && CORE_TOOL_GROUPS[groupName]) {
-                    return {
-                        content: [{ type: 'text', text: JSON.stringify({ error: `'${groupName}' is a core group and always visible. No activation needed.` }) }],
-                    };
+                    return this.jsonTextResponse({ error: `'${groupName}' is a core group and always visible. No activation needed.` });
                 }
                 if (!groupName || !TOOL_GROUPS[groupName]) {
-                    const available = Object.keys(TOOL_GROUPS).join(', ');
-                    return {
-                        content: [{
-                                type: 'text',
-                                text: JSON.stringify({ error: `Unknown group '${groupName}'. Available dynamic groups: ${available}` }),
-                            }],
-                    };
-                }
-                const wasNew = !this.activeGroups.has(groupName);
-                this.activeGroups.add(groupName);
-                if (wasNew) {
-                    this.cachedToolDefinitions = [];
-                    this.server.sendToolListChanged().catch(() => { });
+                    return this.jsonTextResponse({ error: this.getUnknownDynamicGroupError(groupName) });
                 }
-                return {
-                    content: [{
-                            type: 'text',
-                            text: JSON.stringify({
-                                activated: groupName,
-                                tools: TOOL_GROUPS[groupName].tools,
-                                wasAlreadyActive: !wasNew,
-                                activeGroups: Array.from(this.activeGroups),
-                            }, null, 2),
-                        }],
-                };
+                const wasAlreadyActive = this.setDynamicGroupActivation(groupName, true);
+                return this.jsonTextResponse({
+                    activated: groupName,
+                    tools: TOOL_GROUPS[groupName].tools,
+                    wasAlreadyActive,
+                    activeGroups: Array.from(this.activeGroups),
+                });
             }
             case 'deactivate': {
                 if (groupName && CORE_TOOL_GROUPS[groupName]) {
-                    return {
-                        content: [{ type: 'text', text: JSON.stringify({ error: `'${groupName}' is a core group and cannot be deactivated.` }) }],
-                    };
+                    return this.jsonTextResponse({ error: `'${groupName}' is a core group and cannot be deactivated.` });
                 }
                 if (!groupName || !TOOL_GROUPS[groupName]) {
-                    const available = Object.keys(TOOL_GROUPS).join(', ');
-                    return {
-                        content: [{
-                                type: 'text',
-                                text: JSON.stringify({ error: `Unknown group '${groupName}'. Available dynamic groups: ${available}` }),
-                            }],
-                    };
+                    return this.jsonTextResponse({ error: this.getUnknownDynamicGroupError(groupName) });
                 }
-                const wasActive = this.activeGroups.has(groupName);
-                this.activeGroups.delete(groupName);
-                if (wasActive) {
-                    this.cachedToolDefinitions = [];
-                    this.server.sendToolListChanged().catch(() => { });
-                }
-                return {
-                    content: [{
-                            type: 'text',
-                            text: JSON.stringify({
-                                deactivated: groupName,
-                                wasActive,
-                                activeGroups: Array.from(this.activeGroups),
-                            }, null, 2),
-                        }],
-                };
+                const wasActive = this.setDynamicGroupActivation(groupName, false);
+                return this.jsonTextResponse({
+                    deactivated: groupName,
+                    wasActive,
+                    activeGroups: Array.from(this.activeGroups),
+                });
             }
             case 'reset': {
                 const previouslyActive = Array.from(this.activeGroups);
                 this.activeGroups.clear();
                 if (previouslyActive.length > 0) {
-                    this.cachedToolDefinitions = [];
-                    this.server.sendToolListChanged().catch(() => { });
+                    this.notifyToolListChanged();
                 }
-                return {
-                    content: [{
-                            type: 'text',
-                            text: JSON.stringify({
-                                reset: true,
-                                deactivated: previouslyActive,
-                                activeGroups: [],
-                            }, null, 2),
-                        }],
-                };
+                return this.jsonTextResponse({
+                    reset: true,
+                    deactivated: previouslyActive,
+                    activeGroups: [],
+                });
             }
             case 'status':
             default: {
@@ -959,16 +949,11 @@ class GodotServer {
                 }));
                 const totalCoreTools = coreGroupDetails.reduce((sum, g) => sum + g.tools.length, 0);
                 const totalDynamicTools = activeGroupDetails.reduce((sum, g) => sum + (g.tools?.length || 0), 0);
-                return {
-                    content: [{
-                            type: 'text',
-                            text: JSON.stringify({
-                                coreGroups: { count: coreGroupDetails.length, tools: totalCoreTools, groups: coreGroupDetails },
-                                dynamicGroups: { activeCount: this.activeGroups.size, tools: totalDynamicTools, groups: activeGroupDetails },
-                                availableDynamicGroups: Object.keys(TOOL_GROUPS),
-                            }, null, 2),
-                        }],
-                };
+                return this.jsonTextResponse({
+                    coreGroups: { count: coreGroupDetails.length, tools: totalCoreTools, groups: coreGroupDetails },
+                    dynamicGroups: { activeCount: this.activeGroups.size, tools: totalDynamicTools, groups: activeGroupDetails },
+                    availableDynamicGroups: this.getAvailableDynamicGroups(),
+                });
             }
         }
     }
@@ -999,8 +984,11 @@ class GodotServer {
         for (const key in params) {
             if (Object.prototype.hasOwnProperty.call(params, key)) {
                 let normalizedKey = key;
-                // If the key is in snake_case, convert it to camelCase using our mapping
-                if (key.includes('_')) {
+                // Preserve sentinel keys like _type, but normalize regular snake_case keys.
+                if (key.startsWith('_')) {
+                    normalizedKey = key;
+                }
+                else if (key.includes('_')) {
                     normalizedKey = this.parameterMappings[key] || key.replace(/_([a-zA-Z0-9])/g, (_, letter) => letter.toUpperCase());
                 }
                 // Handle nested objects recursively
@@ -1023,8 +1011,10 @@ class GodotServer {
         const result = {};
         for (const key in params) {
             if (Object.prototype.hasOwnProperty.call(params, key)) {
-                // Convert camelCase to snake_case
-                const snakeKey = this.reverseParameterMappings[key] || key.replace(/[A-Z]/g, letter => `_${letter.toLowerCase()}`);
+                // Convert camelCase to snake_case while preserving sentinel keys like _type.
+                const snakeKey = key.startsWith('_')
+                    ? key
+                    : (this.reverseParameterMappings[key] || key.replace(/[A-Z]/g, letter => `_${letter.toLowerCase()}`));
                 // Handle nested objects recursively
                 if (typeof params[key] === 'object' && params[key] !== null && !Array.isArray(params[key])) {
                     result[snakeKey] = this.convertCamelToSnakeCase(params[key]);
@@ -1057,16 +1047,18 @@ class GodotServer {
             }
         }
         try {
-            // Serialize the snake_case parameters to a valid JSON string
+            // Serialize parameters into a temp file to avoid shell/cmd JSON escaping issues
+            // (notably Windows command-line parsing of sequences such as \t, \r, and \").
             const paramsJson = JSON.stringify(snakeCaseParams);
-            // Escape single quotes in the JSON string to prevent command injection
-            const escapedParams = paramsJson.replace(/'/g, "'\\''");
-            // On Windows, cmd.exe does not strip single quotes, so we use
-            // double quotes and escape them to ensure the JSON is parsed
-            // correctly by Godot.
+            const paramsDir = mkdtempSync(join(tmpdir(), 'gopeak-params-'));
+            const paramsFilePath = join(paramsDir, `${operation}.json`);
+            writeFileSync(paramsFilePath, paramsJson, 'utf8');
+            // Escape the params file reference for the current shell.
+            const paramsFileArg = `@file:${paramsFilePath}`;
+            const escapedParams = paramsFileArg.replace(/'/g, "'\\''");
             const isWindows = process.platform === 'win32';
             const quotedParams = isWindows
-                ? `\"${paramsJson.replace(/\"/g, '\\"')}\"`
+                ? `\"${paramsFileArg.replace(/\"/g, '\\"')}\"`
                 : `'${escapedParams}'`;
             // Add debug arguments if debug mode is enabled
             const debugArgs = this.godotDebugMode ? ['--debug-godot'] : [];
@@ -1083,8 +1075,13 @@ class GodotServer {
                 ...debugArgs,
             ].join(' ');
             this.logDebug(`Command: ${cmd}`);
-            const { stdout, stderr } = await execAsync(cmd);
-            return { stdout, stderr };
+            try {
+                const { stdout, stderr } = await execAsync(cmd);
+                return { stdout, stderr: this.sanitizeGodotStderr(stderr) };
+            }
+            finally {
+                rmSync(paramsDir, { recursive: true, force: true });
+            }
         }
         catch (error) {
             // If execAsync throws, it still contains stdout/stderr
@@ -1092,12 +1089,27 @@ class GodotServer {
                 const execError = error;
                 return {
                     stdout: execError.stdout,
-                    stderr: execError.stderr,
+                    stderr: this.sanitizeGodotStderr(execError.stderr),
                 };
             }
             throw error;
         }
     }
+    getEditorStatusPayload() {
+        const status = this.godotBridge.getStatus();
+        const isPortConflict = this.bridgeStartupError?.includes('EADDRINUSE') ?? false;
+        return {
+            ...status,
+            bridgeAvailable: this.bridgeStartupError === null,
+            startupError: this.bridgeStartupError,
+            note: isPortConflict
+                ? 'Bridge port is already in use. Another gopeak instance may own the editor bridge, so this server cannot report that editor connection.'
+                : undefined,
+            suggestion: isPortConflict
+                ? 'Stop duplicate gopeak/MCP server instances or re-run the command from the same server process that owns the bridge port.'
+                : undefined,
+        };
+    }
     /**
      * Get the structure of a Godot project
      * @param projectPath Path to the Godot project
@@ -1449,7 +1461,7 @@ class GodotServer {
                     return await this.handleViaBridge('modify_resource', normalizedArgs);
                 // Editor Plugin Bridge Status
                 case 'get_editor_status':
-                    return { content: [{ type: 'text', text: JSON.stringify(this.godotBridge.getStatus(), null, 2) }] };
+                    return { content: [{ type: 'text', text: JSON.stringify(this.getEditorStatusPayload(), null, 2) }] };
                 // Project Visualizer Tool
                 case 'map_project':
                     return await this.handleMapProject(request.params.arguments);
@@ -2275,6 +2287,27 @@ class GodotServer {
         }
         return null;
     }
+    sanitizeGodotStderr(stderr) {
+        if (!stderr) {
+            return stderr;
+        }
+        const ignoredPatterns = [
+            /WARNING: ObjectDB instances leaked at exit/i,
+            /at:\s+cleanup\s+\(core\/object\/object\.cpp:/i,
+            /ERROR:\s+\d+\s+resources still in use at exit/i,
+            /at:\s+clear\s+\(core\/io\/resource\.cpp:/i,
+        ];
+        const filteredLines = stderr
+            .split(/\r?\n/)
+            .filter((line) => {
+            const trimmed = line.trim();
+            if (!trimmed) {
+                return false;
+            }
+            return !ignoredPatterns.some((pattern) => pattern.test(trimmed));
+        });
+        return filteredLines.join('\n').trim();
+    }
     /**
      * Capture/update current intent snapshot
      */
@@ -4705,11 +4738,13 @@ class GodotServer {
             // Bridge startup issues should not take down the stdio MCP server.
             try {
                 await this.godotBridge.start();
+                this.bridgeStartupError = null;
                 const bridgeStatus = this.godotBridge.getStatus();
                 console.error(`[SERVER] Godot Editor Bridge started on ${bridgeStatus.host}:${bridgeStatus.port}`);
             }
             catch (bridgeError) {
                 const bridgeMessage = bridgeError instanceof Error ? bridgeError.message : String(bridgeError);
+                this.bridgeStartupError = bridgeMessage;
                 console.error(`[SERVER] Warning: Godot Editor Bridge failed to start: ${bridgeMessage}`);
                 console.error('[SERVER] Continuing without bridge-backed editor tools.');
             }

package/build/scripts/godot_operations.gd

@@ -34,7 +34,15 @@ func _init():
     
     var operation = args[operation_index]
     var params_json = args[params_index]
-    
+    if params_json.begins_with("@file:"):
+        var params_file_path = params_json.substr(6)
+        var params_file = FileAccess.open(params_file_path, FileAccess.READ)
+        if params_file == null:
+            log_error("Failed to open params file: " + params_file_path)
+            quit(1)
+        params_json = params_file.get_as_text()
+        params_file.close()
+
     log_info("Operation: " + operation)
     log_debug("Params JSON: " + params_json)
     

package/build/tool-definitions.js

@@ -365,7 +365,7 @@ export function buildToolDefinitions(godotBridgePort) {
                     },
                     properties: {
                         type: 'string',
-                        description: 'Optional properties to set on the node (as JSON string)',
+                        description: 'Optional properties to set on the node (as JSON string). Tagged Godot values such as {"position":{"type":"Vector2","x":100,"y":200}} are the most explicit form; common typed properties like Vector2 also accept inferred shapes such as {"position":{"x":100,"y":200}} or {"position":[100,200]}.',
                     },
                 },
                 required: ['projectPath', 'scenePath', 'nodeType', 'nodeName'],
@@ -526,7 +526,7 @@ export function buildToolDefinitions(godotBridgePort) {
                     },
                     properties: {
                         type: 'string',
-                        description: 'JSON object of properties to set (e.g., {"position": {"x": 100, "y": 200}, "scale": {"x": 2, "y": 2}})',
+                        description: 'JSON object of properties to set. Tagged Godot values are the most explicit form (e.g., {"position":{"type":"Vector2","x":100,"y":200},"scale":{"type":"Vector2","x":2,"y":2}}), but typed properties like Vector2 also accept inferred {"x","y"} objects and numeric arrays.',
                     },
                     saveScene: {
                         type: 'boolean',

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "gopeak",
-  "version": "2.3.5",
+  "version": "2.3.7",
   "mcpName": "io.github.HaD0Yun/gopeak",
-  "description": "GoPeak — MCP server for Godot Engine with 110+ tools, compact/dynamic profiles, GDScript LSP, DAP debugger, screenshots, input injection, and CC0 asset search.",
+  "description": "GoPeak — MCP server for trusted Godot 4 workflows with compact/dynamic tool profiles, setup-gated LSP/DAP/runtime integrations, and migration-safe legacy compatibility.",
   "type": "module",
   "main": "./build/index.js",
   "bin": {
-    "gopeak": "./build/cli.js",
-    "godot-mcp": "./build/cli.js"
+    "gopeak": "build/cli.js",
+    "godot-mcp": "build/cli.js"
   },
   "files": [
     "build",
+    "scripts/postinstall.mjs",
     "README.md",
     "LICENSE"
   ],
@@ -22,7 +23,9 @@
     "test:smoke": "node scripts/smoke-test.mjs",
     "test:integration": "node test-bridge.mjs",
     "test:dynamic-groups": "node test-dynamic-groups.mjs",
-    "test:ci": "npm run test:smoke",
+    "test:docs": "node test-readme-localization-consistency.mjs && node test-docs-package-policy.mjs",
+    "test:regressions": "node test-regressions.mjs",
+    "test:ci": "npm run test:smoke && npm run test:regressions",
     "ci": "npm run build && npm run typecheck && npm run test:ci",
     "prepare": "npm run build",
     "postinstall": "node scripts/postinstall.mjs",
@@ -30,8 +33,10 @@
     "inspector": "npx @modelcontextprotocol/inspector build/index.js",
     "pack": "npm pack --dry-run",
     "version:bump": "node scripts/bump-version.mjs",
-    "test:setup": "npm run build && node test-setup-hooks.mjs && node test-metadata-consistency.mjs",
-    "test:metadata": "npm run build && node test-metadata-consistency.mjs"
+    "test:setup": "npm run build && node test-setup-hooks.mjs && node test-metadata-consistency.mjs && node test-packaging-consistency.mjs",
+    "test:metadata": "npm run build && node test-metadata-consistency.mjs",
+    "test:packaging": "npm run build && node test-packaging-consistency.mjs",
+    "test:docs-policy": "node test-docs-package-policy.mjs"
   },
   "engines": {
     "node": ">=18"
@@ -50,7 +55,8 @@
   },
   "overrides": {
     "@hono/node-server": "^1.19.11",
-    "hono": "4.12.7"
+    "hono": "^4.12.18",
+    "path-to-regexp": "8.4.1"
   },
   "license": "MIT",
   "repository": {

package/scripts/postinstall.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+const OPT_IN_VALUES = new Set(['1', 'true', 'yes', 'on']);
+const shouldInstallHooks = OPT_IN_VALUES.has(String(process.env.GOPEAK_SETUP_HOOKS || '').trim().toLowerCase());
+
+if (!shouldInstallHooks) {
+  process.exit(0);
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const cliPath = join(__dirname, '..', 'build', 'cli.js');
+
+if (!existsSync(cliPath)) {
+  process.exit(0);
+}
+
+try {
+  execFileSync(process.execPath, [cliPath, 'setup', '--silent'], {
+    stdio: 'ignore',
+    env: process.env,
+  });
+} catch {
+  process.exit(0);
+}