godot_analyze_script

Analyze GDScript files to detect 10 common pitfalls including API misuse, tight coupling, and signal issues for improved code quality.

Instructions

Analyse GDScript files for all 10 battle-tested pitfalls: Godot 3→4 API misuse, giant scripts, := on Variant, tight coupling, signal re-entrancy, autoload misuse, missing signal disconnect, _init() timing, Python-isms, and static func on autoloads.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`path`	Yes	Path to .gd file (e.g., res://scripts/player.gd)

Implementation Reference

src/tools/script-analysis.ts:377-424 (handler)

The async handler function that executes the godot_analyze_script tool logic - validates the path, reads the script file, calls analyseScript, and returns formatted warnings or success message

async (args) => {
  if (!ctx.projectDir) {
    return { content: [{ type: "text", text: formatError(projectNotFound()) }] };
  }

  const safeResult = resolveSafePath(ctx.projectDir, args.path);
  if ("error" in safeResult) {
    return { content: [{ type: "text", text: safeResult.error }] };
  }

  if (!existsSync(safeResult.path)) {
    return {
      content: [
        {
          type: "text",
          text: formatError({
            message: `Script not found: ${args.path}`,
            suggestion: "Check the path and try again.",
          }),
        },
      ],
    };
  }

  const content = readFileSync(safeResult.path, "utf-8");
  const warnings = analyseScript(content, safeResult.path, ctx.projectDir);

  if (warnings.length === 0) {
    return {
      content: [
        { type: "text", text: `No pitfalls detected in ${args.path}. Script looks clean.` },
      ],
    };
  }

  return {
    content: [
      {
        type: "text",
        text: JSON.stringify(
          { file: args.path, warningCount: warnings.length, warnings },
          null,
          2
        ),
      },
    ],
  };
}

src/tools/script-analysis.ts:371-376 (schema)

Zod schema definition for the godot_analyze_script tool input - defines 'path' parameter as a string with description

{
  path: z
    .string()
    .describe("Path to .gd file (e.g., res://scripts/player.gd)"),
},
{ readOnlyHint: true, idempotentHint: true, openWorldHint: false },

src/tools/script-analysis.ts:367-426 (registration)

Registers the godot_analyze_script tool with the MCP server via server.tool(), including name, description, schema, hints, and handler

export function registerScriptAnalysis(server: McpServer, ctx: ServerContext): void {
  server.tool(
    "godot_analyze_script",
    "Analyse GDScript files for all 10 battle-tested pitfalls: Godot 3→4 API misuse, giant scripts, := on Variant, tight coupling, signal re-entrancy, autoload misuse, missing signal disconnect, _init() timing, Python-isms, and static func on autoloads.",
    {
      path: z
        .string()
        .describe("Path to .gd file (e.g., res://scripts/player.gd)"),
    },
    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
    async (args) => {
      if (!ctx.projectDir) {
        return { content: [{ type: "text", text: formatError(projectNotFound()) }] };
      }

      const safeResult = resolveSafePath(ctx.projectDir, args.path);
      if ("error" in safeResult) {
        return { content: [{ type: "text", text: safeResult.error }] };
      }

      if (!existsSync(safeResult.path)) {
        return {
          content: [
            {
              type: "text",
              text: formatError({
                message: `Script not found: ${args.path}`,
                suggestion: "Check the path and try again.",
              }),
            },
          ],
        };
      }

      const content = readFileSync(safeResult.path, "utf-8");
      const warnings = analyseScript(content, safeResult.path, ctx.projectDir);

      if (warnings.length === 0) {
        return {
          content: [
            { type: "text", text: `No pitfalls detected in ${args.path}. Script looks clean.` },
          ],
        };
      }

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              { file: args.path, warningCount: warnings.length, warnings },
              null,
              2
            ),
          },
        ],
      };
    }
  );
}

src/tools/script-analysis.ts:82-365 (helper)

The analyseScript helper function containing all 10 pitfall detection patterns for GDScript analysis (Godot 3→4 API, giant scripts, variant type inference, tight coupling, signal re-entrancy, autoload misuse, missing signal disconnect, _init timing, Python-isms)

