@luxorai/mcp 0.0.0-stage → 0.4.0

package/dist/tools/sessions_admin.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { listQuery, ok, protoEnum, searchSchema, sessionIdSchema, tagsPatch, tagsSchema } from "./common.js";
+const SESSION_STATES = ["CREATING", "RUNNING", "PAUSING", "PAUSED", "RESUMING", "TERMINATING", "TERMINATED", "USER_SHUTDOWN"];
+/**
+ * Extended sandbox (session) admin ops on the control plane: wall-clock lifetime
+ * extension, mutable-field updates, bulk termination, activity heartbeats, and
+ * workspace-scoped listing. The lifecycle basics
+ * (create/get/list/terminate/pause/resume) live in sandboxes.ts.
+ */
+export function registerSessionsAdmin(server, client) {
+    server.tool("tenki_extend_sandbox", "Extend a running sandbox's wall-clock lifetime by N seconds so it isn't auto-terminated at its max-duration cap.", {
+        session_id: sessionIdSchema.describe("The sandbox/session ID to extend."),
+        additional_duration_seconds: z
+            .number()
+            .int()
+            .positive()
+            .describe("Extra lifetime to add, in seconds (sent as a Duration string, e.g. 3600s)."),
+    }, async ({ session_id, additional_duration_seconds }) => ok(await client.control("ExtendSession", {
+        sessionId: session_id,
+        additionalDuration: `${additional_duration_seconds}s`,
+    })));
+    server.tool("tenki_update_sandbox", "Update mutable fields on an existing sandbox: name, tags, sticky flag, or max duration. The idle timeout is NOT updatable after creation (UpdateSession has no such field). max_duration_seconds requires an explicit sticky value on the wire: when you pass it without `sticky` the tool checks the sandbox and sends sticky=false only if it is not already sticky (a sticky sandbox is refused, to avoid silently revoking stickiness); sticky=true discards max_duration with a warning. The response carries any `warnings` the API returned.", {
+        session_id: sessionIdSchema.describe("The sandbox/session ID to update."),
+        name: z.string().max(64).optional().describe("New human-readable name (max 64 chars)."),
+        tags: tagsSchema.describe("Replacement tag list. Pass [] (or clear_tags) to remove all tags."),
+        clear_tags: z.boolean().optional().describe("Remove all tags from the sandbox."),
+        sticky: z
+            .boolean()
+            .optional()
+            .describe("true = keep the sandbox alive with no hard lifetime cap (not allowed for service credentials). false = ordinary lifetime: pass max_duration_seconds with it, otherwise the API resets the cap to the workspace default duration from now."),
+        max_duration_seconds: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("New hard lifetime cap in seconds (sent as a Duration string, e.g. 3600s). Sends sticky=false for a non-sticky sandbox unless sticky is given; refused on a sticky sandbox without an explicit sticky value."),
+    }, async ({ session_id, name, tags, clear_tags, sticky, max_duration_seconds }) => {
+        const tagPatch = tagsPatch(tags, clear_tags);
+        if (name === undefined && sticky === undefined && max_duration_seconds === undefined && !Object.keys(tagPatch).length) {
+            throw new Error("tenki_update_sandbox: pass at least one field to change — nothing was sent (the API would return the unchanged sandbox, which reads like a successful update).");
+        }
+        // The API rejects max_duration without an explicit sticky value, and sticky=false
+        // is the only combination that applies the cap. Sending false on a STICKY
+        // sandbox would silently revoke stickiness (hard lifetime + idle reaper), so
+        // the default is only filled in after checking the sandbox is not sticky.
+        let stickyValue = sticky;
+        if (stickyValue === undefined && max_duration_seconds !== undefined) {
+            const current = await client.control("GetSession", { sessionId: session_id });
+            if ((current.session ?? current)?.sticky === true) {
+                throw new Error("tenki_update_sandbox: this sandbox is sticky, so max_duration_seconds would revoke that — pass sticky:false explicitly to un-sticky it with this cap, or sticky:true to keep it (the cap is then ignored).");
+            }
+            stickyValue = false;
+        }
+        return ok(await client.control("UpdateSession", {
+            sessionId: session_id,
+            ...(name !== undefined ? { name } : {}),
+            ...tagPatch,
+            ...(stickyValue !== undefined ? { sticky: stickyValue } : {}),
+            ...(max_duration_seconds !== undefined ? { maxDuration: `${max_duration_seconds}s` } : {}),
+        }));
+    });
+    server.tool("tenki_terminate_sandboxes", "Terminate MULTIPLE sandboxes in one call (bulk, max 100 per call). IRREVERSIBLE — every listed sandbox and its filesystem is destroyed. The response lists `sessions` that were terminated and `failures` with a reason per id that was not. Use tenki_terminate_sandbox for a single one.", {
+        session_ids: z.array(sessionIdSchema).min(1).max(100).describe("The sandbox/session IDs to terminate (1-100)."),
+    }, async ({ session_ids }) => ok(await client.control("TerminateSessions", { sessionIds: session_ids })));
+    server.tool("tenki_report_sandbox_activity", "Report client-side activity on a sandbox to reset its idle timer and keep it from being reaped as idle (a keep-alive heartbeat).", { session_id: sessionIdSchema.describe("The sandbox/session ID to mark as active.") }, async ({ session_id }) => ok(await client.control("ReportSessionActivity", { sessionId: session_id })));
+    server.tool("tenki_list_workspace_sandboxes", "List every sandbox belonging to a specific workspace (defaults to the API key's workspace) with server-side search (name, id, snapshot names/ids, image refs), state/tag/sticky filters, sorting and optional state-count facets — useful for finding a sandbox by name or spotting leaked, still-billing ones. NOTE: the underlying RPC (ListWorkspaceSandboxes) is marked deprecated upstream, but it is the only list with search/sort; tenki_list_sandboxes is the plain credential-scoped list.", {
+        workspace_id: z.string().optional().describe("Workspace to list (defaults to the key's first workspace)."),
+        include_terminated: z.boolean().optional().describe("Include terminated sandboxes (default false)."),
+        search: searchSchema.describe("Free-text search over name, id, snapshot names/ids and published image refs (max 256 chars)."),
+        states: z.array(z.enum(SESSION_STATES)).max(16).optional().describe("Only sandboxes in any of these states (empty = no filter)."),
+        state: z.enum(SESSION_STATES).optional().describe("Only sandboxes in this one state (combines with states)."),
+        tags: z.array(z.string()).optional().describe("Only sandboxes carrying all of these tags."),
+        sticky: z.boolean().optional().describe("Only sticky (true) or only non-sticky (false) sandboxes."),
+        order: z
+            .enum(["STATE_THEN_CREATED"])
+            .optional()
+            .describe("Default order is newest first; STATE_THEN_CREATED groups running, then paused, then terminated (newest first within each). Ignored when sort_by is set."),
+        sort_by: z
+            .enum(["NAME", "STATE", "CREATED_AT", "CPU_CORES", "MEMORY_MB", "DISK_SIZE_GB", "EXPIRATION", "SNAPSHOT_STORAGE"])
+            .optional()
+            .describe("Column to sort by (overrides order)."),
+        sort_desc: z.boolean().optional().describe("Sort descending (default ascending)."),
+        include_facets: z.boolean().optional().describe("Also return per-state counts for the same filter scope (facets)."),
+        page_size: z.number().int().min(1).max(100).optional().describe("Rows per page (max 100)."),
+        page_token: z.string().optional().describe("Cursor from a previous response's nextPageToken."),
+    }, async ({ workspace_id, include_terminated, search, states, state, tags, sticky, order, sort_by, sort_desc, include_facets, page_size, page_token }) => {
+        const workspaceId = workspace_id ?? (await client.resolveOwner()).workspaceId;
+        return ok(await client.control("ListWorkspaceSandboxes", {
+            ...(workspaceId ? { workspaceId } : {}),
+            ...(include_terminated ? { includeTerminated: true } : {}),
+            ...(state ? { state: protoEnum("SESSION_STATE", state) } : {}),
+            ...(states && states.length ? { states: states.map((s) => protoEnum("SESSION_STATE", s)) } : {}),
+            ...(tags && tags.length ? { tags } : {}),
+            ...(sticky !== undefined ? { sticky } : {}),
+            ...(order ? { order: protoEnum("SANDBOX_LIST_ORDER", order) } : {}),
+            ...(sort_by ? { sortBy: protoEnum("SANDBOX_SORT_FIELD", sort_by) } : {}),
+            ...listQuery(search, include_facets, sort_desc),
+            ...(page_size ? { pageSize: page_size } : {}),
+            ...(page_token ? { pageToken: page_token } : {}),
+        }));
+    });
+}

