@tenkicloud/mcp 0.1.0 → 0.3.0

package/dist/tools/auth_status.js

@@ -9,6 +9,8 @@ export function describeCredential(env = process.env) {
     const fromToken = env.TENKI_AUTH_TOKEN?.trim();
     const fromKey = env.TENKI_API_KEY?.trim();
     const raw = fromToken || fromKey;
+    if (!raw && env.TENKI_MCP_OAUTH_ISSUER?.trim())
+        return { kind: "hosted_oauth" };
     if (!raw)
         return { kind: "none" };
     const source = fromToken ? "TENKI_AUTH_TOKEN" : "TENKI_API_KEY";
@@ -19,16 +21,17 @@ export function describeCredential(env = process.env) {
     return { kind: "session_cookie", source };
 }
 const CREDENTIAL_HELP = {
-    none: "No credential found. Set TENKI_API_KEY (a tk_… API key) or TENKI_AUTH_TOKEN (an ory_st_… session token) in the server's environment, then restart it — MCP clients pass env through their server config, e.g. `claude mcp add tenki --env TENKI_API_KEY=tk_… -- npx -y tenki-mcp`, or the \"env\" block in claude_desktop_config.json / .cursor/mcp.json.",
+    none: "No credential found. Set TENKI_API_KEY (a tk_… API key) or TENKI_AUTH_TOKEN (an ory_st_… session token) in the server's environment, then restart it — MCP clients pass env through their server config, e.g. `claude mcp add tenki --env TENKI_API_KEY=tk_… -- npx -y @tenkicloud/mcp`, or the \"env\" block in claude_desktop_config.json / .cursor/mcp.json.",
     api_key: "Authenticated with a tk_… API key (Authorization: Bearer).",
     oauth_session_token: "Authenticated with an ory_st_… session token (X-Session-Token). Session tokens expire; an API key is the stabler choice for a long-running server.",
     session_cookie: "Authenticated with a session cookie (the token matched neither the tk_ nor ory_st_ prefix, so it is sent as a tenki_session cookie). If that is not what you intended, check the value.",
+    hosted_oauth: "Authenticated through the hosted OAuth session for this MCP connection.",
 };
 const authOutputSchema = {
     authenticated: z.boolean().describe("True only when a credential is present AND a live identity probe succeeded."),
     credential: z
-        .enum(["none", "api_key", "oauth_session_token", "session_cookie"])
-        .describe("Kind of credential the server is running with, derived from its prefix. Never includes the token itself."),
+        .enum(["none", "api_key", "oauth_session_token", "session_cookie", "hosted_oauth"])
+        .describe("Kind of credential the server is running with. Never includes the token itself."),
     source: z
         .string()
         .optional()
@@ -96,7 +99,9 @@ export function registerAuthStatus(server, client, toolsRegistered) {
                 ...base,
                 authenticated: false,
                 error: e.message,
-                detail: `A ${cred.kind === "api_key" ? "tk_… API key" : "credential"} is set (from ${cred.source}) but the identity probe failed — it may be expired, revoked, or the endpoint may be wrong. ${CREDENTIAL_HELP.none}`,
+                detail: cred.kind === "hosted_oauth"
+                    ? "The hosted OAuth session is present, but the identity probe failed. Run MCP login again."
+                    : `A ${cred.kind === "api_key" ? "tk_… API key" : "credential"} is set (from ${cred.source}) but the identity probe failed — it may be expired, revoked, or the endpoint may be wrong. ${CREDENTIAL_HELP.none}`,
             };
             return { structuredContent: result, content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         }

package/dist/tools/common.d.ts

@@ -1,4 +1,6 @@
 import { z } from "zod";
+/** Keep registry-backed implementation fields out of public MCP responses. */
+export declare function publicValue(value: unknown): unknown;
 /** Serialize any tool return value as MCP text content. */
 export declare const ok: (value: unknown) => {
     content: {
@@ -21,7 +23,7 @@ export declare const portSchema: z.ZodNumber;
  * leading/trailing whitespace is legal in POSIX filenames, and zod's .trim()
  * (a transform, not a check) would silently retarget the operation to a
  * different file. Call sites override the description with their own examples. */
-export declare const pathSchema: z.ZodEffects<z.ZodString, string, string>;
+export declare const pathSchema: z.ZodString;
 /**
  * Preview-slug schema, matching the server's validatePreviewSlug: 3-63 chars,
  * lowercase/digits/hyphens, no leading/trailing hyphen. ExposePort routes a

package/dist/tools/common.js

@@ -1,10 +1,28 @@
 import { z } from "zod";
+const PUBLIC_KEYS = {
+    registryRef: "image",
+    registry_ref: "image",
+    sourceRegistryImageId: "sourceImageId",
+    source_registry_image_id: "source_image_id",
+    sourceRegistryWorkspaceId: "sourceImageWorkspaceId",
+    source_registry_workspace_id: "source_image_workspace_id",
+    sourceRegistryRef: "sourceImage",
+    source_registry_ref: "source_image",
+};
+/** Keep registry-backed implementation fields out of public MCP responses. */
+export function publicValue(value) {
+    if (Array.isArray(value))
+        return value.map(publicValue);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [PUBLIC_KEYS[key] ?? key, publicValue(child)]));
+}
 /** Serialize any tool return value as MCP text content. */
 export const ok = (value) => ({
-    content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    content: [{ type: "text", text: JSON.stringify(publicValue(value), null, 2) }],
 });
 /** Shared env-map schema used by tools that accept environment variables. */
-export const envSchema = z.record(z.string()).optional().describe("Environment variables as a key→value object.");
+export const envSchema = z.record(z.string(), z.string()).optional().describe("Environment variables as a key→value object.");
 /** Shared session-id schema — every per-sandbox tool takes one of these.
  * Trimmed, unlike pathSchema below: a session id is a UUID, so surrounding
  * whitespace is always an accident (and the API's uuid validation would

package/dist/tools/exec.js

@@ -16,6 +16,22 @@ const execOutputSchema = {
         .string()
         .optional()
         .describe("Present when the command ran but its output could not be read back; stdout/stderr are unknown, not empty."),
+    stdoutTruncated: z
+        .boolean()
+        .optional()
+        .describe("Present (true) when stdout exceeded the output cap and carries only a head+tail preview."),
+    stderrTruncated: z
+        .boolean()
+        .optional()
+        .describe("Present (true) when stderr exceeded the output cap and carries only a head+tail preview."),
+    stdoutPath: z
+        .string()
+        .optional()
+        .describe("Sandbox path holding the FULL stdout, present only when truncated — page through it with tenki_exec (e.g. sed -n / tail -c)."),
+    stderrPath: z
+        .string()
+        .optional()
+        .describe("Sandbox path holding the FULL stderr, present only when truncated — page through it with tenki_exec (e.g. sed -n / tail -c)."),
 };
 /**
  * Field drift between execOutputSchema and ExecResult must fail the build, not
@@ -46,8 +62,9 @@ function sanitizeForTerminal(s) {
 }
 /**
  * Render an ExecResult as plain text for clients that don't consume
- * structuredContent. Carries the FULL stdout/stderr (control chars escaped) —
- * output capping is a separate concern and must not silently drop data here.
+ * structuredContent. Carries the streams as returned (control chars escaped);
+ * any capping happened upstream in execCaptured, which marks it explicitly —
+ * a truncated stream carries an inline marker and its full-output path.
  */
 function execText(r) {
     const head = `exit ${r.exitCode}${r.ok ? "" : " (failed)"}`;
@@ -56,12 +73,14 @@ function execText(r) {
         : "";
     const stdout = sanitizeForTerminal(r.stdout);
     const stderr = sanitizeForTerminal(r.stderr);
-    return `${head}${capture}\n--- stdout (${r.stdout.length} chars, control chars escaped) ---\n${stdout}\n--- stderr (${r.stderr.length} chars, control chars escaped) ---\n${stderr}`;
+    const outTag = r.stdoutTruncated ? ", TRUNCATED — full output at " + r.stdoutPath : "";
+    const errTag = r.stderrTruncated ? ", TRUNCATED — full output at " + r.stderrPath : "";
+    return `${head}${capture}\n--- stdout (${r.stdout.length} chars, control chars escaped${outTag}) ---\n${stdout}\n--- stderr (${r.stderr.length} chars, control chars escaped${errTag}) ---\n${stderr}`;
 }
 /** Command execution inside an existing sandbox. */
 export function registerExec(server, client) {
     server.registerTool("tenki_exec", {
-        description: "Run a command in an existing sandbox and return stdout, stderr, and exit code inline.",
+        description: "Run a command in an existing sandbox and return stdout, stderr, and exit code inline. Streams over max_output_bytes (default 64KB) come back as a head+tail preview with the full output retained at stdoutPath/stderrPath in the sandbox.",
         inputSchema: {
             session_id: sessionIdSchema,
             command: z.string().describe("Executable, e.g. 'npm' or 'python3'."),
@@ -69,10 +88,23 @@ export function registerExec(server, client) {
             cwd: z.string().optional().describe("Working directory (honored in-script)."),
             env: envSchema,
             timeout_seconds: z.number().int().positive().optional(),
+            max_output_bytes: z
+                .number()
+                .int()
+                .min(1024)
+                .max(10_000_000)
+                .optional()
+                .describe("Per-stream inline output cap in bytes (default 65536). Larger output is truncated head+tail and kept in the sandbox at stdoutPath/stderrPath."),
         },
         outputSchema: execOutputSchema,
-    }, async ({ session_id, command, args, cwd, env, timeout_seconds }) => {
-        const result = await client.execCaptured(session_id, command, { args, cwd, env, timeoutSeconds: timeout_seconds });
+    }, async ({ session_id, command, args, cwd, env, timeout_seconds, max_output_bytes }) => {
+        const result = await client.execCaptured(session_id, command, {
+            args,
+            cwd,
+            env,
+            timeoutSeconds: timeout_seconds,
+            maxOutputBytes: max_output_bytes,
+        });
         return {
             structuredContent: { ...result },
             // Two text blocks: serialized JSON first (the MCP spec's

package/dist/tools/git.js

@@ -20,7 +20,7 @@ export function registerGit(server, client) {
         // accepted here and coerced — a client-side rejection of `create: true`
         // for a call that would serialize identically helps nobody.
         args: z
-            .record(z.union([z.string(), z.number(), z.boolean()]))
+            .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
             .optional()
             .describe("Operation args as a key→value object (values are sent as strings; numbers/booleans are coerced). clone: {repo, branch?, depth?, directory?}; checkout: {ref, create?: 'true'}; diff: {range?} or {base?, head?}, {path?}; log: {max_count?, range?, path?}."),
     }, async ({ session_id, operation, args }) => {

package/dist/tools/previews.d.ts

@@ -8,10 +8,10 @@
  *
  * All control-plane ConnectRPC calls on tenki.sandbox.v1.SandboxService.
  *
- * LIVE-VERIFIED shapes (2026-07-20): the preview-URL methods are PROJECT-scoped —
- * the server rejects them with `project_id: value is empty` unless a projectId is
- * sent, and CreatePreviewUrl additionally requires a `slug` (>=3 chars, [a-z0-9-]).
- * projectId defaults to the API key's first project; override with project_id.
+ * LIVE-VERIFIED shapes (2026-08-21): projects were REMOVED from the API (every
+ * project_id field is proto-reserved and unknown fields are silently discarded),
+ * so the preview-URL methods are workspace/id-scoped. CreatePreviewUrl requires
+ * a `slug` (>=3 chars, [a-z0-9-]).
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { TenkiClient } from "../client.js";

package/dist/tools/previews.js

@@ -7,43 +7,33 @@ export function registerPreviews(server, client) {
         port: portSchema.describe("The TCP port inside the sandbox to unexpose (1-65535)."),
     }, async ({ session_id, port }) => ok(await client.control("UnexposePort", { sessionId: session_id, port })));
     // ── Create a shareable preview URL for a port ─────────────────────────────────
-    server.tool("tenki_create_preview_url", "Create a shareable public preview URL for a port in a sandbox. The sandbox must have inbound networking enabled (create it with allow_inbound). Project-scoped; defaults to the key's first project.", {
+    server.tool("tenki_create_preview_url", "Create a shareable public preview URL for a port in a sandbox. The sandbox must have inbound networking enabled (create it with allow_inbound).", {
         session_id: sessionIdSchema.describe("The sandbox session serving the port."),
         port: portSchema.describe("The TCP port inside the sandbox to create a preview URL for (1-65535)."),
         slug: slugSchema,
-        project_id: z.string().optional().describe("Project the preview URL belongs to (defaults to the key's first project)."),
         expires_at: z
             .string()
             .optional()
             .describe("Optional RFC-3339 timestamp at which the preview URL auto-expires. Omit to keep it until the sandbox ends."),
-    }, async ({ session_id, port, slug, project_id, expires_at }) => {
-        const projectId = project_id ?? (await client.resolveOwner()).projectId;
-        return ok(await client.control("CreatePreviewUrl", {
-            sessionId: session_id,
-            port,
-            slug,
-            ...(projectId ? { projectId } : {}),
-            ...(expires_at !== undefined ? { expiresAt: expires_at } : {}),
-        }));
-    });
+    }, async ({ session_id, port, slug, expires_at }) => ok(await client.control("CreatePreviewUrl", {
+        sessionId: session_id,
+        port,
+        slug,
+        ...(expires_at !== undefined ? { expiresAt: expires_at } : {}),
+    })));
     // ── Open (get) a live preview for a port ──────────────────────────────────────
     server.tool("tenki_open_preview", "Open a viewer-token-gated (AUTHENTICATED-mode) preview. USE tenki_expose_port OR tenki_create_preview_url INSTEAD for an ordinary web server: for any port other than the web terminal (7681) the API deliberately returns a non-regional fallback host that currently has no edge route, so the URL 404s (live-verified). The returned viewerToken does resolve via tenki_resolve_preview_token; only the URL is unreachable. Requires allow_inbound.", {
         session_id: sessionIdSchema.describe("The sandbox session serving the port."),
         port: portSchema.describe("The TCP port inside the sandbox to open a preview for (1-65535)."),
-        project_id: z.string().optional().describe("Project scope (defaults to the key's first project)."),
         expires_at: z
             .string()
             .optional()
             .describe("Optional RFC-3339 timestamp at which the preview auto-expires. Omit to keep it until the sandbox ends."),
-    }, async ({ session_id, port, project_id, expires_at }) => {
-        const projectId = project_id ?? (await client.resolveOwner()).projectId;
-        return ok(await client.control("OpenPreview", {
-            sessionId: session_id,
-            port,
-            ...(projectId ? { projectId } : {}),
-            ...(expires_at !== undefined ? { expiresAt: expires_at } : {}),
-        }));
-    });
+    }, async ({ session_id, port, expires_at }) => ok(await client.control("OpenPreview", {
+        sessionId: session_id,
+        port,
+        ...(expires_at !== undefined ? { expiresAt: expires_at } : {}),
+    })));
     // ── List the preview URLs bound to a sandbox / project ────────────────────────
     server.tool("tenki_list_preview_urls", "List the workspace's preview URLs, newest page first. Pass session_id to keep only the ones bound to that sandbox (filtered here, not server-side — so it applies to the page you fetched; raise page_size or follow next_page_token to widen it). Results are paginated: a nextPageToken in the response means more pages exist.", {
         session_id: sessionIdSchema
@@ -54,7 +44,7 @@ export function registerPreviews(server, client) {
         page_token: z.string().optional().describe("Cursor from a previous response's nextPageToken."),
     }, async ({ session_id, workspace_id, page_size, page_token }) => {
         // The RPC has no sessionId field (ListPreviewUrlsRequest: workspace_id,
-        // page_size, page_token, and a deprecated project_id), so a sessionId sent
+        // page_size, page_token), so a sessionId sent
         // on the wire is silently discarded and every session's rows come back.
         // Filter here instead of advertising a filter that does nothing.
         const workspaceId = workspace_id ?? (await client.resolveOwner()).workspaceId;
@@ -72,20 +62,8 @@ export function registerPreviews(server, client) {
         });
     });
     // ── Get / delete a specific preview URL ───────────────────────────────────────
-    server.tool("tenki_get_preview_url", "Fetch a specific preview URL's details by id (project-scoped).", {
-        preview_url_id: z.string().describe("The preview URL id."),
-        project_id: z.string().optional().describe("Project scope (defaults to the key's first project)."),
-    }, async ({ preview_url_id, project_id }) => {
-        const projectId = project_id ?? (await client.resolveOwner()).projectId;
-        return ok(await client.control("GetPreviewUrl", { previewUrlId: preview_url_id, ...(projectId ? { projectId } : {}) }));
-    });
-    server.tool("tenki_delete_preview_url", "Delete a preview URL by id, taking it permanently offline (project-scoped).", {
-        preview_url_id: z.string().describe("The preview URL id to delete."),
-        project_id: z.string().optional().describe("Project scope (defaults to the key's first project)."),
-    }, async ({ preview_url_id, project_id }) => {
-        const projectId = project_id ?? (await client.resolveOwner()).projectId;
-        return ok(await client.control("DeletePreviewUrl", { previewUrlId: preview_url_id, ...(projectId ? { projectId } : {}) }));
-    });
+    server.tool("tenki_get_preview_url", "Fetch a specific preview URL's details by id.", { preview_url_id: z.string().describe("The preview URL id.") }, async ({ preview_url_id }) => ok(await client.control("GetPreviewUrl", { previewUrlId: preview_url_id })));
+    server.tool("tenki_delete_preview_url", "Delete a preview URL by id, taking it permanently offline.", { preview_url_id: z.string().describe("The preview URL id to delete.") }, async ({ preview_url_id }) => ok(await client.control("DeletePreviewUrl", { previewUrlId: preview_url_id })));
     // ── Touch (keep-alive) a preview ──────────────────────────────────────────────
     server.tool("tenki_touch_preview", "Refresh (keep-alive) a live preview by its preview token so it isn't torn down as idle.", { preview_token: z.string().describe("The preview token (from create_preview_url / open_preview).") }, 
     // TouchPreview takes a previewToken, not session/port (live-verified).

package/dist/tools/run.js

@@ -2,7 +2,7 @@ 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.", {
+    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. Output over ~64KB per stream is truncated head+tail — and the sandbox is gone, so for large output use tenki_create_sandbox + tenki_exec and page through the retained file.", {
         language: z.enum(["shell", "python", "javascript"]).describe("Interpreter for the snippet."),
         code: z.string().describe("The code to run."),
         env: envSchema,

package/dist/tools/sandboxes.js

@@ -2,32 +2,37 @@ 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)."),
+    server.registerTool("tenki_create_sandbox", {
+        description: "Create a persistent sandbox microVM, optionally from a snapshot or template image. 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.",
+        inputSchema: z
+            .object({
+            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."),
+            image: z
+                .string()
+                .optional()
+                .describe("Boot from a template image, passed as a reference STRING: the imageDigestRef of a READY build from tenki_build_template / tenki_get_template_build (e.g. 'ws/name@sha256:...'), or 'workspace/name' for its latest version."),
+            tags: z.array(z.string()).optional().describe("Tags for later filtering."),
+            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)."),
+        })
+            .strict(),
     }, 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 } : {}),
@@ -38,7 +43,8 @@ export function registerSandboxes(server, client) {
             ...(a.allow_outbound ? { allowOutbound: true } : {}),
             ...(a.allow_inbound ? { allowInbound: true } : {}),
             ...(a.snapshot_id ? { snapshotId: a.snapshot_id } : {}),
-            ...(a.registry_ref ? { registryRef: a.registry_ref } : {}),
+            // The API still uses registryRef internally for template-image launches.
+            ...(a.image ? { registryRef: a.image } : {}),
             ...(a.tags && a.tags.length ? { tags: a.tags } : {}),
             ...(a.env && Object.keys(a.env).length ? { env: a.env } : {}),
         };

package/dist/tools/sessions_admin.d.ts

@@ -3,7 +3,7 @@ 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
+ * workspace-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

@@ -3,7 +3,7 @@ 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
+ * workspace-scoped listing. The lifecycle basics
  * (create/get/list/terminate/pause/resume) live in sandboxes.ts.
  */
 export function registerSessionsAdmin(server, client) {
@@ -59,18 +59,4 @@ export function registerSessionsAdmin(server, client) {
             ...(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.js

@@ -76,16 +76,4 @@ export function registerSnapshots(server, client) {
             ...(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/templates.js

@@ -24,7 +24,7 @@ export function registerTemplates(server, client) {
         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.", {
+    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().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)."),
@@ -36,13 +36,14 @@ export function registerTemplates(server, client) {
         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."),
+        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)."),
-        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 } : {}),
@@ -52,7 +53,6 @@ export function registerTemplates(server, client) {
             ...(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 } : {}),
@@ -91,7 +91,7 @@ export function registerTemplates(server, client) {
         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."),
+        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 = {
@@ -117,12 +117,15 @@ export function registerTemplates(server, client) {
         ...(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).", {
+    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().optional().describe("Name for the resulting image."),
+        image_name: z
+            .string()
+            .optional()
+            .describe("Name for the resulting image. 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()).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."),
+        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 } : {}),
@@ -133,19 +136,7 @@ export function registerTemplates(server, client) {
     // ── 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 })));
+    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 })));
-    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

@@ -9,7 +9,7 @@
  *   CreateVolume · GetVolume · ListVolumes · UpdateVolume · DeleteVolume ·
  *   ResizeVolume · AttachVolume · DetachVolume
  *
- * CreateVolumeRequest is flat: { workspaceId, name, sizeBytes (int64), projectId? }.
+ * CreateVolumeRequest is flat: { workspaceId, name, sizeBytes (int64) }.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { TenkiClient } from "../client.js";

package/dist/tools/volumes.js

@@ -12,20 +12,16 @@ const sizeBytesSchema = z
     .describe("Volume size in bytes. Must be between 1 MiB (1048576) and 100 GiB (107374182400).");
 export function registerVolumes(server, client) {
     // ── Create ────────────────────────────────────────────────────────────────
-    server.tool("tenki_create_volume", "Create a workspace-scoped persistent volume — durable block storage that survives sandbox teardown. Defaults the workspace and project to the API key's first; override with workspace_id/project_id.", {
+    server.tool("tenki_create_volume", "Create a workspace-scoped persistent volume — durable block storage that survives sandbox teardown. Defaults the workspace to the API key's first; override with workspace_id.", {
         name: z.string().describe("Human-readable name for the volume."),
         size_bytes: sizeBytesSchema,
         workspace_id: z.string().optional().describe("Workspace to create the volume in (defaults to the key's first workspace)."),
-        project_id: z.string().optional().describe("Project to associate the volume with (defaults to the key's first project)."),
-    }, async ({ name, size_bytes, workspace_id, project_id }) => {
-        const owner = await client.resolveOwner();
-        const workspaceId = workspace_id ?? owner.workspaceId;
-        const projectId = project_id ?? owner.projectId;
+    }, async ({ name, size_bytes, workspace_id }) => {
+        const workspaceId = workspace_id ?? (await client.resolveOwner()).workspaceId;
         return ok(await client.control("CreateVolume", {
             ...(workspaceId ? { workspaceId } : {}),
             name,
             sizeBytes: size_bytes,
-            ...(projectId ? { projectId } : {}),
         }));
     });
     // ── Get ───────────────────────────────────────────────────────────────────
@@ -78,17 +74,4 @@ export function registerVolumes(server, client) {
         session_id: sessionIdSchema.describe("The sandbox session to detach the volume from."),
         volume_id: z.string().describe("The volume id to detach."),
     }, async ({ session_id, volume_id }) => ok(await client.control("DetachVolume", { sessionId: session_id, volumeId: volume_id })));
-    // ── List (project-scoped) ─────────────────────────────────────────────────────
-    server.tool("tenki_list_project_volumes", "List persistent volumes in a project (defaults to the key's first project). Supports pagination.", {
-        project_id: z.string().optional().describe("Project to list volumes from (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("ListProjectVolumes", {
-            ...(projectId ? { projectId } : {}),
-            ...(page_size ? { pageSize: page_size } : {}),
-            ...(page_token ? { pageToken: page_token } : {}),
-        }));
-    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenkicloud/mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "mcpName": "io.github.LuxorLabs/tenki-mcp",
   "description": "Model Context Protocol server for Tenki Cloud — disposable microVM sandboxes for AI agents. Create sandboxes, run code, read/write files, run git, expose preview URLs — from any MCP client.",
   "type": "module",
@@ -21,7 +21,7 @@
     "prepack": "npm run build",
     "prepublishOnly": "npm run build",
     "pretest": "npm run build",
-    "test": "node test/offline.test.mjs && node test/exec-output.test.mjs && node test/http-input.test.mjs && node test/security.test.mjs && node test/client-net.test.mjs",
+    "test": "node test/offline.test.mjs && node test/public-shapes.test.mjs && node test/exec-output.test.mjs && node test/http-input.test.mjs && node test/oauth-http.test.mjs && node test/security.test.mjs && node test/client-net.test.mjs",
     "test:all": "npm run build && node test/run.mjs",
     "test:offline": "npm run build && node test/offline.test.mjs"
   },
@@ -44,11 +44,11 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "zod": "^3.23.8"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.5.0"
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2"
   },
   "repository": {
     "type": "git",