@shardflux/mcp 0.3.0

package/dist/server.js

@@ -0,0 +1,687 @@
+/**
+ * Local stdio MCP server for Shardflux workspaces. It translates MCP tool
+ * calls into @shardflux/sdk calls made with the supplied scoped API key:
+ *
+ *   - workspace management: workspace_open / _list / _status / _suspend /
+ *     _resume / _fork, operation_wait, usage_summary;
+ *   - templates (0.3.0): template_get (versions, settings, a version's recipe), template_languages and
+ *     template_build (a recipe v2 object or a template.yaml path inside the
+ *     server's working directory; local `from` paths are uploaded by the SDK);
+ *   - the SDK's workspace tools (`workspaceTools()`: exec, files, processes,
+ *     terminal, git, browser), published with the SDK's own JSON Schemas plus
+ *     `workspace_key` (and `timeout_ms` where the SDK schema has none).
+ *
+ * There is no agent loop and no local workspace directory: every call is one
+ * SDK request/wait against the remote workspace. Workspace tools wake a
+ * suspended workspace on use (SHARDFLUX_WAKE, bounded by
+ * SHARDFLUX_WAKE_TIMEOUT_MS and the call's deadline). Each call has a deadline
+ * (`timeout_ms`, clamped to SHARDFLUX_MCP_TOOL_TIMEOUT_MS) and MCP cancellation
+ * (notifications/cancelled -> `extra.signal`) aborts the underlying SDK
+ * request or wait. Failures come back as `isError` tool results carrying the
+ * API error code. stdout is the protocol; logs go to stderr. Opens, waits and
+ * wakes carry the SDK's lifecycle timing, compacted (`compactTiming`).
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { resolve as resolvePath } from 'node:path';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { SDK_VERSION, Shardflux, ShardfluxApiError, TemplateBuildTimeoutError, TemplateFileError, validateArgs, workspaceTools } from '@shardflux/sdk';
+import { parse as parseYaml } from 'yaml';
+import { DEFAULT_WAKE_TIMEOUT_MS } from "./config.js";
+import { ToolError, describeToolError, redact } from "./errors.js";
+import { makeFetch } from "./http.js";
+export const MCP_SERVER_VERSION = '0.3.0';
+export const ALL_TOOL_PERMISSIONS = ['exec', 'files', 'pty', 'process', 'git', 'browser'];
+const OBSERVED_STATES = ['creating', 'starting', 'running', 'suspending', 'suspended', 'resuming', 'forking', 'stopping', 'failed', 'deleting', 'deleted'];
+/**
+ * The SDK's workspace tool definitions without a workspace. `workspaceTools()`
+ * only touches the workspace inside `execute`, which is never called on these:
+ * the proxy throws on any access, so a change in the SDK that did would fail loudly.
+ */
+export function sdkToolDefinitions(tools = ALL_TOOL_PERMISSIONS) {
+    const noWorkspace = new Proxy({}, {
+        get(_t, prop) {
+            throw new Error(`workspace tool definitions must not access workspace.${String(prop)}`);
+        },
+    });
+    return workspaceTools(noWorkspace, { tools: [...tools] });
+}
+function timeoutProp(ceiling) {
+    return { type: 'integer', minimum: 1, maximum: 3_600_000, description: `Deadline for this call in milliseconds (default and maximum ${ceiling}; larger values are clamped).` };
+}
+function workspaceKeyProp(pinned) {
+    return pinned
+        ? { type: 'string', minLength: 1, maxLength: 200, description: `Workspace key. Optional: this server is pinned to "${pinned}" and only accepts that key.` }
+        : { type: 'string', minLength: 1, maxLength: 200, description: 'Workspace key, e.g. "customer-42/repo-7" (the stable name the workspace was opened with).' };
+}
+const capsProps = {
+    cpu_millis: { type: 'integer', minimum: 1, maximum: 1_000_000, description: 'Optional CPU cap in millicores (the ceiling is min(template, cap, plan)).' },
+    memory_mib: { type: 'integer', minimum: 1, maximum: 16_777_216, description: 'Optional memory cap in MiB.' },
+    disk_gib: { type: 'integer', minimum: 1, maximum: 1_000_000, description: 'Optional disk cap in GiB.' },
+};
+function capsFrom(args) {
+    const c = {};
+    if (typeof args.cpu_millis === 'number')
+        c.cpu_millis = args.cpu_millis;
+    if (typeof args.memory_mib === 'number')
+        c.memory_mib = args.memory_mib;
+    if (typeof args.disk_gib === 'number')
+        c.disk_gib = args.disk_gib;
+    return Object.keys(c).length ? c : undefined;
+}
+/** What tools return for a workspace (no tokens or other credentials). */
+export function summarizeWorkspace(v) {
+    return {
+        id: v.id,
+        key: v.workspace_key,
+        ready: v.observed_state === 'running' && v.desired_state === 'running' && v.deleted_at === null,
+        observed_state: v.observed_state,
+        desired_state: v.desired_state,
+        template: { slug: v.template.slug, version: v.template.version },
+        active_operation: v.active_operation ? summarizeOperation(v.active_operation) : null,
+        pending_reason: v.pending_reason,
+        cell_endpoint: v.cell_endpoint,
+        grants: v.grants,
+        ceilings: v.ceilings ? { cpu_millis: v.ceilings.cpu_millis, memory_mib: v.ceilings.memory_mib, disk_gib: v.ceilings.disk_gib } : null,
+        forked_from_workspace_id: v.forked_from_workspace_id,
+        lifetime: v.lifetime,
+        purpose: v.purpose,
+        disk_layout: v.disk_layout,
+        idle_timeout_seconds: v.idle_timeout_seconds,
+        ended_reason: v.ended_reason,
+        /** Start commands and services of the template version; null when it has none. */
+        startup: v.startup ?? null,
+        created_at: v.created_at,
+        deleted_at: v.deleted_at,
+    };
+}
+/** A template build without the stored recipe (the compiled steps are long): state, version and what the builder refused. */
+export function summarizeBuild(b) {
+    return {
+        id: b.id,
+        template: { slug: b.template.slug, name: b.template.name },
+        target_version: b.target_version,
+        state: b.state,
+        registration: b.registration,
+        template_version: b.template_version,
+        auto_publish: b.auto_publish,
+        failure: b.failure,
+        denied_hosts: b.denied_hosts ?? [],
+        network: b.network,
+        recipe_sha256: b.provenance.recipe_sha256,
+        builder_availability: b.builder_availability.state,
+        created_at: b.created_at,
+        completed_at: b.completed_at,
+        log_tail: b.log.tail ?? null,
+    };
+}
+/** A template for model context: identity, what open resolves to, every version with its settings. */
+export function summarizeTemplate(t) {
+    return {
+        slug: t.slug,
+        name: t.name,
+        owner: t.owner,
+        category: t.category ?? null,
+        open_resolves_to: t.open_resolves_to ? { version: t.open_resolves_to.version, owner: t.open_resolves_to.owner } : null,
+        draft: t.draft ? { workspace_key: t.draft.workspace_key, observed_state: t.draft.observed_state, base_version: t.draft.base_version.version } : null,
+        versions: t.versions.map((v) => ({
+            version: v.version,
+            state: v.state,
+            is_open_version: v.is_open_version,
+            description: v.description,
+            source: v.source?.kind ?? null,
+            disk_layouts: v.disk_layouts,
+            installed_tools: v.installed_tools,
+            settings: v.settings ?? null,
+            created_at: v.created_at,
+        })),
+        versions_truncated: t.versions_truncated,
+    };
+}
+export function summarizeOperation(o) {
+    return {
+        id: o.id,
+        kind: o.kind,
+        state: o.state,
+        state_reason: o.state_reason ?? null,
+        workspace_id: o.workspace_id,
+        created_at: o.created_at,
+        completed_at: o.completed_at ?? null,
+        ...(o.error ? { error: o.error } : {}),
+    };
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * The SDK's LifecycleTiming, compact enough for model context: where an open, a wait or a wake spent its time. Phases
+ * are `phase(reason) ms` in order (`request(held)`: the server held the open; `capacity_pending(no_ready_host)`:
+ * waiting for a host); `server` is the operation's own queued/run/total time; `outside_server_ms` is the rest
+ * (network, polling, view and token).
+ */
+export function compactTiming(t) {
+    const ms = (v) => (v === null ? null : Math.round(v));
+    const s = t.server;
+    return {
+        action: t.action,
+        outcome: t.outcome,
+        ...(t.operationId ? { operation_id: t.operationId } : {}),
+        total_ms: Math.round(t.totalMs),
+        phases: t.phases.map((p) => `${p.phase}${p.reason ? `(${p.reason})` : ''} ${Math.round(p.durationMs)} ms`),
+        server: s
+            ? {
+                queued_ms: ms(s.queuedMs),
+                run_ms: ms(s.runMs),
+                total_ms: ms(s.totalMs),
+                ...(s.startPath ? { start_path: s.startPath } : {}),
+                ...(s.warmFallback ? { warm_fallback: s.warmFallback } : {}),
+                ...(s.resumePath ? { resume_path: s.resumePath } : {}),
+            }
+            : null,
+        outside_server_ms: ms(t.outsideServerMs),
+        retries: t.retries.length,
+    };
+}
+export function okResult(value) {
+    if (isObject(value) && value.mime_type === 'image/png' && typeof value.data_base64 === 'string') {
+        const { data_base64: data, ...meta } = value;
+        return { content: [{ type: 'image', data, mimeType: 'image/png' }, { type: 'text', text: JSON.stringify(meta) }], structuredContent: meta };
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }], structuredContent: isObject(value) ? value : { result: value } };
+}
+/** `timing` (optional): where the failed open/wait/wake spent its time, next to `error`. */
+export function errorResult(info, timing) {
+    const body = timing ? { error: info, timing } : { error: info };
+    return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }], structuredContent: body, isError: true };
+}
+const INSTRUCTIONS = [
+    'Shardflux persistent remote workspaces (Linux computers that keep files, packages and processes between sessions).',
+    'Call workspace_open first (it creates the workspace on first use and reconnects afterwards, never resetting it), then use exec, read_file, write_file and the other workspace tools with the same workspace_key.',
+    'Lifecycle calls return operations; operation_wait keeps waiting. Workspace tools resume a suspended workspace on use; if that takes too long the error (code timeout) names the operation to pass to operation_wait. Errors are tool results with error.code from the Shardflux API.',
+    'A start (open, resume, fork) that no host can admit waits for capacity for at most 15 minutes, then fails with code operation_failed, details.error_code capacity_unavailable and retryable true: nothing was started; retry later if you still need it. retryable false means retrying will not help.',
+    'Opens, waits and wakes add timing (phases, server queued/run time) saying where the time went.',
+    'Templates: template_get shows a template’s versions and settings (the inputs workspace_open takes); template_languages lists what a base offers build.languages; template_build builds a new version from a recipe v2 (unpublished unless publish is true).',
+].join(' ');
+/** POST <cell>/v1/workspaces/{id}/exec/{session}/cancel: the cleanup request the SDK sends when a call is aborted. */
+function isExecCancel(input, init) {
+    const method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
+    if (method !== 'POST')
+        return false;
+    const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+    try {
+        return /^\/v1\/workspaces\/[^/]+\/exec\/[^/]+\/cancel$/.test(new URL(url).pathname);
+    }
+    catch {
+        return false;
+    }
+}
+/** `{NAME: "value"}` from a tool argument (undefined when absent); every value must be a string. */
+function stringMap(v, what) {
+    if (v === undefined)
+        return undefined;
+    if (!isObject(v))
+        throw new ToolError('invalid_arguments', `${what} must be an object of NAME: "value"`);
+    for (const [k, x] of Object.entries(v))
+        if (typeof x !== 'string')
+            throw new ToolError('invalid_arguments', `${what}.${k} must be a string`);
+    return v;
+}
+export function createShardfluxMcpServer(config, opts = {}) {
+    const log = opts.log ?? (() => undefined);
+    const cwd = resolvePath(opts.cwd ?? process.cwd());
+    // Each tool call runs with its abort signal (client cancel or deadline) in async context; every
+    // HTTP request the SDK makes for the call (API and cell gateway) and every backoff sleep observe
+    // it, so a canceled or timed-out call leaves no request or poll loop running behind it. The
+    // deadline (epoch ms) bounds a wake inside the call.
+    const ambient = new AsyncLocalStorage();
+    const baseFetch = opts.fetch ?? makeFetch(opts.env ?? {});
+    const callFetch = (input, init) => {
+        const s = ambient.getStore()?.signal;
+        // The SDK's cleanup after an abort (exec.run -> POST .../exec/{session}/cancel) must outlive the canceled
+        // call, or the command keeps running in the workspace; it is bounded by the SDK (5 s) and the HTTP timeout.
+        if (!s || isExecCancel(input, init))
+            return baseFetch(input, init);
+        return baseFetch(input, { ...init, signal: init?.signal ? AbortSignal.any([init.signal, s]) : s });
+    };
+    const callSleep = (ms) => new Promise((resolve) => {
+        const s = ambient.getStore()?.signal;
+        if (s?.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            s?.removeEventListener('abort', done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        s?.addEventListener('abort', done, { once: true });
+    });
+    // Every traced SDK call (open, waited lifecycle calls, waits, wakes; tool-token fetches are skipped) reports to the tool
+    // call it runs in: its operation (for deadline errors) and its timing.
+    const onProgress = (e) => {
+        const call = ambient.getStore()?.call;
+        if (!call || e.action === 'token' || e.action === 'tool')
+            return;
+        if (e.operationId)
+            call.operationId = e.operationId;
+        if (e.type === 'done')
+            call.timing = e.timing;
+    };
+    const cloud = new Shardflux({
+        apiKey: config.apiKey,
+        baseUrl: config.apiUrl,
+        userAgent: `shardflux-mcp/${MCP_SERVER_VERSION} shardflux-sdk-ts/${SDK_VERSION}`,
+        fetch: callFetch,
+        sleep: callSleep,
+        onProgress,
+    });
+    const pinned = config.workspaceKey;
+    const ceiling = config.toolTimeoutMs;
+    const wakeTimeoutMs = Math.min(config.wakeTimeoutMs ?? DEFAULT_WAKE_TIMEOUT_MS, ceiling);
+    /**
+     * Wake on use for a workspace's tools: `workspace.wake()` within the SDK's transition budget (SHARDFLUX_WAKE_TIMEOUT_MS)
+     * and 250 ms short of the call's deadline, so a wake that runs out reports the operation (OperationTimeoutError) rather
+     * than a bare deadline. null when SHARDFLUX_WAKE=off: the refusal (workspace_not_running) comes back instead.
+     */
+    const wakeFor = (ws) => config.wake === false
+        ? null
+        : (timeoutMs, signal) => {
+            const deadline = ambient.getStore()?.deadline;
+            const left = deadline === undefined ? timeoutMs : Math.min(timeoutMs, deadline - Date.now() - 250);
+            return ws.wake({ timeoutMs: Math.max(1, left), ...(signal ? { signal } : {}) });
+        };
+    // ---- principal and workspace resolution ----------------------------------------------------
+    let meCache;
+    const principal = async () => {
+        if (meCache && Date.now() - meCache.at < 60_000)
+            return meCache.me;
+        const me = await cloud.me();
+        meCache = { me, at: Date.now() };
+        return me;
+    };
+    /** Workspace handles by key; keys are never reused, and a handle keeps its tool tokens between calls. */
+    const handles = new Map();
+    const keyOf = (args) => {
+        const given = typeof args.workspace_key === 'string' ? args.workspace_key : undefined;
+        if (pinned !== undefined) {
+            if (given !== undefined && given !== pinned)
+                throw new ToolError('workspace_pinned', `This server is pinned to workspace "${pinned}"; it cannot operate on "${given}".`, { pinned_workspace_key: pinned });
+            return pinned;
+        }
+        if (given === undefined)
+            throw new ToolError('invalid_arguments', 'workspace_key is required.');
+        return given;
+    };
+    /**
+     * The workspace a key names, across every lifetime and purpose (sessions, drafts and test instances are hidden from
+     * the default list), preferring the live workspace over tombstones: an ended session leaves a tombstone with the same
+     * key, and the key then opens a new workspace.
+     */
+    const resolve = async (key, opts2) => {
+        const cached = handles.get(key);
+        if (cached)
+            return cached;
+        const w = await cloud.workspaces.findByKey(key, { includeDeleted: opts2.includeDeleted === true, signal: opts2.signal });
+        if (opts2.signal.aborted)
+            throw opts2.signal.reason;
+        if (w) {
+            if (w.data.deleted_at === null)
+                handles.set(key, w);
+            return w;
+        }
+        throw new ToolError('not_found', `No workspace with key "${key}" in this project. Create or reconnect it with workspace_open.`);
+    };
+    /** The SDK's wait options for a call: its own timeout fires just before the call deadline, so the result names the operation. */
+    const waitOpts = (call) => ({ timeoutMs: Math.max(1, call.timeoutMs - 250), signal: call.signal });
+    const wait = async (call, operationId) => {
+        call.operationId = operationId;
+        call.timed = true;
+        return cloud.workspaces.waitForOperation(operationId, waitOpts(call));
+    };
+    /** Lifecycle calls: `wait: true` is the SDK's own wait (one trace for the request and the wait). */
+    const lifecycleOpts = (args, call) => {
+        if (args.wait !== true)
+            return {};
+        call.timed = true;
+        return { wait: waitOpts(call) };
+    };
+    // ---- management tools ----------------------------------------------------------------------
+    const keyRequired = pinned === undefined ? ['workspace_key'] : [];
+    const obj = (properties, required = []) => ({
+        type: 'object',
+        properties: { ...properties, timeout_ms: timeoutProp(ceiling) },
+        required,
+        additionalProperties: false,
+    });
+    const management = [
+        {
+            name: 'workspace_open',
+            title: 'Open workspace',
+            description: 'Open a persistent workspace by key: creates it from the template on first use, reconnects (or resumes) it afterwards, never resets it. Waits until it is ready unless wait is false; on timeout the start continues server side (operation_wait), for at most 15 minutes while it waits for capacity. The result’s timing says where the time went.',
+            inputSchema: obj({
+                workspace_key: workspaceKeyProp(pinned),
+                template: {
+                    type: 'string',
+                    minLength: 1,
+                    maxLength: 100,
+                    description: config.template ? `Template slug (default "${config.template}").` : 'Template slug for a new workspace, e.g. "python-node-browser".',
+                },
+                ...capsProps,
+                lifetime: {
+                    type: 'string',
+                    enum: ['persistent', 'session'],
+                    description: 'session: the workspace is discarded after it has been idle for its idle timeout (default 10 minutes); the key then opens a new workspace. Default: the template’s default, else persistent.',
+                },
+                inputs: {
+                    type: 'object',
+                    additionalProperties: true,
+                    description: 'Text inputs the template declares, {"NAME": "value"} (template_get shows a version’s settings.inputs): put into the environment of every command, start command and service. Replaces the inputs of an existing workspace; omitted leaves them unchanged. Secret inputs are stored secrets, never passed here.',
+                },
+                wait: { type: 'boolean', description: 'Wait until the workspace is ready, its start commands and services included (default true).' },
+            }, [...keyRequired, ...(config.template ? [] : ['template'])]),
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+            run: async (args, call) => {
+                const key = keyOf(args);
+                const template = typeof args.template === 'string' ? args.template : config.template;
+                if (!template)
+                    throw new ToolError('invalid_arguments', 'template is required (no SHARDFLUX_TEMPLATE is configured).');
+                const caps = capsFrom(args);
+                const lifetime = args.lifetime === 'session' || args.lifetime === 'persistent' ? args.lifetime : undefined;
+                const inputs = stringMap(args.inputs, 'inputs');
+                call.timed = true;
+                // The SDK's waited open: held by the server until ready (Prefer: wait), then polled; the handle it returns
+                // carries the first tool token, so the next tool call starts at once.
+                const ws = await cloud.workspaces.open({ key, template, ...(caps ? { caps } : {}), ...(lifetime ? { lifetime } : {}), ...(inputs ? { inputs } : {}), agentLabel: config.agentLabel, wait: args.wait === false ? false : waitOpts(call) });
+                handles.set(key, ws);
+                return { workspace: summarizeWorkspace(ws.data), ready: ws.ready, ...(ws.ready ? {} : { next: ws.activeOperation ? `operation ${ws.activeOperation.id} is ${ws.activeOperation.state}; call operation_wait or workspace_open again` : 'the workspace is not running' }) };
+            },
+        },
+        {
+            name: 'workspace_list',
+            title: 'List workspaces',
+            description: 'List the workspaces of this API key’s project (key, state, template, active operation).',
+            inputSchema: obj({
+                prefix: { type: 'string', minLength: 1, maxLength: 200, description: 'Only keys starting with this prefix.' },
+                state: { type: 'string', enum: OBSERVED_STATES, description: 'Observed state filter.' },
+                include_deleted: { type: 'boolean', description: 'Include deleted workspaces (and ended sessions).' },
+                lifetime: { type: 'string', enum: ['persistent', 'session', 'any'], description: 'Lifetime filter (default persistent: session workspaces are hidden).' },
+                purpose: { type: 'string', enum: ['standard', 'template_draft', 'template_test', 'any'], description: 'Purpose filter (default standard: template drafts and test instances are hidden).' },
+                limit: { type: 'integer', minimum: 1, maximum: 200, description: 'Page size (default 50).' },
+                cursor: { type: 'string', minLength: 1, maxLength: 200, description: 'next_cursor from a previous call.' },
+            }),
+            annotations: { readOnlyHint: true, openWorldHint: false },
+            run: async (args) => {
+                const page = await cloud.workspaces.list({
+                    ...(typeof args.prefix === 'string' ? { keyPrefix: args.prefix } : {}),
+                    ...(typeof args.state === 'string' ? { state: args.state } : {}),
+                    ...(args.include_deleted === true ? { includeDeleted: true } : {}),
+                    ...(typeof args.lifetime === 'string' ? { lifetime: args.lifetime } : {}),
+                    ...(typeof args.purpose === 'string' ? { purpose: args.purpose } : {}),
+                    limit: typeof args.limit === 'number' ? args.limit : 50,
+                    ...(typeof args.cursor === 'string' ? { cursor: args.cursor } : {}),
+                });
+                return { workspaces: page.data.map((w) => summarizeWorkspace(w.data)), next_cursor: page.nextCursor };
+            },
+        },
+        {
+            name: 'workspace_status',
+            title: 'Workspace status',
+            description: 'Current state of one workspace (ready, observed/desired state, grants, pending reason) and its most recent operations.',
+            inputSchema: obj({ workspace_key: workspaceKeyProp(pinned) }, keyRequired),
+            annotations: { readOnlyHint: true, openWorldHint: false },
+            run: async (args, call) => {
+                const ws = await resolve(keyOf(args), { includeDeleted: true, signal: call.signal });
+                await ws.refresh();
+                const ops = await cloud.workspaces.operations(ws.id, { limit: 5 });
+                return { workspace: summarizeWorkspace(ws.data), recent_operations: ops.data.map(summarizeOperation) };
+            },
+        },
+        lifecycleTool('workspace_suspend', 'Suspend workspace', 'Suspend a running workspace (durable full-state checkpoint; processes stop). Returns the suspend operation (with wait: once finished, and its timing).', (id, o) => cloud.workspaces.suspend(id, o)),
+        lifecycleTool('workspace_resume', 'Resume workspace', 'Resume a suspended workspace. Returns the resume operation (with wait: once finished, and its timing).', (id, o) => cloud.workspaces.resume(id, o)),
+        {
+            name: 'workspace_fork',
+            title: 'Fork workspace',
+            description: 'Fork a running or suspended workspace into a new key (an independent copy of its committed state). Returns the fork operation and the new workspace (with wait: once finished, and its timing).',
+            inputSchema: obj({
+                workspace_key: workspaceKeyProp(pinned),
+                new_key: { type: 'string', minLength: 1, maxLength: 200, description: 'Key of the new workspace.' },
+                ...capsProps,
+                wait: { type: 'boolean', description: 'Wait until the fork finishes (default false).' },
+            }, [...keyRequired, 'new_key']),
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+            run: async (args, call) => {
+                const source = await resolve(keyOf(args), { signal: call.signal });
+                const caps = capsFrom(args);
+                const res = await cloud.workspaces.fork(source.id, { key: String(args.new_key), ...(caps ? { caps } : {}) }, lifecycleOpts(args, call));
+                call.operationId = res.operation.id;
+                return { operation: summarizeOperation(res.operation), workspace: summarizeWorkspace(res.workspace.data) };
+            },
+        },
+        {
+            name: 'operation_wait',
+            title: 'Wait for operation',
+            description: 'Wait for a lifecycle operation (open, suspend, resume, fork, ...) to finish, up to timeout_ms. Returns the operation and the wait’s timing.',
+            inputSchema: obj({ operation_id: { type: 'string', minLength: 36, maxLength: 36, description: 'Operation id (UUID).' } }, ['operation_id']),
+            annotations: { readOnlyHint: true, openWorldHint: false },
+            run: async (args, call) => ({ operation: summarizeOperation(await wait(call, String(args.operation_id))) }),
+        },
+        {
+            name: 'template_get',
+            title: 'Get template',
+            description: 'A template this project can open: its versions (state, source, installed tools) and each version’s settings (env, open-time inputs, start commands, services, defaults). With version, also that version’s recipe in request form (the recipe v2 document template_build takes; null for versions saved from a workspace and platform versions).',
+            inputSchema: obj({
+                slug: { type: 'string', minLength: 1, maxLength: 100, description: 'Template slug, e.g. "python-node-browser" or an organization template.' },
+                version: { type: 'integer', minimum: 1, maximum: 999_999_999, description: 'Also export this version’s recipe.' },
+                owner: { type: 'string', enum: ['platform', 'organization'], description: 'Pick the platform template even when an organization template shadows its slug.' },
+            }, ['slug']),
+            annotations: { readOnlyHint: true, openWorldHint: false },
+            run: async (args) => {
+                const slug = String(args.slug);
+                const owner = args.owner === 'platform' || args.owner === 'organization' ? args.owner : undefined;
+                const detail = await cloud.templates.get(slug, owner ? { owner } : {});
+                const out = { template: summarizeTemplate(detail) };
+                if (typeof args.version === 'number')
+                    out.recipe = await cloud.templates.versions.recipe(slug, args.version, owner ? { owner } : {});
+                return out;
+            },
+        },
+        {
+            name: 'template_languages',
+            title: 'Template languages',
+            description: 'The languages (python, node, go, rust, java) and versions a base offers a recipe v2’s build.languages, e.g. base "ubuntu-24.04@1". included: the base already has that version (nothing is installed); default: what {id} without a version picks. A version the base has another version of is not offered.',
+            inputSchema: obj({ base: { type: 'string', minLength: 3, maxLength: 120, description: 'The base, <slug>@<version> (as recipe.base).' } }, ['base']),
+            annotations: { readOnlyHint: true, openWorldHint: false },
+            run: async (args) => cloud.templates.languages(String(args.base)),
+        },
+        {
+            name: 'template_build',
+            title: 'Build template',
+            description: 'Build a version of an organization template from a recipe v2 (languages, apt/pip/npm packages, files, build steps, and settings: env, inputs, start commands, services). Give either recipe (the document) or file (a template.yaml or .json path inside this server’s working directory). A file entry may name a local `from` path (a file, or a folder copied as a tar) relative to the template file (to the working directory for recipe); it is uploaded first. The version stays unpublished unless publish is true. Returns the build; with wait, once it is registered or failed (denied_hosts lists hosts the build needed but its network refused).',
+            inputSchema: obj({
+                template_slug: { type: 'string', minLength: 1, maxLength: 100, description: 'Organization template to build into (created by the first build).' },
+                file: { type: 'string', minLength: 1, maxLength: 4096, description: 'template.yaml (or .json) path, relative to the server’s working directory.' },
+                recipe: { type: 'object', additionalProperties: true, description: 'The recipe v2 document: {schema: "shardflux.template-recipe.v2", base: "<slug>@<version>", build: {...}, settings: {...}}.' },
+                display_name: { type: 'string', minLength: 1, maxLength: 200, description: 'Template name when this build creates the template.' },
+                description: { type: 'string', minLength: 1, maxLength: 2000, description: 'Version description.' },
+                publish: { type: 'boolean', description: 'Publish the version once it is registered (new workspaces of the slug then use it). Default false.' },
+                wait: { type: 'boolean', description: 'Wait until the build is registered or failed, up to timeout_ms (default false: return the queued build).' },
+            }, ['template_slug']),
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+            run: async (args, call) => {
+                const hasFile = typeof args.file === 'string';
+                const hasRecipe = isObject(args.recipe);
+                if (hasFile === hasRecipe)
+                    throw new ToolError('invalid_arguments', 'Give exactly one of file (a template.yaml path) or recipe (the recipe v2 document).');
+                const common = {
+                    templateSlug: String(args.template_slug),
+                    ...(typeof args.display_name === 'string' ? { displayName: args.display_name } : {}),
+                    ...(typeof args.description === 'string' ? { description: args.description } : {}),
+                    autoPublish: args.publish === true,
+                    root: cwd,
+                    signal: call.signal,
+                    ...(args.wait === true ? { wait: { timeoutMs: Math.max(1, call.timeoutMs - 250), signal: call.signal } } : {}),
+                };
+                let res;
+                try {
+                    res = hasFile
+                        ? await cloud.templates.buildFromFile(resolvePath(cwd, String(args.file)), { ...common, parseYaml: (text) => parseYaml(text) })
+                        : await cloud.templates.buildFromRecipe(args.recipe, { ...common, baseDir: cwd });
+                }
+                catch (err) {
+                    if (err instanceof TemplateFileError)
+                        throw new ToolError('invalid_arguments', err.message);
+                    if (err instanceof TemplateBuildTimeoutError) {
+                        throw new ToolError('timeout', `${err.message}; the build continues server side (template_get shows the version once it is registered).`, { build_id: err.build.id, state: err.build.state });
+                    }
+                    throw err;
+                }
+                return { build: summarizeBuild(res.build), uploads: res.uploads.map((u) => ({ from: u.from, to: u.to, kind: u.kind, sha256: u.sha256, size: u.size, entries: u.entries, uploaded: u.uploaded })) };
+            },
+        },
+        {
+            name: 'usage_summary',
+            title: 'Usage summary',
+            description: 'Usage of the organization in the current billing period: each meter’s raw, billable and included quantity and cap state.',
+            inputSchema: obj({ organization_id: { type: 'string', minLength: 36, maxLength: 36, description: 'Organization id (default: the API key’s organization).' } }),
+            annotations: { readOnlyHint: true, openWorldHint: false },
+            run: async (args, call) => {
+                const org = typeof args.organization_id === 'string' ? args.organization_id : (await principal()).api_key?.organization_id;
+                if (!org)
+                    throw new ToolError('invalid_arguments', 'organization_id is required.');
+                return cloud.request('GET', `/v1/organizations/${encodeURIComponent(org)}/usage/summary`, { signal: call.signal });
+            },
+        },
+    ];
+    function lifecycleTool(name, title, description, start) {
+        return {
+            name,
+            title,
+            description,
+            inputSchema: obj({ workspace_key: workspaceKeyProp(pinned), wait: { type: 'boolean', description: 'Wait until the operation finishes (default false).' } }, keyRequired),
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+            run: async (args, call) => {
+                const ws = await resolve(keyOf(args), { signal: call.signal });
+                const op = await start(ws.id, lifecycleOpts(args, call));
+                call.operationId = op.id;
+                return { operation: summarizeOperation(op) };
+            },
+        };
+    }
+    // ---- the SDK's workspace tools -------------------------------------------------------------
+    const readOnly = new Set(['read_file', 'list_files', 'list_processes', 'terminal_read', 'git_status', 'browser_screenshot', 'browser_content']);
+    const workspaceDefs = sdkToolDefinitions().map((sdk) => {
+        const own = sdk.parameters.properties ?? {};
+        const hasTimeout = 'timeout_ms' in own;
+        const inputSchema = {
+            ...sdk.parameters,
+            properties: { ...own, workspace_key: workspaceKeyProp(pinned), ...(hasTimeout ? {} : { timeout_ms: timeoutProp(ceiling) }) },
+            required: [...(sdk.parameters.required ?? []), ...keyRequired],
+        };
+        return {
+            name: sdk.name,
+            title: sdk.name.replace(/_/g, ' '),
+            description: sdk.name === 'exec' ? `${sdk.description} Here timeout_ms defaults to, and is capped by, this server's per-call deadline (${ceiling} ms) minus 2 s.` : sdk.description,
+            inputSchema,
+            permission: sdk.permission,
+            annotations: {
+                readOnlyHint: readOnly.has(sdk.name),
+                destructiveHint: !readOnly.has(sdk.name),
+                openWorldHint: sdk.permission === 'browser' || sdk.name === 'git_clone' || sdk.name === 'exec',
+            },
+            run: async (args, call) => {
+                const key = keyOf(args);
+                const sdkArgs = { ...args };
+                delete sdkArgs.workspace_key;
+                if (!hasTimeout)
+                    delete sdkArgs.timeout_ms;
+                else if (sdk.name === 'exec') {
+                    // The command is killed before the call deadline so its output comes back.
+                    const cmdTimeout = typeof sdkArgs.timeout_ms === 'number' ? Math.min(sdkArgs.timeout_ms, call.timeoutMs) : call.timeoutMs;
+                    sdkArgs.timeout_ms = Math.max(1000, cmdTimeout - 2000);
+                }
+                const ws = await resolve(key, { signal: call.signal });
+                // A wake during the call (the workspace was suspended) is timed; a call without one has no timing.
+                call.timed = true;
+                const tool = workspaceTools(ws, { agentLabel: config.agentLabel, tools: [...ALL_TOOL_PERMISSIONS], wake: wakeFor(ws), transitionTimeoutMs: wakeTimeoutMs }).find((t) => t.name === sdk.name);
+                if (!tool)
+                    throw new ToolError('internal_error', `SDK tool ${sdk.name} is missing`);
+                try {
+                    return await tool.execute(sdkArgs, { signal: call.signal });
+                }
+                catch (err) {
+                    // A deleted or foreign workspace: forget the handle so the next call resolves the key again.
+                    if (err instanceof ShardfluxApiError && err.source === 'api' && err.status === 404)
+                        handles.delete(key);
+                    throw err;
+                }
+            },
+        };
+    });
+    const registry = new Map([...management, ...workspaceDefs].map((d) => [d.name, d]));
+    const toMcpTool = (d) => ({
+        name: d.name,
+        title: d.title,
+        description: d.description,
+        inputSchema: d.inputSchema,
+        annotations: { title: d.title, ...d.annotations },
+    });
+    // ---- protocol handlers ---------------------------------------------------------------------
+    const server = new Server({ name: 'shardflux', title: 'Shardflux workspaces', version: MCP_SERVER_VERSION }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        let permitted = ALL_TOOL_PERMISSIONS;
+        try {
+            permitted = (await principal()).api_key?.tool_permissions ?? [];
+        }
+        catch (err) {
+            log('warn', 'could not read the API key’s tool permissions; listing every workspace tool', { error: describeToolError(err) });
+        }
+        return { tools: [...management, ...workspaceDefs.filter((d) => d.permission !== undefined && permitted.includes(d.permission))].map(toMcpTool) };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const name = request.params.name;
+        const def = registry.get(name);
+        if (!def)
+            throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
+        const args = request.params.arguments ?? {};
+        const started = Date.now();
+        const issues = validateArgs(def.inputSchema, args);
+        if (issues.length > 0) {
+            log('info', 'tool call rejected', { tool: name, outcome: 'invalid_arguments' });
+            return errorResult({ code: 'invalid_arguments', message: `Invalid arguments for ${name}: ${issues.join('; ')}`, issues });
+        }
+        const timeoutMs = Math.min(typeof args.timeout_ms === 'number' ? args.timeout_ms : ceiling, ceiling);
+        const deadline = AbortSignal.timeout(timeoutMs);
+        const signal = AbortSignal.any([extra.signal, deadline]);
+        const call = { signal, timeoutMs };
+        const aborted = new Promise((_, reject) => {
+            const onAbort = () => reject(signal.reason instanceof Error ? signal.reason : new DOMException('aborted', extra.signal.aborted ? 'AbortError' : 'TimeoutError'));
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener('abort', onAbort, { once: true });
+        });
+        const running = ambient.run({ signal, deadline: started + timeoutMs, call }, () => def.run(args, call));
+        running.catch(() => undefined); // settled after an abort: nobody awaits it any more
+        aborted.catch(() => undefined);
+        try {
+            const value = await Promise.race([running, aborted]);
+            log('info', 'tool call', { tool: name, outcome: 'ok', ms: Date.now() - started });
+            return okResult(call.timed && call.timing && isObject(value) ? { ...value, timing: compactTiming(call.timing) } : value);
+        }
+        catch (err) {
+            if (extra.signal.aborted) {
+                // The client canceled: the SDK request/wait was aborted; no response is sent for a canceled request.
+                log('info', 'tool call canceled by the client', { tool: name, outcome: 'canceled', ms: Date.now() - started, ...(call.operationId ? { operation_id: call.operationId } : {}) });
+                throw new McpError(ErrorCode.RequestTimeout, 'canceled');
+            }
+            // A structured error (API refusal, the SDK's own wait timeout) wins; a bare abort after the deadline is a timeout.
+            const abortish = !(err instanceof Error) || err.name === 'TimeoutError' || err.name === 'AbortError';
+            const info = describeToolError(deadline.aborted && abortish ? new DOMException('deadline', 'TimeoutError') : err, { operationId: call.operationId, timeoutMs });
+            info.message = redact(info.message, config.apiKey);
+            if (info.code === 'internal_error')
+                log('error', 'tool call failed unexpectedly', { tool: name, error: redact(err instanceof Error ? (err.stack ?? err.message) : String(err), config.apiKey) });
+            log('info', 'tool call', { tool: name, outcome: info.code, ms: Date.now() - started, ...(info.request_id ? { request_id: info.request_id } : {}) });
+            return errorResult(info, call.timed && call.timing ? compactTiming(call.timing) : undefined);
+        }
+    });
+    return server;
+}