package/dist/tools/snapshots.d.ts

@@ -0,0 +1,11 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/**
+ * Snapshots — capture a sandbox's disk + memory as a reusable image.
+ *
+ * Restoring is deliberately NOT a tool here: booting a fresh sandbox from a
+ * snapshot is `tenki_create_sandbox` with `snapshot_id` (CreateSession under the
+ * hood). Attached volumes are NOT captured in a snapshot and must be re-attached
+ * to the restored session separately.
+ */
+export declare function registerSnapshots(server: McpServer, client: TenkiClient): void;

package/dist/tools/snapshots.js

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { ok, sessionIdSchema, tagsPatch, tagsSchema } from "./common.js";
+/**
+ * Snapshots — capture a sandbox's disk + memory as a reusable image.
+ *
+ * Restoring is deliberately NOT a tool here: booting a fresh sandbox from a
+ * snapshot is `tenki_create_sandbox` with `snapshot_id` (CreateSession under the
+ * hood). Attached volumes are NOT captured in a snapshot and must be re-attached
+ * to the restored session separately.
+ */
+export function registerSnapshots(server, client) {
+    server.tool("tenki_create_snapshot", "Capture a running sandbox's disk and memory as a reusable snapshot (attached volumes are NOT captured); boot a new sandbox from it later with tenki_create_sandbox + snapshot_id.", {
+        session_id: sessionIdSchema.describe("The sandbox session to snapshot."),
+        name: z.string().optional().describe("Human-readable name for the snapshot."),
+        expires_at: z
+            .string()
+            .optional()
+            .describe("RFC-3339 / ISO-8601 timestamp at which the snapshot is auto-deleted. Omit to keep indefinitely."),
+        store_raw_image: z
+            .boolean()
+            .optional()
+            .describe("Also store the raw disk image alongside the snapshot (needed to download it later)."),
+        async: z
+            .boolean()
+            .optional()
+            .describe("Return as soon as the snapshot row exists and poll tenki_get_snapshot for READY, instead of blocking until the capture finishes (default false)."),
+    }, async ({ session_id, name, expires_at, store_raw_image, async: isAsync }) => ok(await client.control("CreateSnapshot", {
+        sessionId: session_id,
+        ...(name ? { name } : {}),
+        ...(expires_at ? { expiresAt: expires_at } : {}),
+        ...(store_raw_image !== undefined ? { storeRawImage: store_raw_image } : {}),
+        ...(isAsync ? { async: true } : {}),
+    })));
+    server.tool("tenki_get_snapshot", "Fetch one snapshot's status and metadata by ID.", { snapshot_id: z.string().describe("Snapshot id, from tenki_create_snapshot or tenki_list_snapshots.") }, async ({ snapshot_id }) => ok(await client.control("GetSnapshot", { snapshotId: snapshot_id })));
+    server.tool("tenki_list_snapshots", "List the saved snapshots for the workspace (owner inferred from the API key).", {
+        page_size: z.number().int().positive().optional().describe("Rows per page."),
+        page_token: z.string().optional().describe("Cursor from a previous response's nextPageToken."),
+    }, async ({ page_size, page_token }) => ok(await client.control("ListSnapshots", {
+        ...(page_size ? { pageSize: page_size } : {}),
+        ...(page_token ? { pageToken: page_token } : {}),
+    })));
+    server.tool("tenki_list_session_snapshots", "List the snapshots captured from a specific sandbox session.", {
+        session_id: sessionIdSchema,
+        page_size: z.number().int().positive().optional().describe("Rows per page."),
+        page_token: z.string().optional().describe("Cursor from a previous response's nextPageToken."),
+    }, async ({ session_id, page_size, page_token }) => ok(await client.control("ListSessionSnapshots", {
+        sessionId: session_id,
+        ...(page_size ? { pageSize: page_size } : {}),
+        ...(page_token ? { pageToken: page_token } : {}),
+    })));
+    server.tool("tenki_list_dangling_snapshots", "List dangling snapshots — those whose source session no longer exists — for the workspace, useful for cleanup.", {
+        page_size: z.number().int().positive().optional().describe("Rows per page."),
+        page_token: z.string().optional().describe("Cursor from a previous response's nextPageToken."),
+    }, async ({ page_size, page_token }) => ok(await client.control("ListDanglingSnapshots", {
+        ...(page_size ? { pageSize: page_size } : {}),
+        ...(page_token ? { pageToken: page_token } : {}),
+    })));
+    server.tool("tenki_update_snapshot", "Update a snapshot's mutable metadata: name, expiry (set or clear), and tags. An expired snapshot can no longer be updated, and a pause snapshot's expiry is managed by its sandbox (both failed_precondition).", {
+        snapshot_id: z.string().describe("Snapshot id, from tenki_create_snapshot or tenki_list_snapshots."),
+        name: z.string().max(64).optional().describe("New human-readable name (max 64 chars)."),
+        expires_at: z
+            .string()
+            .optional()
+            .describe("New RFC-3339 / ISO-8601 auto-delete timestamp."),
+        clear_expires_at: z.boolean().optional().describe("Remove the expiry so the snapshot is kept indefinitely."),
+        tags: tagsSchema.describe("Replacement tag list. Pass [] (or clear_tags) to remove all tags."),
+        clear_tags: z.boolean().optional().describe("Remove all tags from the snapshot."),
+    }, async ({ snapshot_id, name, expires_at, clear_expires_at, tags, clear_tags }) => {
+        if (expires_at !== undefined && clear_expires_at) {
+            throw new Error("tenki_update_snapshot: pass either expires_at or clear_expires_at, not both — clear would win and the new expiry would be silently dropped.");
+        }
+        const tagPatch = tagsPatch(tags, clear_tags);
+        if (name === undefined && expires_at === undefined && !clear_expires_at && !Object.keys(tagPatch).length) {
+            throw new Error("tenki_update_snapshot: pass at least one field to change — nothing was sent.");
+        }
+        return ok(await client.control("UpdateSnapshot", {
+            snapshotId: snapshot_id,
+            ...(name !== undefined ? { name } : {}),
+            ...(expires_at !== undefined ? { expiresAt: expires_at } : {}),
+            ...(clear_expires_at ? { clearExpiresAt: true } : {}),
+            ...tagPatch,
+        }));
+    });
+    server.tool("tenki_delete_snapshot", "Permanently delete a snapshot by ID.", { snapshot_id: z.string().describe("Snapshot id, from tenki_create_snapshot or tenki_list_snapshots.") }, async ({ snapshot_id }) => ok(await client.control("DeleteSnapshot", { snapshotId: snapshot_id })));
+    server.tool("tenki_get_snapshot_download_url", "Get a short-lived, pre-signed URL to download a snapshot's raw disk image (requires the snapshot to have been created with store_raw_image).", { snapshot_id: z.string().describe("Snapshot id, from tenki_create_snapshot or tenki_list_snapshots.") }, async ({ snapshot_id }) => ok(await client.control("GetSnapshotDownloadURL", { snapshotId: snapshot_id })));
+    server.tool("tenki_list_workspace_snapshots", "List all snapshots in a workspace (defaults to the key's first workspace). Supports pagination. NOTE: the underlying RPC (ListWorkspaceSnapshots) is deprecated upstream in favour of the credential-scoped tenki_list_snapshots; prefer that unless you need an explicit workspace_id.", {
+        workspace_id: z.string().optional().describe("Workspace to list (defaults to the key's first workspace)."),
+        page_size: z.number().int().positive().optional().describe("Rows per page."),
+        page_token: z.string().optional().describe("Cursor from a previous response's nextPageToken."),
+    }, async ({ workspace_id, page_size, page_token }) => {
+        const workspaceId = workspace_id ?? (await client.resolveOwner()).workspaceId;
+        return ok(await client.control("ListWorkspaceSnapshots", {
+            ...(workspaceId ? { workspaceId } : {}),
+            ...(page_size ? { pageSize: page_size } : {}),
+            ...(page_token ? { pageToken: page_token } : {}),
+        }));
+    });
+}

