@npgamedev/godot-mcp-server 0.0.1 → 1.0.0

package/dist/shared/schemaCoercion.js

@@ -0,0 +1,173 @@
+/**
+ * Schema shaping & coercion — make agent / extension inputs validate
+ * against Zod. A pure leaf: depends only on zod, with no edge to the
+ * registration core, dispatch, or the error contract.
+ *
+ * Three jobs: (1) per-value coercion presets (coercedBoolean / jsonCoerce)
+ * that tool modules attach to individual params; (2) the blanket LLM
+ * string-coercion pass (addStringCoercion) applied to every Zod shape at
+ * registration; (3) raw-JSON-Schema → Zod conversion for extension tools.
+ */
+import { z } from "zod";
+// ── MCP string-coercion helpers ────────────────────────────────────
+/**
+ * Boolean schema that coerces string inputs ("true"→true, "false"→false).
+ * MCP clients may send all values as strings for dynamically-registered
+ * tools (added via tools/list_changed). Standard z.boolean() rejects
+ * strings; z.coerce.boolean() converts "false" to true (truthy string).
+ * This preprocess handles the "false" case correctly.
+ */
+export const coercedBoolean = () => z.preprocess((v) => (typeof v === "string" ? v.toLowerCase() === "true" || v === "1" : v), z.boolean());
+/**
+ * Preprocess for JSON-string coercion: parses stringified arrays/objects.
+ * Same root cause as coercedBoolean — MCP clients may serialize complex
+ * values as JSON strings rather than native JSON types.
+ */
+export const jsonCoerce = (v) => {
+    if (typeof v === "string") {
+        try {
+            return JSON.parse(v);
+        }
+        catch {
+            return v;
+        }
+    }
+    return v;
+};
+// ── LLM string coercion ────────────────────────────────────────────
+// LLM agents sometimes serialize complex params as JSON strings instead
+// of passing structured values (e.g. "[{...}]" instead of [{...}]).
+// This pre-validation pass tries JSON.parse on string values when the
+// schema expects array/object/number/boolean.
+export function coerceStringValue(val) {
+    if (typeof val !== "string")
+        return val;
+    // Fast-reject: strings that clearly aren't JSON-encoded values
+    const trimmed = val.trim();
+    if (trimmed.length === 0)
+        return val;
+    const first = trimmed[0];
+    if (first !== "[" &&
+        first !== "{" &&
+        first !== '"' &&
+        first !== "t" &&
+        first !== "f" &&
+        first !== "n" &&
+        !/^-?\d/.test(trimmed)) {
+        return val;
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return val;
+    }
+}
+/** Resolve the innermost Zod type name, unwrapping optional/nullable/default. */
+export function innerZodType(schema) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Zod v4 internal
+    let s = schema;
+    // Walk through wrappers: optional → ZodOptional._zod.def.innerType,
+    // nullable → ZodNullable._zod.def.innerType, default → ZodDefault._zod.def.innerType.
+    while (s?._zod?.def?.innerType) {
+        s = s._zod.def.innerType;
+    }
+    return s?._zod?.def?.type;
+}
+/**
+ * Wrap each top-level key in a Zod shape with z.preprocess() so that
+ * JSON-encoded strings are parsed before Zod validation. Skips params
+ * whose schema expects a string — a JSON-encoded string value passed
+ * to a string param should not be unwrapped.
+ */
+export function addStringCoercion(shape) {
+    const coerced = {};
+    for (const [key, schema] of Object.entries(shape)) {
+        const inner = innerZodType(schema);
+        // Skip schemas that are string-typed (would unwrap intended JSON strings),
+        // enum-typed (discrete values, not JSON), or already preprocessed (pipe —
+        // e.g. coercedBoolean() already handles its own string coercion).
+        if (inner === "string" || inner === "enum" || inner === "pipe") {
+            coerced[key] = schema;
+        }
+        else {
+            // Wrap with preprocess so JSON-encoded strings are parsed before Zod.
+            // z.preprocess() is a ZodPipe, not a ZodOptional — and the MCP SDK emits
+            // the JSON Schema with io:"input" (pipeStrategy), where the pipe's input
+            // side does NOT inherit the inner .optional(). That flips optional params
+            // to `required` in tools/list (e.g. an optional radius/max_nodes would be
+            // advertised as required). Re-apply .optional() so the wrapper stays
+            // optional on the input side. (undefined short-circuits the outer optional,
+            // so coercion and any inner default are unaffected for provided values.)
+            const wrapped = z.preprocess(coerceStringValue, schema);
+            coerced[key] = schema instanceof z.ZodOptional ? wrapped.optional() : wrapped;
+        }
+    }
+    return coerced;
+}
+// ── JSON Schema → Zod conversion ────────────────────────────────────
+/**
+ * Detect whether an inputSchema is raw JSON Schema (from extension
+ * commands) rather than a Zod shape. Heuristic: top-level "type" key
+ * with plain string value, OR "properties" key that is a plain object
+ * (not a Zod schema). Zod schemas have a `_zod` property; plain JSON
+ * Schema `properties` objects do not.
+ */
+export function isRawJsonSchema(schema) {
+    if (!schema || typeof schema !== "object")
+        return false;
+    const obj = schema;
+    if (typeof obj.type === "string")
+        return true;
+    if (typeof obj.properties === "object" && obj.properties !== null) {
+        // A Zod schema (used as a field named "properties") has _zod; a
+        // JSON Schema properties object is a plain dict of field descriptors.
+        return !obj.properties._zod;
+    }
+    return false;
+}
+/**
+ * Convert a raw JSON Schema object to a Zod shape compatible with the
+ * MCP SDK's registerTool. Handles the common types extension authors use.
+ */
+export function jsonSchemaToZodShape(schema) {
+    const properties = schema.properties;
+    if (!properties)
+        return {};
+    const required = new Set(schema.required ?? []);
+    const shape = {};
+    for (const [key, prop] of Object.entries(properties)) {
+        let zodType;
+        switch (prop.type) {
+            case "string":
+                if (Array.isArray(prop.enum) && prop.enum.length > 0) {
+                    zodType = z.enum(prop.enum);
+                }
+                else {
+                    zodType = z.string();
+                }
+                break;
+            case "number":
+            case "integer":
+                zodType = z.coerce.number();
+                break;
+            case "boolean":
+                zodType = coercedBoolean();
+                break;
+            case "array":
+                zodType = z.preprocess(jsonCoerce, z.array(z.any()));
+                break;
+            default:
+                zodType = z.any();
+                break;
+        }
+        if (typeof prop.description === "string") {
+            zodType = zodType.describe(prop.description);
+        }
+        if (!required.has(key)) {
+            zodType = zodType.optional();
+        }
+        shape[key] = zodType;
+    }
+    return shape;
+}

