@shardflux/mcp 0.3.0

package/dist/errors.d.ts

@@ -0,0 +1,24 @@
+/** A refusal decided by this server (argument/pinning problems, unknown workspace key). */
+export declare class ToolError extends Error {
+    name: string;
+    readonly code: string;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+export interface ToolErrorInfo {
+    code: string;
+    message: string;
+    status?: number;
+    request_id?: string;
+    retryable?: boolean;
+    operation_id?: string;
+    source?: 'api' | 'cell';
+    details?: Record<string, unknown>;
+    issues?: string[];
+    last_state?: string;
+}
+export declare function redact(text: string, key?: string): string;
+export declare function describeToolError(err: unknown, context?: {
+    operationId?: string | undefined;
+    timeoutMs?: number;
+}): ToolErrorInfo;

package/dist/errors.js

@@ -0,0 +1,72 @@
+/**
+ * Tool errors are returned as MCP tool results (`isError: true`) whose
+ * content is `{ "error": { code, message, ... } }` with the API's closed error
+ * code, never as protocol failures, so the calling model can react to them.
+ */
+import { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateUploadError, ToolArgumentError } from '@shardflux/sdk';
+/** A refusal decided by this server (argument/pinning problems, unknown workspace key). */
+export class ToolError extends Error {
+    name = 'ToolError';
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}
+const KEY_PATTERN = /sfk_[A-Za-z0-9]{8,}_[A-Za-z0-9]+/g;
+export function redact(text, key) {
+    let out = text.replace(KEY_PATTERN, 'sfk_[redacted]');
+    if (key && key.length >= 8)
+        out = out.split(key).join('[redacted]');
+    return out;
+}
+const named = (err, name) => typeof err === 'object' && err !== null && err.name === name;
+export function describeToolError(err, context = {}) {
+    if (err instanceof ShardfluxApiError) {
+        return {
+            code: err.code,
+            message: err.message,
+            status: err.status,
+            request_id: err.requestId,
+            retryable: err.retryable,
+            source: err.source,
+            ...(err.operationId ? { operation_id: err.operationId } : {}),
+            ...(err.details ? { details: err.details } : {}),
+        };
+    }
+    if (err instanceof ToolArgumentError)
+        return { code: 'invalid_arguments', message: err.message, issues: err.issues };
+    if (err instanceof ToolError)
+        return { code: err.code, message: err.message, ...(err.details ? { details: err.details } : {}) };
+    if (err instanceof OperationTimeoutError) {
+        return { code: 'timeout', message: `${err.message} Call operation_wait with this operation_id to keep waiting.`, operation_id: err.operationId, last_state: err.lastState, retryable: true };
+    }
+    if (err instanceof OperationFailedError) {
+        // retryable: the operation error's own flag. capacity_unavailable (no host could admit the start before its
+        // deadline) is retryable: nothing was started, so the agent may try again later.
+        const opDetails = err.operation.error?.details;
+        const reason = typeof opDetails === 'object' && opDetails !== null ? opDetails.reason : undefined;
+        const details = { ...(err.errorCode ? { error_code: err.errorCode } : {}), ...(typeof reason === 'string' ? { reason } : {}) };
+        const hint = err.errorCode === 'capacity_unavailable' ? '. No host could admit it before its deadline and nothing was started; you may retry later.' : '';
+        return { code: 'operation_failed', message: `${err.message}${hint}`, operation_id: err.operationId, retryable: err.retryable, ...(Object.keys(details).length ? { details } : {}) };
+    }
+    if (named(err, 'TimeoutError')) {
+        return {
+            code: 'timeout',
+            message: `The tool call did not finish within ${context.timeoutMs ?? 'its'} ms${context.operationId ? '; the operation continues server side (use operation_wait)' : ''}.`,
+            retryable: true,
+            ...(context.operationId ? { operation_id: context.operationId } : {}),
+        };
+    }
+    if (err instanceof TemplateUploadError)
+        return { code: 'upload_failed', message: err.message, ...(err.status ? { status: err.status } : {}), details: { sha256: err.sha256, ...(err.code ? { storage_code: err.code } : {}) } };
+    if (err instanceof ShardfluxProtocolError)
+        return { code: 'protocol_error', message: err.message, status: err.status };
+    if (err instanceof TypeError && err.message === 'fetch failed') {
+        const cause = err.cause;
+        return { code: 'network_error', message: `Cannot reach the Shardflux API or cell gateway (${cause?.code ?? cause?.message ?? 'network error'}).`, retryable: true };
+    }
+    return { code: 'internal_error', message: err instanceof Error ? err.message : String(err) };
+}

package/dist/http.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The fetch given to the SDK: the runtime's fetch with `Connection: close` on
+ * every request (API and cell gateway).
+ *
+ * Why: Node 26.7's bundled undici (8.9.0) intermittently stalls a request
+ * sent on a reused keep-alive connection until an unrelated timer fires (up to
+ * ~30 s, the SDK's request timeout, after which the SDK retries). Reproduced
+ * with bare fetch against both node:http and Fastify servers; Node 22 (undici
+ * 6.28) and `Connection: close` do not stall. A fresh connection per request
+ * costs one TCP/TLS handshake, which is negligible for these call rates.
+ * Set SHARDFLUX_HTTP_KEEPALIVE=1 to use the runtime's keep-alive pooling.
+ */
+export declare function makeFetch(env: Record<string, string | undefined>, base?: typeof fetch): typeof fetch;

package/dist/http.js

@@ -0,0 +1,21 @@
+/**
+ * The fetch given to the SDK: the runtime's fetch with `Connection: close` on
+ * every request (API and cell gateway).
+ *
+ * Why: Node 26.7's bundled undici (8.9.0) intermittently stalls a request
+ * sent on a reused keep-alive connection until an unrelated timer fires (up to
+ * ~30 s, the SDK's request timeout, after which the SDK retries). Reproduced
+ * with bare fetch against both node:http and Fastify servers; Node 22 (undici
+ * 6.28) and `Connection: close` do not stall. A fresh connection per request
+ * costs one TCP/TLS handshake, which is negligible for these call rates.
+ * Set SHARDFLUX_HTTP_KEEPALIVE=1 to use the runtime's keep-alive pooling.
+ */
+export function makeFetch(env, base = fetch) {
+    if (env.SHARDFLUX_HTTP_KEEPALIVE === '1')
+        return base;
+    return (input, init) => {
+        const headers = new Headers(init?.headers);
+        headers.set('connection', 'close');
+        return base(input, { ...init, headers });
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @shardflux/mcp — local stdio MCP server exposing Shardflux workspace tools
+ * through @shardflux/sdk with a supplied scoped API key. The executable is
+ * `shardflux-mcp` (bin.ts); `createShardfluxMcpServer()` builds the same server for any
+ * MCP transport.
+ */
+export { ALL_TOOL_PERMISSIONS, MCP_SERVER_VERSION, compactTiming, createShardfluxMcpServer, errorResult, okResult, sdkToolDefinitions, summarizeBuild, summarizeOperation, summarizeTemplate, summarizeWorkspace } from './server.js';
+export type { Logger, ObjectSchema, ServerOptions } from './server.js';
+export { ConfigError, DEFAULT_TOOL_TIMEOUT_MS, DEFAULT_WAKE_TIMEOUT_MS, MAX_TOOL_TIMEOUT_MS, apiUrlFrom, loadConfig } from './config.js';
+export type { McpConfig } from './config.js';
+export { ToolError, describeToolError, redact } from './errors.js';
+export type { ToolErrorInfo } from './errors.js';
+export { main, stderrLogger } from './main.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @shardflux/mcp — local stdio MCP server exposing Shardflux workspace tools
+ * through @shardflux/sdk with a supplied scoped API key. The executable is
+ * `shardflux-mcp` (bin.ts); `createShardfluxMcpServer()` builds the same server for any
+ * MCP transport.
+ */
+export { ALL_TOOL_PERMISSIONS, MCP_SERVER_VERSION, compactTiming, createShardfluxMcpServer, errorResult, okResult, sdkToolDefinitions, summarizeBuild, summarizeOperation, summarizeTemplate, summarizeWorkspace } from "./server.js";
+export { ConfigError, DEFAULT_TOOL_TIMEOUT_MS, DEFAULT_WAKE_TIMEOUT_MS, MAX_TOOL_TIMEOUT_MS, apiUrlFrom, loadConfig } from "./config.js";
+export { ToolError, describeToolError, redact } from "./errors.js";
+export { main, stderrLogger } from "./main.js";

package/dist/main.d.ts

@@ -0,0 +1,5 @@
+import type { McpConfig } from './config.js';
+import type { Logger } from './server.js';
+/** One JSON line per event on stderr; the API key is redacted from every line. */
+export declare function stderrLogger(config: Pick<McpConfig, 'apiKey' | 'logLevel'>, write?: (line: string) => void): Logger;
+export declare function main(env?: Record<string, string | undefined>): Promise<number | null>;

package/dist/main.js

@@ -0,0 +1,60 @@
+/**
+ * Process wiring for the stdio MCP server: configuration from the
+ * environment, a stderr logger (stdout carries the protocol), the stdio
+ * transport, and shutdown when the client closes stdin or on SIGINT/SIGTERM.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ConfigError, loadConfig } from "./config.js";
+import { redact } from "./errors.js";
+import { MCP_SERVER_VERSION, createShardfluxMcpServer } from "./server.js";
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+/** One JSON line per event on stderr; the API key is redacted from every line. */
+export function stderrLogger(config, write = (l) => void process.stderr.write(l)) {
+    const min = LEVELS[config.logLevel];
+    return (level, message, fields = {}) => {
+        if (LEVELS[level] < min)
+            return;
+        write(`${redact(JSON.stringify({ time: new Date().toISOString(), level, service: 'shardflux-mcp', message, ...fields }), config.apiKey)}\n`);
+    };
+}
+export async function main(env = process.env) {
+    let config;
+    try {
+        config = loadConfig(env);
+    }
+    catch (err) {
+        const message = err instanceof ConfigError ? err.message : String(err);
+        process.stderr.write(`${JSON.stringify({ time: new Date().toISOString(), level: 'error', service: 'shardflux-mcp', message: `configuration error: ${redact(message, env.SHARDFLUX_API_KEY)}` })}\n`);
+        return 2;
+    }
+    const log = stderrLogger(config);
+    const server = createShardfluxMcpServer(config, { log, env });
+    const transport = new StdioServerTransport();
+    let closing = false;
+    const shutdown = (reason) => {
+        if (closing)
+            return;
+        closing = true;
+        log('info', 'shutting down', { reason });
+        void server
+            .close()
+            .catch(() => undefined)
+            .finally(() => process.exit(0));
+    };
+    server.onerror = (err) => log('warn', 'protocol error', { error: redact(err.message, config.apiKey) });
+    await server.connect(transport);
+    process.stdin.on('end', () => shutdown('stdin closed'));
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    log('info', 'ready', {
+        version: MCP_SERVER_VERSION,
+        api_url: config.apiUrl,
+        pinned_workspace_key: config.workspaceKey ?? null,
+        default_template: config.template ?? null,
+        agent_label: config.agentLabel,
+        tool_timeout_ms: config.toolTimeoutMs,
+        wake: config.wake,
+        wake_timeout_ms: config.wakeTimeoutMs,
+    });
+    return null;
+}

package/dist/server.d.ts

@@ -0,0 +1,204 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { JsonSchema, LifecycleTiming, Operation, TemplateBuild, TemplateDetail, TemplateOwner, ToolName, WorkspaceTool, WorkspaceView } from '@shardflux/sdk';
+import type { McpConfig } from './config.js';
+import type { ToolErrorInfo } from './errors.js';
+export declare const MCP_SERVER_VERSION = "0.3.0";
+export declare const ALL_TOOL_PERMISSIONS: readonly ToolName[];
+export type ObjectSchema = JsonSchema & {
+    type: 'object';
+    properties: Record<string, JsonSchema>;
+    required: string[];
+};
+export interface Logger {
+    (level: 'debug' | 'info' | 'warn' | 'error', message: string, fields?: Record<string, unknown>): void;
+}
+/**
+ * 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 declare function sdkToolDefinitions(tools?: readonly ToolName[]): WorkspaceTool[];
+/** What tools return for a workspace (no tokens or other credentials). */
+export declare function summarizeWorkspace(v: WorkspaceView): {
+    id: string;
+    key: string;
+    ready: boolean;
+    observed_state: "running" | "failed" | "suspended" | "deleted" | "creating" | "starting" | "suspending" | "resuming" | "forking" | "stopping" | "deleting";
+    desired_state: "running" | "suspended" | "deleted";
+    template: {
+        slug: string;
+        version: number;
+    };
+    active_operation: {
+        error?: {
+            [key: string]: unknown;
+        } | undefined;
+        id: string;
+        kind: "open" | "suspend" | "resume" | "fork" | "snapshot" | "restore" | "delete" | "move" | "resize" | "volume_create" | "volume_attach" | "volume_detach" | "volume_delete" | "reset" | "layer_snapshot";
+        state: "capacity_pending" | "queued" | "running" | "succeeded" | "failed" | "canceled";
+        state_reason: string | null;
+        workspace_id: string | null;
+        created_at: string;
+        completed_at: string | null;
+    } | null;
+    pending_reason: string | null;
+    cell_endpoint: string | null;
+    grants: {
+        [key: string]: unknown;
+    } | null;
+    ceilings: {
+        cpu_millis: number;
+        memory_mib: number;
+        disk_gib: number;
+    } | null;
+    forked_from_workspace_id: string | null;
+    lifetime: "persistent" | "session";
+    purpose: "standard" | "template_draft" | "template_test";
+    disk_layout: "legacy" | "layered";
+    idle_timeout_seconds: number | null;
+    ended_reason: "closed" | "idle_timeout" | "draft_discarded" | null;
+    /** Start commands and services of the template version; null when it has none. */
+    startup: {
+        state: "pending" | "running" | "ready" | "failed";
+        trigger: ("create" | "boot" | "resume") | null;
+        step: string | null;
+        service: string | null;
+        exit_code: number | null;
+        output_tail: string | null;
+        reason: string | null;
+        operation_id: string | null;
+        at: string | null;
+    } | null;
+    created_at: string;
+    deleted_at: string | null;
+};
+/** A template build without the stored recipe (the compiled steps are long): state, version and what the builder refused. */
+export declare function summarizeBuild(b: TemplateBuild): {
+    id: string;
+    template: {
+        slug: string;
+        name: string;
+    };
+    target_version: number | null;
+    state: import("@shardflux/sdk").TemplateBuildState;
+    registration: {
+        state: import("@shardflux/sdk").TemplateBuildRegistrationState;
+        registered_at: string | null;
+        error: {
+            code: string;
+            message: string;
+        } | null;
+    };
+    template_version: {
+        id: string;
+        version: number;
+        published: boolean;
+    } | null;
+    auto_publish: boolean;
+    failure: {
+        code: string;
+        message: string;
+    } | null;
+    denied_hosts: string[];
+    network: {
+        mode: "none" | "egress_allowlist";
+        allow_hosts: string[];
+    };
+    recipe_sha256: string | null;
+    builder_availability: "available" | "unavailable";
+    created_at: string;
+    completed_at: string | null;
+    log_tail: string | null;
+};
+/** A template for model context: identity, what open resolves to, every version with its settings. */
+export declare function summarizeTemplate(t: TemplateDetail): {
+    slug: string;
+    name: string;
+    owner: TemplateOwner;
+    category: import("@shardflux/sdk").TemplateCategory | null;
+    open_resolves_to: {
+        version: number;
+        owner: TemplateOwner;
+    } | null;
+    draft: {
+        workspace_key: string;
+        observed_state: string;
+        base_version: number;
+    } | null;
+    versions: {
+        version: number;
+        state: import("@shardflux/sdk").TemplateVersionState;
+        is_open_version: boolean;
+        description: string | null;
+        source: "recipe" | "workspace" | "git" | null;
+        disk_layouts: ("legacy" | "layered")[];
+        installed_tools: {
+            name: string;
+            version: string;
+        }[];
+        settings: {
+            env: {
+                [key: string]: string;
+            };
+            inputs: {
+                [key: string]: import("@shardflux/sdk").components["schemas"]["TemplateInput"];
+            };
+            start: import("@shardflux/sdk").components["schemas"]["TemplateStartCommand"][];
+            services: {
+                [key: string]: import("@shardflux/sdk").components["schemas"]["TemplateService"];
+            };
+            defaults: import("@shardflux/sdk").components["schemas"]["TemplateDefaults"];
+        };
+        created_at: string;
+    }[];
+    versions_truncated: boolean;
+};
+export declare function summarizeOperation(o: Operation): {
+    error?: {
+        [key: string]: unknown;
+    } | undefined;
+    id: string;
+    kind: "open" | "suspend" | "resume" | "fork" | "snapshot" | "restore" | "delete" | "move" | "resize" | "volume_create" | "volume_attach" | "volume_detach" | "volume_delete" | "reset" | "layer_snapshot";
+    state: "capacity_pending" | "queued" | "running" | "succeeded" | "failed" | "canceled";
+    state_reason: string | null;
+    workspace_id: string | null;
+    created_at: string;
+    completed_at: string | null;
+};
+/**
+ * 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 declare function compactTiming(t: LifecycleTiming): {
+    total_ms: number;
+    phases: string[];
+    server: {
+        resume_path?: string | undefined;
+        warm_fallback?: string | undefined;
+        start_path?: string | undefined;
+        queued_ms: number | null;
+        run_ms: number | null;
+        total_ms: number | null;
+    } | null;
+    outside_server_ms: number | null;
+    retries: number;
+    operation_id?: string | undefined;
+    action: import("@shardflux/sdk").LifecycleAction;
+    outcome: import("@shardflux/sdk").TimingOutcome;
+};
+export declare function okResult(value: unknown): CallToolResult;
+/** `timing` (optional): where the failed open/wait/wake spent its time, next to `error`. */
+export declare function errorResult(info: ToolErrorInfo, timing?: ReturnType<typeof compactTiming>): CallToolResult;
+export interface ServerOptions {
+    log?: Logger;
+    /** Replaces the HTTP client entirely (tests); default: the runtime fetch via makeFetch(env). */
+    fetch?: typeof fetch;
+    /** Process environment (SHARDFLUX_HTTP_KEEPALIVE). */
+    env?: Record<string, string | undefined>;
+    /** template_build reads local files only inside this directory (default: the process's working directory). */
+    cwd?: string;
+}
+export declare function createShardfluxMcpServer(config: McpConfig, opts?: ServerOptions): Server;