@tenkicloud/mcp 0.1.0

package/dist/tools/registry.js

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { ok } from "./common.js";
+const VISIBILITY = { public: "REGISTRY_VISIBILITY_PUBLIC", private: "REGISTRY_VISIBILITY_PRIVATE" };
+const IMAGE_KIND = { snapshot: "REGISTRY_IMAGE_KIND_SNAPSHOT", template: "REGISTRY_IMAGE_KIND_TEMPLATE" };
+export function registerRegistry(server, client) {
+    // ── Publish ─────────────────────────────────────────────────────────────────
+    server.tool("tenki_publish_image", "Publish a custom sandbox image into the workspace registry from a snapshot or a template.", {
+        reference: z
+            .string()
+            .regex(/^[^:@]+$/, "publish takes the TAGLESS form <workspace>/<artifact> — the API rejects a tag or @snapshot here")
+            .describe("Target image reference in TAGLESS form <workspace>/<artifact>, e.g. myws/myimage — the API rejects a tag or @snapshot on publish."),
+        kind: z.enum(["snapshot", "template"]).describe("Source kind for the image contents."),
+        snapshot_id: z.string().optional().describe("Snapshot id to publish (required when kind=snapshot)."),
+        source_template_id: z.string().optional().describe("Template id to publish (required when kind=template)."),
+        visibility: z.enum(["public", "private"]).optional().describe("public (resolvable by anyone) or private (default)."),
+    }, async ({ reference, kind, snapshot_id, source_template_id, visibility }) => ok(await client.control("PublishRegistryImage", {
+        ref: reference,
+        kind: IMAGE_KIND[kind],
+        ...(snapshot_id !== undefined ? { snapshotId: snapshot_id } : {}),
+        ...(source_template_id !== undefined ? { sourceTemplateId: source_template_id } : {}),
+        ...(visibility !== undefined ? { visibility: VISIBILITY[visibility] } : {}),
+    })));
+    // ── Get ─────────────────────────────────────────────────────────────────────
+    server.tool("tenki_get_image", "Retrieve one custom sandbox image from the registry by its reference.", { reference: z.string().describe("Image reference <workspace>/<artifact>[:tag].") }, async ({ reference }) => ok(await client.control("GetRegistryImage", { ref: reference })));
+    // ── List ────────────────────────────────────────────────────────────────────
+    server.tool("tenki_list_images", "List custom sandbox images in the registry, optionally filtered to a single workspace.", {
+        workspace_id: z.string().optional().describe("Optional workspace to filter the listed images by."),
+        page_size: z.number().int().positive().optional().describe("Max images to return per page."),
+        page_token: z.string().optional().describe("Pagination token from a previous response's nextPageToken."),
+    }, async ({ workspace_id, page_size, page_token }) => ok(await client.control("ListRegistryImages", {
+        ...(workspace_id !== undefined ? { workspaceId: workspace_id } : {}),
+        ...(page_size !== undefined ? { pageSize: page_size } : {}),
+        ...(page_token !== undefined ? { pageToken: page_token } : {}),
+    })));
+    // ── Set visibility ────────────────────────────────────────────────────────────
+    server.tool("tenki_set_image_visibility", "Make a custom sandbox image public (publicly resolvable) or private (restricted to the workspace).", {
+        reference: z.string().describe("Image reference <workspace>/<artifact>[:tag]."),
+        visibility: z.enum(["public", "private"]).describe("Target visibility for the image."),
+    }, async ({ reference, visibility }) => ok(await client.control("SetRegistryImageVisibility", { ref: reference, visibility: VISIBILITY[visibility] })));
+    // ── Delete (whole image by ref, or one version by ids) ─────────────────────────
+    server.tool("tenki_delete_image", "Delete a custom sandbox image (by reference), or delete a single version (by image_id + snapshot_id).", {
+        reference: z.string().optional().describe("Image reference to delete the whole image."),
+        image_id: z.string().optional().describe("Image UUID (with snapshot_id) to delete a single version."),
+        snapshot_id: z.string().optional().describe("Snapshot UUID (with image_id) to delete a single version."),
+    }, async ({ reference, image_id, snapshot_id }) => {
+        if (image_id !== undefined && snapshot_id !== undefined) {
+            return ok(await client.control("DeleteRegistryImageVersion", { imageId: image_id, snapshotId: snapshot_id }));
+        }
+        if (reference !== undefined)
+            return ok(await client.control("DeleteRegistryImage", { ref: reference }));
+        throw new Error("Provide `reference` to delete an image, or `image_id`+`snapshot_id` to delete one version.");
+    });
+    // ── Resolve ref ────────────────────────────────────────────────────────────────
+    server.tool("tenki_resolve_image_ref", "Resolve a registry reference (tag or ref) to its concrete pinned digest/ref.", { registry_ref: z.string().describe("The registry reference to resolve, e.g. myws/myimage:latest.") }, async ({ registry_ref }) => {
+        const owner = await client.resolveOwner();
+        return ok(await client.control("ResolveRegistryRef", {
+            ref: registry_ref,
+            ...(owner.workspaceId ? { workspaceId: owner.workspaceId } : {}),
+        }));
+    });
+    // ── Share ──────────────────────────────────────────────────────────────────────
+    server.tool("tenki_share_image", "Grant another workspace access to a custom sandbox image.", {
+        reference: z.string().describe("Image reference <workspace>/<artifact>[:tag]."),
+        grantee_workspace_id: z.string().describe("The workspace to grant access to."),
+    }, 
+    // ShareImage uses imageRef + targetWorkspaceId (not ref/granteeWorkspaceId).
+    async ({ reference, grantee_workspace_id }) => ok(await client.control("ShareImage", { imageRef: reference, targetWorkspaceId: grantee_workspace_id })));
+    // ── Unshare (revoke a share) ────────────────────────────────────────────────────
+    server.tool("tenki_unshare_image", "Revoke a previously-granted share on a custom sandbox image, by grant id or grantee workspace.", {
+        reference: z.string().describe("Image reference (use the TAGLESS <workspace>/<artifact> form)."),
+        grant_id: z.string().optional().describe("Specific share grant to revoke (preferred; provide this or grantee_workspace_id)."),
+        grantee_workspace_id: z.string().optional().describe("Workspace whose access to revoke."),
+    }, async ({ reference, grant_id, grantee_workspace_id }) => {
+        // Without one of these the server revokes nothing and still returns the
+        // image object, which reads as a successful revoke. Mirror the guard
+        // tenki_delete_image already applies to its own one-of.
+        if (!grant_id && !grantee_workspace_id) {
+            throw new Error("tenki_unshare_image: pass grant_id (preferred) or grantee_workspace_id. With neither, the API revokes nothing and returns the image unchanged, which looks like success.");
+        }
+        return ok(await client.control("UnshareRegistryImage", {
+            ref: reference,
+            ...(grant_id !== undefined ? { grantId: grant_id } : {}),
+            ...(grantee_workspace_id !== undefined ? { targetWorkspaceId: grantee_workspace_id } : {}),
+        }));
+    });
+    // ── List share grants ───────────────────────────────────────────────────────────
+    server.tool("tenki_list_image_share_grants", "List the share grants (workspaces granted access) on a custom sandbox image.", {
+        reference: z.string().describe("Image reference to list grants for (use the TAGLESS <workspace>/<artifact> form)."),
+        page_size: z.number().int().positive().optional().describe("Max grants to return per page."),
+        page_token: z.string().optional().describe("Pagination token from a previous response's nextPageToken."),
+    }, async ({ reference, page_size, page_token }) => ok(await client.control("ListRegistryShareGrants", {
+        ref: reference,
+        ...(page_size !== undefined ? { pageSize: page_size } : {}),
+        ...(page_token !== undefined ? { pageToken: page_token } : {}),
+    })));
+    // ── Revoke a specific share grant (by grant id) ─────────────────────────────────
+    server.tool("tenki_revoke_image_share_grant", "Revoke a specific registry-image share grant by its grant id.", { grant_id: z.string().describe("The share grant id (UUID) to revoke.") }, async ({ grant_id }) => ok(await client.control("RevokeRegistryShareGrant", { grantId: grant_id })));
+}