package/dist/shared/stableJson.js

@@ -0,0 +1,27 @@
+/**
+ * Stable serialization utility for deterministic JSON output.
+ */
+/**
+ * Stable JSON.stringify with sorted keys: identical inputs produce
+ * byte-identical strings.
+ *
+ * Where this earns prompt-cache hits is the re-sent schema/tools block —
+ * stable key order keeps that whole-request payload byte-identical across
+ * turns, so Anthropic's cache matches it. A per-call tool response is
+ * serialized exactly once into history, so sorting its keys buys no extra
+ * cache hit; it is retained there for output stability (a tool's response
+ * keys don't reorder between otherwise-identical calls).
+ */
+export function stableStringify(value) {
+    return JSON.stringify(value, sortedReplacer);
+}
+function sortedReplacer(_key, value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        const sorted = {};
+        for (const k of Object.keys(value).sort()) {
+            sorted[k] = value[k];
+        }
+        return sorted;
+    }
+    return value;
+}

package/dist/shared/types.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/version.js

@@ -0,0 +1,82 @@
+/**
+ * Version utilities — the server's own version (read from package.json) and the
+ * Godot version-gating helpers. {@link GodotVer} is the parsed `[major, minor]`
+ * tuple the tool-version gate compares against; the rest parse, compare, and
+ * bound-check engine versions for the registration-time and per-call gates, plus
+ * a semver severity compare for the auth-handshake version check.
+ *
+ * @module
+ */
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+// ── Server version (single source of truth: package.json) ───────────
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let cachedVersion = undefined;
+/** Read the server version from package.json. Cached after first call. */
+export function getServerVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    try {
+        // package.json lives at the package root — two levels up from this module's
+        // home (dist/shared/version.js when built; src/shared/version.ts under tsx).
+        const pkg = JSON.parse(readFileSync(join(__dirname, "..", "..", "package.json"), "utf-8"));
+        cachedVersion = pkg.version ?? "0.0.0";
+    }
+    catch {
+        cachedVersion = "0.0.0";
+    }
+    return cachedVersion;
+}
+/** Parse a "major.minor" or "major.minor.patch" string to a [major, minor] tuple. */
+export function parseGodotVer(v) {
+    const parts = v.split(".").map(Number);
+    return [parts[0] ?? 0, parts[1] ?? 0];
+}
+/** Compare two GodotVer tuples. Returns negative/0/positive like strcmp. */
+export function compareGodotVer(a, b) {
+    if (a[0] !== b[0])
+        return a[0] - b[0];
+    return a[1] - b[1];
+}
+/** Check whether a connected Godot version is >= the given minimum. */
+export function isVersionAtLeast(connected, min) {
+    return compareGodotVer(connected, parseGodotVer(min)) >= 0;
+}
+/** Check whether a connected Godot version is <= the given maximum. */
+export function isVersionAtMost(connected, max) {
+    return compareGodotVer(connected, parseGodotVer(max)) <= 0;
+}
+/** Check whether a connected Godot version falls within [min, max] bounds (each bound optional, inclusive). */
+export function isVersionCompatible(connected, min, max) {
+    if (min != null && !isVersionAtLeast(connected, min))
+        return false;
+    if (max != null && !isVersionAtMost(connected, max))
+        return false;
+    return true;
+}
+/**
+ * Compare two semver version strings.
+ *
+ * Returns:
+ *   "ok"      — versions match (all components equal)
+ *   "minor"   — same major, different minor or patch
+ *   "major"   — different major version
+ *   "unknown" — remote is undefined/empty (pre-handshake peer)
+ */
+export function compareVersions(local, remote) {
+    if (remote == null || remote === "")
+        return "unknown";
+    const localParts = local.split(".").map(Number);
+    const remoteParts = remote.split(".").map(Number);
+    if (localParts.length !== 3 || remoteParts.length !== 3)
+        return "unknown";
+    if (localParts.some((n) => !Number.isFinite(n)) || remoteParts.some((n) => !Number.isFinite(n))) {
+        return "unknown";
+    }
+    if (localParts[0] !== remoteParts[0])
+        return "major";
+    if (localParts[1] !== remoteParts[1] || localParts[2] !== remoteParts[2])
+        return "minor";
+    return "ok";
+}

