gopeak 2.3.2 → 2.3.4

package/README.md

@@ -5,15 +5,17 @@
 [![](https://img.shields.io/badge/Node.js-339933?style=flat&logo=nodedotjs&logoColor=white 'Node.js')](https://nodejs.org/en/download/)
 [![](https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white 'TypeScript')](https://www.typescriptlang.org/)
 [![npm](https://img.shields.io/npm/v/gopeak?style=flat&logo=npm&logoColor=white 'npm')](https://www.npmjs.com/package/gopeak)
-[![](https://img.shields.io/github/last-commit/HaD0Yun/godot-mcp 'Last Commit')](https://github.com/HaD0Yun/godot-mcp/commits/main)
-[![](https://img.shields.io/github/stars/HaD0Yun/godot-mcp 'Stars')](https://github.com/HaD0Yun/godot-mcp/stargazers)
-[![](https://img.shields.io/github/forks/HaD0Yun/godot-mcp 'Forks')](https://github.com/HaD0Yun/godot-mcp/network/members)
+[![](https://img.shields.io/github/last-commit/HaD0Yun/Gopeak-godot-mcp 'Last Commit')](https://github.com/HaD0Yun/Gopeak-godot-mcp/commits/main)
+[![](https://img.shields.io/github/stars/HaD0Yun/Gopeak-godot-mcp 'Stars')](https://github.com/HaD0Yun/Gopeak-godot-mcp/stargazers)
+[![](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)
 
 ![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.**
 
+> 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
+
 ---
 
 ## Quick Start (3 Minutes)
@@ -169,7 +171,7 @@ gopeak
 ### C) From source
 
 ```bash
-git clone https://github.com/HaD0Yun/godot-mcp.git
+git clone https://github.com/HaD0Yun/Gopeak-godot-mcp.git
 cd godot-mcp
 npm install
 npm run build
@@ -183,13 +185,21 @@ GoPeak also exposes two CLI bin names:
 
 ---
 
+## Documentation
+
+- [Documentation Map](docs/README.md)
+- [Architecture](docs/architecture.md)
+- [Platform Roadmap](docs/platform-roadmap.md)
+- [Unity-MCP Benchmark Plan](docs/unity-mcp-benchmark-plan.md)
+- [Release Process](docs/release-process.md)
+
 ## CI
 
 GitHub Actions runs on push/PR and executes:
 
 1. `npm run build`
 2. `npx tsc --noEmit`
-3. `npm run test:ci`
+3. `npm run smoke`
 
 Run the same checks locally:
 
@@ -219,13 +229,13 @@ Full release checklist: [`docs/release-process.md`](docs/release-process.md).
 Install in your Godot project folder:
 
 ```bash
-curl -sL https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install-addon.sh | bash
+curl -sL https://raw.githubusercontent.com/HaD0Yun/Gopeak-godot-mcp/main/install-addon.sh | bash
 ```
 
 PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/HaD0Yun/godot-mcp/main/install-addon.ps1 -UseBasicParsing | iex
+iwr https://raw.githubusercontent.com/HaD0Yun/Gopeak-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).

package/build/cli/check.js

@@ -63,7 +63,7 @@ async function backgroundCheck() {
 function printUpdateBox(current, latest) {
     const line1 = `  🚀 GoPeak v${latest} available! (current: v${current})`;
     const line2 = `  npm update -g gopeak`;
-    const line3 = `  https://github.com/HaD0Yun/godot-mcp/releases`;
+    const line3 = `  https://github.com/HaD0Yun/Gopeak-godot-mcp/releases`;
     const maxLen = Math.max(line1.length, line2.length, line3.length) + 2;
     const pad = (s) => s + ' '.repeat(Math.max(0, maxLen - s.length));
     console.log('');

package/build/cli/notify.js

@@ -7,7 +7,7 @@
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
 import { createInterface } from 'readline';
 import { NOTIFY_FILE, STAR_PROMPTED_FILE, ensureGopeakDir, commandExists, runCommand, } from './utils.js';
-const REPO_URL = 'https://github.com/HaD0Yun/godot-mcp';
+const REPO_URL = 'https://github.com/HaD0Yun/Gopeak-godot-mcp';
 export async function showNotification() {
     ensureGopeakDir();
     const hasUpdate = existsSync(NOTIFY_FILE);
@@ -61,12 +61,12 @@ async function handleStar() {
         return;
     }
     // Check if already starred
-    const checkResult = await runCommand('gh api user/starred/HaD0Yun/godot-mcp');
+    const checkResult = await runCommand('gh api user/starred/HaD0Yun/Gopeak-godot-mcp');
     if (checkResult.code === 0) {
         console.log('  ⭐ Already starred! Thank you!');
         return;
     }
-    const starResult = await runCommand('gh api -X PUT user/starred/HaD0Yun/godot-mcp');
+    const starResult = await runCommand('gh api -X PUT user/starred/HaD0Yun/Gopeak-godot-mcp');
     if (starResult.code === 0) {
         console.log('  ⭐ Starred! Thank you for your support!');
     }

package/build/cli/setup.js

@@ -5,7 +5,7 @@
  * with a precheck function that displays cached GoPeak update notifications.
  */
 import { existsSync, readFileSync, writeFileSync, appendFileSync } from 'fs';
-import { getShellRcFile, getShellName, getLocalVersion, ensureGopeakDir, ONBOARDING_SHOWN_FILE, STAR_PROMPTED_FILE, } from './utils.js';
+import { getShellRcFile, getShellName, getLocalVersion, ensureGopeakDir, ONBOARDING_SHOWN_FILE, STAR_PROMPTED_FILE, supportsShellHooks, } from './utils.js';
 const MARKER_START = '# >>> GoPeak shell hooks >>>';
 const MARKER_END = '# <<< GoPeak shell hooks <<<';
 /** The shell hook block that gets appended to the RC file. */
@@ -55,6 +55,13 @@ function generateHookBlock() {
 }
 export async function setupShellHooks(args = []) {
     const silent = args.includes('--silent');
+    if (!supportsShellHooks()) {
+        if (!silent) {
+            console.log('ℹ️  GoPeak shell hooks are only installed for bash/zsh on Unix-like systems.');
+            console.log('   Skipping shell hook setup on this platform/shell.');
+        }
+        return;
+    }
     const rcFile = getShellRcFile();
     const shellName = getShellName();
     const log = silent ? (..._args) => { } : console.log.bind(console);
@@ -106,7 +113,7 @@ function printOnboarding(log = console.log) {
     log('║                                                      ║');
     log('║  110+ tools for Godot Engine via MCP                 ║');
     log('║                                                      ║');
-    log('║  📖 Docs:   https://github.com/HaD0Yun/godot-mcp   ║');
+    log('║  📖 Docs:   https://github.com/HaD0Yun/Gopeak-godot-mcp   ║');
     log('║  ⭐ Star:   gopeak star                              ║');
     log('║  🔄 Update: npm update -g gopeak                     ║');
     log('╚══════════════════════════════════════════════════════╝');

package/build/cli/star.js

@@ -7,7 +7,7 @@
  */
 import { commandExists, runCommand, STAR_PROMPTED_FILE, ensureGopeakDir } from './utils.js';
 import { existsSync, writeFileSync } from 'fs';
-const REPO = 'HaD0Yun/godot-mcp';
+const REPO = 'HaD0Yun/Gopeak-godot-mcp';
 const REPO_URL = `https://github.com/${REPO}`;
 export async function starGoPeak() {
     // 1. Check if gh CLI exists

package/build/cli/utils.js

@@ -122,6 +122,11 @@ export function getShellName() {
         return 'zsh';
     return 'bash';
 }
+export function supportsShellHooks(platform = process.platform, shell = process.env.SHELL ?? '') {
+    if (platform === 'win32')
+        return false;
+    return shell.includes('bash') || shell.includes('zsh');
+}
 /* ------------------------------------------------------------------ */
 /*  Command helpers                                                    */
 /* ------------------------------------------------------------------ */

package/build/cli.js

@@ -82,7 +82,7 @@ Usage:
 Shell hooks wrap these commands with update notifications:
   claude, codex, gemini, opencode, omc, omx
 
-More info: https://github.com/HaD0Yun/godot-mcp
+More info: https://github.com/HaD0Yun/Gopeak-godot-mcp
 `.trim());
 }
 main().catch((err) => {

package/build/index.js

@@ -671,42 +671,109 @@ class GodotServer {
                 const payload = JSON.stringify({ command, params, id: Date.now() });
                 socket.write(payload + '\n');
             });
-            let responseData = '';
+            let responseBuffer = Buffer.alloc(0);
+            let resolved = false;
             const timer = setTimeout(() => {
+                if (resolved) {
+                    return;
+                }
+                resolved = true;
                 socket.destroy();
                 resolve({
                     content: [{ type: 'text', text: `Runtime command '${command}' timed out after ${TIMEOUT_MS}ms. Ensure the Godot game is running with the MCP runtime addon enabled.` }],
                 });
             }, TIMEOUT_MS);
-            socket.setEncoding('utf8');
+            const resolveRuntimePayload = (parsed) => {
+                if (resolved) {
+                    return;
+                }
+                resolved = true;
+                clearTimeout(timer);
+                socket.destroy();
+                if (parsed.type === 'screenshot' && parsed.data) {
+                    resolve({
+                        content: [
+                            { type: 'text', text: `Screenshot captured: ${parsed.width}x${parsed.height} ${parsed.format}` },
+                            { type: 'image', data: parsed.data, mimeType: 'image/png' },
+                        ],
+                    });
+                    return;
+                }
+                resolve({
+                    content: [{ type: 'text', text: JSON.stringify(parsed, null, 2) }],
+                });
+            };
             socket.on('data', (chunk) => {
-                responseData += chunk;
-                if (responseData.includes('\n') || responseData.includes('}')) {
-                    clearTimeout(timer);
-                    socket.destroy();
+                responseBuffer = Buffer.concat([responseBuffer, Buffer.from(chunk)]);
+                const parsedMessages = [];
+                const parseCandidate = (candidate) => {
+                    const trimmed = candidate.trim();
+                    if (!trimmed) {
+                        return;
+                    }
                     try {
-                        const parsed = JSON.parse(responseData.trim());
-                        if (parsed.type === 'screenshot' && parsed.data) {
-                            resolve({
-                                content: [
-                                    { type: 'text', text: `Screenshot captured: ${parsed.width}x${parsed.height} ${parsed.format}` },
-                                    { type: 'image', text: parsed.data },
-                                ],
-                            });
-                            return;
-                        }
-                        resolve({
-                            content: [{ type: 'text', text: JSON.stringify(parsed, null, 2) }],
-                        });
+                        parsedMessages.push(JSON.parse(trimmed));
                     }
                     catch {
-                        resolve({
-                            content: [{ type: 'text', text: responseData.trim() || 'Command sent successfully (no structured response).' }],
-                        });
+                        // Ignore malformed frame/line and keep scanning.
+                    }
+                };
+                // First, parse the framed payload format emitted by Godot's StreamPeerTCP.put_utf8_string().
+                let offset = 0;
+                while (offset + 4 <= responseBuffer.length) {
+                    const frameLength = responseBuffer.readUInt32LE(offset);
+                    if (frameLength <= 0 || offset + 4 + frameLength > responseBuffer.length) {
+                        break;
                     }
+                    const frame = responseBuffer.subarray(offset + 4, offset + 4 + frameLength).toString('utf8');
+                    parseCandidate(frame);
+                    offset += 4 + frameLength;
+                }
+                if (offset > 0) {
+                    responseBuffer = responseBuffer.subarray(offset);
+                }
+                // Fallback for plain newline-delimited JSON payloads.
+                let newlineIndex = responseBuffer.indexOf(0x0a);
+                while (newlineIndex !== -1) {
+                    const line = responseBuffer.subarray(0, newlineIndex).toString('utf8');
+                    responseBuffer = responseBuffer.subarray(newlineIndex + 1);
+                    parseCandidate(line);
+                    newlineIndex = responseBuffer.indexOf(0x0a);
+                }
+                if (parsedMessages.length > 0) {
+                    const candidate = parsedMessages.find((message) => message?.type === 'screenshot' && message?.data)
+                        ?? parsedMessages.find((message) => message?.type === 'pong')
+                        ?? parsedMessages.find((message) => message?.type && message.type !== 'welcome')
+                        ?? null;
+                    if (candidate) {
+                        resolveRuntimePayload(candidate);
+                    }
+                }
+            });
+            socket.on('end', () => {
+                if (resolved) {
+                    return;
+                }
+                clearTimeout(timer);
+                const responseData = responseBuffer.toString('utf8').trim();
+                resolved = true;
+                try {
+                    const parsed = JSON.parse(responseData);
+                    resolve({
+                        content: [{ type: 'text', text: JSON.stringify(parsed, null, 2) }],
+                    });
+                }
+                catch {
+                    resolve({
+                        content: [{ type: 'text', text: responseData || 'Command sent successfully (no structured response).' }],
+                    });
                 }
             });
             socket.on('error', (error) => {
+                if (resolved) {
+                    return;
+                }
+                resolved = true;
                 clearTimeout(timer);
                 resolve({
                     content: [{ type: 'text', text: `Failed to connect to Godot runtime addon at ${RUNTIME_HOST}:${RUNTIME_PORT}: ${error.message}. Ensure the game is running with the MCP runtime autoload enabled.` }],
@@ -726,8 +793,41 @@ class GodotServer {
         }
         return handleDAPTool(this.dapClient, toolName, args);
     }
+    sanitizeExportedToolName(toolName) {
+        const sanitized = toolName
+            .normalize('NFKD')
+            .replace(/[^\x00-\x7F]/g, '')
+            .replace(/[^a-zA-Z0-9-]+/g, '-')
+            .replace(/-+/g, '-')
+            .replace(/^-+|-+$/g, '')
+            .slice(0, 128);
+        return sanitized.length > 0 ? sanitized : 'tool';
+    }
+    buildToolNameResolutionMap(allTools) {
+        const resolutionMap = new Map();
+        const register = (candidateName, resolvedName) => {
+            const existing = resolutionMap.get(candidateName);
+            if (existing && existing !== resolvedName) {
+                throw new Error(`Sanitized tool name collision: "${candidateName}" maps to both "${existing}" and "${resolvedName}"`);
+            }
+            resolutionMap.set(candidateName, resolvedName);
+        };
+        for (const tool of allTools) {
+            register(tool.name, tool.name);
+            register(this.sanitizeExportedToolName(tool.name), tool.name);
+        }
+        for (const [compactName, legacyName] of Object.entries(this.compactAliasToLegacy)) {
+            register(compactName, legacyName);
+            register(this.sanitizeExportedToolName(compactName), legacyName);
+        }
+        return resolutionMap;
+    }
     resolveToolAlias(requestedToolName) {
-        return this.compactAliasToLegacy[requestedToolName] || requestedToolName;
+        const allTools = this.getAllToolDefinitions();
+        const resolutionMap = this.buildToolNameResolutionMap(allTools);
+        return resolutionMap.get(requestedToolName)
+            || resolutionMap.get(this.sanitizeExportedToolName(requestedToolName))
+            || requestedToolName;
     }
     buildCompactTools(allTools) {
         const compactTools = [];
@@ -744,6 +844,26 @@ class GodotServer {
         }
         return compactTools;
     }
+    sanitizeToolsForList(tools) {
+        const seenNames = new Map();
+        return tools.map((tool) => {
+            const sanitizedName = this.sanitizeExportedToolName(tool.name);
+            const existing = seenNames.get(sanitizedName);
+            if (existing && existing !== tool.name) {
+                throw new Error(`Sanitized tool name collision in tools/list: "${sanitizedName}" from "${existing}" and "${tool.name}"`);
+            }
+            seenNames.set(sanitizedName, tool.name);
+            if (sanitizedName !== tool.name) {
+                this.logDebug(`Exporting tool "${tool.name}" as "${sanitizedName}" for OpenAI-compatible clients`);
+            }
+            return sanitizedName === tool.name
+                ? tool
+                : {
+                    ...tool,
+                    name: sanitizedName,
+                };
+        });
+    }
     getExposedTools(allTools) {
         if (this.toolExposureProfile === 'full' || this.toolExposureProfile === 'legacy') {
             return allTools;
@@ -3559,7 +3679,7 @@ class GodotServer {
         this.server.setRequestHandler(ListToolsRequestSchema, async (request) => {
             const allTools = buildToolDefinitions();
             this.cachedToolDefinitions = allTools;
-            const exposedTools = this.getExposedTools(allTools);
+            const exposedTools = this.sanitizeToolsForList(this.getExposedTools(allTools));
             return this.paginateToolsForList(exposedTools, request.params?.cursor);
         });
         // Handle tool calls
@@ -4586,6 +4706,26 @@ class GodotServer {
         })
             .filter((v) => v !== null);
     }
+    extractLastJsonLine(stdout) {
+        const lines = stdout
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        for (let i = lines.length - 1; i >= 0; i -= 1) {
+            const line = lines[i];
+            if (!(line.startsWith('{') || line.startsWith('['))) {
+                continue;
+            }
+            try {
+                JSON.parse(line);
+                return line;
+            }
+            catch {
+                continue;
+            }
+        }
+        return null;
+    }
     /**
      * Capture/update current intent snapshot
      */
@@ -5377,7 +5517,7 @@ class GodotServer {
                 return this.createErrorResponse(`Failed to list scene nodes: ${stderr}`, ['Verify the scene file is valid']);
             }
             return {
-                content: [{ type: 'text', text: stdout.trim() }],
+                content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
             };
         }
         catch (error) {
@@ -5414,7 +5554,7 @@ class GodotServer {
                 return this.createErrorResponse(`Failed to get node properties: ${stderr}`, ['Verify the node path is correct', 'Check if the node exists in the scene']);
             }
             return {
-                content: [{ type: 'text', text: stdout.trim() }],
+                content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
             };
         }
         catch (error) {
@@ -5603,7 +5743,7 @@ class GodotServer {
                 return this.createErrorResponse(`Failed to get import status: ${stderr}`, ['Verify the resource path if specified']);
             }
             return {
-                content: [{ type: 'text', text: stdout.trim() }],
+                content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
             };
         }
         catch (error) {
@@ -5638,7 +5778,7 @@ class GodotServer {
                 return this.createErrorResponse(`Failed to get import options: ${stderr}`, ['Verify the resource is an importable file type']);
             }
             return {
-                content: [{ type: 'text', text: stdout.trim() }],
+                content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
             };
         }
         catch (error) {
@@ -5744,7 +5884,7 @@ class GodotServer {
                 return this.createErrorResponse(`Failed to list export presets: ${stderr}`, ['Check if export_presets.cfg exists in the project']);
             }
             return {
-                content: [{ type: 'text', text: stdout.trim() }],
+                content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
             };
         }
         catch (error) {
@@ -5814,7 +5954,7 @@ class GodotServer {
                 return this.createErrorResponse(`Failed to validate project: ${stderr}`, ['Verify the project structure is valid']);
             }
             return {
-                content: [{ type: 'text', text: stdout.trim() }],
+                content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
             };
         }
         catch (error) {
@@ -5850,7 +5990,7 @@ class GodotServer {
                 return this.createErrorResponse(`Failed to get dependencies: ${stderr}`, ['Verify the resource path is correct']);
             }
             return {
-                content: [{ type: 'text', text: stdout.trim() }],
+                content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
             };
         }
         catch (error) {
@@ -5882,7 +6022,7 @@ class GodotServer {
                 return this.createErrorResponse(`Failed to find resource usages: ${stderr}`, ['Verify the resource path is correct']);
             }
             return {
-                content: [{ type: 'text', text: stdout.trim() }],
+                content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
             };
         }
         catch (error) {
@@ -5914,7 +6054,7 @@ class GodotServer {
                 return this.createErrorResponse(`Failed to parse error log: ${stderr}`, ['Verify the log content or ensure godot.log exists']);
             }
             return {
-                content: [{ type: 'text', text: stdout.trim() }],
+                content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
             };
         }
         catch (error) {
@@ -5945,7 +6085,7 @@ class GodotServer {
                 return this.createErrorResponse(`Failed to get project health: ${stderr}`, ['Verify the project structure']);
             }
             return {
-                content: [{ type: 'text', text: stdout.trim() }],
+                content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
             };
         }
         catch (error) {
@@ -5979,7 +6119,7 @@ class GodotServer {
                 return this.createErrorResponse(`Failed to get project setting: ${stderr}`, ['Verify the setting path is correct']);
             }
             return {
-                content: [{ type: 'text', text: stdout.trim() }],
+                content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
             };
         }
         catch (error) {
@@ -6103,7 +6243,7 @@ class GodotServer {
                 return this.createErrorResponse(`Failed to list autoloads: ${stderr}`, ['Verify the project structure']);
             }
             return {
-                content: [{ type: 'text', text: stdout.trim() }],
+                content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
             };
         }
         catch (error) {
@@ -6260,7 +6400,7 @@ class GodotServer {
                 return this.createErrorResponse(`Failed to list connections: ${stderr}`, ['Verify the scene path is correct']);
             }
             return {
-                content: [{ type: 'text', text: stdout.trim() }],
+                content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
             };
         }
         catch (error) {
@@ -6279,32 +6419,59 @@ class GodotServer {
             return this.createErrorResponse('Project path is required', ['Provide a valid path to a Godot project directory']);
         }
         try {
-            // Runtime connection requires a running Godot instance with the addon
-            // For now, return status based on active process
-            if (this.activeProcess) {
+            const runtime = await this.handleRuntimeCommand('ping', {});
+            const runtimeText = runtime?.content?.[0]?.text || '';
+            let runtimePayload = null;
+            try {
+                runtimePayload = JSON.parse(runtimeText);
+            }
+            catch {
+                runtimePayload = null;
+            }
+            const runtimeConnected = runtimePayload?.type === 'pong';
+            if (runtimeConnected) {
                 return {
                     content: [{
                             type: 'text',
                             text: JSON.stringify({
                                 connected: true,
                                 status: 'running',
-                                note: 'A Godot process is active. Use inspect_runtime_tree to explore.',
+                                processActive: Boolean(this.activeProcess),
+                                runtimeAddon: 'connected',
+                                note: 'Godot runtime addon responded to ping. Use inspect_runtime_tree to explore.',
+                                runtimeResponse: runtimePayload,
                             }, null, 2),
                         }],
                 };
             }
-            else {
+            if (this.activeProcess) {
                 return {
                     content: [{
                             type: 'text',
                             text: JSON.stringify({
                                 connected: false,
-                                status: 'not_running',
-                                note: 'No active Godot process. Use run_project to start one.',
+                                status: 'process_running_runtime_disconnected',
+                                processActive: true,
+                                runtimeAddon: 'unreachable',
+                                note: 'A Godot process is active, but the runtime addon did not respond on port 7777.',
+                                runtimeResponse: runtimeText,
                             }, null, 2),
                         }],
                 };
             }
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            connected: false,
+                            status: 'not_running',
+                            processActive: false,
+                            runtimeAddon: 'unreachable',
+                            note: 'No active Godot process or runtime addon detected. Use run_project to start one.',
+                            runtimeResponse: runtimeText,
+                        }, null, 2),
+                    }],
+            };
         }
         catch (error) {
             return this.createErrorResponse(`Failed to get runtime status: ${error?.message || 'Unknown error'}`, ['Ensure Godot is installed correctly']);
@@ -6319,27 +6486,14 @@ class GodotServer {
             return this.createErrorResponse('Project path is required', ['Provide a valid path to a Godot project directory']);
         }
         try {
-            // Runtime inspection requires a running Godot instance
-            if (!this.activeProcess) {
-                return this.createErrorResponse('No active Godot process', ['Use run_project to start a Godot instance first']);
-            }
-            // Return information about the running process
-            return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify({
-                            status: 'running',
-                            nodePath: args.nodePath || '/',
-                            depth: args.depth || 3,
-                            note: 'Runtime tree inspection requires the godot_mcp_runtime addon. Current output shows debug logs.',
-                            recentOutput: this.activeProcess.output.slice(-20),
-                            recentErrors: this.activeProcess.errors.slice(-10),
-                        }, null, 2),
-                    }],
-            };
+            return await this.handleRuntimeCommand('get_tree', {
+                root: args.nodePath || '/root',
+                depth: args.depth || 3,
+                include_properties: Boolean(args.includeProperties),
+            });
         }
         catch (error) {
-            return this.createErrorResponse(`Failed to inspect runtime tree: ${error?.message || 'Unknown error'}`, ['Ensure a Godot process is running']);
+            return this.createErrorResponse(`Failed to inspect runtime tree: ${error?.message || 'Unknown error'}`, ['Ensure a Godot process is running with the runtime addon enabled']);
         }
     }
     /**
@@ -6351,24 +6505,11 @@ class GodotServer {
             return this.createErrorResponse('Missing required parameters', ['Provide projectPath, nodePath, property, and value']);
         }
         try {
-            if (!this.activeProcess) {
-                return this.createErrorResponse('No active Godot process', ['Use run_project to start a Godot instance first']);
-            }
-            // Runtime property modification requires the addon
-            return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify({
-                            status: 'not_implemented',
-                            note: 'Runtime property modification requires the godot_mcp_runtime addon installed in the running project.',
-                            requested: {
-                                nodePath: args.nodePath,
-                                property: args.property,
-                                value: args.value,
-                            },
-                        }, null, 2),
-                    }],
-            };
+            return await this.handleRuntimeCommand('set_property', {
+                path: args.nodePath,
+                property: args.property,
+                value: args.value,
+            });
         }
         catch (error) {
             return this.createErrorResponse(`Failed to set runtime property: ${error?.message || 'Unknown error'}`, ['Ensure a Godot process is running with the runtime addon']);
@@ -6383,24 +6524,11 @@ class GodotServer {
             return this.createErrorResponse('Missing required parameters', ['Provide projectPath, nodePath, and method']);
         }
         try {
-            if (!this.activeProcess) {
-                return this.createErrorResponse('No active Godot process', ['Use run_project to start a Godot instance first']);
-            }
-            // Runtime method calling requires the addon
-            return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify({
-                            status: 'not_implemented',
-                            note: 'Runtime method calling requires the godot_mcp_runtime addon installed in the running project.',
-                            requested: {
-                                nodePath: args.nodePath,
-                                method: args.method,
-                                args: args.args || [],
-                            },
-                        }, null, 2),
-                    }],
-            };
+            return await this.handleRuntimeCommand('call_method', {
+                path: args.nodePath,
+                method: args.method,
+                args: Array.isArray(args.args) ? args.args : [],
+            });
         }
         catch (error) {
             return this.createErrorResponse(`Failed to call runtime method: ${error?.message || 'Unknown error'}`, ['Ensure a Godot process is running with the runtime addon']);
@@ -6415,24 +6543,9 @@ class GodotServer {
             return this.createErrorResponse('Project path is required', ['Provide a valid path to a Godot project directory']);
         }
         try {
-            if (!this.activeProcess) {
-                return this.createErrorResponse('No active Godot process', ['Use run_project to start a Godot instance first']);
-            }
-            // Basic metrics from process output
-            return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify({
-                            status: 'running',
-                            metrics: {
-                                outputLines: this.activeProcess.output.length,
-                                errorLines: this.activeProcess.errors.length,
-                                note: 'Detailed metrics require the godot_mcp_runtime addon.',
-                            },
-                            requestedMetrics: args.metrics || 'all',
-                        }, null, 2),
-                    }],
-            };
+            return await this.handleRuntimeCommand('get_metrics', {
+                metrics: Array.isArray(args.metrics) ? args.metrics : [],
+            });
         }
         catch (error) {
             return this.createErrorResponse(`Failed to get runtime metrics: ${error?.message || 'Unknown error'}`, ['Ensure a Godot process is running']);
@@ -6861,7 +6974,7 @@ class GodotServer {
                 return this.createErrorResponse(`Failed to list plugins: ${stderr}`, ['Verify the project structure']);
             }
             return {
-                content: [{ type: 'text', text: stdout.trim() }],
+                content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
             };
         }
         catch (error) {
@@ -7000,7 +7113,7 @@ class GodotServer {
                 return this.createErrorResponse(`Failed to search project: ${stderr}`, ['Check if the query/regex pattern is valid']);
             }
             return {
-                content: [{ type: 'text', text: stdout.trim() }],
+                content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
             };
         }
         catch (error) {
@@ -7787,7 +7900,16 @@ uniform float dissolve_amount : hint_range(0.0, 1.0) = 0.0;
             params.instantiable_only = args.instantiableOnly;
         if (args?.instantiable_only !== undefined)
             params.instantiable_only = args.instantiable_only;
-        return await this.executeOperation('query_classes', params, projectPath);
+        const { stdout, stderr } = await this.executeOperation('query_classes', params, projectPath);
+        if (stderr && stderr.trim()) {
+            return this.createErrorResponse(`Failed to query classes: ${stderr.trim()}`, [
+                'Check the project path and ensure project.godot exists',
+                'Verify the category/filter arguments are valid',
+            ]);
+        }
+        return {
+            content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
+        };
     }
     /**
      * Handle the query_class_info tool — ClassDB introspection
@@ -7808,7 +7930,16 @@ uniform float dissolve_amount : hint_range(0.0, 1.0) = 0.0;
             params.include_inherited = args.includeInherited;
         if (args?.include_inherited !== undefined)
             params.include_inherited = args.include_inherited;
-        return await this.executeOperation('query_class_info', params, projectPath);
+        const { stdout, stderr } = await this.executeOperation('query_class_info', params, projectPath);
+        if (stderr && stderr.trim()) {
+            return this.createErrorResponse(`Failed to query class info: ${stderr.trim()}`, [
+                'Check that the class name exists in the current Godot version',
+                'Verify the project path and ClassDB availability',
+            ]);
+        }
+        return {
+            content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
+        };
     }
     /**
      * Handle the inspect_inheritance tool — ClassDB introspection
@@ -7822,9 +7953,17 @@ uniform float dissolve_amount : hint_range(0.0, 1.0) = 0.0;
         if (!className) {
             throw new McpError(ErrorCode.InvalidParams, 'className is required');
         }
-        return await this.executeOperation('inspect_inheritance', {
+        const { stdout, stderr } = await this.executeOperation('inspect_inheritance', {
             class_name: className,
         }, projectPath);
+        if (stderr && stderr.trim()) {
+            return this.createErrorResponse(`Failed to inspect inheritance: ${stderr.trim()}`, [
+                'Check that the class name exists in the current Godot version',
+            ]);
+        }
+        return {
+            content: [{ type: 'text', text: this.extractLastJsonLine(stdout) || stdout.trim() }],
+        };
     }
     /**
      * Handle the modify_resource tool

package/build/lsp_client.js

@@ -1,6 +1,6 @@
-import { readFile } from 'node:fs/promises';
+import { readFile, realpath } from 'node:fs/promises';
 import { createConnection } from 'node:net';
-import { dirname, resolve } from 'node:path';
+import { dirname, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 export class GodotLSPClient {
     socket = null;
@@ -464,6 +464,38 @@ function normalizeLSPError(error) {
     }
     return String(error);
 }
+function normalizePathForComparison(pathValue) {
+    const resolved = resolve(pathValue);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+function isPathWithinRoot(rootPath, candidatePath) {
+    const normalizedRoot = normalizePathForComparison(rootPath);
+    const normalizedCandidate = normalizePathForComparison(candidatePath);
+    const rootPrefix = normalizedRoot.endsWith(sep) ? normalizedRoot : `${normalizedRoot}${sep}`;
+    return normalizedCandidate === normalizedRoot || normalizedCandidate.startsWith(rootPrefix);
+}
+async function resolveLSPPaths(projectPathValue, scriptPathValue) {
+    const requestedProjectPath = resolve(projectPathValue);
+    let projectPath;
+    try {
+        projectPath = await realpath(requestedProjectPath);
+    }
+    catch {
+        throw new Error(`Project path does not exist: ${requestedProjectPath}`);
+    }
+    const requestedScriptPath = resolve(projectPath, scriptPathValue);
+    let scriptPath;
+    try {
+        scriptPath = await realpath(requestedScriptPath);
+    }
+    catch {
+        throw new Error(`Script file does not exist: ${requestedScriptPath}`);
+    }
+    if (!isPathWithinRoot(projectPath, scriptPath)) {
+        throw new Error('scriptPath resolves outside the project root boundary.');
+    }
+    return { projectPath, scriptPath };
+}
 export async function handleLSPTool(client, toolName, args) {
     try {
         if (!args || typeof args !== 'object') {
@@ -478,8 +510,7 @@ export async function handleLSPTool(client, toolName, args) {
         if (typeof scriptPathValue !== 'string' || scriptPathValue.length === 0) {
             throw new Error('Missing required argument: scriptPath');
         }
-        const projectPath = resolve(projectPathValue);
-        const scriptPath = resolve(projectPath, scriptPathValue);
+        const { projectPath, scriptPath } = await resolveLSPPaths(projectPathValue, scriptPathValue);
         const content = await readFile(scriptPath, 'utf8');
         await client.initialize(projectPath);
         switch (toolName) {

package/build/providers/ambientcg.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, createWriteStream, appendFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import * as https from 'https';
+import { providerLog } from './logging.js';
 const AMBIENTCG_CONFIG = {
     name: 'ambientcg',
     displayName: 'AmbientCG',
@@ -111,7 +112,7 @@ export class AmbientCGProvider {
             });
         }
         catch (error) {
-            console.error(`[AmbientCG] Search failed: ${error}`);
+            providerLog('error', this.config.name, 'Search failed', error);
             return [];
         }
     }
@@ -159,6 +160,7 @@ export class AmbientCGProvider {
             };
         }
         catch (error) {
+            providerLog('error', this.config.name, 'Download failed', error);
             return {
                 success: false,
                 assetId,

package/build/providers/kenney.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, createWriteStream, appendFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import * as https from 'https';
+import { providerLog } from './logging.js';
 const KENNEY_CONFIG = {
     name: 'kenney',
     displayName: 'Kenney',
@@ -105,6 +106,7 @@ export class KenneyProvider {
         const { assetId, projectPath, targetFolder = 'downloaded_assets/kenney' } = options;
         const pack = KENNEY_ASSET_PACKS.find(p => p.id === assetId);
         if (!pack) {
+            providerLog('warn', this.config.name, `Asset pack not found: ${assetId}`);
             return {
                 success: false,
                 assetId,
@@ -144,6 +146,7 @@ export class KenneyProvider {
             };
         }
         catch (error) {
+            providerLog('error', this.config.name, 'Download failed', error);
             return {
                 success: false,
                 assetId,

package/build/providers/logging.js

@@ -0,0 +1,19 @@
+export function formatProviderError(error) {
+    if (error instanceof Error) {
+        return error.stack ?? error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}
+export function providerLog(level, provider, message, error) {
+    const errorSuffix = error === undefined ? '' : ` | error=${formatProviderError(error)}`;
+    const timestamp = new Date().toISOString();
+    console.error(`[${timestamp}] [providers:${provider}] [${level.toUpperCase()}] ${message}${errorSuffix}`);
+}

package/build/providers/manager.js

@@ -2,6 +2,7 @@ import { PROVIDER_PRIORITY, } from './types.js';
 import { PolyHavenProvider } from './polyhaven.js';
 import { AmbientCGProvider } from './ambientcg.js';
 import { KenneyProvider } from './kenney.js';
+import { providerLog } from './logging.js';
 export class AssetManager {
     providers = new Map();
     sortedProviders = [];
@@ -40,7 +41,7 @@ export class AssetManager {
                 allResults.push(...results);
             }
             catch (error) {
-                console.error(`[AssetManager] Search failed for ${provider.config.name}: ${error}`);
+                providerLog('error', 'asset-manager', `Search failed for ${provider.config.name}`, error);
             }
         }
         return allResults
@@ -66,7 +67,7 @@ export class AssetManager {
                 }
             }
             catch (error) {
-                console.error(`[AssetManager] Search failed for ${provider.config.name}: ${error}`);
+                providerLog('error', 'asset-manager', `Search failed for ${provider.config.name}`, error);
             }
         }
         return [];
@@ -104,7 +105,7 @@ export class AssetManager {
                 }
             }
             catch (error) {
-                console.error(`[AssetManager] Download failed for ${provider.config.name}: ${error}`);
+                providerLog('error', 'asset-manager', `Download failed for ${provider.config.name}`, error);
             }
         }
         return {

package/build/providers/polyhaven.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, createWriteStream, appendFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import * as https from 'https';
+import { providerLog } from './logging.js';
 const POLYHAVEN_CONFIG = {
     name: 'polyhaven',
     displayName: 'Poly Haven',
@@ -115,7 +116,7 @@ export class PolyHavenProvider {
                 .slice(0, maxResults);
         }
         catch (error) {
-            console.error(`[PolyHaven] Search failed: ${error}`);
+            providerLog('error', this.config.name, 'Search failed', error);
             return [];
         }
     }
@@ -176,6 +177,7 @@ export class PolyHavenProvider {
             };
         }
         catch (error) {
+            providerLog('error', this.config.name, 'Download failed', error);
             return {
                 success: false,
                 assetId,

package/build/scripts/godot_operations.gd

@@ -2835,6 +2835,10 @@ func get_node_by_path_v2(scene_root: Node, node_path: String) -> Node:
     
     return scene_root.get_node_or_null(clean_path)
 
+# Backward-compatible alias for newer helpers that still call the old name
+func get_node_from_path(scene_root: Node, node_path: String) -> Node:
+    return get_node_by_path_v2(scene_root, node_path)
+
 # Helper function to build node tree structure recursively
 func build_node_tree(node: Node, current_depth: int, max_depth: int, include_properties: bool) -> Dictionary:
     var result = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gopeak",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "mcpName": "io.github.HaD0Yun/gopeak",
   "description": "GoPeak — The most comprehensive MCP server for Godot Engine. 95+ tools: scene management, GDScript LSP diagnostics, DAP debugger, screenshot capture, input injection, ClassDB introspection, CC0 asset library. AI-assisted game development with Claude, Cursor, Cline, OpenCode.",
   "type": "module",
@@ -17,23 +17,27 @@
   "scripts": {
     "build": "tsc && node scripts/build-visualizer.js && node scripts/build.js",
     "typecheck": "tsc --noEmit",
+    "test": "npm run test:ci",
+    "smoke": "npm run test:ci",
     "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",
     "ci": "npm run build && npm run typecheck && npm run test:ci",
     "prepare": "npm run build",
-    "postinstall": "node build/cli.js setup --silent 2>/dev/null || true",
+    "postinstall": "node -e \"try{require('child_process').execFileSync(process.execPath,['build/cli.js','setup','--silent'],{stdio:'ignore'})}catch{}\"",
     "watch": "tsc --watch",
     "inspector": "npx @modelcontextprotocol/inspector build/index.js",
     "pack": "npm pack --dry-run",
-    "version:bump": "node scripts/bump-version.mjs"
+    "version:bump": "node scripts/bump-version.mjs",
+    "test:setup": "npm run build && node test-setup-hooks.mjs"
   },
   "engines": {
     "node": ">=18"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.0",
-    "axios": "^1.7.9",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "axios": "^1.13.6",
     "fs-extra": "^11.2.0",
     "ws": "^8.18.0"
   },
@@ -43,14 +47,18 @@
     "esbuild": "^0.24.2",
     "typescript": "^5.3.3"
   },
+  "overrides": {
+    "@hono/node-server": "^1.19.11",
+    "hono": "4.12.7"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/HaD0Yun/godot-mcp.git"
+    "url": "git+https://github.com/HaD0Yun/Gopeak-godot-mcp.git"
   },
-  "homepage": "https://github.com/HaD0Yun/godot-mcp#readme",
+  "homepage": "https://github.com/HaD0Yun/Gopeak-godot-mcp#readme",
   "bugs": {
-    "url": "https://github.com/HaD0Yun/godot-mcp/issues"
+    "url": "https://github.com/HaD0Yun/Gopeak-godot-mcp/issues"
   },
   "author": {
     "name": "HaD0Yun",