package/dist/tools/run.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/** The headline one-shot execution tool. */
+export declare function registerRun(server: McpServer, client: TenkiClient): void;

package/dist/tools/run.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { ok, envSchema } from "./common.js";
+/** The headline one-shot execution tool. */
+export function registerRun(server, client) {
+    server.tool("tenki_run_code", "Boot a throwaway microVM, run a snippet (shell/python/javascript), return its stdout/stderr/exit code, and tear the sandbox down. Cost-guarded and self-terminating. Use this for one-shot execution when you don't need a persistent sandbox.", {
+        language: z.enum(["shell", "python", "javascript"]).describe("Interpreter for the snippet."),
+        code: z.string().describe("The code to run."),
+        env: envSchema,
+        timeout_seconds: z.number().int().positive().optional().describe("Max seconds for the run (default 30)."),
+    }, async ({ language, code, env, timeout_seconds }) => ok(await client.runCode(language, code, { env, timeoutSeconds: timeout_seconds })));
+}

package/dist/tools/sandboxes.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/** Sandbox (session) lifecycle. */
+export declare function registerSandboxes(server: McpServer, client: TenkiClient): void;

package/dist/tools/sandboxes.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { ok, envSchema, sessionIdSchema } from "./common.js";
+/** Sandbox (session) lifecycle. */
+export function registerSandboxes(server, client) {
+    server.tool("tenki_create_sandbox", "Create a persistent sandbox microVM. Returns the session (id, state) and its data-plane endpoint. Boots in ~2s. Use tenki_exec / tenki_read_file / tenki_write_file against the returned session_id.", {
+        name: z.string().optional().describe("Human-readable name."),
+        cpu_cores: z.number().int().min(1).max(16).optional().describe("vCPUs (default 2)."),
+        memory_mb: z.number().int().min(128).max(65536).optional().describe("Memory in MB (default 4096)."),
+        disk_size_gb: z.number().int().positive().optional().describe("Disk in GB (default 5)."),
+        max_duration_seconds: z.number().int().positive().optional().describe("Hard lifetime cap in seconds."),
+        idle_timeout_minutes: z.number().int().positive().optional().describe("Reap after N idle minutes."),
+        clone_repo_url: z.string().optional().describe("Git URL to clone into the sandbox on boot."),
+        allow_outbound: z.boolean().optional().describe("Allow outbound networking (off by default)."),
+        allow_inbound: z.boolean().optional().describe("Allow inbound networking (off by default)."),
+        snapshot_id: z.string().optional().describe("Boot from a snapshot."),
+        registry_ref: z.string().optional().describe("Boot from a custom registry image."),
+        tags: z.array(z.string()).optional().describe("Tags for later filtering."),
+        project_id: z.string().optional().describe("Project to create in (defaults to the key's first project)."),
+        workspace_id: z.string().optional().describe("Workspace to create in (defaults to the key's first workspace)."),
+        env: envSchema,
+        wait_ready: z.boolean().optional().describe("Poll until the sandbox is RUNNING before returning (default true)."),
+    }, async (a) => {
+        const owner = await client.resolveOwner();
+        const projectId = a.project_id ?? owner.projectId;
+        const workspaceId = a.workspace_id ?? owner.workspaceId;
+        const body = {
+            ...(owner.ownerType ? { ownerType: owner.ownerType } : {}),
+            ...(owner.ownerId ? { ownerId: owner.ownerId } : {}),
+            ...(workspaceId ? { workspaceId } : {}),
+            ...(projectId ? { projectId } : {}),
+            ...(a.name ? { name: a.name } : {}),
+            ...(a.cpu_cores ? { cpuCores: a.cpu_cores } : {}),
+            ...(a.memory_mb ? { memoryMb: a.memory_mb } : {}),
+            ...(a.disk_size_gb ? { diskSizeGb: a.disk_size_gb } : {}),
+            ...(a.max_duration_seconds ? { maxDuration: `${a.max_duration_seconds}s` } : {}),
+            ...(a.idle_timeout_minutes ? { idleTimeoutMinutes: a.idle_timeout_minutes } : {}),
+            ...(a.clone_repo_url ? { cloneRepoUrl: a.clone_repo_url } : {}),
+            ...(a.allow_outbound ? { allowOutbound: true } : {}),
+            ...(a.allow_inbound ? { allowInbound: true } : {}),
+            ...(a.snapshot_id ? { snapshotId: a.snapshot_id } : {}),
+            ...(a.registry_ref ? { registryRef: a.registry_ref } : {}),
+            ...(a.tags && a.tags.length ? { tags: a.tags } : {}),
+            ...(a.env && Object.keys(a.env).length ? { env: a.env } : {}),
+        };
+        const resp = await client.control("CreateSession", body);
+        const session = resp.session ?? resp;
+        const sessionId = session.id ?? resp.sessionId;
+        const dataPlaneEndpoint = resp.dataPlaneEndpoint ?? resp.data_plane_endpoint;
+        const wait = a.wait_ready !== false;
+        const finalSession = wait && sessionId ? await client.waitForState(sessionId, "RUNNING") : session;
+        return ok({ session: finalSession, dataPlaneEndpoint });
+    });
+    server.tool("tenki_get_sandbox", "Fetch a sandbox's current state and metadata.", { session_id: sessionIdSchema }, async ({ session_id }) => ok(await client.control("GetSession", { sessionId: session_id })));
+    server.tool("tenki_list_sandboxes", "List sandboxes for the workspace.", {
+        include_terminated: z.boolean().optional().describe("Include terminated sandboxes (default false)."),
+        page_size: z.number().int().positive().optional(),
+        page_token: z.string().optional(),
+    }, async ({ include_terminated, page_size, page_token }) => ok(await client.control("ListSessions", {
+        ...(include_terminated ? { includeTerminated: true } : {}),
+        ...(page_size ? { pageSize: page_size } : {}),
+        ...(page_token ? { pageToken: page_token } : {}),
+    })));
+    server.tool("tenki_terminate_sandbox", "Terminate (destroy) a sandbox. The microVM and its filesystem are gone after this.", { session_id: sessionIdSchema }, async ({ session_id }) => ok(await client.control("TerminateSession", { sessionId: session_id })));
+    server.tool("tenki_pause_sandbox", "Pause a sandbox (snapshot + suspend) so it can be resumed later.", { session_id: sessionIdSchema }, async ({ session_id }) => ok(await client.control("PauseSession", { sessionId: session_id })));
+    server.tool("tenki_resume_sandbox", "Resume a previously paused sandbox.", { session_id: sessionIdSchema }, async ({ session_id }) => ok(await client.control("ResumeSession", { sessionId: session_id })));
+}