package/dist/startup/cliArgs.js

@@ -0,0 +1,103 @@
+/**
+ * Hand-rolled CLI argument parser for the server bin (no dependency).
+ *
+ * Collects the recognised `--flag`s into a flat {@link CliArgs} struct and hands
+ * it to the port resolver — it does NO port validation or precedence itself (that
+ * is the resolver's job). The surface is deliberately tiny: explicit
+ * `--flag value` / `--flag=value` value flags, two boolean gates, no positionals,
+ * no bundling, no convenience forms. An unrecognised flag, a stray positional, or
+ * a value flag missing its value sets `error`, which the composition root turns
+ * into a fail-loud exit.
+ *
+ * @module
+ */
+// Value flags — maps the long name to the CliArgs field it populates.
+const VALUE_FLAGS = {
+    "--editor-port": "editorPort",
+    "--runtime-port": "runtimePort",
+    "--lsp-port": "lspPort",
+    "--lsp-host": "lspHost",
+};
+/**
+ * Parse the server's CLI arguments — pass `process.argv.slice(2)`.
+ *
+ * @param argv - the raw argument list, without the node binary and script path
+ * @returns the collected {@link CliArgs}; `error` is set on the first parse
+ *   problem, but scanning continues so `--help` is still detected when it follows
+ *   a bad flag
+ * @remarks Both `--flag value` and `--flag=value` forms are accepted for value
+ *   flags. A next token that begins with `--` is treated as the *next flag*, not
+ *   a value — so a value flag at the end of argv (or before another flag) is a
+ *   missing-value error rather than silently swallowing the following flag.
+ */
+export function parseCliArgs(argv) {
+    const args = { help: false, toolsCount: false, listEager: false };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (!token.startsWith("--")) {
+            recordError(args, `unexpected argument "${token}" (no positional arguments are accepted)`);
+            continue;
+        }
+        const eq = token.indexOf("=");
+        const name = eq === -1 ? token : token.slice(0, eq);
+        const inlineValue = eq === -1 ? undefined : token.slice(eq + 1);
+        if (name === "--help") {
+            args.help = true;
+            continue;
+        }
+        if (name === "--tools-count") {
+            args.toolsCount = true;
+            continue;
+        }
+        if (name === "--list-eager") {
+            args.listEager = true;
+            continue;
+        }
+        const field = VALUE_FLAGS[name];
+        if (field === undefined) {
+            recordError(args, `unknown flag "${name}"`);
+            continue;
+        }
+        let value = inlineValue;
+        if (value === undefined && i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+            value = argv[i + 1];
+            i++;
+        }
+        if (value === undefined || value === "") {
+            recordError(args, `missing value for "${name}"`);
+            continue;
+        }
+        args[field] = value;
+    }
+    return args;
+}
+// Keep only the first error — later tokens after a bad flag are symptoms, not the cause.
+function recordError(args, message) {
+    if (args.error === undefined)
+        args.error = message;
+}
+/** The `--help` text (printed to stdout). Kept in sync with {@link parseCliArgs}'s flag set. */
+export function formatHelp() {
+    return [
+        "godot-mcp-server — MCP bridge to the Godot 4.x editor",
+        "",
+        "Usage: godot-mcp-server [options]",
+        "",
+        "Port options (a flag overrides its env var, which overrides registry discovery):",
+        "  --editor-port <n>    Editor WebSocket port to dial (env: GODOT_MCP_EDITOR_PORT)",
+        "  --runtime-port <n>   Playtest-runtime WebSocket port to dial (env: GODOT_MCP_RUNTIME_PORT)",
+        "  --lsp-port <n>       GDScript LSP port to dial (env: GODOT_MCP_LSP_PORT)",
+        "  --lsp-host <h>       GDScript LSP host to dial (env: GODOT_MCP_LSP_HOST)",
+        "",
+        "Other options:",
+        "  --tools-count        Print the static tool-count summary and exit",
+        "  --list-eager         Print the eager+meta tool manifest (JSON) and exit",
+        "  --help               Show this help and exit",
+        "",
+        "These flags move the DIAL target only. The ports the editor/runtime BIND",
+        "(listen side) are configured toolkit-side — see the toolkit's",
+        "advanced-configuration docs. With no options the server discovers ports via",
+        "the shared project registry.",
+        "",
+    ].join("\n");
+}

