Godot MCP

Instructions

Implementation Reference

• src/index.ts:896-912 (registration)

  Registers the 'get_uid' tool with its description and input schema in the ListTools response.
  name: 'get_uid', description: 'Get the UID for a specific file in a Godot project (for Godot 4.4+)', inputSchema: { type: 'object', properties: { projectPath: { type: 'string', description: 'Path to the Godot project directory', }, filePath: { type: 'string', description: 'Path to the file (relative to project) for which to get the UID', }, }, required: ['projectPath', 'filePath'], }, },
• src/index.ts:958-959 (registration)

  Registers the handler dispatch for 'get_uid' tool in the CallToolRequestSchema switch statement.
  case 'get_uid': return await this.handleGetUid(request.params.arguments);
• src/index.ts:1951-2055 (handler)

  Handler function that validates inputs, checks Godot version compatibility, and executes the underlying Godot script operation to retrieve the UID for a file in the project.
  private async handleGetUid(args: any) { // Normalize parameters to camelCase args = this.normalizeParameters(args); if (!args.projectPath || !args.filePath) { return this.createErrorResponse( 'Missing required parameters', ['Provide projectPath and filePath'] ); } if (!this.validatePath(args.projectPath) || !this.validatePath(args.filePath)) { return this.createErrorResponse( 'Invalid path', ['Provide valid paths without ".." or other potentially unsafe characters'] ); } try { // Ensure godotPath is set if (!this.godotPath) { await this.detectGodotPath(); if (!this.godotPath) { return this.createErrorResponse( 'Could not find a valid Godot executable path', [ 'Ensure Godot is installed correctly', 'Set GODOT_PATH environment variable to specify the correct path', ] ); } } // Check if the project directory exists and contains a project.godot file const projectFile = join(args.projectPath, 'project.godot'); if (!existsSync(projectFile)) { return this.createErrorResponse( `Not a valid Godot project: ${args.projectPath}`, [ 'Ensure the path points to a directory containing a project.godot file', 'Use list_projects to find valid Godot projects', ] ); } // Check if the file exists const filePath = join(args.projectPath, args.filePath); if (!existsSync(filePath)) { return this.createErrorResponse( `File does not exist: ${args.filePath}`, ['Ensure the file path is correct'] ); } // Get Godot version to check if UIDs are supported const { stdout: versionOutput } = await execAsync(`"${this.godotPath}" --version`); const version = versionOutput.trim(); if (!this.isGodot44OrLater(version)) { return this.createErrorResponse( `UIDs are only supported in Godot 4.4 or later. Current version: ${version}`, [ 'Upgrade to Godot 4.4 or later to use UIDs', 'Use resource paths instead of UIDs for this version of Godot', ] ); } // Prepare parameters for the operation (already in camelCase) const params = { filePath: args.filePath, }; // Execute the operation const { stdout, stderr } = await this.executeOperation('get_uid', params, args.projectPath); if (stderr && stderr.includes('Failed to')) { return this.createErrorResponse( `Failed to get UID: ${stderr}`, [ 'Check if the file is a valid Godot resource', 'Ensure the file path is correct', ] ); } return { content: [ { type: 'text', text: `UID for ${args.filePath}: ${stdout.trim()}`, }, ], }; } catch (error: any) { return this.createErrorResponse( `Failed to get UID: ${error?.message || 'Unknown error'}`, [ 'Ensure Godot is installed correctly', 'Check if the GODOT_PATH environment variable is set correctly', 'Verify the project path is accessible', ] ); } }
• src/index.ts:474-542 (helper)

  Helper method that executes Godot operations via headless Godot with the godot_operations.gd script, used by get_uid to run the 'get_uid' operation.
  private async executeOperation( operation: string, params: OperationParams, projectPath: string ): Promise<{ stdout: string; stderr: string }> { this.logDebug(`Executing operation: ${operation} in project: ${projectPath}`); this.logDebug(`Original operation params: ${JSON.stringify(params)}`); // Convert camelCase parameters to snake_case for Godot script const snakeCaseParams = this.convertCamelToSnakeCase(params); this.logDebug(`Converted snake_case params: ${JSON.stringify(snakeCaseParams)}`); // Ensure godotPath is set if (!this.godotPath) { await this.detectGodotPath(); if (!this.godotPath) { throw new Error('Could not find a valid Godot executable path'); } } try { // Serialize the snake_case parameters to a valid JSON string 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 isWindows = process.platform === 'win32'; const quotedParams = isWindows ? `\"${paramsJson.replace(/\"/g, '\\"')}\"` : `'${escapedParams}'`; // Add debug arguments if debug mode is enabled const debugArgs = GODOT_DEBUG_MODE ? ['--debug-godot'] : []; // Construct the command with the operation and JSON parameters const cmd = [ `"${this.godotPath}"`, '--headless', '--path', `"${projectPath}"`, '--script', `"${this.operationsScriptPath}"`, operation, quotedParams, // Pass the JSON string as a single argument ...debugArgs, ].join(' '); this.logDebug(`Command: ${cmd}`); const { stdout, stderr } = await execAsync(cmd); return { stdout, stderr }; } catch (error: unknown) { // If execAsync throws, it still contains stdout/stderr if (error instanceof Error && 'stdout' in error && 'stderr' in error) { const execError = error as Error & { stdout: string; stderr: string }; return { stdout: execError.stdout, stderr: execError.stderr, }; } throw error; } }
• src/index.ts:399-407 (helper)

  Helper function used by get_uid handler to check if the Godot version supports UIDs (4.4+).
  private isGodot44OrLater(version: string): boolean { const match = version.match(/^(\d+)\.(\d+)/); if (match) { const major = parseInt(match[1], 10); const minor = parseInt(match[2], 10); return major > 4 || (major === 4 && minor >= 4); } return false; }