package/dist/tools/sessions_admin.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/**
+ * Extended sandbox (session) admin ops on the control plane: wall-clock lifetime
+ * extension, mutable-field updates, bulk termination, activity heartbeats, and
+ * workspace/project-scoped listing. The lifecycle basics
+ * (create/get/list/terminate/pause/resume) live in sandboxes.ts.
+ */
+export declare function registerSessionsAdmin(server: McpServer, client: TenkiClient): void;

package/dist/tools/sessions_admin.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { ok, sessionIdSchema } from "./common.js";
+/**
+ * Extended sandbox (session) admin ops on the control plane: wall-clock lifetime
+ * extension, mutable-field updates, bulk termination, activity heartbeats, and
+ * workspace/project-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 — its name, tags, idle timeout, or max duration.", {
+        session_id: sessionIdSchema.describe("The sandbox/session ID to update."),
+        name: z.string().optional().describe("New human-readable name."),
+        tags: z.array(z.string()).optional().describe("Replacement tag list (send [] to clear all tags)."),
+        idle_timeout_minutes: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Auto-pause after this many idle minutes (cost-safety cap)."),
+        max_duration_seconds: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("New hard lifetime cap in seconds (sent as a Duration string, e.g. 3600s)."),
+    }, async ({ session_id, name, tags, idle_timeout_minutes, max_duration_seconds }) => ok(await client.control("UpdateSession", {
+        sessionId: session_id,
+        ...(name !== undefined ? { name } : {}),
+        ...(tags !== undefined ? { tags } : {}),
+        ...(idle_timeout_minutes !== undefined ? { idleTimeoutMinutes: idle_timeout_minutes } : {}),
+        ...(max_duration_seconds !== undefined ? { maxDuration: `${max_duration_seconds}s` } : {}),
+    })));
+    server.tool("tenki_terminate_sandboxes", "Terminate MULTIPLE sandboxes in one call (bulk). IRREVERSIBLE — every listed sandbox and its filesystem is destroyed. Use tenki_terminate_sandbox for a single one.", {
+        session_ids: z.array(sessionIdSchema).min(1).describe("The sandbox/session IDs to terminate."),
+    }, 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) — useful for spotting leaked, still-billing sandboxes across the workspace.", {
+        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)."),
+        page_size: z.number().int().positive().optional(),
+        page_token: z.string().optional(),
+    }, async ({ workspace_id, include_terminated, page_size, page_token }) => {
+        const workspaceId = workspace_id ?? (await client.resolveOwner()).workspaceId;
+        return ok(await client.control("ListWorkspaceSandboxes", {
+            ...(workspaceId ? { workspaceId } : {}),
+            ...(include_terminated ? { includeTerminated: true } : {}),
+            ...(page_size ? { pageSize: page_size } : {}),
+            ...(page_token ? { pageToken: page_token } : {}),
+        }));
+    });
+    server.tool("tenki_list_project_sandboxes", "List every sandbox belonging to a specific project (defaults to the API key's default project).", {
+        project_id: z.string().optional().describe("Project to list (defaults to the key's first project)."),
+        include_terminated: z.boolean().optional().describe("Include terminated sandboxes (default false)."),
+        page_size: z.number().int().positive().optional(),
+        page_token: z.string().optional(),
+    }, async ({ project_id, include_terminated, page_size, page_token }) => {
+        const projectId = project_id ?? (await client.resolveOwner()).projectId;
+        return ok(await client.control("ListProjectSandboxes", {
+            ...(projectId ? { projectId } : {}),
+            ...(include_terminated ? { includeTerminated: true } : {}),
+            ...(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,91 @@
+import { z } from "zod";
+import { ok, sessionIdSchema } 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 ({ session_id, name, expires_at, store_raw_image }) => ok(await client.control("CreateSnapshot", {
+        sessionId: session_id,
+        ...(name ? { name } : {}),
+        ...(expires_at ? { expiresAt: expires_at } : {}),
+        ...(store_raw_image !== undefined ? { storeRawImage: store_raw_image } : {}),
+    })));
+    server.tool("tenki_get_snapshot", "Fetch one snapshot's status and metadata by ID.", { snapshot_id: z.string() }, 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(),
+        page_token: z.string().optional(),
+    }, 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(),
+        page_token: z.string().optional(),
+    }, 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(),
+        page_token: z.string().optional(),
+    }, 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 and/or expiry).", {
+        snapshot_id: z.string(),
+        name: z.string().optional().describe("New human-readable name."),
+        expires_at: z
+            .string()
+            .optional()
+            .describe("New RFC-3339 / ISO-8601 auto-delete timestamp."),
+    }, async ({ snapshot_id, name, expires_at }) => ok(await client.control("UpdateSnapshot", {
+        snapshotId: snapshot_id,
+        ...(name !== undefined ? { name } : {}),
+        ...(expires_at !== undefined ? { expiresAt: expires_at } : {}),
+    })));
+    server.tool("tenki_delete_snapshot", "Permanently delete a snapshot by ID.", { snapshot_id: z.string() }, 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() }, 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.", {
+        workspace_id: z.string().optional().describe("Workspace to list (defaults to the key's first workspace)."),
+        page_size: z.number().int().positive().optional(),
+        page_token: z.string().optional(),
+    }, 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 } : {}),
+        }));
+    });
+    server.tool("tenki_list_project_snapshots", "List all snapshots in a project (defaults to the key's first project). Supports pagination.", {
+        project_id: z.string().optional().describe("Project to list (defaults to the key's first project)."),
+        page_size: z.number().int().positive().optional(),
+        page_token: z.string().optional(),
+    }, async ({ project_id, page_size, page_token }) => {
+        const projectId = project_id ?? (await client.resolveOwner()).projectId;
+        return ok(await client.control("ListProjectSnapshots", {
+            ...(projectId ? { projectId } : {}),
+            ...(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 are grounded in the published Tenki API surface (CreateSession's
+ * ssh_authorized_keys field → sshAuthorizedKeys). The cert-issuance and gateway
+ * shapes are SDK-name-verified but not exercised end-to-end here.
+ */
+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,17 @@
+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.", {
+        session_id: sessionIdSchema,
+        public_keys: z.array(z.string()).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.", {
+        session_id: sessionIdSchema,
+        public_key: z.string().describe("The SSH public key to sign into a certificate."),
+    }, async ({ session_id, public_key }) => ok(await client.control("IssueSandboxSSHCert", { sessionId: session_id, publicKey: public_key }, SSH_GATEWAY_SERVICE)));
+    server.tool("tenki_list_ssh_gateways", "List the currently active SSH gateways for the workspace.", { workspace_id: z.string().optional().describe("Workspace to list (defaults to the key's first workspace).") }, async ({ workspace_id }) => {
+        const workspaceId = workspace_id ?? (await client.resolveOwner()).workspaceId;
+        return ok(await client.control("ListActiveSSHGateways", { ...(workspaceId ? { workspaceId } : {}) }, SSH_GATEWAY_SERVICE));
+    });
+}