package/dist/startup/configReload.js

@@ -0,0 +1,57 @@
+/**
+ * Live config reload — re-reads .mcp.json env vars and rebuilds the
+ * tool list without restarting the server process.
+ *
+ * Triggered by a WebSocket notification from the Godot plugin when the
+ * user changes settings in the editor UI.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Read .mcp.json from the project root and return the env vars
+ * for the godot-mcp-toolkit server entry.  Returns undefined on any failure
+ * (missing file, parse error, no matching server key).
+ */
+export function readMcpJsonEnv(projectPath) {
+    try {
+        const mcpJsonPath = join(projectPath, ".mcp.json");
+        const raw = readFileSync(mcpJsonPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        const servers = parsed?.mcpServers;
+        if (!servers)
+            return undefined;
+        // Find our server entry (mirrors mcp_json_sync.gd._find_server_key).
+        let serverEntry = servers["godot-mcp-toolkit"];
+        if (!serverEntry) {
+            for (const key of Object.keys(servers)) {
+                if (key.toLowerCase().includes("godot-mcp")) {
+                    serverEntry = servers[key];
+                    break;
+                }
+            }
+        }
+        if (!serverEntry?.env)
+            return undefined;
+        return serverEntry.env;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Apply new env vars to process.env.  Only touches GODOT_MCP_* keys
+ * to avoid overwriting unrelated environment.
+ */
+export function applyEnvUpdate(newEnv) {
+    const prefix = "GODOT_MCP_";
+    // Remove MCP vars that are no longer in .mcp.json.
+    for (const key of Object.keys(process.env)) {
+        if (key.startsWith(prefix) && !(key in newEnv)) {
+            delete process.env[key];
+        }
+    }
+    // Set / update vars from .mcp.json.
+    for (const [key, value] of Object.entries(newEnv)) {
+        process.env[key] = String(value);
+    }
+}

package/dist/startup/hooks.js

@@ -0,0 +1,89 @@
+export class HookPipeline {
+    hooks = [];
+    /** Register a hook. Hooks fire in registration order (FIFO). */
+    use(hook) {
+        this.hooks.push(hook);
+    }
+    /**
+     * Execute the hook chain around a tool handler.
+     * If any hook throws, the error is caught and logged — dispatch
+     * continues with the remaining chain so one misbehaving hook
+     * cannot break all tool calls.
+     */
+    async execute(req, handler) {
+        let chain = handler;
+        // Build chain from innermost (last hook) to outermost (first hook).
+        for (let i = this.hooks.length - 1; i >= 0; i--) {
+            const hook = this.hooks[i];
+            const next = chain;
+            chain = async () => {
+                try {
+                    return await hook(req, next);
+                }
+                catch (err) {
+                    process.stderr.write(`[godot-mcp] hook error: ${err.message}\n`);
+                    return next();
+                }
+            };
+        }
+        return chain();
+    }
+    get length() {
+        return this.hooks.length;
+    }
+}
+// ── Seed hooks ─────────────────────────────────────────────────────────
+/** Logging hook — writes tool name + duration to stderr. */
+export function loggingHook() {
+    return async (req, next) => {
+        const start = Date.now();
+        const result = await next();
+        const ms = Date.now() - start;
+        process.stderr.write(`[godot-mcp] tool=${req.name} duration=${ms}ms isError=${!!result.isError}\n`);
+        return result;
+    };
+}
+/**
+ * Rate-limit hook — rejects calls that exceed `maxPerWindow` within
+ * `windowMs`. Disabled when `maxPerWindow` is 0 (default).
+ */
+export function rateLimitHook(maxPerWindow = 0, windowMs = 60_000) {
+    if (maxPerWindow <= 0)
+        return undefined;
+    const timestamps = [];
+    return async (_req, next) => {
+        const now = Date.now();
+        while (timestamps.length > 0 && timestamps[0] <= now - windowMs) {
+            timestamps.shift();
+        }
+        if (timestamps.length >= maxPerWindow) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: `Rate limit exceeded (${maxPerWindow} calls per ${windowMs / 1000}s)`,
+                            code: "RATE_LIMITED",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        timestamps.push(now);
+        return next();
+    };
+}
+/** Create a pre-configured pipeline with seed hooks. */
+export function createHookPipeline() {
+    const pipeline = new HookPipeline();
+    // Logging is always on (writes to stderr, low cost).
+    pipeline.use(loggingHook());
+    // Rate limiting off by default; users can set GODOT_MCP_RATE_LIMIT.
+    const limit = Number(process.env.GODOT_MCP_RATE_LIMIT ?? "0");
+    const rlHook = rateLimitHook(limit);
+    if (rlHook)
+        pipeline.use(rlHook);
+    return pipeline;
+}

package/dist/startup/lifecycle.js

@@ -0,0 +1,22 @@
+/** Install SIGINT/SIGTERM graceful shutdown (await bridge.close → exit 0) and the
+ *  unhandledRejection / uncaughtException stderr loggers that keep the bridge alive. */
+export function installProcessHandlers(bridge) {
+    async function shutdown() {
+        try {
+            await bridge.close();
+        }
+        finally {
+            process.exit(0);
+        }
+    }
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    // Prevent unhandled errors from crashing the bridge process.
+    // Log to stderr for diagnostics; the bridge stays alive.
+    process.on("unhandledRejection", (reason) => {
+        process.stderr.write(`[godot-mcp] unhandledRejection: ${reason}\n`);
+    });
+    process.on("uncaughtException", (err) => {
+        process.stderr.write(`[godot-mcp] uncaughtException: ${err?.stack ?? err}\n`);
+    });
+}

package/dist/startup/portConfig.js

@@ -0,0 +1,127 @@
+import { lookupProject } from "../registry.js";
+// Matches the toolkit's default editor bind port and the historical fallback.
+const DEFAULT_EDITOR_PORT = "6550";
+/** A pin failed validation — the composition root turns this into stderr + exit 1. */
+export class PortConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PortConfigError";
+    }
+}
+/**
+ * Whether a raw pin string is a usable TCP port: all digits (no sign, decimal,
+ * or unit suffix) and in 1–65535. Port 0 ("any free port") is rejected — a pin
+ * must name the exact port both sides agree on.
+ */
+export function isValidPort(value) {
+    if (!/^\d+$/.test(value))
+        return false;
+    const port = parseInt(value, 10);
+    return port >= 1 && port <= 65535;
+}
+// Fail loud on a bad pin. `label` names the exact source the user typed
+// (`--editor-port` or GODOT_MCP_EDITOR_PORT) so the error is directly fixable.
+function requireValidPin(value, label) {
+    if (!isValidPort(value)) {
+        throw new PortConfigError(`${label} value "${value}" is not a valid port — expected an integer 1–65535`);
+    }
+}
+/**
+ * Resolve editor / runtime / LSP dial config from CLI flags, env, and the
+ * registry. The editor port is fully resolved (CLI > env > registry > `6550`);
+ * the runtime and LSP channels resolve a pin only (CLI > env, else `undefined` =
+ * discover lazily).
+ *
+ * @param cli - parsed CLI flags (the highest-precedence tier)
+ * @param projectPath - absolute project path used for registry discovery when
+ *   the editor channel has no pin
+ * @throws PortConfigError when an effective pin (the value precedence selected)
+ *   is not an integer 1–65535 — shadowed values are not validated
+ */
+export function resolvePortConfig(cli, projectPath) {
+    // Editor — the one channel dialed eagerly, so resolve to a concrete port.
+    let editorPort;
+    let editorPinned;
+    let editorSource;
+    const envEditorPort = process.env.GODOT_MCP_EDITOR_PORT;
+    if (cli.editorPort) {
+        requireValidPin(cli.editorPort, "--editor-port");
+        editorPort = cli.editorPort;
+        editorPinned = true;
+        editorSource = "cli";
+    }
+    else if (envEditorPort) {
+        requireValidPin(envEditorPort, "GODOT_MCP_EDITOR_PORT");
+        editorPort = envEditorPort;
+        editorPinned = true;
+        editorSource = "env";
+    }
+    else {
+        const entry = lookupProject(projectPath);
+        if (entry) {
+            editorPort = String(entry.port);
+            editorSource = "discovery";
+        }
+        else {
+            editorPort = DEFAULT_EDITOR_PORT;
+            editorSource = "default";
+        }
+        editorPinned = false;
+    }
+    // Runtime — pin only (CLI > env); undefined → runtimeConnection discovers lazily.
+    const envRuntimePort = process.env.GODOT_MCP_RUNTIME_PORT;
+    if (cli.runtimePort)
+        requireValidPin(cli.runtimePort, "--runtime-port");
+    else if (envRuntimePort)
+        requireValidPin(envRuntimePort, "GODOT_MCP_RUNTIME_PORT");
+    const runtimePort = cli.runtimePort ?? envRuntimePort;
+    const runtimeSource = cli.runtimePort ? "cli" : envRuntimePort ? "env" : "discovery";
+    // LSP — override only (CLI > env); undefined → lspClient discovers lazily.
+    const envLspPort = process.env.GODOT_MCP_LSP_PORT;
+    if (cli.lspPort)
+        requireValidPin(cli.lspPort, "--lsp-port");
+    else if (envLspPort)
+        requireValidPin(envLspPort, "GODOT_MCP_LSP_PORT");
+    const lspPort = cli.lspPort ?? envLspPort;
+    const lspHost = cli.lspHost ?? process.env.GODOT_MCP_LSP_HOST;
+    const lspSource = cli.lspPort ? "cli" : envLspPort ? "env" : "discovery";
+    return {
+        editorPort,
+        editorPinned,
+        editorSource,
+        runtimePort,
+        runtimeSource,
+        lspPort,
+        lspHost,
+        lspSource,
+    };
+}
+/**
+ * {@link resolvePortConfig} as a preflight gate: a {@link PortConfigError}
+ * becomes a precise stderr line + `process.exit(1)` (fail loud at startup, never
+ * an ERR_INVALID_URL crash at first dial). Anything else rethrows.
+ */
+export function resolvePortConfigOrExit(cli, projectPath) {
+    try {
+        return resolvePortConfig(cli, projectPath);
+    }
+    catch (err) {
+        if (err instanceof PortConfigError) {
+            process.stderr.write(`[godot-mcp] ${err.message}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+}
+/**
+ * Log each channel's resolved port + source to **stderr** — never stdout, which
+ * is the MCP transport (a stray write there reaches the LLM). Informational; the
+ * actionable desync error surfaces separately from the bridge. "auto" marks a
+ * channel with no pin (discovered per connect).
+ */
+export function logResolvedPortConfig(config) {
+    const runtime = config.runtimePort ?? "auto";
+    const lsp = config.lspPort ?? "auto";
+    process.stderr.write(`[godot-mcp] port config: editor=${config.editorPort} [${config.editorSource}], ` +
+        `runtime=${runtime} [${config.runtimeSource}], lsp=${lsp} [${config.lspSource}]\n`);
+}