summer-engine 2.6.6 → 2.8.0

package/dist/mcp/server.js

@@ -7,16 +7,18 @@ import { registerDebugTools } from "./tools/debug-tools.js";
 import { registerVisualTools } from "./tools/visual-tools.js";
 import { WITH_ENGINE_META } from "./tools/with-engine.js";
 import { registerProjectTools } from "./tools/project-tools.js";
+import { registerFileTools } from "./tools/file-tools.js";
 import { registerAssetTools } from "./tools/asset-tools.js";
 import { registerGenerateTools } from "./tools/generate-tools.js";
 import { registerCloudTools } from "./tools/cloud-tools.js";
+import { registerCreatorTools } from "./tools/creator-tools.js";
+import { getCachedBootDriftNotice as getCachedNotice, setCachedBootDriftNotice, } from "../lib/mcp-boot-notice.js";
+import { appendMcpLogEvent } from "../lib/mcp-log.js";
 import { buildBootDriftNotice, fetchLatestRegistryVersion, } from "../lib/version-check.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../../package.json");
-let cachedBootDriftNotice = null;
-export function getCachedBootDriftNotice() {
-    return cachedBootDriftNotice;
-}
+let processDiagnosticsInstalled = false;
+export const getCachedBootDriftNotice = getCachedNotice;
 /**
  * Fire-and-forget probe of the npm registry on MCP boot. Caches the result for
  * the session. We never await this in startup so a slow / offline registry
@@ -27,9 +29,14 @@ async function probeBootDrift() {
     const registry = await fetchLatestRegistryVersion();
     // Agent is unknown at the MCP layer; use a generic placeholder. Doctor still
     // prescribes the correct agent-aware command via setup recommendations.
-    cachedBootDriftNotice = buildBootDriftNotice(version, registry);
+    setCachedBootDriftNotice(buildBootDriftNotice(version, registry));
 }
 let cachedClient = null;
+let engineSelection;
+export function configureMcpEngineSelection(selection) {
+    engineSelection = selection ? { ...selection } : undefined;
+    cachedClient = null;
+}
 export async function getClient() {
     if (cachedClient) {
         // The engine rotates its api-token (and can change ports) on every launch, so
@@ -45,12 +52,16 @@ export async function getClient() {
         }
     }
     try {
-        cachedClient = await EngineApiClient.connect();
+        cachedClient = await EngineApiClient.connect(engineSelection);
         return cachedClient;
     }
-    catch {
+    catch (error) {
         cachedClient = null;
-        throw new Error("Summer Engine is not running. Open it first, or run: npx summer-engine run\n" +
+        const reason = error instanceof Error
+            ? error.message
+            : "Summer Engine is not running.";
+        throw new Error(reason + "\n" +
+            "Open the intended project in Summer Engine, or run: npx summer-engine run\n" +
             "Note: only tools that touch the local project need the engine. Cloud tools " +
             "(summer_generate_*, summer_search_assets, summer_list_my_assets, summer_get_asset, " +
             "summer_check_job) work right now without it — they only need 'npx summer-engine login'.");
@@ -69,8 +80,56 @@ export function resetClient() {
  * out to produce pathological payloads in practice, the right fix is
  * adding range/depth/filter parameters to that tool — not a blanket cap.
  */