package/dist/tools/ssh.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ssh.ts — SSH access tools for tenki-mcp.
+ *
+ * UpdateSSHAuthorizedKeys sets the authorized_keys on a running sandbox (on
+ * SandboxService). IssueSandboxSSHCert and ListActiveSSHGateways live on a
+ * SEPARATE ConnectRPC service (SSHGatewayClientService), reached by passing the
+ * service path to client.control.
+ *
+ * Request shapes follow proto/tenki/sandbox/v1/ssh_gateway_client.proto:
+ * IssueSandboxSSHCertRequest { session_id, public_key (32-8192 chars), requested_ttl, source_addresses[] }
+ * ListActiveSSHGatewaysRequest { region, session_id } — there is NO workspace_id field.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+export declare function registerSsh(server: McpServer, client: TenkiClient): void;

package/dist/tools/ssh.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { ok, sessionIdSchema } from "./common.js";
+const SSH_GATEWAY_SERVICE = "tenki.sandbox.v1.SSHGatewayClientService";
+export function registerSsh(server, client) {
+    server.tool("tenki_update_ssh_keys", "Set the SSH authorized public keys on a running sandbox, enabling direct SSH access for the given keys. Replaces the current set (at least one key is required — the API has no 'clear' operation).", {
+        session_id: sessionIdSchema,
+        public_keys: z
+            .array(z.string().min(1))
+            .min(1)
+            .describe("SSH public keys (ssh-ed25519 …, ssh-rsa …) to authorize. Replaces the current set."),
+    }, async ({ session_id, public_keys }) => ok(await client.control("UpdateSSHAuthorizedKeys", { sessionId: session_id, sshAuthorizedKeys: public_keys })));
+    server.tool("tenki_issue_ssh_cert", "Issue a short-lived SSH certificate for a public key, authorizing SSH access to a sandbox via the SSH gateway. Returns the certificate, the CA public key (caPub) for known_hosts, expiry, a renewal hint, and pinHostKey — when true, verify the gateway host certificate against caPub (e.g. a `@cert-authority` known_hosts line) rather than trusting on first use.", {
+        session_id: sessionIdSchema,
+        public_key: z
+            .string()
+            .min(32)
+            .max(8192)
+            .describe("OpenSSH-format public key to sign into a certificate (e.g. 'ssh-ed25519 AAAA…')."),
+        requested_ttl_seconds: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Requested certificate lifetime in seconds; the server caps it to policy."),
+        source_addresses: z
+            .array(z.string())
+            .max(16)
+            .optional()
+            .describe("CIDRs bound into the cert's source-address critical option; SSH refuses the cert from any other source IP."),
+    }, async ({ session_id, public_key, requested_ttl_seconds, source_addresses }) => ok(await client.control("IssueSandboxSSHCert", {
+        sessionId: session_id,
+        publicKey: public_key,
+        ...(requested_ttl_seconds ? { requestedTtl: `${requested_ttl_seconds}s` } : {}),
+        ...(source_addresses && source_addresses.length ? { sourceAddresses: source_addresses } : {}),
+    }, SSH_GATEWAY_SERVICE)));
+    server.tool("tenki_list_ssh_gateways", "List the currently active SSH gateways (id, region, public endpoint, health). Filter by region, or pass session_id to get only the gateways that can reach that sandbox's host. Gateways are fleet-wide, not per workspace.", {
+        region: z.string().optional().describe("Only gateways in this region (e.g. 'us', 'eu'). Omit for all regions."),
+        session_id: sessionIdSchema.optional().describe("Only gateways that can reach this sandbox's host."),
+    }, async ({ region, session_id }) => ok(await client.control("ListActiveSSHGateways", {
+        ...(region ? { region } : {}),
+        ...(session_id ? { sessionId: session_id } : {}),
+    }, SSH_GATEWAY_SERVICE)));
+}

