summer-engine 3.8.0 → 4.2.0

package/dist/mcp/command.js

@@ -1,14 +1,21 @@
 import { Command, Option } from "commander";
 import { configureAgentMcp, parseAgent, parseScope, supportedAgents, } from "../installer/agent-config.js";
 import { startMcpServer } from "./server.js";
+import { TOOLSETS } from "./tool-surface.js";
 export const mcpCommand = new Command("mcp")
     .description("Start the MCP server for AI tool integration (Cursor, Claude Code, etc.)")
     .option("--project <path>", "Bind local engine tools to the editor running this project")
     .option("--instance <id>", "Bind local engine tools to one exact Summer editor instance")
+    .option("--profile <profile>", "Tool profile: full (every tool, the default), engine (engine, generation and the store; under 128 tools), assets (generation and the asset library, no engine). Env: SUMMER_PROFILE")
+    .option("--toolsets <list>", `Comma-separated toolsets to add (alone: core plus these): ${TOOLSETS.join(", ")}, or all. Env: SUMMER_TOOLSETS`)
+    .option("--surface <surface>", "Tool surface: v4 (the default: engine tools, summer_search and summer_call for the operation catalog) or v3 (the 3.x tools). Env: SUMMER_SURFACE")
     .action(async (opts) => {
     await startMcpServer({
         projectPath: opts.project,
         instanceId: opts.instance,
+        profile: opts.profile,
+        toolsets: opts.toolsets,
+        surface: opts.surface,
     });
 });
 // Deprecated alias. `summer setup <agent>` (src/cli/commands/setup.ts) is the

package/dist/mcp/hosted-mount.d.ts

@@ -1,4 +1,5 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Tool } from "@modelcontextprotocol/sdk/types.js";
 import { type HostedClient, type HostedConnectDependencies } from "../core/hosted-mcp.js";
 export type { HostedClient };
 /**
@@ -30,6 +31,8 @@ export interface HostedMountState {
     resources: string[];
     /** Hosted names the local MCP already defines (kept local). */
     collisions: string[];