+function errorDetails(error) {
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+        };
+    }
+    return { message: String(error) };
+}
+function writeMcpStderr(event, details = {}) {
+    process.stderr.write(`[summer-mcp] ${JSON.stringify({ event, ...details })}\n`);
+}
+function installMcpProcessDiagnostics() {
+    if (processDiagnosticsInstalled)
+        return;
+    processDiagnosticsInstalled = true;
+    process.once("uncaughtException", (error) => {
+        const details = errorDetails(error);
+        appendMcpLogEvent("mcp:uncaught_exception", details);
+        writeMcpStderr("mcp:uncaught_exception", {
+            message: details.message,
+            log: "~/.summer/mcp.log",
+        });
+        process.exit(1);
+    });
+    process.once("unhandledRejection", (reason) => {
+        const details = errorDetails(reason);
+        appendMcpLogEvent("mcp:unhandled_rejection", details);
+        writeMcpStderr("mcp:unhandled_rejection", {
+            message: details.message,
+            log: "~/.summer/mcp.log",
+        });
+        process.exit(1);
+    });
+    process.once("SIGTERM", () => {
+        appendMcpLogEvent("mcp:sigterm", { pid: process.pid });
+        process.exit(0);
+    });
+    process.once("SIGINT", () => {
+        appendMcpLogEvent("mcp:sigint", { pid: process.pid });
+        process.exit(0);
+    });
+    process.once("exit", (code) => {
+        appendMcpLogEvent("mcp:exit", { pid: process.pid, code });
+    });
+}
 function installResultSizeLogger(server) {
     const original = server.tool.bind(server);
+    let registeredToolCount = 0;
     server.tool = function patchedTool(...args) {
         if (args.length < 2)
             return original(...args);
@@ -81,6 +140,7 @@ function installResultSizeLogger(server) {
         const handler = args[lastIdx];
         if (typeof handler !== "function")
             return original(...args);
+        registeredToolCount += 1;
         const wrapped = async (...handlerArgs) => {
             const startedAt = Date.now();
             const result = await handler(...handlerArgs);
@@ -133,6 +193,11 @@ function installResultSizeLogger(server) {
                             chars,
                             bytes,
                         });
+                        appendMcpLogEvent("mcp:result_size", {
+                            toolName: name,
+                            chars,
+                            bytes,
+                        });
                         process.stderr.write(`[summer-mcp] ${line}\n`);
                     }
                 }
@@ -146,25 +211,53 @@ function installResultSizeLogger(server) {
         newArgs[lastIdx] = wrapped;
         return original(...newArgs);
     };
+    return () => registeredToolCount;
 }
