better-godot-mcp: Instructions file for Codex

AGENTS.md - better-godot-mcp

Composite MCP Server for Godot Engine. TypeScript, Node.js >= 24, bun, ESM.

Build / Lint / Test Commands

bun install                 # Install dependencies
bun run build               # tsc --build && esbuild CLI bundle
bun run check               # Biome check + tsc --noEmit (CI command)
bun run check:fix           # Auto-fix Biome issues
bun run test                # vitest run (all tests)
bun run test:watch          # vitest in watch mode
bun run dev                 # tsx watch dev server

# Run a single test file
bun x vitest run tests/helpers/errors.test.ts

# Run a single test by name
bun x vitest run -t "test name pattern"

# Mise shortcuts
mise run setup              # Full dev environment setup
mise run lint               # bun run check
mise run test               # bun run test (vitest)
mise run fix                # bun run check:fix

Code Style

Formatting (Biome)

• Indent: 2 spaces
• Line width: 120
• Quotes: Single quotes
• Semicolons: As needed (omit when possible)
• Trailing commas: All (JS/TS), None (JSON)
• Arrow parens: Always (x) => ...
• Line endings: LF

Imports

1. Node.js builtins with node: prefix (import { join } from 'node:path')
2. External packages (@modelcontextprotocol/sdk, zod)
3. Internal modules (relative paths ./, ../)
4. Use import type for type-only imports (enforced by verbatimModuleSyntax)
5. Always use .js extension in import paths (ESM/NodeNext requirement)

import { execSync } from 'node:child_process'
import { Server } from '@modelcontextprotocol/sdk/server/index.js'
import type { GodotConfig } from './godot/types.js'
import { registerTools } from './tools/registry.js'

TypeScript

• strict: true, verbatimModuleSyntax: true, isolatedModules: true
• Target: ES2024, Module: NodeNext
• Schema validation: Zod v4

Naming Conventions

Element	Convention	Example
Functions/variables	camelCase	detectGodot(), envPath
Module constants	UPPER_SNAKE_CASE	SERVER_NAME, DEFAULT_TIMEOUT_MS
Interfaces/Types	PascalCase	GodotConfig, DetectionResult
Classes	PascalCase	GodotMCPError
Files/directories	kebab-case	scene-parser.ts, composite/
Tool names/params	snake_case	input_map, project_path