+    /** Hosted tools left out because the server's tool limit was reached. */
+    overLimit: string[];
     error?: {
         code: string;
         message: string;
@@ -42,9 +45,31 @@ export interface HostedMountState {
  * reports each mounted tool's own JSON Schema rather than the passthrough one.
  * Returns mount(), which callers run after connect without awaiting it.
  */
-export declare function prepareHostedMount(server: McpServer, deps?: HostedMountDependencies, options?: {
+/** Fields and handling this package adds around a hosted tool (the v4 surface saves generated files here). */
+export interface HostedLocalHook {
+    /** The input schema a client lists for the tool. */
+    inputSchema(tool: Tool): Tool["inputSchema"];
+    /** Runs the call; `forward` sends arguments on to the hosted tool, `tool` is its listing (annotations included). */
+    call(name: string, args: Record<string, unknown>, forward: (args: Record<string, unknown>) => Promise<Record<string, unknown>>, tool: Tool): Promise<Record<string, unknown>>;
+}
+export interface HostedMountOptions {
     firstListWaitMs?: number;
-}): {
+    /** The profile's filter: false leaves a hosted tool out. Default: every tool. */
+    includeTool?: (name: string) => boolean;
+    /** Mount no tool once the server has this many. Default: no limit. */
+    maxTools?: number;
+    /** The description a mounted tool gets here. Default: the hosted one. */
+    describe?: (tool: Tool) => string;
+    /** Runs after each successful mount (another mount can follow it). */
+    onMounted?: () => void;
+    /** What summer_store_tools calls the hosted tools this profile mounts.
+     *  Default: the full profile's store, publishing, board and Grow tools. */
+    hostedToolsLabel?: string;
+    /** Local fields and handling around each mounted tool. Default: none. */
+    local?: HostedLocalHook;
+}
+export declare function prepareHostedMount(server: McpServer, deps?: HostedMountDependencies, options?: HostedMountOptions): {
     mount: () => Promise<HostedMountState>;
     state: HostedMountState;
+    call: (name: string, args: Record<string, unknown>) => Promise<Record<string, unknown>>;
 };

package/dist/mcp/hosted-mount.js

@@ -1,6 +1,6 @@
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-import { connectHostedMcp } from "../core/hosted-mcp.js";
+import { connectHostedMcp, hostedConnectFailure, HostedUnreachableError, withV3Surface } from "../core/hosted-mcp.js";
 import { getStoreAccessToken, OAuthError, resolveMcpResourceUrl } from "../core/oauth.js";
 import { appendMcpLogEvent } from "../core/mcp-log.js";
 import { providerSafeSchema } from "./provider-safe-schema.js";
@@ -26,7 +26,7 @@ export const STORE_TOOLS_STATUS = "summer_store_tools";
 export const FIRST_LIST_WAIT_MS = 5_000;
 const passthroughArgs = z.object({}).passthrough();
 export const defaultHostedMountDependencies = {
-    url: () => resolveMcpResourceUrl(),
+    url: () => withV3Surface(resolveMcpResourceUrl()),
     token: () => getStoreAccessToken(),
     connect: connectHostedMcp,
 };
@@ -45,16 +45,10 @@ async function listAll(page, key) {
 function errorText(error) {
     return { content: [{ type: "text", text: JSON.stringify({ ok: false, ...error }) }], isError: true };
 }
-/**
- * Get the server ready for hosted tools before the transport connects (the
- * SDK fixes capabilities at connect): resource handlers exist, and tools/list
- * reports each mounted tool's own JSON Schema rather than the passthrough one.
- * Returns mount(), which callers run after connect without awaiting it.
- */
 export function prepareHostedMount(server, deps = defaultHostedMountDependencies, options = {}) {
     const firstListWaitMs = options.firstListWaitMs ?? FIRST_LIST_WAIT_MS;
     let listed = false;
-    const state = { status: "idle", tools: [], prompts: [], resources: [], collisions: [] };
+    const state = { status: "idle", tools: [], prompts: [], resources: [], collisions: [], overLimit: [] };
     const schemas = new Map();
     const registries = server;
     // Declare the resources capability now: registering one and removing it
@@ -74,7 +68,7 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
                 ...result,
                 tools: result.tools.map((tool) => {
                     const hosted = schemas.get(tool.name);
-                    return hosted ? { ...tool, inputSchema: providerSafeSchema(hosted.inputSchema), ...(hosted.annotations ? { annotations: hosted.annotations } : {}), ...(hosted.title ? { title: hosted.title } : {}) } : tool;
+                    return hosted ? { ...tool, inputSchema: providerSafeSchema(options.local ? options.local.inputSchema(hosted) : hosted.inputSchema), ...(hosted.annotations ? { annotations: hosted.annotations } : {}), ...(hosted.title ? { title: hosted.title } : {}) } : tool;
                 }),
             };
         });
@@ -93,6 +87,8 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
     }
     let statusTool = null;
     let running = null;
+    let connected = null;
+    const listedToolCount = () => Object.values(registries._registeredTools).filter((tool) => tool.enabled !== false).length;
     /** Wait for a mount in progress, at most ms; returns at once when none runs. */
     async function waitForMount(ms) {
         if (!running || ms <= 0)
@@ -105,8 +101,12 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
         if (statusTool || STORE_TOOLS_STATUS in registries._registeredTools)
             return;
         statusTool = server.registerTool(STORE_TOOLS_STATUS, {
-            description: "The Summer store, publishing, board and Grow tools come from the hosted Summer Engine MCP and are not loaded. Call this to see why and how to fix it (usually: run \"summer login --store\" in a terminal); it loads them when the sign-in works.",
+            title: "Load the hosted Summer tools",
+            description: `The ${options.hostedToolsLabel ?? "Summer store, publishing, board and Grow tools"} come from the hosted Summer Engine MCP and are not loaded. Call this to see why and how to fix it (usually: run "summer login --store" in a terminal); it loads them when the sign-in works.`,
             inputSchema: passthroughArgs,
+            // Registered after the server's annotation pass, so it carries its own:
+            // it asks Summer's servers which tools this sign-in may use and changes nothing.
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
         }, async () => {
             const after = await mount();
             if (after.status === "mounted") {
@@ -124,14 +124,12 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
         }
         catch (error) {
             state.status = "unavailable";
-            state.error =
-                error instanceof OAuthError
-                    ? { code: error.code, message: error.message.replace(` ${error.recovery}`, ""), recovery: error.recovery }
-                    : {
-                        code: "store_tools_unreachable",
-                        message: `The hosted Summer Engine MCP did not answer: ${error instanceof Error ? error.message : String(error)}.`,
-                        recovery: 'Recovery: check the network; if it says unauthorized, run "summer login --store --force". Then call summer_store_tools.',
-                    };
+            const failure = hostedConnectFailure(error, 'Recovery: check the network; if it says unauthorized, run "summer login --store --force". Then call summer_store_tools.');
+            state.error = {
+                code: failure instanceof OAuthError ? failure.code : "store_tools_unreachable",
+                message: failure.message.replace(` ${failure.recovery}`, ""),
+                recovery: failure.recovery,
+            };
             appendMcpLogEvent("mcp:hosted_mount_failed", { code: state.error.code });
             showStatusTool();
             return state;
@@ -149,10 +147,19 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
             }
             if (schemas.has(tool.name))
                 continue;
+            if (options.includeTool && !options.includeTool(tool.name))
+                continue;
+            // The limit is on what a client lists: tools a surface keeps unlisted (v4) do not count.
+            if (options.maxTools !== undefined && listedToolCount() >= options.maxTools) {
+                if (!state.overLimit.includes(tool.name))
+                    state.overLimit.push(tool.name);
+                continue;
+            }
             schemas.set(tool.name, tool);
-            server.registerTool(tool.name, { description: tool.description ?? "", inputSchema: passthroughArgs, ...(tool.annotations ? { annotations: tool.annotations } : {}) }, async (args) => {
+            server.registerTool(tool.name, { description: options.describe ? options.describe(tool) : (tool.description ?? ""), inputSchema: passthroughArgs, ...(tool.annotations ? { annotations: tool.annotations } : {}) }, async (args) => {
                 try {
-                    return (await client.callTool({ name: tool.name, arguments: args }));
+                    const forward = (sent) => client.callTool({ name: tool.name, arguments: sent });
+                    return (options.local ? await options.local.call(tool.name, args, forward, tool) : await forward(args));
                 }
                 catch (error) {
                     return errorText({
@@ -185,9 +192,17 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
         }
         statusTool?.remove();
         statusTool = null;
+        connected = client;
         state.status = "mounted";
         delete state.error;
-        appendMcpLogEvent("mcp:hosted_mounted", { tools: state.tools.length, prompts: state.prompts.length, resources: state.resources.length, collisions: state.collisions.length });
+        options.onMounted?.();
+        appendMcpLogEvent("mcp:hosted_mounted", {
+            tools: state.tools.length,
+            prompts: state.prompts.length,
+            resources: state.resources.length,
+            collisions: state.collisions.length,
+            ...(state.overLimit.length ? { overLimit: state.overLimit } : {}),
+        });
         return state;
     }
     /** Mount once; a failed mount runs again on the next call. */
@@ -209,5 +224,20 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
         }
         return running;
     }
-    return { mount, state };
+    /**
+     * Call a hosted tool whether or not it is listed here (the v4 surface's
+     * summer_search and summer_call stay local and forward through this).
+     */
+    async function call(name, args) {
+        const after = await mount();
+        if (!connected) {
+            const error = after.error ?? { code: "store_tools_unavailable", message: "The hosted Summer server is not connected.", recovery: 'Recovery: run "summer login".' };
+            // Nothing was sent. A sign-in failure keeps its OAuth code; anything else is the server not answering.
+            if (error.code === "store_tools_unreachable" || error.code === "store_tools_unavailable")
+                throw new HostedUnreachableError(error.message, error.recovery);
+            throw new OAuthError(error.code, error.message, error.recovery);
+        }
+        return connected.callTool({ name, arguments: args });
+    }
+    return { mount, state, call };
 }

package/dist/mcp/legacy-toolset.d.ts

@@ -0,0 +1,27 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { type SkillMarkerCandidate } from "../installer/version-check.js";
+/**
+ * The legacy toolset of the v4 surface (SPEC §8.1, §12.3): every 3.x tool
+ * name listed again, each running as it did in 3.x, each description
+ * starting "3.x name; use <op>." It keeps skills written for 3.x working.
+ *
+ * On when the toolsets name `legacy` (`--toolsets legacy`,
+ * SUMMER_TOOLSETS=legacy), or SUMMER_LEGACY_TOOLS=on, or, unless
+ * SUMMER_LEGACY_TOOLS=off, while the Summer skills installed on this
+ * computer are older than 4.0 (their .summer-version marker).
+ */
+export declare const LEGACY_TOOLSET = "legacy";
+/** `--toolsets` without `legacy`, and whether it was there. */
+export declare function takeLegacyToolset(list: string | undefined): {
+    toolsets: string | undefined;
+    requested: boolean;
+};
+/** True when any installed Summer skills carry a marker older than 4.0. */
+export declare function installedSkillsBefore4(candidates?: SkillMarkerCandidate[]): boolean;
+export type LegacyReason = "toolsets" | "env" | "skills" | "off";
+export declare function resolveLegacy(requested: boolean, env?: NodeJS.ProcessEnv, skillsBefore4?: () => boolean): {
+    on: boolean;
+    reason: LegacyReason;
+};
+/** A hosted 3.x tool's description in the legacy toolset: its operation, then its first sentence. */
+export declare function legacyHostedDescription(tool: Pick<Tool, "name" | "description">): string;

package/dist/mcp/legacy-toolset.js

@@ -0,0 +1,43 @@
+import { resolveOpName } from "../core/ops/contract.js";
+import { defaultSkillMarkerCandidates, readSkillMarker } from "../installer/version-check.js";
+/**
+ * The legacy toolset of the v4 surface (SPEC §8.1, §12.3): every 3.x tool
+ * name listed again, each running as it did in 3.x, each description
+ * starting "3.x name; use <op>." It keeps skills written for 3.x working.
+ *
+ * On when the toolsets name `legacy` (`--toolsets legacy`,
+ * SUMMER_TOOLSETS=legacy), or SUMMER_LEGACY_TOOLS=on, or, unless
+ * SUMMER_LEGACY_TOOLS=off, while the Summer skills installed on this
+ * computer are older than 4.0 (their .summer-version marker).
+ */
+export const LEGACY_TOOLSET = "legacy";
+/** `--toolsets` without `legacy`, and whether it was there. */
+export function takeLegacyToolset(list) {
+    if (list === undefined)
+        return { toolsets: undefined, requested: false };
+    const parts = list.split(",").map((part) => part.trim());
+    const rest = parts.filter((part) => part.toLowerCase() !== LEGACY_TOOLSET);
+    return { toolsets: rest.filter(Boolean).join(","), requested: rest.length !== parts.length };
+}
+/** True when any installed Summer skills carry a marker older than 4.0. */
+export function installedSkillsBefore4(candidates = defaultSkillMarkerCandidates()) {
+    return candidates.some((candidate) => {
+        const major = Number.parseInt(readSkillMarker(candidate.dir)?.version.split(".")[0] ?? "", 10);
+        return Number.isFinite(major) && major < 4;
+    });
+}
+export function resolveLegacy(requested, env = process.env, skillsBefore4 = installedSkillsBefore4) {
+    if (requested)
+        return { on: true, reason: "toolsets" };
+    const forced = (env.SUMMER_LEGACY_TOOLS ?? "").trim().toLowerCase();
+    if (forced === "on")
+        return { on: true, reason: "env" };
+    if (forced === "off")
+        return { on: false, reason: "off" };
+    return skillsBefore4() ? { on: true, reason: "skills" } : { on: false, reason: "off" };
+}
+/** A hosted 3.x tool's description in the legacy toolset: its operation, then its first sentence. */
+export function legacyHostedDescription(tool) {
+    const first = (tool.description ?? "").split(/(?<=\.)\s/)[0]?.slice(0, 200) ?? "";
+    return `3.x name; use ${resolveOpName(tool.name)}. ${first}`.trim();
+}

package/dist/mcp/ops-surface.d.ts

@@ -0,0 +1,59 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import { type FileSaver } from "../core/ops/save-files.js";
+import type { HostedLocalHook } from "./hosted-mount.js";
+/**
+ * The v4 surface of the local MCP (`summer mcp --surface v4`, SUMMER_SURFACE=v4):
+ * one catalog of Summer operations instead of one tool per feature.
+ *
+ * - Listed: the engine operations under their 3.x names (the core build loop
+ *   keeps its tools) plus the operations split out of mixed 3.x tools,
+ *   docs.search and docs.read, the hosted server's direct tools (mounted from
+ *   its v4 surface), summer_search and summer_call.
+ * - An engine tool here is its operation: a short summary (the how-to is its
+ *   guide, docs.read tool/<slug>), annotations from its effect, and the one
+ *   answer shape, with engine_not_running and the other codes instead of
+ *   plain text.
+ * - Every other local 3.x tool stays registered but unlisted: summer_call
+ *   runs it by its operation name or its old name, through the same handler.
+ *   The legacy toolset lists them again under their 3.x names.
+ * - Cloud operations run on the hosted server: summer_call forwards them to
+ *   the hosted summer_call with the person's sign-in; summer_search merges
+ *   the hosted hits with the local ones.
+ */
+export declare const SUMMER_SEARCH = "summer_search";
+export declare const SUMMER_CALL = "summer_call";
+export declare const OPS_MCP_INSTRUCTIONS: string;
+/** The assets profile's version: no engine tools, so it names none. */
+export declare const OPS_MCP_ASSETS_INSTRUCTIONS: string;
+/** Runs a tool on the hosted server's v4 surface (hosted-mount.ts). */
+export interface CloudCaller {
+    call(name: string, args: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+export interface OpsSurfaceOptions {
+    /** Keep the engine operations listed (profiles with engine tools). */
+    engine: boolean;
+    cloud: CloudCaller;
+    /** The legacy toolset: list every local 3.x name too, each running as it did in 3.x. */
+    legacy?: boolean;
+    /** Saves generated files on this machine (`out`, localPath); shared with the mounted hosted tools. */
+    files: FileSaver;
+}
+/** Its v4 description, within the 300-character summary rule; the full text stays on the 3.x surface. */
+export declare const ENGINE_REFERENCE_SUMMARY = "Look up an engine class offline before writing script code: inherits, properties, methods, signals and constants, or one member. Lists only members declared on that class (walk inherits). No engine needed. Next: summer_run_script.";
+/** The read footer in this surface's words: feedback goes through summer_call (docs.feedback is not listed). */
+export declare const V4_FOOTER_SUFFIX = "If this entry is wrong, stale, or you deviate from it, report via summer_call {\"op\":\"docs.feedback\"}.";
+/** MCP annotations from an operation's effect (SPEC §4.1); engine operations never need a retry key. */
+export declare function annotationsForEffect(effect: "read" | "write", openWorld: boolean, title: string): ToolAnnotations;
+/** A parameter description cut to its whole sentences within PARAM_LIMIT characters; the guide has it whole. */
+export declare function shortParamDescription(text: string): string;
+export declare function v4Text(text: string): string;
+export declare function applyOpsSurface(server: McpServer, options: OpsSurfaceOptions): void;
+/**
+ * The hosted direct tools on the v4 surface. Those that take `out`
+ * (summer_assets_generate_image, summer_assets_get, summer_jobs_wait, ...)
+ * show it in their listed input, and a call keeps it here and saves the files
+ * the answer names. A call that throws answers in the one shape too
+ * (hostedCallFailure), never with a plain "retry".
+ */
+export declare function hostedFileTools(files: FileSaver): HostedLocalHook;