Minimal Godot MCP

Instructions

Implementation Reference

• src/tools/get-diagnostics.ts:16-51 (handler)

  Core handler function that validates input, checks LSP connection status, and fetches diagnostics for the specified GDScript file using DiagnosticsManager.
  export async function getDiagnostics( diagnosticsManager: DiagnosticsManager, isConnected: boolean, input: GetDiagnosticsInput ): Promise<GetDiagnosticsOutput> { const { file_path } = input; // Validate input if (!file_path) { throw new Error('file_path is required. Use scan_workspace_diagnostics for workspace-wide checks.'); } if (!file_path.endsWith('.gd')) { throw new Error('file_path must be a .gd file'); } // Check if LSP is connected if (!isConnected) { return { diagnostics: {}, error: `Godot LSP is not running. Please ask the user to start Godot with their project: CLI: godot --editor --path /path/to/project GUI: Open the project in Godot Editor The Language Server Protocol must be enabled (default: ON) in: Project → Project Settings → Network → Language Server Once Godot is running, diagnostics will be available automatically.`, }; } // Get diagnostics for specific file const fileDiagnostics = await diagnosticsManager.getFileDiagnostics(file_path); return { diagnostics: { [file_path]: fileDiagnostics } }; }
• src/tools/get-diagnostics.ts:56-70 (registration)

  MCP tool registration including name, description, and input schema definition.
  export const getDiagnosticsTool = { name: 'get_diagnostics', description: 'Retrieve errors, warnings, and diagnostic messages for a GDScript (.gd) file from the Godot Language Server. Returns syntax errors, type errors, and code quality issues. Fast operation (<1s). Use this to check individual .gd files for problems. For workspace-wide scanning, use scan_workspace_diagnostics instead.', inputSchema: { type: 'object', properties: { file_path: { type: 'string', description: 'Absolute path to the GDScript (.gd) file to analyze for errors, warnings, and issues.', }, }, required: ['file_path'], }, };
• src/tools/get-diagnostics.ts:4-11 (schema)

  TypeScript interfaces defining input and output structures for the getDiagnostics tool.
  export interface GetDiagnosticsInput { file_path?: string; } export interface GetDiagnosticsOutput { diagnostics: Record<string, Diagnostic[]>; error?: string; }
• src/index.ts:70-82 (handler)

  MCP server request handler dispatch for 'get_diagnostics' tool call, invoking the core handler and formatting response.
  if (name === 'get_diagnostics') { const input = args as unknown as GetDiagnosticsInput; const result = await getDiagnostics(diagnosticsManager, isConnected, input); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; }
• src/diagnostics-manager.ts:38-54 (helper)

  Helper method in DiagnosticsManager that handles file-specific diagnostics retrieval by validating path, opening file in LSP, and returning cached diagnostics.
  async getFileDiagnostics(filePath: string): Promise<Diagnostic[]> { if (!this.workspacePath) { throw new Error('Workspace path not set. Ensure Godot is running with a project open.'); } // Validate path is within workspace to prevent path traversal const normalizedPath = resolve(filePath); const relativePath = relative(this.workspacePath, normalizedPath); if (relativePath.startsWith('..') || !relativePath) { throw new Error(`File path must be within workspace: ${filePath}`); } const content = await readFile(normalizedPath, 'utf-8'); await this.lspClient.openFile(normalizedPath, content); return this.lspClient.getDiagnostics(normalizedPath); }