breakpoint-mcp 1.0.0

package/dist/tools/backend.js

@@ -0,0 +1,532 @@
+import { z } from "zod";
+import { gate } from "../confirm.js";
+/**
+ * Group M (second half) — Backend-SDK integration scaffolding (`backend_*`,
+ * `*_scaffold`).
+ *
+ * Principle: host nothing, scaffold everything. Running a leaderboard DB, a
+ * save-store or an auth service is a hosted service, outside the scope of editor
+ * control — but generating the integration against the game's *installed* SDK is
+ * in scope.
+ *
+ *   Detection (read-only, over the editor bridge):
+ *     - backend_detect       — which of the known SDKs (SilentWolf / Nakama /
+ *                              PlayFab / Photon) are installed in this project,
+ *                              and how they were found (autoload / addon / class)
+ *
+ *   Codegen (writes a `res://…gd`, elicitation-gated — the mp_* codegen model):
+ *     - backend_configure    — an SDK config/bootstrap autoload script
+ *     - leaderboard_scaffold — submit/fetch leaderboard helpers
+ *     - cloudsave_scaffold   — save/load cloud-save helpers
+ *     - auth_scaffold        — login/register/logout helpers
+ *
+ * Every codegen tool is **feature-detected two ways, and never a dead call**:
+ *   1. If the requested SDK provides no such API (e.g. Photon has no
+ *      leaderboard/cloud-save/auth — it is realtime transport), it degrades to
+ *      `status:"unsupported_feature"` and writes nothing.
+ *   2. If the SDK is not installed in the project, it degrades to
+ *      `status:"sdk_missing"` ("install <SDK> first") and writes nothing.
+ * Only when the SDK is both capable and installed is code generated. The
+ * GDScript is built HOST-side (so the templates are unit-tested) and written by
+ * the editor's FileAccess through the shared `mp.write_script` bridge method.
+ * We host nothing: no leaderboard DB, no save storage, no auth service — bring
+ * your own backend, we wire it for you.
+ */
+// ---- result envelopes (mirror tools/netcode.ts) --------------------------
+function ok(obj) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(obj, null, 2) }],
+        structuredContent: obj,
+    };
+}
+function fail(err) {
+    const be = err;
+    const code = be?.code ?? "error";
+    const message = be?.message ?? String(err);
+    return {
+        isError: true,
+        content: [{ type: "text", text: `Backend scaffold error [${code}]: ${message}` }],
+    };
+}
+// ---- the known SDKs + their capability matrix ----------------------------
+// Capabilities are intrinsic to each SDK (independent of whether it is
+// installed): Photon is realtime multiplayer/relay, so it has no
+// leaderboard / cloud-save / auth surface to scaffold against.
+export const BACKEND_SDKS = ["silentwolf", "nakama", "playfab", "photon"];
+export const SDK_INFO = {
+    silentwolf: { label: "SilentWolf", docs: "https://silentwolf.com", auth: true, leaderboard: true, cloudsave: true },
+    nakama: { label: "Nakama", docs: "https://heroiclabs.com/docs/nakama/", auth: true, leaderboard: true, cloudsave: true },
+    playfab: { label: "PlayFab", docs: "https://learn.microsoft.com/gaming/playfab/", auth: true, leaderboard: true, cloudsave: true },
+    photon: { label: "Photon", docs: "https://www.photonengine.com/", auth: false, leaderboard: false, cloudsave: false },
+};
+/** Does this SDK provide the given feature? `configure` is universal. Pure. */
+export function hasCapability(sdk, feature) {
+    if (feature === "configure")
+        return true;
+    const info = SDK_INFO[sdk];
+    return feature === "auth" ? info.auth : feature === "leaderboard" ? info.leaderboard : info.cloudsave;
+}
+/** SDK labels that provide `feature` (for the unsupported_feature message). Pure. */
+export function supportersOf(feature) {
+    return BACKEND_SDKS.filter((s) => hasCapability(s, feature)).map((s) => SDK_INFO[s].label);
+}
+// ------------------------------------------------------------- codegen ----
+// Pure, exported for unit tests. GDScript is tab-indented (matches operations.gd
+// and tools/netcode.ts); no line is ever space-indented.
+const GEN_HEADER = "## Generated by Breakpoint MCP";
+/** Join GDScript lines (each carries its own leading tabs) + a trailing newline. */
+function gd(lines) {
+    return lines.join("\n") + "\n";
+}
+/** A provided value, or a clearly-marked placeholder to fill in. */
+function ph(value, placeholder) {
+    return value && value.length > 0 ? value : placeholder;
+}
+export function buildConfigScript(sdk, o = {}) {
+    switch (sdk) {
+        case "silentwolf":
+            return gd([
+                "extends Node",
+                `${GEN_HEADER} — backend_configure (SilentWolf)`,
+                "## Register this script as an autoload so configure() runs at startup.",
+                "## Requires the SilentWolf addon (res://addons/silent_wolf). Docs: https://silentwolf.com",
+                "",
+                `const API_KEY := "${ph(o.apiKey, "YOUR_SILENTWOLF_API_KEY")}"`,
+                `const GAME_ID := "${ph(o.gameId, "YOUR_SILENTWOLF_GAME_ID")}"`,
+                "",
+                "func _ready() -> void:",
+                "\tconfigure()",
+                "",
+                "func configure() -> void:",
+                "\tSilentWolf.configure({",
+                "\t\t\"api_key\": API_KEY,",
+                "\t\t\"game_id\": GAME_ID,",
+                "\t\t\"log_level\": 1,",
+                "\t})",
+            ]);
+        case "nakama":
+            return gd([
+                "extends Node",
+                `${GEN_HEADER} — backend_configure (Nakama)`,
+                "## Register as an autoload so `client` is globally available.",
+                "## Requires the Nakama addon (res://addons/com.heroiclabs.nakama). Docs: https://heroiclabs.com/docs/nakama/",
+                "",
+                "const SCHEME := \"http\"",
+                `const HOST := "${ph(o.host, "127.0.0.1")}"`,
+                `const PORT := ${o.port ?? 7350}`,
+                `const SERVER_KEY := "${ph(o.serverKey, "defaultkey")}"`,
+                "",
+                "var client  # NakamaClient",
+                "",
+                "func _ready() -> void:",
+                "\tconfigure()",
+                "",
+                "func configure() -> void:",
+                "\tclient = Nakama.create_client(SERVER_KEY, HOST, PORT, SCHEME)",
+            ]);
+        case "playfab":
+            return gd([
+                "extends Node",
+                `${GEN_HEADER} — backend_configure (PlayFab)`,
+                "## Register as an autoload. Requires the godot-playfab addon.",
+                "## Docs: https://learn.microsoft.com/gaming/playfab/",
+                "",
+                `const TITLE_ID := "${ph(o.titleId, "YOUR_PLAYFAB_TITLE_ID")}"`,
+                "",
+                "func _ready() -> void:",
+                "\tconfigure()",
+                "",
+                "func configure() -> void:",
+                "\tPlayFabManager.settings.title_id = TITLE_ID",
+            ]);
+        case "photon":
+            return gd([
+                "extends Node",
+                `${GEN_HEADER} — backend_configure (Photon)`,
+                "## Photon is realtime multiplayer (matchmaking / relay). Set your App ID + region.",
+                "## Requires a Photon Godot integration. Docs: https://www.photonengine.com/",
+                "",
+                `const APP_ID := "${ph(o.appId, "YOUR_PHOTON_APP_ID")}"`,
+                `const REGION := "${ph(o.region, "us")}"`,
+                "",
+                "func _ready() -> void:",
+                "\tconfigure()",
+                "",
+                "func configure() -> void:",
+                "\t# Wire APP_ID / REGION into your Photon client's connect settings.",
+                "\tprint(\"Photon configured: app=%s region=%s\" % [APP_ID, REGION])",
+            ]);
+    }
+}
+export function buildAuthScript(sdk) {
+    switch (sdk) {
+        case "silentwolf":
+            return gd([
+                "extends Node",
+                `${GEN_HEADER} — auth_scaffold (SilentWolf)`,
+                "## Requires the SilentWolf addon + a configured SilentWolf (see backend_configure).",
+                "",
+                "signal registered(success: bool, error: String)",
+                "signal logged_in(success: bool, error: String)",
+                "",
+                "func register(username: String, email: String, password: String, confirm_password: String) -> void:",
+                "\tvar res = await SilentWolf.Auth.register_player(username, email, password, confirm_password).sw_registration_complete",
+                "\tregistered.emit(bool(res.get(\"success\", false)), str(res.get(\"error\", \"\")))",
+                "",
+                "func login(username: String, password: String, remember: bool = false) -> void:",
+                "\tvar res = await SilentWolf.Auth.login_player(username, password, remember).sw_login_complete",
+                "\tlogged_in.emit(bool(res.get(\"success\", false)), str(res.get(\"error\", \"\")))",
+                "",
+                "func logout() -> void:",
+                "\tSilentWolf.Auth.logout_player()",
+            ]);
+        case "nakama":
+            return gd([
+                "extends Node",
+                `${GEN_HEADER} — auth_scaffold (Nakama)`,
+                "## Requires a Nakama client (see backend_configure). Uses authenticate_email_async.",
+                "",
+                "signal authenticated(success: bool, error: String)",
+                "",
+                "var session  # NakamaSession",
+                "",
+                "func authenticate_email(client, email: String, password: String, create: bool = true) -> void:",
+                "\tsession = await client.authenticate_email_async(email, password, null, create)",
+                "\tif session.is_exception():",
+                "\t\tauthenticated.emit(false, str(session.get_exception().message))",
+                "\telse:",
+                "\t\tauthenticated.emit(true, \"\")",
+            ]);
+        case "playfab":
+            return gd([
+                "extends Node",
+                `${GEN_HEADER} — auth_scaffold (PlayFab)`,
+                "## Requires the godot-playfab addon + a configured title (see backend_configure).",
+                "",
+                "func login_with_email(email: String, password: String) -> void:",
+                "\tvar req := PlayFabManager.client.LoginWithEmailAddress(email, password)",
+                "\treq.connect(\"result\", _on_login_result)",
+                "\treq.connect(\"error\", _on_login_error)",
+                "",
+                "func register(email: String, password: String, username: String) -> void:",
+                "\tvar req := PlayFabManager.client.RegisterPlayFabUser(email, password, username)",
+                "\treq.connect(\"result\", _on_login_result)",
+                "\treq.connect(\"error\", _on_login_error)",
+                "",
+                "func _on_login_result(result) -> void:",
+                "\tprint(\"PlayFab login OK: \", result)",
+                "",
+                "func _on_login_error(error) -> void:",
+                "\tpush_error(\"PlayFab login failed: %s\" % error)",
+            ]);
+        case "photon":
+            // Guarded by hasCapability before we ever get here; keep the switch total.
+            throw new Error("Photon does not provide an auth API");
+    }
+}
+export function buildLeaderboardScript(sdk, opts = { leaderboard: "main" }) {
+    const name = opts.leaderboard;
+    switch (sdk) {
+        case "silentwolf":
+            return gd([
+                "extends Node",
+                `${GEN_HEADER} — leaderboard_scaffold (SilentWolf) — board "${name}"`,
+                "## Requires the SilentWolf addon + a configured SilentWolf (see backend_configure).",
+                "",
+                `const LEADERBOARD := "${name}"`,
+                "",
+                "func submit_score(player_name: String, score: int) -> void:",
+                "\tawait SilentWolf.Scores.save_score(player_name, score, LEADERBOARD).sw_save_score_complete",
+                "",
+                "func fetch_top(count: int = 10) -> Array:",
+                "\tvar res = await SilentWolf.Scores.get_scores(count, LEADERBOARD).sw_get_scores_complete",
+                "\treturn res.get(\"scores\", [])",
+            ]);
+        case "nakama":
+            return gd([
+                "extends Node",
+                `${GEN_HEADER} — leaderboard_scaffold (Nakama) — id "${name}"`,
+                "## Requires a Nakama client + session (see backend_configure / auth_scaffold).",
+                "",
+                `const LEADERBOARD_ID := "${name}"`,
+                "",
+                "func submit_score(client, session, score: int) -> void:",
+                "\tawait client.write_leaderboard_record_async(session, LEADERBOARD_ID, score)",
+                "",
+                "func fetch_top(client, session, count: int = 10) -> Array:",
+                "\tvar records = await client.list_leaderboard_records_async(session, LEADERBOARD_ID, [], count)",
+                "\treturn records.records",
+            ]);
+        case "playfab":
+            return gd([
+                "extends Node",
+                `${GEN_HEADER} — leaderboard_scaffold (PlayFab) — statistic "${name}"`,
+                "## Requires the godot-playfab addon + a configured title (see backend_configure).",
+                "",
+                `const STATISTIC := "${name}"`,
+                "",
+                "func submit_score(value: int) -> void:",
+                "\tPlayFabManager.client.UpdatePlayerStatistics([{ \"StatisticName\": STATISTIC, \"Value\": value }])",
+                "",
+                "func fetch_top(count: int = 10) -> void:",
+                "\tvar req := PlayFabManager.client.GetLeaderboard(STATISTIC, 0, count)",
+                "\treq.connect(\"result\", _on_leaderboard)",
+                "",
+                "func _on_leaderboard(result) -> void:",
+                "\tprint(\"PlayFab leaderboard: \", result)",
+            ]);
+        case "photon":
+            throw new Error("Photon does not provide a leaderboard API");
+    }
+}
+export function buildCloudSaveScript(sdk) {
+    switch (sdk) {
+        case "silentwolf":
+            return gd([
+                "extends Node",
+                `${GEN_HEADER} — cloudsave_scaffold (SilentWolf)`,
+                "## Requires the SilentWolf addon + a configured SilentWolf (see backend_configure).",
+                "",
+                "func save_data(player_name: String, data: Dictionary) -> void:",
+                "\tawait SilentWolf.Players.save_player_data(player_name, data).sw_save_player_data_complete",
+                "",
+                "func load_data(player_name: String) -> Dictionary:",
+                "\tvar res = await SilentWolf.Players.get_player_data(player_name).sw_get_player_data_complete",
+                "\treturn res.get(\"player_data\", {})",
+            ]);
+        case "nakama":
+            return gd([
+                "extends Node",
+                `${GEN_HEADER} — cloudsave_scaffold (Nakama)`,
+                "## Requires a Nakama client + session (see backend_configure / auth_scaffold).",
+                "",
+                "const COLLECTION := \"savegame\"",
+                "",
+                "func save_data(client, session, key: String, data: Dictionary) -> void:",
+                "\tvar write := NakamaWriteStorageObject.new(COLLECTION, key, 1, 1, JSON.stringify(data), \"\")",
+                "\tawait client.write_storage_objects_async(session, [write])",
+                "",
+                "func load_data(client, session, key: String) -> Dictionary:",
+                "\tvar ids := [NakamaStorageObjectId.new(COLLECTION, key, session.user_id)]",
+                "\tvar objects = await client.read_storage_objects_async(session, ids)",
+                "\tif objects.objects.size() == 0:",
+                "\t\treturn {}",
+                "\treturn JSON.parse_string(objects.objects[0].value)",
+            ]);
+        case "playfab":
+            return gd([
+                "extends Node",
+                `${GEN_HEADER} — cloudsave_scaffold (PlayFab)`,
+                "## Requires the godot-playfab addon + a configured title (see backend_configure).",
+                "",
+                "func save_data(data: Dictionary) -> void:",
+                "\tPlayFabManager.client.UpdateUserData(data)",
+                "",
+                "func load_data() -> void:",
+                "\tvar req := PlayFabManager.client.GetUserData([])",
+                "\treq.connect(\"result\", _on_user_data)",
+                "",
+                "func _on_user_data(result) -> void:",
+                "\tprint(\"PlayFab user data: \", result)",
+            ]);
+        case "photon":
+            throw new Error("Photon does not provide a cloud-save API");
+    }
+}
+// ------------------------------------------------------------- registration ----
+export function registerBackendTools(server, bridge, _config) {
+    const call = async (method, params = {}) => bridge.request(method, params);
+    async function detect() {
+        const r = (await call("backend.detect"));
+        return { backends: r.backends ?? [], detected: r.detected ?? [] };
+    }
+    async function writeScript(toPath, content, overwrite) {
+        return (await call("mp.write_script", { to_path: toPath, content, overwrite }));
+    }
+    /**
+     * The shared scaffolder for the four codegen tools. Two feature-detect gates
+     * before anything is written: (1) does this SDK provide the feature at all,
+     * (2) is it installed in the project. Either degrades cleanly (nothing
+     * written, not an error); only a capable + installed SDK reaches the writer.
+     */
+    async function runScaffold(opts) {
+        const info = SDK_INFO[opts.sdk];
+        if (!opts.toPath.startsWith("res://") || !opts.toPath.endsWith(".gd")) {
+            return fail({ code: "bad_params", message: "'to_path' must be a res:// .gd path" });
+        }
+        // (1) capability — intrinsic to the SDK, no bridge needed.
+        if (!hasCapability(opts.sdk, opts.feature)) {
+            return ok({
+                status: "unsupported_feature",
+                sdk: opts.sdk,
+                kind: opts.kind,
+                path: null,
+                message: `${info.label} does not provide a ${opts.feature} API — it is realtime transport only. Supported by: ${supportersOf(opts.feature).join(", ")}.`,
+            });
+        }
+        // (2) installed? — ask the editor which SDKs are present.
+        let det;
+        try {
+            det = await detect();
+        }
+        catch (err) {
+            return fail(err);
+        }
+        if (!det.detected.includes(opts.sdk)) {
+            return ok({
+                status: "sdk_missing",
+                sdk: opts.sdk,
+                kind: opts.kind,
+                path: null,
+                message: `The ${info.label} SDK is not installed in this project — install it first (${info.docs}), then re-run. Nothing was written.`,
+            });
+        }
+        // Capable + installed → generate. Writing a .gd is destructive → gated.
+        const blocked = await gate(server, opts.confirm, `Write ${opts.kind} scaffold (${info.label}) to ${opts.toPath}`);
+        if (blocked)
+            return blocked;
+        try {
+            const content = opts.build();
+            const r = await writeScript(opts.toPath, content, opts.overwrite);
+            return ok({
+                status: String(r.status ?? "written"),
+                sdk: opts.sdk,
+                kind: opts.kind,
+                path: r.path ?? opts.toPath,
+                bytes: r.bytes ?? content.length,
+                created: r.created ?? true,
+                message: `Wrote a ${opts.kind} scaffold for ${info.label} to ${opts.toPath}.`,
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    }
+    // ---------------------------------------------------------- backend_detect ----
+    server.registerTool("backend_detect", {
+        title: "Detect installed backend SDKs",
+        description: "Report which of the known game-backend SDKs (SilentWolf, Nakama, PlayFab, Photon) are installed in this " +
+            "project and how each was found (an enabled autoload, an addon directory under res://addons, or a global " +
+            "class_name). Read-only — nothing is written. Use it before backend_configure / *_scaffold to see what you " +
+            "can generate against.",
+        inputSchema: {
+            sdk: z.enum(BACKEND_SDKS).optional().describe("Focus the report on a single SDK (default: report all four)"),
+        },
+    }, async ({ sdk }) => {
+        try {
+            const det = await detect();
+            const backends = sdk ? det.backends.filter((b) => b.sdk === sdk) : det.backends;
+            const detected = sdk ? det.detected.filter((s) => s === sdk) : det.detected;
+            const message = detected.length
+                ? `Detected: ${detected.map((s) => SDK_INFO[s]?.label ?? s).join(", ")}.`
+                : "No supported backend SDK detected. Install SilentWolf, Nakama, PlayFab or Photon to scaffold against it.";
+            return ok({ detected, backends, message });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    // ------------------------------------------------------- backend_configure ----
+    server.registerTool("backend_configure", {
+        title: "Scaffold a backend SDK config",
+        description: "Generate a config/bootstrap GDScript for a game-backend SDK (SilentWolf / Nakama / PlayFab / Photon): a Node " +
+            "whose configure() wires the API key / game id / host / title id from constants you fill in. Register it as an " +
+            "autoload so it runs at startup. FEATURE-DETECTED: if the SDK is not installed, degrades to a clear " +
+            "'install <SDK> first' result and writes nothing. DESTRUCTIVE (writes a .gd file) — gated by confirmation.",
+        inputSchema: {
+            sdk: z.enum(BACKEND_SDKS).describe("Which backend SDK to configure"),
+            to_path: z.string().optional().describe("Destination res:// .gd path (default res://backend/<sdk>_config.gd)"),
+            api_key: z.string().optional().describe("SilentWolf API key baked into the script"),
+            game_id: z.string().optional().describe("SilentWolf game id"),
+            title_id: z.string().optional().describe("PlayFab title id"),
+            app_id: z.string().optional().describe("Photon app id"),
+            host: z.string().optional().describe("Nakama host (default 127.0.0.1)"),
+            port: z.number().int().positive().optional().describe("Nakama port (default 7350)"),
+            server_key: z.string().optional().describe("Nakama server key (default defaultkey)"),
+            region: z.string().optional().describe("Photon region (default us)"),
+            overwrite: z.boolean().optional().describe("Overwrite if the file already exists (default false)"),
+            confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
+        },
+    }, async ({ sdk, to_path, api_key, game_id, title_id, app_id, host, port, server_key, region, overwrite, confirm }) => {
+        return runScaffold({
+            sdk,
+            feature: "configure",
+            kind: "config",
+            toPath: to_path ?? `res://backend/${sdk}_config.gd`,
+            overwrite: overwrite ?? false,
+            confirm,
+            build: () => buildConfigScript(sdk, { apiKey: api_key, gameId: game_id, titleId: title_id, appId: app_id, host, port, serverKey: server_key, region }),
+        });
+    });
+    // ----------------------------------------------------- leaderboard_scaffold ----
+    server.registerTool("leaderboard_scaffold", {
+        title: "Scaffold leaderboard integration",
+        description: "Generate submit/fetch leaderboard helpers against an installed backend SDK. FEATURE-DETECTED both ways: if the " +
+            "SDK provides no leaderboard API (Photon is realtime transport), degrades to 'unsupported_feature'; if the SDK " +
+            "is not installed, degrades to 'install <SDK> first'. Neither writes anything. DESTRUCTIVE (writes a .gd) — gated.",
+        inputSchema: {
+            sdk: z.enum(BACKEND_SDKS).describe("Which backend SDK to target"),
+            to_path: z.string().optional().describe("Destination res:// .gd path (default res://backend/leaderboard.gd)"),
+            leaderboard_name: z.string().optional().describe("Leaderboard id / statistic name baked into the script (default 'main')"),
+            overwrite: z.boolean().optional().describe("Overwrite if the file already exists (default false)"),
+            confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
+        },
+    }, async ({ sdk, to_path, leaderboard_name, overwrite, confirm }) => {
+        return runScaffold({
+            sdk,
+            feature: "leaderboard",
+            kind: "leaderboard",
+            toPath: to_path ?? "res://backend/leaderboard.gd",
+            overwrite: overwrite ?? false,
+            confirm,
+            build: () => buildLeaderboardScript(sdk, { leaderboard: leaderboard_name ?? "main" }),
+        });
+    });
+    // ------------------------------------------------------- cloudsave_scaffold ----
+    server.registerTool("cloudsave_scaffold", {
+        title: "Scaffold cloud-save integration",
+        description: "Generate save/load cloud-save helpers against an installed backend SDK. FEATURE-DETECTED both ways: if the SDK " +
+            "provides no cloud-save API (Photon is realtime transport), degrades to 'unsupported_feature'; if the SDK is not " +
+            "installed, degrades to 'install <SDK> first'. Neither writes anything. DESTRUCTIVE (writes a .gd) — gated.",
+        inputSchema: {
+            sdk: z.enum(BACKEND_SDKS).describe("Which backend SDK to target"),
+            to_path: z.string().optional().describe("Destination res:// .gd path (default res://backend/cloud_save.gd)"),
+            overwrite: z.boolean().optional().describe("Overwrite if the file already exists (default false)"),
+            confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
+        },
+    }, async ({ sdk, to_path, overwrite, confirm }) => {
+        return runScaffold({
+            sdk,
+            feature: "cloudsave",
+            kind: "cloudsave",
+            toPath: to_path ?? "res://backend/cloud_save.gd",
+            overwrite: overwrite ?? false,
+            confirm,
+            build: () => buildCloudSaveScript(sdk),
+        });
+    });
+    // ------------------------------------------------------------ auth_scaffold ----
+    server.registerTool("auth_scaffold", {
+        title: "Scaffold auth integration",
+        description: "Generate login/register/logout helpers against an installed backend SDK. FEATURE-DETECTED both ways: if the SDK " +
+            "provides no auth API (Photon is realtime transport), degrades to 'unsupported_feature'; if the SDK is not " +
+            "installed, degrades to 'install <SDK> first'. Neither writes anything. DESTRUCTIVE (writes a .gd) — gated.",
+        inputSchema: {
+            sdk: z.enum(BACKEND_SDKS).describe("Which backend SDK to target"),
+            to_path: z.string().optional().describe("Destination res:// .gd path (default res://backend/auth.gd)"),
+            overwrite: z.boolean().optional().describe("Overwrite if the file already exists (default false)"),
+            confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
+        },
+    }, async ({ sdk, to_path, overwrite, confirm }) => {
+        return runScaffold({
+            sdk,
+            feature: "auth",
+            kind: "auth",
+            toPath: to_path ?? "res://backend/auth.gd",
+            overwrite: overwrite ?? false,
+            confirm,
+            build: () => buildAuthScript(sdk),
+        });
+    });
+}
+//# sourceMappingURL=backend.js.map

package/dist/tools/cli.js

@@ -0,0 +1,130 @@
+import { spawn, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { log } from "../logger.js";
+import { registerTaskTool } from "../tasks.js";
+import { ok } from "./lsp-common.js";
+const execFileAsync = promisify(execFile);
+/** Run the Godot binary to completion, capturing stdout/stderr. */
+async function runCaptured(cfg, args, timeoutMs, signal) {
+    try {
+        const { stdout, stderr } = await execFileAsync(cfg.godotBin, args, {
+            cwd: cfg.projectPath,
+            timeout: timeoutMs,
+            maxBuffer: 32 * 1024 * 1024,
+            signal,
+        });
+        return { code: 0, stdout, stderr, timedOut: false };
+    }
+    catch (err) {
+        const e = err;
+        return {
+            code: typeof e.code === "number" ? e.code : null,
+            stdout: e.stdout ?? "",
+            stderr: e.stderr ?? e.message ?? "",
+            timedOut: Boolean(e.killed) && e.signal === "SIGTERM",
+        };
+    }
+}
+/** Launch the Godot binary detached (for long-lived editor/game processes). */
+function launchDetached(cfg, args) {
+    const child = spawn(cfg.godotBin, args, {
+        cwd: cfg.projectPath,
+        detached: true,
+        stdio: "ignore",
+    });
+    child.unref();
+    return child.pid ?? null;
+}
+/** Truncate long output so a single tool result stays reasonable. */
+function tail(s, max = 8000) {
+    if (s.length <= max)
+        return s;
+    return "…(truncated)…\n" + s.slice(s.length - max);
+}
+export function registerCliTools(server, cfg) {
+    server.registerTool("godot_version", {
+        title: "Godot version",
+        description: "Return the version string of the configured Godot binary.",
+        inputSchema: {},
+    }, async () => {
+        const r = await runCaptured(cfg, ["--version"], 15000);
+        return ok({ version: r.stdout.trim() || r.stderr.trim(), raw: r });
+    });
+    server.registerTool("godot_launch_editor", {
+        title: "Launch editor",
+        description: "Open the Godot editor for the configured project (detached). Needed before any editor_* bridge tool can be used.",
+        inputSchema: {},
+    }, async () => {
+        const pid = launchDetached(cfg, ["-e", "--path", cfg.projectPath]);
+        log(`launched editor pid=${pid}`);
+        return ok({ launched: true, pid, project: cfg.projectPath });
+    });
+    server.registerTool("godot_run_project", {
+        title: "Run project",
+        description: "Run the project (detached). Optionally start from a specific scene path (res://...). Returns the process id.",
+        inputSchema: {
+            scene: z.string().optional().describe("Optional scene to run, e.g. res://levels/test.tscn"),
+        },
+    }, async ({ scene }) => {
+        const args = ["--path", cfg.projectPath];
+        if (scene)
+            args.push(scene);
+        const pid = launchDetached(cfg, args);
+        return ok({ running: true, pid, scene: scene ?? null });
+    });
+    registerTaskTool(server, "godot_export", {
+        title: "Export project",
+        description: "Headless export using an export preset. Runs to completion and returns exit code + logs. Can be slow — " +
+            "exposed as an MCP task, so task-aware clients can poll, await, or cancel it (tasks/get, tasks/result, tasks/cancel).",
+        inputSchema: {
+            preset: z.string().describe("Export preset name as defined in export_presets.cfg"),
+            output_path: z.string().describe("Output file path for the exported build"),
+            debug: z.boolean().optional().describe("Export a debug build instead of release (default false)"),
+            timeout_ms: z.number().int().positive().optional().describe("Max run time (default 600000)"),
+        },
+    }, async ({ preset, output_path, debug, timeout_ms }, signal) => {
+        const flag = debug ? "--export-debug" : "--export-release";
+        const r = await runCaptured(cfg, ["--headless", "--path", cfg.projectPath, flag, preset, output_path], timeout_ms ?? 600000, signal);
+        return ok({
+            preset,
+            output_path,
+            exit_code: r.code,
+            timed_out: r.timedOut,
+            stdout: tail(r.stdout),
+            stderr: tail(r.stderr),
+        });
+    });
+    registerTaskTool(server, "godot_import", {
+        title: "Import assets",
+        description: "Headless (re)import of project assets. Runs to completion and returns exit code + logs. " +
+            "Exposed as an MCP task (poll/await/cancel via tasks/get, tasks/result, tasks/cancel).",
+        inputSchema: {
+            timeout_ms: z.number().int().positive().optional().describe("Max run time (default 600000)"),
+        },
+    }, async ({ timeout_ms }, signal) => {
+        const r = await runCaptured(cfg, ["--headless", "--path", cfg.projectPath, "--import"], timeout_ms ?? 600000, signal);
+        return ok({ exit_code: r.code, timed_out: r.timedOut, stdout: tail(r.stdout), stderr: tail(r.stderr) });
+    });
+    registerTaskTool(server, "godot_run_headless_script", {
+        title: "Run headless script",
+        description: "Run a GDScript in headless mode (godot --headless -s <script>). Use this to invoke test runners " +
+            "(GdUnit4 / GUT) or any batch tool. Returns exit code + logs. Exposed as an MCP task, so a long test " +
+            "run can be polled, awaited, or cancelled (tasks/get, tasks/result, tasks/cancel).",
+        inputSchema: {
+            script_path: z.string().describe("Script to execute, e.g. res://addons/gdUnit4/bin/GdUnitCmdTool.gd"),
+            args: z.array(z.string()).optional().describe("Extra CLI args passed after the script"),
+            timeout_ms: z.number().int().positive().optional().describe("Max run time (default 600000)"),
+        },
+    }, async ({ script_path, args, timeout_ms }, signal) => {
+        const r = await runCaptured(cfg, ["--headless", "--path", cfg.projectPath, "-s", script_path, ...(args ?? [])], timeout_ms ?? 600000, signal);
+        return ok({
+            script_path,
+            exit_code: r.code,
+            timed_out: r.timedOut,
+            stdout: tail(r.stdout),
+            stderr: tail(r.stderr),
+        });
+    });
+}
+//# sourceMappingURL=cli.js.map