godot-agent-loop CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

Godot Agent Loop (@beremaran/godot-agent-loop): a TypeScript MCP server (stdio transport) that lets agents author, run, observe, and verify Godot 4 games. Entry point src/index.ts, compiled to build/index.js. Godot 4.7 is both the compatibility floor and primary target.

Commands

npm run build          # tsc + metadata/adapter sync + scripts/build.js (copies GDScript into build/)
npm test               # unit tests (vitest)
npx vitest run tests/tool-registry.test.ts            # single unit test file
npx vitest run tests/tool-registry.test.ts -t "name"  # single test by name
npm run test:e2e       # retained full-path MCP E2E (builds first, needs Godot)
npm run build && npx vitest run --config vitest.e2e.config.ts tests/e2e/representative-path.test.ts  # single E2E file
npm run lint           # eslint + markdownlint; npm run lint:md:fix auto-fixes markdown
npm run check          # lint + build + retained unit suite; used by CI and release validation
npm run check:built    # lint + retained unit suite, assuming a fresh build
npm run check:fast     # lint + tsc --noEmit — what the Husky pre-commit hook runs (~seconds)
npm run inspector      # MCP Inspector against build/index.js

Godot binary resolution for E2E tests: GODOT_BIN (executable path) → godot4/godot on PATH → first godot* executable inside GODOT_PATH (a directory). Note: the MCP server itself treats GODOT_PATH as an executable path, not a directory — the E2E harness passes the binary explicitly.

Architecture

Tool pipeline (TypeScript side)

Every MCP tool flows through this chain:

• src/tool-definitions.ts — name + JSON schema for all tools.
• src/tool-manifest.ts — one entry per tool: domain, handler method, backend, action list, privilege flag. Typed as Record<ToolName, ...> so completeness is a compile-time fact.
• src/domain-tool-registries.ts — dispatches to the three handler classes in src/tool-handlers/: lifecycle (processes/editor), project (validation, imports, integrity, .NET, add-ons, exports), game (runtime interaction).
• src/tool-surface.ts — the advertised surface. Default is a lean 20-tool core set covering the author → validate → run → observe → interact → assert loop; GODOT_MCP_TOOL_SURFACE=full advertises the complete 64-tool catalog. The godot_catalog tool searches/describes the full catalog and godot_call dispatches a hidden tool by name either way. Size budgets (bytes/token/count) are constants here.