package/dist/tools/templates.d.ts

@@ -0,0 +1,15 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/**
+ * Template tools — custom-image templates and their builds.
+ *
+ * A "template" is a reusable sandbox-image spec (base image + setup script +
+ * default resources/env); building one produces a snapshot/image that sandboxes
+ * can boot from. Method names and request fields are matched to the generated
+ * `tenki.sandbox.v1.SandboxService` protobuf (the wire contract the control
+ * plane actually speaks). Notable shapes: sizing is a nested `resources` object
+ * ({ cpuCores, memoryMb, diskSizeGb }); the env map is `envVars`; a build is
+ * addressed by `buildId`; and ListActiveTemplateBuilds / ListTemplateBuilds are scoped
+ * by `templateId`.
+ */
+export declare function registerTemplates(server: McpServer, client: TenkiClient): void;

package/dist/tools/templates.js

@@ -0,0 +1,162 @@
+import { z } from "zod";
+import { envSchema, listQuery, ok, protoEnum, searchSchema, tagsPatch, tagsSchema } from "./common.js";
+/**
+ * Template tools — custom-image templates and their builds.
+ *
+ * A "template" is a reusable sandbox-image spec (base image + setup script +
+ * default resources/env); building one produces a snapshot/image that sandboxes
+ * can boot from. Method names and request fields are matched to the generated
+ * `tenki.sandbox.v1.SandboxService` protobuf (the wire contract the control
+ * plane actually speaks). Notable shapes: sizing is a nested `resources` object
+ * ({ cpuCores, memoryMb, diskSizeGb }); the env map is `envVars`; a build is
+ * addressed by `buildId`; and ListActiveTemplateBuilds / ListTemplateBuilds are scoped
+ * by `templateId`.
+ */
+export function registerTemplates(server, client) {
+    /** Assemble the nested TemplateResources object from flat sizing params (omitting any unset). */
+    const resourcesFrom = (cpuCores, memoryMb, diskSizeGb) => {
+        const r = {};
+        if (cpuCores !== undefined)
+            r.cpuCores = cpuCores;
+        if (memoryMb !== undefined)
+            r.memoryMb = memoryMb;
+        if (diskSizeGb !== undefined)
+            r.diskSizeGb = diskSizeGb;
+        return r;
+    };
+    // ── Create ──────────────────────────────────────────────────────────────────
+    server.tool("tenki_create_template", "Create a custom-image template (a reusable sandbox-image spec: base image + setup script + default resources). Build it into a bootable image later with tenki_build_template. NOTE: only a TYPED template (created with builder_spec, no legacy fields) can build a named, publishable image (image_name) that tenki_create_sandbox boots via its `image` arg.", {
+        name: z.string().min(1).max(64).describe("Human-readable template name (1-64 chars)."),
+        base_image_id: z.string().optional().describe("Base image ID to build on top of."),
+        setup_script: z.string().optional().describe("Shell script run at build time to provision the image. Required for a from-scratch template (the API rejects a create without it unless you derive from a parent template/image)."),
+        start_cmd: z.string().optional().describe("Command run when a sandbox boots from this template."),
+        cpu_cores: z.number().int().min(1).max(128).optional().describe("Default vCPUs for sandboxes from this template (1-128; workspace plan may cap lower)."),
+        memory_mb: z.number().int().min(512).max(524288).refine((n) => n % 2 === 0, "memory_mb must be even").optional().describe("Default memory in MB (512-524288, even)."),
+        disk_size_gb: z.number().int().min(5).max(100).optional().describe("Default disk in GB (5-100)."),
+        env_vars: envSchema,
+        tags: tagsSchema.describe("Tags for later filtering (≤20, each ≤32 chars of a-z 0-9 _ : . -)."),
+        parent_template_id: z.string().optional().describe("Derive this template from an existing template."),
+        parent_image: z.string().optional().describe("Derive this template from an existing built image reference."),
+        builder_spec: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Typed template spec, passed through as-is — e.g. {specVersion:'tenki.template.v1', base:{image:'sandbox'}, workdir:'/home/tenki', steps:[{run:{command:'...'}}], resources:{cpuCores,memoryMb,diskSizeGb}}. Mutually exclusive with base_image_id/setup_script/start_cmd/env_vars/cpu_cores/memory_mb/disk_size_gb/parent_* (the API rejects mixing). Required if the template's builds should publish an image (tenki_build_template image_name)."),
+        workspace_id: z.string().optional().describe("Workspace to create in (defaults to the key's first workspace)."),
+    }, async (a) => {
+        const owner = await client.resolveOwner();
+        const workspaceId = a.workspace_id ?? owner.workspaceId;
+        const resources = resourcesFrom(a.cpu_cores, a.memory_mb, a.disk_size_gb);
+        const body = {
+            ...(workspaceId ? { workspaceId } : {}),
+            name: a.name,
+            ...(a.base_image_id ? { baseImageId: a.base_image_id } : {}),
+            ...(a.setup_script !== undefined ? { setupScript: a.setup_script } : {}),
+            ...(a.start_cmd !== undefined ? { startCmd: a.start_cmd } : {}),
+            ...(a.env_vars && Object.keys(a.env_vars).length ? { envVars: a.env_vars } : {}),
+            ...(Object.keys(resources).length ? { resources } : {}),
+            ...(a.tags && a.tags.length ? { tags: a.tags } : {}),
+            ...(a.parent_template_id ? { parentTemplateId: a.parent_template_id } : {}),
+            ...(a.parent_image ? { parentImage: a.parent_image } : {}),
+            ...(a.builder_spec ? { builderSpec: a.builder_spec } : {}),
+        };
+        return ok(await client.control("CreateTemplate", body));
+    });
+    // ── Get ─────────────────────────────────────────────────────────────────────
+    server.tool("tenki_get_template", "Retrieve one template by ID.", { template_id: z.string().describe("The template ID.") }, async ({ template_id }) => ok(await client.control("GetTemplate", { templateId: template_id })));
+    // ── List ────────────────────────────────────────────────────────────────────
+    server.tool("tenki_list_templates", "List templates for the workspace with server-side search, build-state filter, tag filter, sorting and optional state-count facets.", {
+        tags: z.array(z.string()).optional().describe("Only return templates that carry all of these tags."),
+        search: searchSchema.describe("Free-text search over template name/id (max 256 chars)."),
+        states: z
+            .array(z.enum(["READY", "BUILDING", "PENDING", "FAILED", "UNBUILT"]))
+            .max(16)
+            .optional()
+            .describe("Only templates whose latest build is in any of these states (UNBUILT = never built)."),
+        sort_by: z.enum(["NAME", "CREATED_AT", "UPDATED_AT"]).optional().describe("Column to sort by."),
+        sort_desc: z.boolean().optional().describe("Sort descending (default ascending)."),
+        include_facets: z.boolean().optional().describe("Also return per-state counts for the same filter scope."),
+        workspace_id: z.string().optional().describe("Workspace to list from (defaults to the key's first workspace)."),
+        page_size: z.number().int().min(1).max(100).optional().describe("Rows per page (max 100)."),
+        page_token: z.string().optional().describe("Cursor from a previous response's nextPageToken."),
+    }, async ({ tags, search, states, sort_by, sort_desc, include_facets, workspace_id, page_size, page_token }) => {
+        const owner = await client.resolveOwner();
+        const workspaceId = workspace_id ?? owner.workspaceId;
+        return ok(await client.control("ListTemplates", {
+            ...(workspaceId ? { workspaceId } : {}),
+            ...(tags && tags.length ? { tags } : {}),
+            ...(states && states.length ? { states: states.map((s) => protoEnum("TEMPLATE_LIST_STATE", s)) } : {}),
+            ...(sort_by ? { sortBy: protoEnum("TEMPLATE_SORT_FIELD", sort_by) } : {}),
+            ...listQuery(search, include_facets, sort_desc),
+            ...(page_size ? { pageSize: page_size } : {}),
+            ...(page_token ? { pageToken: page_token } : {}),
+        }));
+    });
+    // ── Update ──────────────────────────────────────────────────────────────────
+    server.tool("tenki_update_template", "Update mutable fields on a template. Only the fields you provide are changed; pass clear_tags to remove all tags.", {
+        template_id: z.string().describe("The template ID to update."),
+        name: z.string().optional().describe("New human-readable name."),
+        base_image_id: z.string().optional().describe("New base image ID."),
+        setup_script: z.string().optional().describe("New build-time provisioning script."),
+        start_cmd: z.string().optional().describe("New boot command."),
+        cpu_cores: z.number().int().min(1).max(128).optional().describe("New default vCPUs (1-128)."),
+        memory_mb: z.number().int().min(512).max(524288).refine((n) => n % 2 === 0, "memory_mb must be even").optional().describe("New default memory in MB (512-524288, even)."),
+        disk_size_gb: z.number().int().min(5).max(100).optional().describe("New default disk in GB (5-100)."),
+        env_vars: envSchema,
+        tags: tagsSchema.describe("Replacement tag list. Pass [] (or clear_tags) to remove all tags."),
+        clear_tags: z.boolean().optional().describe("Remove all tags from the template."),
+        builder_spec: z.record(z.string(), z.unknown()).optional().describe("Advanced structured build spec (TemplateBuildSpec); passed through as-is."),
+    }, async (a) => {
+        const resources = resourcesFrom(a.cpu_cores, a.memory_mb, a.disk_size_gb);
+        const body = {
+            templateId: a.template_id,
+            ...(a.name !== undefined ? { name: a.name } : {}),
+            ...(a.base_image_id !== undefined ? { baseImageId: a.base_image_id } : {}),
+            ...(a.setup_script !== undefined ? { setupScript: a.setup_script } : {}),
+            ...(a.start_cmd !== undefined ? { startCmd: a.start_cmd } : {}),
+            ...(a.env_vars && Object.keys(a.env_vars).length ? { envVars: a.env_vars } : {}),
+            ...(Object.keys(resources).length ? { resources } : {}),
+            ...tagsPatch(a.tags, a.clear_tags),
+            ...(a.builder_spec ? { builderSpec: a.builder_spec } : {}),
+        };
+        if (Object.keys(body).length === 1) {
+            throw new Error("tenki_update_template: pass at least one field to change — nothing was sent.");
+        }
+        return ok(await client.control("UpdateTemplate", body));
+    });
+    // ── Delete ──────────────────────────────────────────────────────────────────
+    server.tool("tenki_delete_template", "Delete a template by ID. Pass force to delete even when builds or dependents exist.", {
+        template_id: z.string().describe("The template ID to delete."),
+        force: z.boolean().optional().describe("Force deletion despite dependents (default false)."),
+    }, async ({ template_id, force }) => ok(await client.control("DeleteTemplate", {
+        templateId: template_id,
+        ...(force ? { force: true } : {}),
+    })));
+    // ── Build ───────────────────────────────────────────────────────────────────
+    server.tool("tenki_build_template", "Trigger a build for a template, producing a bootable image. Returns the created build — poll it with tenki_get_template_build until READY; the ready build's imageDigestRef is what tenki_create_sandbox's `image` arg takes.", {
+        template_id: z.string().describe("The template ID to build."),
+        image_name: z
+            .string()
+            .regex(/^[a-z][a-z0-9-]{0,63}$/, "lowercase letters, digits and hyphens; must start with a letter; max 64 chars")
+            .optional()
+            .describe("Name for the resulting image (^[a-z][a-z0-9-]{0,63}$). Requires a TYPED template (created with builder_spec) — the API rejects it for legacy setup-script templates."),
+        publish_raw_image: z.boolean().optional().describe("Publish the raw rootfs image alongside the build snapshot."),
+        build_secrets: z.record(z.string(), z.string()).optional().describe("Build-time secrets as a key→value object (not persisted into the image)."),
+        build_env: z.record(z.string(), z.string()).optional().describe("Per-build environment overrides frozen into this build only."),
+    }, async ({ template_id, image_name, publish_raw_image, build_secrets, build_env }) => ok(await client.control("BuildTemplate", {
+        templateId: template_id,
+        ...(image_name !== undefined ? { imageName: image_name } : {}),
+        ...(publish_raw_image !== undefined ? { publishRawImage: publish_raw_image } : {}),
+        ...(build_secrets && Object.keys(build_secrets).length ? { buildSecrets: build_secrets } : {}),
+        ...(build_env && Object.keys(build_env).length ? { buildEnv: build_env } : {}),
+    })));
+    // ── Cancel build ──────────────────────────────────────────────────────────────
+    server.tool("tenki_cancel_template_build", "Cancel an in-progress template build by its build ID.", { build_id: z.string().describe("The template build ID to cancel.") }, async ({ build_id }) => ok(await client.control("CancelTemplateBuild", { buildId: build_id })));
+    // ── Get build ─────────────────────────────────────────────────────────────────
+    server.tool("tenki_get_template_build", "Retrieve one template build by its build ID (state, progress, and result image). A READY build's imageDigestRef is the reference tenki_create_sandbox's `image` arg takes.", { build_id: z.string().describe("The template build ID.") }, async ({ build_id }) => ok(await client.control("GetTemplateBuild", { buildId: build_id })));
+    // ── List active builds ──────────────────────────────────────────────────────────
+    server.tool("tenki_list_active_template_builds", "List the currently active (in-progress) builds for a given template.", { template_id: z.string().describe("The template ID whose active builds to list.") }, async ({ template_id }) => ok(await client.control("ListActiveTemplateBuilds", { templateId: template_id })));
+    // ── List builds (history + storage) ─────────────────────────────────────────────
+    server.tool("tenki_list_template_builds", "List every build of a template (not just active ones) with what each image holds in workspace storage: version, state, imageBytes, isCurrent, isLaunchable, and deleteBlockedReason (empty when tenki_delete_template_build can free it). Also returns the template-level storage totals.", { template_id: z.string().min(1).describe("The template ID whose builds to list.") }, async ({ template_id }) => ok(await client.control("ListTemplateBuilds", { templateId: template_id })));
+    // ── Delete build ────────────────────────────────────────────────────────────────
+    server.tool("tenki_delete_template_build", "Delete one template build's image to free workspace storage and retire the build (irreversible; a published image version carrying this build is removed with it). Refused with failed_precondition when the image cannot be freed, e.g. the build is still running, its image is still being written or deleted, the template is published from it, a sandbox that is not terminated (running or paused) still uses it, or an image tag, share, snapshot variant or derived template references it — check deleteBlockedReason via tenki_list_template_builds first (empty = deletable). Deleting the template's current build repoints the template at its latest remaining launchable build, or leaves it with none. Returns freedBytes, or cleanupPending when the image is still being removed.", { build_id: z.string().min(1).describe("The template build ID to delete.") }, async ({ build_id }) => ok(await client.control("DeleteTemplateBuild", { buildId: build_id })));
+}

