summer-engine 2.7.0 → 2.8.0

package/dist/lib/engine.js

@@ -1,19 +1,22 @@
-import { readFile } from "fs/promises";
-import { join } from "path";
+import { lstat, readFile, readdir, realpath, stat } from "fs/promises";
+import { dirname, join, resolve } from "path";
 import { getSummerDir } from "./auth.js";
 const DEFAULT_PORT = 6550;
-export async function getApiToken() {
+const INSTANCE_SCHEMA_VERSION = 1;
+const INSTANCE_STALE_MS = 180_000;
+const MAX_INSTANCE_FILE_BYTES = 64 * 1024;
+export async function getApiToken(summerDir = getSummerDir()) {
     try {
-        const token = await readFile(join(getSummerDir(), "api-token"), "utf-8");
+        const token = await readFile(join(summerDir, "api-token"), "utf-8");
         return token.trim() || null;
     }
     catch {
         return null;
     }
 }
-export async function getApiPort() {
+export async function getApiPort(summerDir = getSummerDir()) {
     try {
-        const port = await readFile(join(getSummerDir(), "api-port"), "utf-8");
+        const port = await readFile(join(summerDir, "api-port"), "utf-8");
         const parsed = parseInt(port.trim(), 10);
         return isNaN(parsed) ? DEFAULT_PORT : parsed;
     }
@@ -21,6 +24,237 @@ export async function getApiPort() {
         return DEFAULT_PORT;
     }
 }
+function stringFromUnknown(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+}
+function numberFromUnknown(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? value
+        : undefined;
+}
+function processIsAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function canonicalPath(path) {
+    const absolute = resolve(path);
+    try {
+        return await realpath(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+export async function findProjectRoot(startPath) {
+    let current = await canonicalPath(startPath);
+    try {
+        if (!(await stat(current)).isDirectory()) {
+            current = dirname(current);
+        }
+    }
+    catch {
+        return null;
+    }
+    while (true) {
+        try {
+            if ((await stat(join(current, "project.godot"))).isFile()) {
+                return current;
+            }
+        }
+        catch {
+            // Keep walking toward the filesystem root.
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function parseEngineInstance(value) {
+    const record = asRecord(value);
+    if (!record || record.schemaVersion !== INSTANCE_SCHEMA_VERSION)
+        return null;
+    const instanceId = stringFromUnknown(record.instanceId);
+    const pid = numberFromUnknown(record.pid);
+    const port = numberFromUnknown(record.port);
+    const token = stringFromUnknown(record.token);
+    const resourceRoot = stringFromUnknown(record.resourceRoot);
+    const heartbeatAt = numberFromUnknown(record.heartbeatAt);
+    if (!instanceId ||
+        !pid ||
+        !Number.isInteger(pid) ||
+        !port ||
+        !Number.isInteger(port) ||
+        port < 1 ||
+        port > 65535 ||
+        !token ||
+        !resourceRoot ||
+        !heartbeatAt) {
+        return null;
+    }
+    return {
+        schemaVersion: 1,
+        instanceId,
+        pid,
+        port,
+        token,
+        projectId: stringFromUnknown(record.projectId),
+        projectIdHash: stringFromUnknown(record.projectIdHash),
+        resourceRoot,
+        projectName: stringFromUnknown(record.projectName),
+        heartbeatAt,
+        engineVersion: stringFromUnknown(record.engineVersion),
+    };
+}
+export async function listEngineInstances(nowMs = Date.now(), summerDir = getSummerDir()) {
+    const instancesDir = join(summerDir, "instances");
+    try {
+        const dirInfo = await lstat(instancesDir);
+        if (!dirInfo.isDirectory() || dirInfo.isSymbolicLink())
+            return [];
+    }
+    catch {
+        return [];
+    }
+    const entries = await readdir(instancesDir, { withFileTypes: true });
+    const instances = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".json"))
+            continue;
+        const path = join(instancesDir, entry.name);
+        try {
+            const info = await lstat(path);
+            if (!info.isFile() ||
+                info.isSymbolicLink() ||
+                info.size > MAX_INSTANCE_FILE_BYTES) {
+                continue;
+            }
+            const parsed = parseEngineInstance(JSON.parse(await readFile(path, "utf-8")));
+            if (!parsed || !processIsAlive(parsed.pid))
+                continue;
+            if (nowMs - parsed.heartbeatAt * 1000 > INSTANCE_STALE_MS)
+                continue;
+            parsed.resourceRoot = await canonicalPath(parsed.resourceRoot);
+            instances.push(parsed);
+        }
+        catch {
+            // One malformed or concurrently-replaced entry must not hide other editors.
+        }
+    }
+    return instances.sort((a, b) => a.resourceRoot.localeCompare(b.resourceRoot) ||
+        a.instanceId.localeCompare(b.instanceId));
+}
+function formatInstances(instances) {
+    return instances
+        .map((instance) => {
+        const label = instance.projectName
+            ? `${instance.projectName} (${instance.resourceRoot})`
+            : instance.resourceRoot;
+        return `  - ${label} [${instance.instanceId}]`;
+    })
+        .join("\n");
+}
+async function connectionForInstance(instance, selection) {
+    const health = await checkEngineHealth(instance.port);
+    if (!health) {
+        throw new Error(`Summer Engine instance ${instance.instanceId} is not responding on port ${instance.port}.`);
+    }
+    if (health.instanceId !== instance.instanceId) {
+        throw new Error(`Summer Engine registry identity changed on port ${instance.port}; refusing to connect to the wrong editor.`);
+    }
+    if (instance.projectIdHash &&
+        health.projectIdHash &&
+        instance.projectIdHash !== health.projectIdHash) {
+        throw new Error(`Summer Engine project identity changed on port ${instance.port}; refusing to connect to the wrong project.`);
+    }
+    return {
+        port: instance.port,
+        token: instance.token,
+        health,
+        instance,
+        selection: { ...selection },
+        source: "registry",
+    };
+}
+export async function resolveEngineConnection(selection = {}, options = {}) {
+    const summerDir = options.summerDir ?? getSummerDir();
+    const explicitInstanceId = stringFromUnknown(selection.instanceId);
+    const explicitProjectPath = stringFromUnknown(selection.projectPath);
+    const cwd = stringFromUnknown(selection.cwd);
+    const requestedProjectRoot = explicitProjectPath
+        ? await findProjectRoot(explicitProjectPath)
+        : !explicitInstanceId && cwd
+            ? await findProjectRoot(cwd)
+            : null;
+    if (explicitProjectPath && !requestedProjectRoot) {
+        throw new Error(`No project.godot found at or above ${resolve(explicitProjectPath)}.`);
+    }
+    const instances = await listEngineInstances(options.nowMs ?? Date.now(), summerDir);
+    let candidates = instances;
+    if (explicitInstanceId) {
+        candidates = candidates.filter((instance) => instance.instanceId === explicitInstanceId);
+    }
+    if (requestedProjectRoot) {
+        const canonicalRoot = await canonicalPath(requestedProjectRoot);
+        candidates = candidates.filter((instance) => instance.resourceRoot === canonicalRoot);
+    }
+    if (explicitInstanceId || requestedProjectRoot) {
+        if (candidates.length === 1) {
+            return connectionForInstance(candidates[0], {
+                ...selection,
+                projectPath: requestedProjectRoot ?? selection.projectPath,
+            });
+        }
+        if (candidates.length > 1) {
+            throw new Error(`More than one Summer editor matches this project. Select one with \`summer mcp --instance <id>\`:\n${formatInstances(candidates)}`);
+        }
+        const canUseLegacyForInferredProject = instances.length === 0 &&
+            !explicitInstanceId &&
+            !explicitProjectPath &&
+            Boolean(requestedProjectRoot);
+        if (!canUseLegacyForInferredProject) {
+            const target = explicitInstanceId
+                ? `instance ${explicitInstanceId}`
+                : `project ${requestedProjectRoot}`;
+            throw new Error(`No running Summer editor matches ${target}. Open that project in Summer Engine and retry.`);
+        }
+    }
+    if (instances.length === 1) {
+        return connectionForInstance(instances[0], selection);
+    }
+    if (instances.length > 1) {
+        throw new Error("Multiple Summer editors are running and this agent is not inside a Summer project. " +
+            "Start the agent from the project directory, or pass `summer mcp --project <path>`.\n" +
+            formatInstances(instances));
+    }
+    const [port, token] = await Promise.all([
+        getApiPort(summerDir),
+        getApiToken(summerDir),
+    ]);
+    if (!token) {
+        throw new Error("Summer Engine is not running (no api-token found). Open Summer Engine first.");
+    }
+    const health = await checkEngineHealth(port);
+    if (!health) {
+        throw new Error(`Summer Engine is not responding on port ${port}. Make sure it's open.`);
+    }
+    return {
+        port,
+        token,
+        health,
+        selection: null,
+        source: "legacy",
+    };
+}
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value

package/dist/lib/public-surface-paths.d.ts

@@ -0,0 +1,13 @@
+export interface PathFlavor {
+    isAbsolute(path: string): boolean;
+    relative(from: string, to: string): string;
+    resolve(...paths: string[]): string;
+    sep: string;
+}
+export interface PublicSurfaceRoots {
+    packageRoot: string;
+    engineRoot: string;
+}
+export declare function snapshotPublicPath(pathFlavor: PathFlavor, roots: PublicSurfaceRoots, file: string): string;
+export declare function compareByCodePoint(left: string, right: string): number;
+export declare function stablePublicPathInventory(pathFlavor: PathFlavor, roots: PublicSurfaceRoots, files: readonly string[]): string;

package/dist/lib/public-surface-paths.js

@@ -0,0 +1,42 @@
+function relativeWithin(pathFlavor, root, file) {
+    const resolvedRoot = pathFlavor.resolve(root);
+    const resolvedFile = pathFlavor.resolve(file);
+    const candidate = pathFlavor.relative(resolvedRoot, resolvedFile);
+    if (pathFlavor.isAbsolute(candidate) ||
+        candidate === ".." ||
+        candidate.startsWith(`..${pathFlavor.sep}`)) {
+        return null;
+    }
+    return candidate;
+}
+function toPosix(pathFlavor, path) {
+    return path.split(pathFlavor.sep).join("/");
+}
+export function snapshotPublicPath(pathFlavor, roots, file) {
+    const packageRelative = relativeWithin(pathFlavor, roots.packageRoot, file);
+    if (packageRelative !== null) {
+        return `cli/${toPosix(pathFlavor, packageRelative)}`;
+    }
+    const engineRelative = relativeWithin(pathFlavor, roots.engineRoot, file);
+    if (engineRelative !== null) {
+        return `engine/${toPosix(pathFlavor, engineRelative)}`;
+    }
+    throw new Error(`Public surface escapes both inventory roots: ${file}`);
+}
+export function compareByCodePoint(left, right) {
+    const leftPoints = [...left].map((character) => character.codePointAt(0));
+    const rightPoints = [...right].map((character) => character.codePointAt(0));
+    const sharedLength = Math.min(leftPoints.length, rightPoints.length);
+    for (let index = 0; index < sharedLength; index += 1) {
+        if (leftPoints[index] !== rightPoints[index]) {
+            return leftPoints[index] - rightPoints[index];
+        }
+    }
+    return leftPoints.length - rightPoints.length;
+}
+export function stablePublicPathInventory(pathFlavor, roots, files) {
+    return files
+        .map((file) => snapshotPublicPath(pathFlavor, roots, file))
+        .sort(compareByCodePoint)
+        .join("\n");
+}

package/dist/lib/skills-registry.d.ts

@@ -545,6 +545,14 @@ export declare const SKILL_REGISTRY: readonly [{
     readonly recommended: true;
     readonly requiresMcpTools: readonly ["summer_play", "summer_stop", "summer_get_console", "summer_get_debugger_errors", "summer_get_diagnostics"];
     readonly testScenario: "Just finished a gameplay feature — skill drives a golden-path + edge-case playthrough with diagnostics capture before the feature can be marked done.";
+}, {
+    readonly name: "headless-scripting";
+    readonly category: "workflow";
+    readonly public: true;
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf", "cline", "roo-code", "kilo-code", "gemini", "github-copilot", "vscode-copilot", "opencode"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_get_project_context", "summer_write_file"];
+    readonly testScenario: "User needs a navmesh baked, collision generated, an Animation authored, or raw assets re-imported — skill runs a GDScript file against the real engine binary instead of reporting the capability as missing, and blocks the 'run it headless and screenshot it' plan that silently returns null.";
 }, {
     readonly name: "debugging-game-feel";
     readonly category: "workflow";

package/dist/lib/skills-registry.js

@@ -1023,6 +1023,15 @@ export const SKILL_REGISTRY = [
         ],
         testScenario: "Just finished a gameplay feature — skill drives a golden-path + edge-case playthrough with diagnostics capture before the feature can be marked done.",
     },
+    {
+        name: "headless-scripting",
+        category: "workflow",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: ["summer_get_project_context", "summer_write_file"],
+        testScenario: "User needs a navmesh baked, collision generated, an Animation authored, or raw assets re-imported — skill runs a GDScript file against the real engine binary instead of reporting the capability as missing, and blocks the 'run it headless and screenshot it' plan that silently returns null.",
+    },
     {
         name: "debugging-game-feel",
         category: "workflow",

package/dist/lib/store.d.ts

@@ -0,0 +1,14 @@
+export declare class SummerStoreError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function getSummerDir(): string;
+/** Test-only seam. Passing null restores the real ~/.summer path. */
+export declare function setSummerDirForTests(path: string | null): void;
+export declare function ensureSummerStore(): Promise<string>;
+export declare function readStoreText(name: string): Promise<string | null>;
+export declare function readStoreJson<T>(name: string): Promise<T | null>;
+export declare function writeStoreText(name: string, value: string): Promise<void>;
+export declare function writeStoreJson(name: string, value: unknown): Promise<void>;
+export declare function appendStoreJsonLine(name: string, value: unknown): Promise<void>;
+export declare function removeStoreFile(name: string): Promise<boolean>;

package/dist/lib/store.js

@@ -0,0 +1,145 @@
+import { appendFile, chmod, lstat, mkdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+let summerDirOverride = null;
+export class SummerStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SummerStoreError";
+    }
+}
+export function getSummerDir() {
+    return summerDirOverride ?? join(homedir(), ".summer");
+}
+/** Test-only seam. Passing null restores the real ~/.summer path. */
+export function setSummerDirForTests(path) {
+    summerDirOverride = path;
+}
+function storePath(name) {
+    if (!name || basename(name) !== name || name === "." || name === "..") {
+        throw new SummerStoreError("invalid_store_path", `Invalid Summer store filename "${name}". Recovery: use a single filename inside ~/.summer/.`);
+    }
+    return join(getSummerDir(), name);
+}
+async function hardenMode(path, mode) {
+    try {
+        await chmod(path, mode);
+    }
+    catch (error) {
+        const code = error.code;
+        // Windows does not implement POSIX permission bits consistently.
+        if (process.platform !== "win32" && code !== "EPERM")
+            throw error;
+    }
+}
+export async function ensureSummerStore() {
+    const dir = getSummerDir();
+    try {
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        const info = await lstat(dir);
+        if (info.isSymbolicLink() || !info.isDirectory()) {
+            throw new SummerStoreError("unsafe_store_directory", `${dir} must be a real directory, not a file or symlink. Recovery: move it aside, create a directory at ${dir}, and run the command again.`);
+        }
+        await hardenMode(dir, 0o700);
+        return dir;
+    }
+    catch (error) {
+        if (error instanceof SummerStoreError)
+            throw error;
+        throw new SummerStoreError("store_unavailable", `Cannot secure ${dir}. Recovery: make sure the directory is owned and writable by your user, then run the command again.`);
+    }
+}
+async function assertSafeExistingFile(path) {
+    try {
+        const info = await lstat(path);
+        if (info.isSymbolicLink() || !info.isFile()) {
+            throw new SummerStoreError("unsafe_store_file", `${path} must be a regular file, not a directory or symlink. Recovery: move it aside and run the command again.`);
+        }
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export async function readStoreText(name) {
+    const path = storePath(name);
+    if (!(await assertSafeExistingFile(path)))
+        return null;
+    try {
+        await hardenMode(path, 0o600);
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error instanceof SummerStoreError)
+            throw error;
+        throw new SummerStoreError("store_read_failed", `Cannot read ${path}. Recovery: make sure the file is owned and readable by your user, then run the command again.`);
+    }
+}
+export async function readStoreJson(name) {
+    const raw = await readStoreText(name);
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new SummerStoreError("invalid_store_json", `${storePath(name)} is not valid JSON. Recovery: move that file aside and run the command again.`);
+    }
+}
+export async function writeStoreText(name, value) {
+    const dir = await ensureSummerStore();
+    const destination = storePath(name);
+    await assertSafeExistingFile(destination);
+    const temporary = join(dir, `.${name}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, value, {
+            encoding: "utf8",
+            mode: 0o600,
+            flag: "wx",
+        });
+        await hardenMode(temporary, 0o600);
+        await rename(temporary, destination);
+        await hardenMode(destination, 0o600);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        if (error instanceof SummerStoreError)
+            throw error;
+        throw new SummerStoreError("store_write_failed", `Cannot write ${destination}. Recovery: make sure ${dir} is owned and writable by your user, then run the command again.`);
+    }
+}
+export async function writeStoreJson(name, value) {
+    await writeStoreText(name, `${JSON.stringify(value, null, 2)}\n`);
+}
+export async function appendStoreJsonLine(name, value) {
+    await ensureSummerStore();
+    const path = storePath(name);
+    await assertSafeExistingFile(path);
+    try {
+        await appendFile(path, `${JSON.stringify(value)}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        await hardenMode(path, 0o600);
+    }
+    catch {
+        throw new SummerStoreError("store_append_failed", `Cannot append to ${path}. Recovery: make sure the file is owned and writable by your user, then run the command again.`);
+    }
+}
+export async function removeStoreFile(name) {
+    const path = storePath(name);
+    if (!(await assertSafeExistingFile(path)))
+        return false;
+    try {
+        await rm(path);
+        return true;
+    }
+    catch {
+        throw new SummerStoreError("store_remove_failed", `Cannot remove ${path}. Recovery: make sure the file is owned and writable by your user, then run the command again.`);
+    }
+}

package/dist/lib/summer-compatibility.d.ts

@@ -0,0 +1,6 @@
+export declare const SUMMER_ENGINE_COMPATIBILITY: Readonly<{
+    currentTechnicalBaseVersion: "4.6.1";
+    projectFeatureTag: string;
+    plannedNextTechnicalBaseVersion: "4.7.1";
+    upstreamPolicy: "continuous-upstream";
+}>;

package/dist/lib/summer-compatibility.js

@@ -0,0 +1,22 @@
+/**
+ * Summer CLI compatibility values.
+ *
+ * Keep the current technical base in one place. The project feature tag is
+ * derived from it so `summer create` cannot drift to a different line. This
+ * source is cross-checked against the repository compatibility contract by
+ * `summer-compatibility.test.ts`.
+ */
+const CURRENT_TECHNICAL_BASE_VERSION = "4.6.1";
+function featureTagFor(version) {
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(version);
+    if (!match) {
+        throw new Error(`Invalid Summer Engine technical base version: ${version}`);
+    }
+    return `${match[1]}.${match[2]}`;
+}
+export const SUMMER_ENGINE_COMPATIBILITY = Object.freeze({
+    currentTechnicalBaseVersion: CURRENT_TECHNICAL_BASE_VERSION,
+    projectFeatureTag: featureTagFor(CURRENT_TECHNICAL_BASE_VERSION),
+    plannedNextTechnicalBaseVersion: "4.7.1",
+    upstreamPolicy: "continuous-upstream",
+});

package/dist/mcp/server.d.ts

@@ -1,6 +1,13 @@
 import { EngineApiClient } from "../lib/api-client.js";
+import type { EngineSelection } from "../lib/engine.js";
 import { getCachedBootDriftNotice as getCachedNotice } from "../lib/mcp-boot-notice.js";
 export declare const getCachedBootDriftNotice: typeof getCachedNotice;
+export declare function configureMcpEngineSelection(selection?: EngineSelection): void;
 export declare function getClient(): Promise<EngineApiClient>;
 export declare function resetClient(): void;
-export declare function startMcpServer(): Promise<void>;
+export interface StartMcpServerOptions {
+    projectPath?: string;
+    instanceId?: string;
+    cwd?: string;
+}
+export declare function startMcpServer(options?: StartMcpServerOptions): Promise<void>;

package/dist/mcp/server.js

@@ -11,6 +11,7 @@ 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";
@@ -31,6 +32,11 @@ async function probeBootDrift() {
     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
@@ -46,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'.");
@@ -203,13 +213,23 @@ function installResultSizeLogger(server) {
     };
     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",
@@ -226,6 +246,7 @@ export async function startMcpServer() {
     registerAssetTools(server);
     registerGenerateTools(server);
     registerCloudTools(server);
+    registerCreatorTools(server);
     // Fire-and-forget — never block tool registration on the npm registry.
     void probeBootDrift().catch((error) => {
         setCachedBootDriftNotice(null);

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;