summer-engine 2.6.5 → 2.7.0

package/dist/mcp/server.js

@@ -7,16 +7,17 @@ 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 { 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,7 +28,7 @@ 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;
 export async function getClient() {
@@ -69,8 +70,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 +130,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 +183,11 @@ function installResultSizeLogger(server) {
                             chars,
                             bytes,
                         });
+                        appendMcpLogEvent("mcp:result_size", {
+                            toolName: name,
+                            chars,
+                            bytes,
+                        });
                         process.stderr.write(`[summer-mcp] ${line}\n`);
                     }
                 }
@@ -146,25 +201,42 @@ function installResultSizeLogger(server) {
         newArgs[lastIdx] = wrapped;
         return original(...newArgs);
     };
+    return () => registeredToolCount;
 }
 export async function startMcpServer() {
+    installMcpProcessDiagnostics();
+    appendMcpLogEvent("mcp:start", {
+        version,
+        pid: process.pid,
+        node: process.version,
+        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);
     // 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/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;

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

@@ -0,0 +1,154 @@
+import { z } from "zod";
+import { withEngine } from "./with-engine.js";
+// MCP clients may issue tool calls concurrently. Keep the complete read->write
+// transaction ordered for one project file while allowing unrelated files to
+// proceed in parallel. The tail is always released in `finally`, so a rejected
+// tool call cannot wedge later edits.
+const fileMutationTails = new Map();
+async function withFileMutationTurn(projectIdHash, path, fn) {
+    // Windows project paths are case-insensitive. Canonicalize only the lock key;
+    // preserve the caller's exact safe path in the operation sent to the engine.
+    const canonicalPathKey = path.replace(/\\/g, "/").toLowerCase();
+    const key = `${projectIdHash ?? "unbound"}\n${canonicalPathKey}`;
+    const previous = fileMutationTails.get(key) ?? Promise.resolve();
+    let release;
+    const gate = new Promise((resolve) => {
+        release = resolve;
+    });
+    const current = previous.catch(() => undefined).then(() => gate);
+    fileMutationTails.set(key, current);
+    await previous.catch(() => undefined);
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+        if (fileMutationTails.get(key) === current) {
+            fileMutationTails.delete(key);
+        }
+    }
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function safeProjectPath(path) {
+    const normalized = path.trim().replace(/\\/g, "/");
+    if (!normalized.startsWith("res://") || normalized.includes("..")) {
+        throw new Error("File path must be a traversal-free res:// project path.");
+    }
+    return normalized;
+}
+function validSha256(value) {
+    return typeof value === "string" && /^[0-9a-f]{64}$/i.test(value);
+}
+function readTextPayload(result) {
+    const root = asRecord(result);
+    const data = asRecord(root?.data);
+    if (root?.ok === false) {
+        throw new Error(String(root.error ?? "Engine could not read the file."));
+    }
+    if (data?.encoding === "binary" || typeof data?.content !== "string") {
+        throw new Error("Safe text mutation refused: the engine did not return text content.");
+    }
+    if (data.truncated === true) {
+        throw new Error("Safe text mutation refused: the file exceeds the 1 MB read limit.");
+    }
+    const sha256 = typeof data.sha256 === "string" ? data.sha256 : undefined;
+    if (!validSha256(sha256)) {
+        throw new Error("Safe text mutation refused: the engine did not return a full-file sha256 receipt.");
+    }
+    return {
+        content: data.content,
+        sha256,
+        size: typeof data.size === "number" ? data.size : undefined,
+    };
+}
+function occurrenceCount(content, needle) {
+    let count = 0;
+    let offset = 0;
+    while (true) {
+        const index = content.indexOf(needle, offset);
+        if (index < 0)
+            return count;
+        count++;
+        offset = index + needle.length;
+    }
+}
+export function registerFileTools(server) {
+    server.tool("summer_read_file", `Read a text file from the engine-bound project and return its full-file sha256 receipt.
+
+Use the returned sha256 as expected_sha256 when overwriting an existing file. Paths must begin with res://.`, {
+        path: z.string().describe("Project path, e.g. res://scripts/player.gd"),
+        max_bytes: z.number().int().positive().max(1_000_000).default(200_000),
+    }, async ({ path, max_bytes }) => withEngine(async (client) => client.readProjectFile(safeProjectPath(path), max_bytes)));
+    server.tool("summer_write_file", `Create or safely overwrite a complete text file through the identity-bound engine.
+
+For a new file, set create_only:true. For an existing file, first call summer_read_file and pass its sha256 as expected_sha256. Exactly one guard is required; unguarded writes fail closed. Supports scripts, .tscn scenes, .tres resources, JSON, docs, and project config.`, {
+        path: z.string().describe("Project path, e.g. res://scenes/player.tscn"),
+        content: z.string().describe("Complete new UTF-8 file content."),
+        create_only: z.boolean().optional().describe("Required for a new file; refuses if the path already exists."),
+        expected_sha256: z.string().optional().describe("Required for overwriting an existing file; obtain from summer_read_file."),
+    }, async ({ path, content, create_only, expected_sha256 }) => withEngine(async (client) => {
+        const safePath = safeProjectPath(path);
+        const guardedCreate = create_only === true;
+        const guardedOverwrite = validSha256(expected_sha256);
+        if (expected_sha256 !== undefined && !guardedOverwrite) {
+            throw new Error("Safe write refused: expected_sha256 must be a 64-character hexadecimal sha256 from summer_read_file. Nothing was written.");
+        }
+        if (guardedCreate === guardedOverwrite) {
+            throw new Error("Safe write requires exactly one guard: create_only:true for a new file, or a 64-character expected_sha256 from summer_read_file for an existing file. Nothing was written.");
+        }
+        const op = {
+            op: "WriteFile",
+            path: safePath,
+            content,
+        };
+        if (guardedCreate)
+            op.mustNotExist = true;
+        if (guardedOverwrite)
+            op.expectedSha256 = expected_sha256.toLowerCase();
+        return withFileMutationTurn(client.getBoundProjectIdHash(), safePath, () => client.executeIdentityBoundOps([op]));
+    }));
+    server.tool("summer_replace_text", `Safely replace text in an existing project file through the identity-bound engine.
+
+The MCP server reads the complete file, requires a unique match by default, computes the new content, and submits a sha256-guarded WriteFile. Set replace_all:true only when every exact occurrence should change.`, {
+        path: z.string().describe("Project path, e.g. res://scripts/player.gd"),
+        old_text: z.string().min(1).describe("Exact text to replace."),
+        new_text: z.string().describe("Replacement text; may be empty."),
+        replace_all: z.boolean().default(false).describe("Replace every exact occurrence instead of requiring one unique match."),
+    }, async ({ path, old_text, new_text, replace_all }) => withEngine(async (client) => {
+        const safePath = safeProjectPath(path);
+        return withFileMutationTurn(client.getBoundProjectIdHash(), safePath, async () => {
+            const current = readTextPayload(await client.readProjectFile(safePath, 1_000_000));
+            const matches = occurrenceCount(current.content, old_text);
+            if (matches === 0) {
+                throw new Error("Safe replace refused: old_text was not found. Nothing was written.");
+            }
+            if (!replace_all && matches !== 1) {
+                throw new Error(`Safe replace refused: old_text matched ${matches} times. Provide a unique span or set replace_all:true. Nothing was written.`);
+            }
+            const content = replace_all
+                ? current.content.split(old_text).join(new_text)
+                : current.content.replace(old_text, new_text);
+            if (content === current.content) {
+                return {
+                    ok: true,
+                    noOp: true,
+                    path: safePath,
+                    sha256: current.sha256,
+                    matches,
+                };
+            }
+            return client.executeIdentityBoundOps([
+                {
+                    op: "WriteFile",
+                    path: safePath,
+                    content,
+                    expectedSha256: current.sha256,
+                },
+            ]);
+        });
+    }));
+}