package/dist/tools/templates.d.ts

@@ -0,0 +1,14 @@
+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 is scoped by `templateId`.
+ */
+export declare function registerTemplates(server: McpServer, client: TenkiClient): void;

package/dist/tools/templates.js

@@ -0,0 +1,151 @@
+import { z } from "zod";
+import { ok, envSchema } 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 is 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.", {
+        name: z.string().describe("Human-readable template name."),
+        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(16).optional().describe("Default vCPUs for sandboxes from this template (1-16)."),
+        memory_mb: z.number().int().min(512).max(65536).optional().describe("Default memory in MB (512-65536)."),
+        disk_size_gb: z.number().int().min(5).max(100).optional().describe("Default disk in GB (5-100)."),
+        env_vars: envSchema,
+        tags: z.array(z.string()).optional().describe("Tags for later filtering."),
+        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.unknown()).optional().describe("Advanced structured build spec (TemplateBuildSpec); passed through as-is."),
+        workspace_id: z.string().optional().describe("Workspace to create in (defaults to the key's first workspace)."),
+        project_id: z.string().optional().describe("Project to create in (defaults to the key's first project)."),
+    }, async (a) => {
+        const owner = await client.resolveOwner();
+        const workspaceId = a.workspace_id ?? owner.workspaceId;
+        const projectId = a.project_id ?? owner.projectId;
+        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 } : {}),
+            ...(projectId ? { projectId } : {}),
+            ...(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, optionally filtered by tags.", {
+        tags: z.array(z.string()).optional().describe("Only return templates that carry all of these tags."),
+        workspace_id: z.string().optional().describe("Workspace to list from (defaults to the key's first workspace)."),
+        page_size: z.number().int().positive().optional(),
+        page_token: z.string().optional(),
+    }, async ({ tags, 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 } : {}),
+            ...(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(16).optional().describe("New default vCPUs (1-16)."),
+        memory_mb: z.number().int().min(512).max(65536).optional().describe("New default memory in MB (512-65536)."),
+        disk_size_gb: z.number().int().min(5).max(100).optional().describe("New default disk in GB (5-100)."),
+        env_vars: envSchema,
+        tags: z.array(z.string()).optional().describe("Replacement set of tags."),
+        clear_tags: z.boolean().optional().describe("Remove all tags from the template."),
+        builder_spec: z.record(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 } : {}),
+            ...(a.tags && a.tags.length ? { tags: a.tags } : {}),
+            ...(a.clear_tags ? { clearTags: true } : {}),
+            ...(a.builder_spec ? { builderSpec: a.builder_spec } : {}),
+        };
+        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).", {
+        template_id: z.string().describe("The template ID to build."),
+        image_name: z.string().optional().describe("Name for the resulting image."),
+        publish_raw_image: z.boolean().optional().describe("Publish the raw rootfs image alongside the build snapshot."),
+        build_secrets: z.record(z.string()).optional().describe("Build-time secrets as a key→value object (not persisted into the image)."),
+        build_env: z.record(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).", { 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 })));
+    server.tool("tenki_list_project_templates", "List templates in a project (defaults to the key's first project). Supports pagination.", {
+        project_id: z.string().optional().describe("Project to list (defaults to the key's first project)."),
+        page_size: z.number().int().positive().optional(),
+        page_token: z.string().optional(),
+    }, async ({ project_id, page_size, page_token }) => {
+        const projectId = project_id ?? (await client.resolveOwner()).projectId;
+        return ok(await client.control("ListProjectTemplates", {
+            ...(projectId ? { projectId } : {}),
+            ...(page_size ? { pageSize: page_size } : {}),
+            ...(page_token ? { pageToken: page_token } : {}),
+        }));
+    });
+}

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), projectId? }.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+export declare function registerVolumes(server: McpServer, client: TenkiClient): void;