package/dist/tools/titles.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Human-readable tool titles, applied centrally by the registration guard in
+ * server.ts so every tool advertises one (MCP `Tool.title` and
+ * `annotations.title`). Connector directories require a title on every tool;
+ * test/presubmission.test.mjs fails if a registered tool has no entry here or an
+ * entry names a tool that is not registered.
+ */
+export declare const TOOL_TITLES: Readonly<Record<string, string>>;

package/dist/tools/titles.js

@@ -0,0 +1,102 @@
+/**
+ * Human-readable tool titles, applied centrally by the registration guard in
+ * server.ts so every tool advertises one (MCP `Tool.title` and
+ * `annotations.title`). Connector directories require a title on every tool;
+ * test/presubmission.test.mjs fails if a registered tool has no entry here or an
+ * entry names a tool that is not registered.
+ */
+export const TOOL_TITLES = {
+    // Identity / auth
+    tenki_whoami: "Show Current Identity",
+    tenki_auth_status: "Check Credential Status",
+    // Sandboxes
+    tenki_run_code: "Run Code in a Throwaway Sandbox",
+    tenki_create_sandbox: "Create Sandbox",
+    tenki_get_sandbox: "Get Sandbox",
+    tenki_get_sandbox_metrics: "Get Sandbox Metrics",
+    tenki_list_sandboxes: "List Sandboxes",
+    tenki_list_workspace_sandboxes: "List Workspace Sandboxes",
+    tenki_terminate_sandbox: "Terminate Sandbox",
+    tenki_terminate_sandboxes: "Terminate Multiple Sandboxes",
+    tenki_pause_sandbox: "Pause Sandbox",
+    tenki_resume_sandbox: "Resume Sandbox",
+    tenki_fork_sandbox: "Fork Sandbox",
+    tenki_extend_sandbox: "Extend Sandbox Lifetime",
+    tenki_update_sandbox: "Update Sandbox",
+    tenki_report_sandbox_activity: "Report Sandbox Activity",
+    // Commands and files
+    tenki_exec: "Run Command in Sandbox",
+    tenki_read_file: "Read File",
+    tenki_write_file: "Write File",
+    tenki_list_files: "List Directory",
+    tenki_stat_path: "Get Path Info",
+    tenki_make_dir: "Create Directory",
+    tenki_remove_path: "Delete File or Directory",
+    tenki_move_path: "Move or Rename Path",
+    tenki_get_upload_url: "Get File Upload URL",
+    tenki_get_download_url: "Get Artifact Download URL",
+    // Git
+    tenki_git_clone: "Clone Git Repository",
+    tenki_git_checkout: "Check Out Git Ref",
+    tenki_git_diff: "Show Git Diff",
+    tenki_git_log: "Show Git Log",
+    // Ports and previews
+    tenki_expose_port: "Expose Port",
+    tenki_list_exposed_ports: "List Exposed Ports",
+    tenki_unexpose_port: "Unexpose Port",
+    tenki_create_preview_url: "Create Preview URL",
+    tenki_open_preview: "Open Authenticated Preview",
+    tenki_list_preview_urls: "List Preview URLs",
+    tenki_get_preview_url: "Get Preview URL",
+    tenki_delete_preview_url: "Delete Preview URL",
+    tenki_touch_preview: "Keep Preview Alive",
+    tenki_bind_preview_url: "Bind Preview URL",
+    tenki_unbind_preview_url: "Unbind Preview URL",
+    tenki_resolve_preview_token: "Resolve Preview Token",
+    // Snapshots
+    tenki_create_snapshot: "Create Snapshot",
+    tenki_get_snapshot: "Get Snapshot",
+    tenki_list_snapshots: "List Snapshots",
+    tenki_list_session_snapshots: "List Sandbox Snapshots",
+    tenki_list_dangling_snapshots: "List Dangling Snapshots",
+    tenki_list_workspace_snapshots: "List Workspace Snapshots",
+    tenki_update_snapshot: "Update Snapshot",
+    tenki_delete_snapshot: "Delete Snapshot",
+    tenki_get_snapshot_download_url: "Get Snapshot Download URL",
+    // Volumes
+    tenki_create_volume: "Create Volume",
+    tenki_get_volume: "Get Volume",
+    tenki_list_volumes: "List Volumes",
+    tenki_update_volume: "Update Volume",
+    tenki_delete_volume: "Delete Volume",
+    tenki_resize_volume: "Resize Volume",
+    tenki_attach_volume: "Attach Volume",
+    tenki_detach_volume: "Detach Volume",
+    // Egress policies
+    tenki_create_egress_policy: "Create Egress Policy",
+    tenki_get_egress_policy: "Get Egress Policy",
+    tenki_list_egress_policies: "List Egress Policies",
+    tenki_update_egress_policy: "Replace Egress Policy",
+    tenki_delete_egress_policy: "Delete Egress Policy",
+    // Templates
+    tenki_create_template: "Create Template",
+    tenki_get_template: "Get Template",
+    tenki_list_templates: "List Templates",
+    tenki_update_template: "Update Template",
+    tenki_delete_template: "Delete Template",
+    tenki_build_template: "Build Template",
+    tenki_cancel_template_build: "Cancel Template Build",
+    tenki_get_template_build: "Get Template Build",
+    tenki_list_active_template_builds: "List Active Template Builds",
+    tenki_list_template_builds: "List Template Builds",
+    tenki_delete_template_build: "Delete Template Build",
+    // Workspace
+    tenki_get_workspace_usage: "Get Workspace Usage",
+    tenki_list_ci_runner_sizes: "List CI Runner Sizes",
+    tenki_get_workspace_preview_domains: "Get Wildcard Preview Domains",
+    tenki_update_workspace_preview_domains: "Update Wildcard Preview Domains",
+    // SSH
+    tenki_update_ssh_keys: "Set SSH Authorized Keys",
+    tenki_issue_ssh_cert: "Issue SSH Certificate",
+    tenki_list_ssh_gateways: "List SSH Gateways",
+};

package/dist/tools/volumes.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Volume tools — workspace-scoped persistent block storage for Tenki sandboxes.
+ *
+ * Volumes are durable disks that outlive any single sandbox: create one in a
+ * workspace, then attach it into a running session at a mount path. All calls
+ * here are control-plane (tenki.sandbox.v1.SandboxService). Method names and
+ * request field shapes are ported from the live-verified n8n community node
+ * (github.com/opencolin/n8n-nodes-tenki) and its endpoint research:
+ *   CreateVolume · GetVolume · ListVolumes · UpdateVolume · DeleteVolume ·
+ *   ResizeVolume · AttachVolume · DetachVolume
+ *
+ * CreateVolumeRequest is flat: { workspaceId, name, sizeBytes (int64) }.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+export declare function registerVolumes(server: McpServer, client: TenkiClient): void;