gopeak 2.3.5 → 2.3.6

package/README.md

@@ -144,6 +144,20 @@ 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
 
@@ -353,6 +367,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}` }),
-                            }],
-                    };
-                }
-                const wasActive = this.activeGroups.has(groupName);
-                this.activeGroups.delete(groupName);
-                if (wasActive) {
-                    this.cachedToolDefinitions = [];
-                    this.server.sendToolListChanged().catch(() => { });
+                    return this.jsonTextResponse({ error: this.getUnknownDynamicGroupError(groupName) });
                 }
-                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 };
+            }
+            finally {
+                rmSync(paramsDir, { recursive: true, force: true });
+            }
         }
         catch (error) {
             // If execAsync throws, it still contains stdout/stderr
@@ -1098,6 +1095,21 @@ class GodotServer {
             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);
@@ -4705,11 +4717,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,6 +1,6 @@
 {
   "name": "gopeak",
-  "version": "2.3.5",
+  "version": "2.3.6",
   "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.",
   "type": "module",
@@ -11,6 +11,7 @@
   },
   "files": [
     "build",
+    "scripts/postinstall.mjs",
     "README.md",
     "LICENSE"
   ],
@@ -22,7 +23,8 @@
     "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: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 +32,9 @@
     "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"
   },
   "engines": {
     "node": ">=18"
@@ -50,7 +53,8 @@
   },
   "overrides": {
     "@hono/node-server": "^1.19.11",
-    "hono": "4.12.7"
+    "hono": "4.12.7",
+    "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);
+}