function analyseScript(
  content: string,
  filePath: string,
  projectDir: string
): ScriptWarning[] {
  const warnings: ScriptWarning[] = [];
  const lines = content.split("\n");

  // Pitfall 1: Godot 3→4 API detection
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    // Skip comments
    if (line.trim().startsWith("#")) continue;

    for (const pattern of GODOT3_PATTERNS) {
      if (pattern.pattern.test(line)) {
        warnings.push({
          pitfall: "godot3-api",
          severity: "warning",
          line: i + 1,
          message: pattern.message,
          suggestion: pattern.suggestion,
        });
      }
    }
  }

  // Pitfall 2: Giant script (>300 lines)
  if (lines.length > 300) {
    warnings.push({
      pitfall: "giant-script",
      severity: "warning",
      line: null,
      message: `Large script (${lines.length} lines).`,
      suggestion:
        "Consider splitting into smaller focused scripts or using composition. Target under 300 lines per script.",
    });
  }

  // Pitfall 3: := on Variant return type
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    if (line.trim().startsWith("#")) continue;

    // Detect := with Dictionary.get(), Array methods returning Variant, ternary
    if (line.match(/:=\s*.*\.get\s*\(/) || line.match(/:=\s*.*if\s+.*\s+else\s+/)) {
      warnings.push({
        pitfall: "variant-type-inference",
        severity: "warning",
        line: i + 1,
        message: ":= type inference on Variant return.",
        suggestion:
          "Use explicit type annotation or = instead of := to avoid parse errors. " +
          "Example: var value: Variant = dict.get(\"key\", null)",
      });
    }
  }

  // Pitfall 4: Tight coupling (excessive get_node/$ references)
  let distantNodeRefs = 0;
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    if (line.trim().startsWith("#")) continue;

    // Count get_node or $ with paths that go up (..) or are deeply nested
    const getNodeMatch = line.match(/get_node\s*\(\s*["']([^"']+)["']\s*\)/);
    const dollarMatch = line.match(/\$([A-Za-z0-9_/]+)/);

    const path = getNodeMatch?.[1] ?? dollarMatch?.[1];
    if (path && (path.includes("..") || path.split("/").length > 2)) {
      distantNodeRefs++;
    }
  }
  if (distantNodeRefs > 5) {
    warnings.push({
      pitfall: "tight-coupling",
      severity: "warning",
      line: null,
      message: `Tight coupling: ${distantNodeRefs} references to distant nodes.`,
      suggestion:
        "Consider using signals, groups, or dependency injection instead of direct node path references.",
    });
  }

  // Pitfall 5: Signal re-entrancy
  // Detect: property assignment, then emit_signal/emit on same indentation level
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    if (line.trim().startsWith("#")) continue;

    // Look for emit between state changes
    if (line.match(/\.\s*emit\s*\(/) || line.match(/emit_signal\s*\(/)) {
      // Check if there are state-modifying lines before AND after at same indent
      const indent = line.match(/^(\s*)/)?.[1]?.length ?? 0;
      let stateChangeBefore = false;
      let stateChangeAfter = false;

      // Look backwards for state change
      for (let j = i - 1; j >= Math.max(0, i - 10); j--) {
        const prev = lines[j];
        const prevIndent = prev.match(/^(\s*)/)?.[1]?.length ?? 0;
        if (prevIndent < indent && prev.trim().match(/^func\s/)) break;
        if (prevIndent === indent && prev.match(/\s*\w+\s*=(?!=)/)) {
          stateChangeBefore = true;
          break;
        }
      }

      // Look forwards for state change
      for (let j = i + 1; j < Math.min(lines.length, i + 10); j++) {
        const next = lines[j];
        const nextIndent = next.match(/^(\s*)/)?.[1]?.length ?? 0;
        if (nextIndent < indent && next.trim() !== "") break;
        if (nextIndent === indent && next.match(/\s*\w+\s*=(?!=)/)) {
          stateChangeAfter = true;
          break;
        }
      }

      if (stateChangeBefore && stateChangeAfter) {
        warnings.push({
          pitfall: "signal-re-entrancy",
          severity: "warning",
          line: i + 1,
          message: "Signal re-entrancy risk: signal emitted between state changes.",
          suggestion:
            "Connected handlers will execute synchronously before subsequent lines run. " +
            "Consider emitting signals at the end of state changes, or use call_deferred() for the emission.",
        });
      }
    }
  }

  // Pitfall 6: Autoload misuse - static func on autoloads
  // Check if this script is registered as an autoload
  const config = parseProjectGodot(projectDir);
  if (config) {
    const isAutoload = config.autoloads.some(
      (a) => filePath.endsWith(a.path.replace("res://", ""))
    );
    if (isAutoload) {
      for (let i = 0; i < lines.length; i++) {
        if (lines[i].match(/^static\s+func\s/)) {
          warnings.push({
            pitfall: "static-func-autoload",
            severity: "warning",
            line: i + 1,
            message: "static func on autoload script.",
            suggestion:
              "Godot 4 warns STATIC_CALLED_ON_INSTANCE when calling static methods on autoload instances. " +
              "Use regular func instead, or move static utilities to a non-autoload class.",
          });
        }
      }
    }

    // Check total autoload count
    if (config.autoloads.length > 5) {
      warnings.push({
        pitfall: "too-many-autoloads",
        severity: "warning",
        line: null,
        message: `${config.autoloads.length} autoloads detected.`,
        suggestion:
          "Autoloads are global singletons — only use for genuinely global systems (GameState, AudioManager, SaveSystem). " +
          "Consider using regular classes for utilities.",
      });
    }
  }

  // Pitfall 7: Missing signal disconnect
  const connectCalls: Array<{ line: number; signal: string }> = [];
  let hasExitTree = false;
  const disconnectSignals = new Set<string>();

  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    if (line.trim().startsWith("#")) continue;

    // Detect .connect() calls
    const connectMatch = line.match(/(\w+)\.connect\s*\(/);
    if (connectMatch) {
      connectCalls.push({ line: i + 1, signal: connectMatch[1] });
    }

    // Detect _exit_tree function
    if (line.match(/^func\s+_exit_tree\s*\(/)) {
      hasExitTree = true;
    }

    // Detect .disconnect() calls
    const disconnectMatch = line.match(/(\w+)\.disconnect\s*\(/);
    if (disconnectMatch) {
      disconnectSignals.add(disconnectMatch[1]);
    }
  }

  if (connectCalls.length > 0 && !hasExitTree) {
    warnings.push({
      pitfall: "missing-signal-disconnect",
      severity: "warning",
      line: connectCalls[0].line,
      message: "Signal connected without disconnect in _exit_tree().",
      suggestion:
        "This can cause errors when the listening node is freed but the signal source persists. " +
        "Add _exit_tree() and disconnect signals there.",
    });
  }

  // Pitfall 8: _init() timing - node tree access in _init
  let inInit = false;
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];

    if (line.match(/^func\s+_init\s*\(/)) {
      inInit = true;
      continue;
    }
    if (inInit && line.match(/^func\s+/) && !line.match(/^func\s+_init/)) {
      inInit = false;
      continue;
    }

    if (inInit) {
      if (
        line.match(/get_node\s*\(/) ||
        line.match(/\$[A-Za-z]/) ||
        line.match(/get_parent\s*\(/) ||
        line.match(/get_tree\s*\(/)
      ) {
        warnings.push({
          pitfall: "init-timing",
          severity: "warning",
          line: i + 1,
          message: "Node tree access in _init().",
          suggestion:
            "The node is not in the scene tree during _init(). " +
            "Use _ready() for node access, or _enter_tree() if you need the tree before children are ready.",
        });
      }
    }
  }

  // Pitfall 9: Python-isms
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    if (line.trim().startsWith("#")) continue;

    // List comprehension syntax
    if (line.match(/\[.+\s+for\s+\w+\s+in\s+/)) {
      warnings.push({
        pitfall: "python-ism",
        severity: "warning",
        line: i + 1,
        message: "Python-style list comprehension detected.",
        suggestion: "GDScript doesn't support list comprehensions. Use Array.map() or a for loop.",
      });
    }

    // Python imports
    if (line.match(/^import\s+\w+/) || line.match(/^from\s+\w+\s+import/)) {
      warnings.push({
        pitfall: "python-ism",
        severity: "warning",
        line: i + 1,
        message: "Python-style import detected.",
        suggestion: "GDScript uses preload() or load() for imports, not Python's import syntax.",
      });
    }

    // Python builtins
    if (line.match(/\blen\s*\(/) && !line.match(/\.\s*len\s*\(/)) {
      warnings.push({
        pitfall: "python-ism",
        severity: "warning",
        line: i + 1,
        message: "Python-style len() detected.",
        suggestion: "GDScript uses .size() for arrays/strings, not len().",
      });
    }
  }

  return warnings;
}

src/register-tools.ts:21-21 (registration)
Calls registerScriptAnalysis(server, ctx) to register the godot_analyze_script tool with the MCP server during initialization
```
registerScriptAnalysis(server, ctx);
```

godot-forge