-export async function startMcpServer() {
+export async function startMcpServer(options = {}) {
+    configureMcpEngineSelection({
+        instanceId: options.instanceId ?? process.env.SUMMER_ENGINE_INSTANCE_ID,
+        projectPath: options.projectPath ?? process.env.SUMMER_ENGINE_PROJECT,
+        cwd: options.cwd ?? process.cwd(),
+    });
+    installMcpProcessDiagnostics();
+    appendMcpLogEvent("mcp:start", {
+        version,
+        pid: process.pid,
+        node: process.version,
+        cwd: process.cwd(),
+        selection: {
+            instanceId: options.instanceId ? "explicit" : undefined,
+            projectPath: options.projectPath ? "explicit" : undefined,
+            cwd: options.cwd ?? process.cwd(),
+        },
+    });
     const server = new McpServer({
         name: "summer-engine",
         version,
     });
     // Passive observability: log result-size to stderr but do not modify
     // results. See installResultSizeLogger above.
-    installResultSizeLogger(server);
+    const getRegisteredToolCount = installResultSizeLogger(server);
     registerSceneTools(server);
     registerDebugTools(server);
     registerVisualTools(server);
     registerProjectTools(server);
+    registerFileTools(server);
     registerAssetTools(server);
     registerGenerateTools(server);
     registerCloudTools(server);
+    registerCreatorTools(server);
     // Fire-and-forget — never block tool registration on the npm registry.
-    void probeBootDrift();
+    void probeBootDrift().catch((error) => {
+        setCachedBootDriftNotice(null);
+        appendMcpLogEvent("mcp:boot_drift_probe_failed", errorDetails(error));
+    });
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    appendMcpLogEvent("mcp:ready", {
+        version,
+        pid: process.pid,
+        toolCount: getRegisteredToolCount(),
+    });
     process.stderr.write(`[summer-mcp] MCP server running v${version}.\n`);
 }

package/dist/mcp/tools/asset-tools.js

@@ -168,7 +168,10 @@ async function buildImportEntriesForAsset(asset, targetPath) {
     return { imports: [{ url: fileUrl, path }], importPath: path };
 }
 async function importResolvedAsset(args) {
-    const { asset, parent, path, name } = args;
+    const { asset, parent, scenePath, path, name } = args;
+    if (parent && !scenePath) {
+        throw new Error("scenePath is required when importing an asset into a scene");
+    }
     const { imports, importPath } = await buildImportEntriesForAsset(asset, path);
     const client = await getClient();
     const importResult = imports.length === 1
@@ -176,20 +179,30 @@ async function importResolvedAsset(args) {
             { op: "ImportFromUrl", url: imports[0].url, path: imports[0].path },
         ])
         : await client.executeOps([{ op: "ImportFromUrlBatch", imports }]);
-    const ok = importResult?.results?.[0]?.ok;
-    if (!ok) {
-        throw new Error("Could not import asset. Check engine logs.");
+    const importReceipts = importResult?.results ?? [];
+    const importFailure = importReceipts.find((receipt) => receipt?.ok === false);
+    if (importResult?.status === "error" || importFailure) {
+        throw new Error(importFailure?.error || "Could not import asset. Check engine logs.");
     }
     let addedToScene = false;
+    let sceneReceipt = null;
     if (parent && asset.type === "3d_model") {
-        await client.executeOps([
+        sceneReceipt = await client.executeIdentityBoundOps([
             {
                 op: "InstantiateScene",
                 parent,
                 scene: importPath,
                 name: sanitizeNodeName(name || asset.title),
             },
-        ]);
+            { op: "SaveScene" },
+        ], { scenePath });
+        const placementReceipts = sceneReceipt?.results ?? [];
+        const placementFailure = placementReceipts.find((receipt) => receipt?.ok !== true);
+        if (sceneReceipt?.status === "error" ||
+            placementReceipts.length !== 2 ||
+            placementFailure) {
+            throw new Error(placementFailure?.error || `Could not add asset to ${scenePath}`);
+        }
         addedToScene = true;
     }
     return {
@@ -200,6 +213,8 @@ async function importResolvedAsset(args) {
         importedTo: importPath,
         addedToScene,
         parent: parent || null,
+        scenePath: scenePath || null,
+        sceneReceipt,
     };
 }
 function jsonSuccess(data) {
@@ -345,8 +360,8 @@ Cloud tool — works WITHOUT the Summer Engine app open.`, {
 Use this when the asset was just generated, selected from my assets, or returned
 by search. Unlike summer_import_asset, this does not search or guess: it fetches
 the asset by ID, downloads it through Summer Engine, and runs Godot's import
-pipeline. For 3D models, pass parent to instantiate it in the open scene after
-import.
+pipeline. For 3D models, pass parent and scenePath to instantiate it in that
+exact scene; it does not need to be the active editor tab.
 
 Requires the Summer Engine app to be open with the project loaded (generation
 itself does not — only this import step does).`, {
@@ -359,11 +374,15 @@ itself does not — only this import step does).`, {
             .string()
             .optional()
             .describe("Optional parent node path. For 3D models only; imports and instantiates under this node."),
+        scenePath: z
+            .string()
+            .optional()
+            .describe("Required with parent. Exact res:// scene that receives the 3D model."),
         name: z
             .string()
             .optional()
             .describe("Optional scene node name when parent is provided."),
-    }, async ({ assetId, path, parent, name }) => {
+    }, async ({ assetId, path, parent, scenePath, name }) => {
         const fetched = await getAssetApi(assetId);
         if (fetched.error || !fetched.asset) {
             return jsonError({
@@ -375,6 +394,7 @@ itself does not — only this import step does).`, {
             const imported = await importResolvedAsset({
                 asset: fetched.asset,
                 parent,
+                scenePath,
                 path,
                 name,
             });
@@ -390,7 +410,7 @@ itself does not — only this import step does).`, {
             return jsonError({
                 error: "import_failed",
                 message: msg,
-                hint: "Make sure Summer Engine is running and the target scene is open.",
+                hint: "Make sure Summer Engine is running and pass the exact scenePath when parent is set.",
             });
         }
     });
@@ -402,9 +422,10 @@ Searches, picks the top result, downloads and imports it, then optionally adds i
 Requires authentication. If the user gets an auth error, they need to run 'npx summer-engine login' in their terminal first. Summer Engine must be running.`, {
         query: z.string().describe("What to find, e.g. 'low-poly tree', 'wooden crate'"),
         parent: z.string().optional().describe("Parent node path to add the asset under, e.g. './World'. If omitted, only imports (no scene placement)"),
+        scenePath: z.string().optional().describe("Required with parent. Exact res:// target scene path."),
         assetType: z.enum(["2d_image", "animation", "3d_model", "audio", "music", "all"]).default("3d_model").describe("Preferred asset type"),
         source: z.enum(["library", "my_assets", "all"]).default("all").describe("Where to search before importing"),
-    }, async ({ query, parent, assetType, source }) => {
+    }, async ({ query, parent, scenePath, assetType, source }) => {
         const searchResult = await searchAssetsApi({ query, assetType, limit: 5, source });
         if (searchResult.error) {
             return {
@@ -443,7 +464,7 @@ Requires authentication. If the user gets an auth error, they need to run 'npx s
             };
         }
         try {
-            const imported = await importResolvedAsset({ asset: best, parent });
+            const imported = await importResolvedAsset({ asset: best, parent, scenePath });
             // 2D sprites and audio: import only; user adds to scene manually
             return {
                 content: [

package/dist/mcp/tools/cloud-tools.js

@@ -15,28 +15,28 @@ function textJson(value) {
     };
 }
 export function registerCloudTools(server) {
-    server.tool("summer_cloud_init", "Enable Summer Cloud for a project.", projectArg.shape, async (args) => textJson(await cloudInit({ project: args.project, face: "mcp" })));
-    server.tool("summer_cloud_status", "Show Summer Cloud sync status.", projectArg.shape, async (args) => textJson(await cloudStatus({ project: args.project, face: "mcp" })));
-    server.tool("summer_cloud_push", "Push local project changes to Summer Cloud.", {
+    server.tool("summer_cloud_init", "Enable Summer Cloud (content-addressed whole-project sync) for a project, writing the git-tracked summer-cloud.json binding. Use once per project before the first push, or after deleting the binding to fork the project into a new cloud line.", projectArg.shape, async (args) => textJson(await cloudInit({ project: args.project, face: "mcp" })));
+    server.tool("summer_cloud_status", "Show what a sync would move: file counts, paths queued to push or pull, and any waiting conflict sets. Always call this before push or pull so you can report the delete and change counts to the user; never sync blind.", projectArg.shape, async (args) => textJson(await cloudStatus({ project: args.project, face: "mcp" })));
+    server.tool("summer_cloud_push", "Upload local project changes to Summer Cloud as a new restorable version (use to back up big assets, move to another machine, or snapshot before a risky bulk op). confirmDeletes gates large deletions (more than 10 files, or >=20% of the tree, or the whole tree): run summer_cloud_status first, show the exact delete count to the user, and only set it once they confirm. Never pass confirmDeletes blindly.", {
         ...projectArg.shape,
-        confirmDeletes: z.boolean().default(false).describe("Required when a push would delete many cloud files."),
-        bootstrap: bootstrap.optional().describe("No-base bootstrap choice."),
-        adoptPath: z.boolean().optional().describe("Accept that the project folder moved and update the recorded path."),
+        confirmDeletes: z.boolean().default(false).describe("Gate for large cloud deletions. Required when a push would delete more than 10 files, at least 20% of the tracked tree, or the entire tree. Surface the delete count from summer_cloud_status to the user before setting this; never set it blindly."),
+        bootstrap: bootstrap.optional().describe("No-base bootstrap choice when local and cloud both have files: keep-cloud, keep-local, or merge. Present the choice to the user."),
+        adoptPath: z.boolean().optional().describe("Accept that the project folder moved and update the recorded path. Only set after confirming the move is intentional, not a copy."),
     }, async (args) => textJson(await cloudPush({ ...args, face: "mcp" })));
-    server.tool("summer_cloud_pull", "Pull Summer Cloud changes into the local project.", {
+    server.tool("summer_cloud_pull", "Download Summer Cloud changes into the local project (use to fetch a teammate's bytes or hydrate on a second machine). A local checkpoint is written before any destructive apply, and concurrent edits become recoverable conflict sets rather than silent overwrites. Run summer_cloud_status first.", {
         ...projectArg.shape,
-        bootstrap: bootstrap.optional().describe("No-base bootstrap choice."),
-        adoptPath: z.boolean().optional().describe("Accept that the project folder moved and update the recorded path."),
+        bootstrap: bootstrap.optional().describe("No-base bootstrap choice when local and cloud both have files: keep-cloud, keep-local, or merge. Present the choice to the user."),
+        adoptPath: z.boolean().optional().describe("Accept that the project folder moved and update the recorded path. Only set after confirming the move is intentional, not a copy."),
     }, async (args) => textJson(await cloudPull({ ...args, face: "mcp" })));
-    server.tool("summer_cloud_restore", "Restore a retained cloud version (creates a new head version server-side, then pulls), or a local pre-sync checkpoint via checkpointStamp.", {
+    server.tool("summer_cloud_restore", "Roll a project back to an earlier state. Pass version to restore a retained cloud version (creates a new head version server-side, then pulls); pass checkpointStamp to restore a local pre-sync checkpoint for unpushed work. The restore restores bytes but does not delete files a later sync added, so review the extraneous-file list it returns.", {
         ...projectArg.shape,
-        version: z.number().int().positive().optional().describe("Cloud version to restore."),
-        checkpointStamp: z.string().optional().describe("Local checkpoint stamp (see summer_cloud_checkpoints)."),
+        version: z.number().int().positive().optional().describe("Cloud version to restore (see summer_cloud_status / version history)."),
+        checkpointStamp: z.string().optional().describe("Local checkpoint stamp (see summer_cloud_checkpoints). Use for unpushed local-only work."),
     }, async (args) => textJson(await cloudRestore({ project: args.project, version: args.version, checkpoint: args.checkpointStamp, face: "mcp" })));
-    server.tool("summer_cloud_checkpoints", "List local pre-sync checkpoints.", projectArg.shape, async (args) => textJson(await cloudCheckpoints({ project: args.project, face: "mcp" })));
-    server.tool("summer_cloud_conflicts", "List local Summer Cloud conflict sets, or restore a preserved conflict file with restorePath.", {
+    server.tool("summer_cloud_checkpoints", "List the local pre-sync checkpoints taken before destructive applies. Use to find a checkpoint stamp to pass to summer_cloud_restore when recovering local-only work.", projectArg.shape, async (args) => textJson(await cloudCheckpoints({ project: args.project, face: "mcp" })));
+    server.tool("summer_cloud_conflicts", "List preserved Summer Cloud conflict sets (the losing bytes from concurrent edits, never discarded), or recover one by passing restorePath to re-enter it as a fresh edit. Use after a push or pull reports conflicts so the user can choose what to keep.", {
         ...projectArg.shape,
-        restorePath: z.string().optional().describe("Project-relative path to restore from the conflict sets."),
+        restorePath: z.string().optional().describe("Project-relative path to restore from the conflict sets, re-entered as a fresh edit."),
         set: z.string().optional().describe("Conflict set stamp; defaults to the newest set containing the path."),
     }, async (args) => textJson(await cloudConflicts({ project: args.project, restorePath: args.restorePath, set: args.set, face: "mcp" })));
 }

package/dist/mcp/tools/creator-tools.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerCreatorTools(server: McpServer): void;

package/dist/mcp/tools/creator-tools.js

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { CreatorOperationError, listCreatorReleases, publishCreator, readCreatorLogs, } from "../../lib/creator.js";
+import { CONFIG_KEYS, getConfigValue, isConfigKey, readSummerConfig, setConfigValue, unsetConfigValue, } from "../../lib/config.js";
+function textJson(value, isError = false) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2),
+            },
+        ],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+async function creatorResult(operation) {
+    try {
+        return textJson(await operation());
+    }
+    catch (error) {
+        if (error instanceof CreatorOperationError) {
+            return textJson({
+                ok: false,
+                code: error.code,
+                operation: error.operation,
+                message: error.message,
+                recovery: error.recovery,
+            }, true);
+        }
+        return textJson({
+            ok: false,
+            code: "creator_request_invalid",
+            message: error instanceof Error ? error.message : String(error),
+        }, true);
+    }
+}
+export function registerCreatorTools(server) {
+    server.tool("summer_creator_publish", "Publish an exact exported Summer .pck through the versioned Summercraft creator API. First call with confirm=false and present the returned project, version, digest, size, artifact path, channel, and notes; set confirm only after the user approves that exact target. The server independently verifies token scope, ownership, bytes, and review state.", {
+        project: z.string().optional().describe("Project root. Defaults to the current working directory."),
+        artifact: z.string().describe("Exact path to the exported Summer .pck artifact."),
+        version: z.string().describe("Immutable release version."),
+        manifest: z.string().optional().describe("Optional path to a JSON release manifest."),
+        projectId: z.string().optional().describe("Creator project ID. Defaults to ~/.summer/config.json."),
+        channel: z.string().optional().describe("Release channel. Defaults to the configured channel or production."),
+        notes: z.string().optional().describe("Release notes shown during confirmation and recorded in the local audit."),
+        confirm: z.boolean().default(false).describe("Set true only after the user approves the exact release target."),
+    }, async (args) => creatorResult(() => publishCreator({
+        ...args,
+        face: "mcp",
+    })));
+    server.tool("summer_creator_releases", "List real creator-owned releases from the versioned Summercraft creator API. The server independently verifies the exact publish scope and project ownership.", {
+        projectId: z.string().optional().describe("Creator project ID. Defaults to ~/.summer/config.json."),
+        limit: z.number().int().min(1).max(100).default(20),
+        cursor: z.string().optional().describe("Opaque nextCursor from the previous page."),
+    }, async (args) => creatorResult(() => listCreatorReleases({
+        ...args,
+        face: "mcp",
+    })));
+    server.tool("summer_creator_logs", "Read creator runtime logs for a project or release. If the required platform route or token scope is unavailable, returns the exact recovery action instead of placeholder logs.", {
+        projectId: z.string().optional().describe("Creator project ID. Defaults to ~/.summer/config.json."),
+        releaseId: z.string().optional().describe("Optional release ID."),
+        limit: z.number().int().min(1).max(1000).default(100),
+    }, async (args) => creatorResult(() => readCreatorLogs({
+        ...args,
+        face: "mcp",
+    })));
+    server.tool("summer_creator_config", "Read or update the shared non-secret ~/.summer configuration used by the CLI and this MCP. Mutations require confirm=true. Tokens are never returned or accepted by this tool.", {
+        action: z.enum(["list", "get", "set", "unset"]),
+        key: z.enum(CONFIG_KEYS).optional(),
+        value: z.string().optional(),
+        confirm: z.boolean().default(false),
+    }, async ({ action, key, value, confirm }) => creatorResult(async () => {
+        if (action === "list") {
+            const config = await readSummerConfig();
+            return {
+                ok: true,
+                values: Object.fromEntries(CONFIG_KEYS.map((name) => [
+                    name,
+                    getConfigValue(config, name) ?? null,
+                ])),
+            };
+        }
+        if (!key || !isConfigKey(key)) {
+            throw new Error(`A valid key is required. Recovery: use one of ${CONFIG_KEYS.join(", ")}.`);
+        }
+        if (action === "get") {
+            return {
+                ok: true,
+                key,
+                value: getConfigValue(await readSummerConfig(), key) ?? null,
+            };
+        }
+        if (!confirm) {
+            throw new Error(`Changing ${key} requires confirmation. Recovery: show the exact change to the user, then retry with confirm=true.`);
+        }
+        if (action === "set") {
+            if (value === undefined) {
+                throw new Error(`A value is required for ${key}. Recovery: provide value and retry with confirm=true.`);
+            }
+            const config = await setConfigValue(key, value);
+            return { ok: true, key, value: getConfigValue(config, key) };
+        }
+        const config = await unsetConfigValue(key);
+        return { ok: true, key, value: getConfigValue(config, key) ?? null };
+    }));
+}

package/dist/mcp/tools/debug-tools.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { withEngine } from "./with-engine.js";
 import { shapeEngineLogResponse } from "../../lib/log-filters.js";
+import { createDebugReportArtifact } from "../../lib/debug-report.js";
 export function registerDebugTools(server) {
     server.tool("summer_get_diagnostics", `Quick overview of all errors and warnings from both the editor console and the runtime debugger. Returns error counts and a guidance message.
 
@@ -92,11 +93,53 @@ After starting, use summer_get_diagnostics to check for runtime errors.
 You can run a specific scene instead of the main scene — useful for testing individual levels or UI screens.`, {
         scene: z.string().optional().describe("Scene to run instead of main scene, e.g. 'res://levels/test_level.tscn'"),
     }, async ({ scene }) => withEngine(async (client) => client.play(scene)));
-    server.tool("summer_stop", "Stop the running game. Call this before making scene changes — some operations require the game to not be running.", {}, async () => withEngine(async (client) => client.stop()));
+    server.tool("summer_stop", "Stop the running game. Use after runtime verification or when you intentionally need to restart the running instance; ordinary editor scene mutations do not require a blanket stop.", {}, async () => withEngine(async (client) => client.stop()));
     server.tool("summer_is_running", "Check if the game is currently running. Returns the active scene path if running.", {}, async () => withEngine(async (client) => client.executeOps([{ op: "IsGameRunning" }])));
     server.tool("summer_get_script_errors", `Check a GDScript file for parse/compile errors without running the game.
 
 Use after writing or editing a .gd file to verify it compiles. Returns line numbers, error messages, and severity. Much faster than running the game to discover script errors.`, {
         path: z.string().describe("Script path, e.g. 'res://scripts/player.gd' or 'res://player_controller.gd'"),
     }, async ({ path }) => withEngine(async (client) => client.getScriptErrors(path)));
+    server.tool("summer_create_debug_report", `Create a support-ready Markdown report for /summer debug.
+
+Use this when the user says "/summer debug", asks to send Summer a bug report,
+or needs a portable artifact from a failing Codex/cloud/agent session. The
+report includes Summer doctor checks, engine health, diagnostics, console
+output, debugger errors/warnings, and an agent handoff prompt. It omits auth
+tokens and project file contents, but the user should still review it before
+sending because local paths and stack traces may appear.`, {
+        issue: z.string().optional().describe("User-visible issue or repro summary."),
+        output_path: z.string().optional().describe("Where to write the Markdown report. Defaults to the open project root, or the current working directory if no project is open."),
+        include_play_session: z.boolean().optional().default(false).describe("Launch the game briefly and collect post-play diagnostics."),
+        play_wait_ms: z.number().optional().default(2500).describe("Milliseconds to wait after launching the game when include_play_session is true."),
+        max_console_lines: z.number().optional().default(200).describe("Console lines to include after filtering/deduping."),
+        max_debugger_entries: z.number().optional().default(100).describe("Debugger error/warning entries to include after filtering/deduping."),
+        include_doctor: z.boolean().optional().default(true).describe("Include summer doctor checks in the report."),
+    }, async ({ issue, output_path, include_play_session, play_wait_ms, max_console_lines, max_debugger_entries, include_doctor, }) => {
+        const artifact = await createDebugReportArtifact({
+            issue,
+            outputPath: output_path,
+            includePlaySession: include_play_session,
+            playWaitMs: play_wait_ms,
+            maxConsoleLines: max_console_lines,
+            maxDebuggerEntries: max_debugger_entries,
+            includeDoctor: include_doctor,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ok: true,
+                        path: artifact.path,
+                        engineConnected: artifact.report.engine.connected,
+                        generatedAt: artifact.report.generatedAt,
+                        issue: artifact.report.issue,
+                        doctorSummary: artifact.report.doctor?.summary ?? null,
+                        reviewNote: "Report omits auth tokens, but the user should review local paths and stack traces before sending.",
+                    }, null, 2),
+                },
+            ],
+        };
+    });
 }

package/dist/mcp/tools/file-tools.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerFileTools(server: McpServer): void;