@tenkicloud/mcp 0.1.0

package/dist/tools/volumes.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { ok, pathSchema, sessionIdSchema } from "./common.js";
+/** Volume size bounds the control plane accepts: 1 MiB … 100 GiB, in bytes. */
+const MIN_VOLUME_BYTES = 1_048_576; // 1 MiB
+const MAX_VOLUME_BYTES = 107_374_182_400; // 100 GiB
+/** Shared size-in-bytes schema for create + resize, range-checked before the call. */
+const sizeBytesSchema = z
+    .number()
+    .int()
+    .min(MIN_VOLUME_BYTES)
+    .max(MAX_VOLUME_BYTES)
+    .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.", {
+        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;
+        return ok(await client.control("CreateVolume", {
+            ...(workspaceId ? { workspaceId } : {}),
+            name,
+            sizeBytes: size_bytes,
+            ...(projectId ? { projectId } : {}),
+        }));
+    });
+    // ── Get ───────────────────────────────────────────────────────────────────
+    server.tool("tenki_get_volume", "Fetch a single volume's metadata and current state by its id.", { volume_id: z.string().describe("The volume id, e.g. vol_….") }, async ({ volume_id }) => ok(await client.control("GetVolume", { volumeId: volume_id })));
+    // ── List ──────────────────────────────────────────────────────────────────
+    server.tool("tenki_list_volumes", "List persistent volumes in a workspace (defaults to the key's first workspace). Supports pagination.", {
+        workspace_id: z.string().optional().describe("Workspace to list volumes from (defaults to the key's first workspace)."),
+        page_size: z.number().int().positive().optional().describe("Max volumes to return per page."),
+        page_token: z.string().optional().describe("Page token from a previous response's nextPageToken."),
+    }, async ({ workspace_id, page_size, page_token }) => {
+        const owner = await client.resolveOwner();
+        const workspaceId = workspace_id ?? owner.workspaceId;
+        return ok(await client.control("ListVolumes", {
+            ...(workspaceId ? { workspaceId } : {}),
+            ...(page_size ? { pageSize: page_size } : {}),
+            ...(page_token ? { pageToken: page_token } : {}),
+        }));
+    });
+    // ── Update ────────────────────────────────────────────────────────────────
+    server.tool("tenki_update_volume", "Rename a volume (update its human-readable name). To change a volume's size use tenki_resize_volume instead.", {
+        volume_id: z.string().describe("The volume id to update."),
+        name: z.string().describe("New human-readable name for the volume."),
+    }, async ({ volume_id, name }) => ok(await client.control("UpdateVolume", { volumeId: volume_id, name })));
+    // ── Delete ────────────────────────────────────────────────────────────────
+    server.tool("tenki_delete_volume", "Permanently delete a volume and destroy its data. Fails with VolumeInUse if the volume is still attached to a session — detach it first.", { volume_id: z.string().describe("The volume id to delete.") }, async ({ volume_id }) => ok(await client.control("DeleteVolume", { volumeId: volume_id })));
+    // ── Resize ────────────────────────────────────────────────────────────────
+    server.tool("tenki_resize_volume", "Grow a volume to a new size in bytes (1 MiB … 100 GiB). Volumes can grow but not shrink.", {
+        volume_id: z.string().describe("The volume id to resize."),
+        size_bytes: sizeBytesSchema,
+    }, async ({ volume_id, size_bytes }) => ok(await client.control("ResizeVolume", { volumeId: volume_id, newSizeBytes: size_bytes })));
+    // ── Attach ────────────────────────────────────────────────────────────────
+    server.tool("tenki_attach_volume", "Mount a volume into a running sandbox at an absolute path. Set read_only to mount without write access.", {
+        session_id: sessionIdSchema.describe("The sandbox session to attach the volume to."),
+        volume_id: z.string().describe("The volume id to attach."),
+        mount_path: pathSchema.describe("Absolute path inside the sandbox to mount at, e.g. /mnt/data."),
+        read_only: z.boolean().optional().describe("Mount the volume read-only (default false = read-write)."),
+    }, async ({ session_id, volume_id, mount_path, read_only }) => ok(
+    // AttachVolumeRequest nests the target under a `volume` sub-message
+    // (live-verified: a flat volumeId is rejected "volume: value is required").
+    await client.control("AttachVolume", {
+        sessionId: session_id,
+        volume: {
+            volumeId: volume_id,
+            mountPath: mount_path,
+            ...(read_only !== undefined ? { readOnly: read_only } : {}),
+        },
+    })));
+    // ── Detach ────────────────────────────────────────────────────────────────
+    server.tool("tenki_detach_volume", "Unmount a volume from a sandbox session.", {
+        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/dist/tools/workspace.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/** Workspace-level sandbox usage + default settings (incl. snapshot retention). */
+export declare function registerWorkspace(server: McpServer, client: TenkiClient): void;

package/dist/tools/workspace.js

@@ -0,0 +1,129 @@
+import { z } from "zod";
+import { ok } from "./common.js";
+/**
+ * Resolve which workspace an op targets: honour an explicit id, else fall back
+ * to the API key's first workspace (via WhoAmI, inside resolveOwner). Mirrors
+ * the live-verified n8n node's `resolveWorkspaceId` helper.
+ */
+async function resolveWorkspaceId(client, provided) {
+    if (provided && provided.trim())
+        return provided.trim();
+    const owner = await client.resolveOwner();
+    return owner.workspaceId;
+}
+/** Workspace-level sandbox usage + default settings (incl. snapshot retention). */
+export function registerWorkspace(server, client) {
+    server.tool("tenki_get_workspace_usage", "Get per-second sandbox billing and usage figures for a workspace — use this for cost visibility across all of the workspace's sandboxes.", {
+        workspace_id: z
+            .string()
+            .optional()
+            .describe("Workspace to report on. Omit to use the API key's first workspace."),
+    }, async ({ workspace_id }) => {
+        const workspaceId = await resolveWorkspaceId(client, workspace_id);
+        return ok(await client.control("GetWorkspaceSandboxUsage", {
+            ...(workspaceId ? { workspaceId } : {}),
+        }));
+    });
+    server.tool("tenki_get_workspace_settings", "Read a workspace's sandbox quotas and retention policy: max snapshots/templates/volumes/total bytes, max concurrent and sticky sessions, max preview URLs, and the pause/snapshot retention periods. These are workspace limits — there are no per-session defaults (idle timeout and max duration are set per sandbox at creation).", {
+        workspace_id: z
+            .string()
+            .optional()
+            .describe("Workspace to read. Omit to use the API key's first workspace."),
+    }, async ({ workspace_id }) => {
+        const workspaceId = await resolveWorkspaceId(client, workspace_id);
+        return ok(await client.control("GetWorkspaceSandboxSettings", {
+            ...(workspaceId ? { workspaceId } : {}),
+        }));
+    });
+    server.tool("tenki_update_workspace_settings", "Update a workspace's sandbox quotas and retention periods. Only the fields you pass change. Each quota has a matching clear_* flag to remove the override and fall back to the platform default; pass the value OR its clear flag, not both. There are no per-session defaults here — idle timeout and max duration are set per sandbox at creation.", {
+        workspace_id: z
+            .string()
+            .optional()
+            .describe("Workspace to update. Omit to use the API key's first workspace."),
+        pause_retention_days: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("How long a paused sandbox's snapshot is kept before it becomes unresumable."),
+        clear_pause_retention: z.boolean().optional().describe("Remove the pause-retention override (use the platform default)."),
+        snapshot_retention_days: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("How long snapshots are kept before automatic cleanup."),
+        clear_snapshot_retention: z
+            .boolean()
+            .optional()
+            .describe("Remove the snapshot-retention override, i.e. keep snapshots indefinitely."),
+        max_snapshots: z.number().int().positive().optional().describe("Maximum snapshots in the workspace."),
+        max_templates: z.number().int().positive().optional().describe("Maximum templates in the workspace."),
+        max_volumes: z.number().int().positive().optional().describe("Maximum volumes in the workspace."),
+        max_total_bytes: z.number().int().positive().optional().describe("Maximum combined snapshot + volume storage in bytes."),
+        max_concurrent_sessions: z.number().int().positive().optional().describe("Maximum simultaneously active sandboxes."),
+        max_sticky_sessions: z.number().int().positive().optional().describe("Maximum sticky sandboxes."),
+        max_preview_urls: z.number().int().positive().optional().describe("Maximum preview URLs in the workspace."),
+    }, async (a) => {
+        const workspaceId = await resolveWorkspaceId(client, a.workspace_id);
+        const body = { ...(workspaceId ? { workspaceId } : {}) };
+        // Durations are protobuf Duration — JSON wants a seconds string ("2592000s").
+        if (a.pause_retention_days !== undefined)
+            body.pauseRetention = `${a.pause_retention_days * 86400}s`;
+        if (a.clear_pause_retention)
+            body.clearPauseRetention = true;
+        if (a.snapshot_retention_days !== undefined)
+            body.snapshotRetention = `${a.snapshot_retention_days * 86400}s`;
+        if (a.clear_snapshot_retention)
+            body.clearSnapshotRetention = true;
+        if (a.max_snapshots !== undefined)
+            body.maxSnapshots = a.max_snapshots;
+        if (a.max_templates !== undefined)
+            body.maxTemplates = a.max_templates;
+        if (a.max_volumes !== undefined)
+            body.maxVolumes = a.max_volumes;
+        // int64 on the wire — send as a string so large values survive JSON.
+        if (a.max_total_bytes !== undefined)
+            body.maxTotalBytes = String(a.max_total_bytes);
+        if (a.max_concurrent_sessions !== undefined)
+            body.maxConcurrentSessions = a.max_concurrent_sessions;
+        if (a.max_sticky_sessions !== undefined)
+            body.maxStickySessions = a.max_sticky_sessions;
+        // The per-project field is deprecated; the workspace alias is backed by the same quota.
+        if (a.max_preview_urls !== undefined)
+            body.maxPreviewUrlsPerWorkspace = a.max_preview_urls;
+        if (Object.keys(body).length <= 1) {
+            throw new Error("tenki_update_workspace_settings: pass at least one setting to change. Nothing was sent — the API would have returned the unchanged settings, which reads like a successful update.");
+        }
+        return ok(await client.control("UpdateWorkspaceSandboxSettings", body));
+    });
+    server.tool("tenki_get_snapshot_retention_settings", "Get the workspace's pause- and snapshot-retention periods. DEPRECATED upstream: this RPC is marked deprecated in the API — tenki_get_workspace_settings returns the same retention fields alongside the quotas. An empty response means no retention override, i.e. kept indefinitely.", { workspace_id: z.string().optional().describe("Workspace (defaults to the key's first workspace).") }, async ({ workspace_id }) => {
+        const workspaceId = workspace_id ?? (await client.resolveOwner()).workspaceId;
+        return ok(await client.control("GetWorkspaceSnapshotRetentionSettings", { ...(workspaceId ? { workspaceId } : {}) }));
+    });
+    server.tool("tenki_update_snapshot_retention_settings", "Update the workspace's snapshot-retention policy: how long snapshots are kept before automatic cleanup. Pass retention_days to set it, or clear_retention to keep snapshots indefinitely (the unset state) — exactly one of the two. DEPRECATED upstream: prefer tenki_update_workspace_settings, which sets the same retention (and pause retention) alongside the quotas.", {
+        retention_days: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Days to retain snapshots before automatic cleanup. Omit and pass clear_retention to keep them indefinitely."),
+        clear_retention: z
+            .boolean()
+            .optional()
+            .describe("Remove the retention period so snapshots are kept indefinitely. Mutually exclusive with retention_days."),
+        workspace_id: z.string().optional().describe("Workspace (defaults to the key's first workspace)."),
+    }, async ({ retention_days, clear_retention, workspace_id }) => {
+        if ((retention_days === undefined) === (clear_retention !== true)) {
+            throw new Error("tenki_update_snapshot_retention_settings: pass exactly one of retention_days (to set a period) or clear_retention: true (to keep snapshots indefinitely).");
+        }
+        const workspaceId = workspace_id ?? (await client.resolveOwner()).workspaceId;
+        return ok(await client.control("UpdateWorkspaceSnapshotRetentionSettings", {
+            ...(workspaceId ? { workspaceId } : {}),
+            // protobuf Duration on the wire, with a companion clear flag —
+            // there is no `retentionDays` field (sending one is silently dropped).
+            ...(retention_days !== undefined ? { snapshotRetention: `${retention_days * 86400}s` } : {}),
+            ...(clear_retention ? { clearSnapshotRetention: true } : {}),
+        }));
+    });
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@tenkicloud/mcp",
+  "version": "0.1.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",
+  "bin": {
+    "tenki-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "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:all": "npm run build && node test/run.mjs",
+    "test:offline": "npm run build && node test/offline.test.mjs"
+  },
+  "keywords": [
+    "tenki",
+    "mcp",
+    "model-context-protocol",
+    "sandbox",
+    "microvm",
+    "ai-agents",
+    "code-execution"
+  ],
+  "license": "MIT",
+  "author": "Tenki Cloud (https://tenki.cloud)",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LuxorLabs/tenki-mcp.git"
+  },
+  "homepage": "https://github.com/LuxorLabs/tenki-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/LuxorLabs/tenki-mcp/issues"
+  }
+}