@tenkicloud/mcp 0.1.0

package/dist/tools/auth_status.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+/**
+ * Classify the ambient credential WITHOUT returning any of its material.
+ * Mirrors the header selection in client.ts (`tk_` → Bearer API key,
+ * `ory_st_` → OAuth/Ory session token, anything else → session cookie) and
+ * index.ts's precedence (TENKI_AUTH_TOKEN wins over TENKI_API_KEY).
+ */
+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)
+        return { kind: "none" };
+    const source = fromToken ? "TENKI_AUTH_TOKEN" : "TENKI_API_KEY";
+    if (raw.startsWith("tk_"))
+        return { kind: "api_key", source };
+    if (raw.startsWith("ory_st_"))
+        return { kind: "oauth_session_token", source };
+    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.",
+    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.",
+};
+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."),
+    source: z
+        .string()
+        .optional()
+        .describe("Environment variable the credential came from (TENKI_AUTH_TOKEN takes precedence over TENKI_API_KEY)."),
+    endpoint: z.string().describe("Control-plane base URL the server is pointed at."),
+    toolsRegistered: z
+        .number()
+        .int()
+        .describe("How many tools this server registered. Without a credential only this one is registered."),
+    identity: z
+        .object({
+        ownerType: z.string().optional(),
+        ownerId: z.string().optional(),
+        workspaces: z.number().int().optional(),
+    })
+        .optional()
+        .describe("Identity returned by the live probe, when it succeeded."),
+    error: z.string().optional().describe("Why the probe failed, when a credential is present but unusable (expired, revoked, wrong endpoint)."),
+    detail: z.string().describe("Human-readable status plus, when unauthenticated, how to supply a credential."),
+};
+/**
+ * Report authentication status. `client` is null when the server booted without
+ * a credential; `toolsRegistered` lets the caller see it is in that degraded
+ * single-tool mode rather than guessing from a short tools/list.
+ */
+export function registerAuthStatus(server, client, toolsRegistered) {
+    server.registerTool("tenki_auth_status", {
+        description: "Report whether the server has a usable Tenki credential, which kind (API key vs OAuth session token), and the endpoint it targets — verified with a live identity probe. Call this first when other tools fail with auth errors, or when this is the only tool available (which means no credential is configured). Reports status only; it does not log in and never returns the token.",
+        inputSchema: {},
+        outputSchema: authOutputSchema,
+    }, async () => {
+        const cred = describeCredential();
+        const endpoint = process.env.TENKI_API_ENDPOINT || process.env.TENKI_API_URL || "https://api.tenki.cloud";
+        const base = {
+            credential: cred.kind,
+            ...(cred.source ? { source: cred.source } : {}),
+            endpoint,
+            toolsRegistered,
+        };
+        if (!client || cred.kind === "none") {
+            const result = {
+                ...base,
+                authenticated: false,
+                detail: CREDENTIAL_HELP.none,
+            };
+            return { structuredContent: result, content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        try {
+            const resp = await client.control("WhoAmI", {});
+            const workspaces = Array.isArray(resp.workspaces) ? resp.workspaces.length : undefined;
+            const result = {
+                ...base,
+                authenticated: true,
+                identity: {
+                    ...(typeof resp.ownerType === "string" ? { ownerType: resp.ownerType } : {}),
+                    ...(typeof resp.ownerId === "string" ? { ownerId: resp.ownerId } : {}),
+                    ...(workspaces !== undefined ? { workspaces } : {}),
+                },
+                detail: CREDENTIAL_HELP[cred.kind],
+            };
+            return { structuredContent: result, content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (e) {
+            const result = {
+                ...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}`,
+            };
+            return { structuredContent: result, content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+    });
+}

package/dist/tools/common.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+/** Serialize any tool return value as MCP text content. */
+export declare const ok: (value: unknown) => {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/** Shared env-map schema used by tools that accept environment variables. */
+export declare const envSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+/** 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
+ * reject it), which makes trimming a safe correction rather than the silent
+ * retargeting it would be for a filename. */
+export declare const sessionIdSchema: z.ZodString;
+/** Shared TCP-port schema. */
+export declare const portSchema: z.ZodNumber;
+/** Shared sandbox-path schema — rejects an empty or whitespace-only path
+ * client-side instead of by a server error, WITHOUT transforming the value:
+ * 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>;
+/**
+ * Preview-slug schema, matching the server's validatePreviewSlug: 3-63 chars,
+ * lowercase/digits/hyphens, no leading/trailing hyphen. ExposePort routes a
+ * slug through the SAME preview validation (exposePersistentPreviewURL), so
+ * this applies to tenki_expose_port too. The server additionally rejects
+ * consecutive hyphens, reserved names, and workspace-length overflows —
+ * those stay server-side.
+ */
+export declare const slugSchema: z.ZodString;

package/dist/tools/common.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+/** Serialize any tool return value as MCP text content. */
+export const ok = (value) => ({
+    content: [{ type: "text", text: JSON.stringify(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.");
+/** 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
+ * reject it), which makes trimming a safe correction rather than the silent
+ * retargeting it would be for a filename. */
+export const sessionIdSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .describe("Sandbox session id (UUID), from tenki_create_sandbox or tenki_list_sandboxes.");
+/** Shared TCP-port schema. */
+export const portSchema = z.number().int().min(1).max(65535).describe("TCP port inside the sandbox (1-65535).");
+/** Shared sandbox-path schema — rejects an empty or whitespace-only path
+ * client-side instead of by a server error, WITHOUT transforming the value:
+ * 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 const pathSchema = z
+    .string()
+    .refine((s) => s.trim().length > 0, "path must not be empty or whitespace-only")
+    .describe("Absolute path inside the sandbox, under /home/tenki.");
+/**
+ * Preview-slug schema, matching the server's validatePreviewSlug: 3-63 chars,
+ * lowercase/digits/hyphens, no leading/trailing hyphen. ExposePort routes a
+ * slug through the SAME preview validation (exposePersistentPreviewURL), so
+ * this applies to tenki_expose_port too. The server additionally rejects
+ * consecutive hyphens, reserved names, and workspace-length overflows —
+ * those stay server-side.
+ */
+export const slugSchema = z
+    .string()
+    .min(3)
+    .max(63)
+    .regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, "lowercase letters, digits, and hyphens; cannot start or end with a hyphen")
+    .describe("Subdomain slug for the preview URL (3-63 chars, lowercase letters/digits/hyphens, no leading/trailing hyphen).");

package/dist/tools/exec.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/** Command execution inside an existing sandbox. */
+export declare function registerExec(server: McpServer, client: TenkiClient): void;

package/dist/tools/exec.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import { envSchema, sessionIdSchema } from "./common.js";
+/**
+ * Structured result contract for tenki_exec. Mirrors ExecResult in client.ts —
+ * the SDK validates every successful result against this, so the two must stay
+ * in lockstep field-for-field.
+ */
+const execOutputSchema = {
+    command: z.string().describe("The executable that was run."),
+    args: z.array(z.string()).describe("Arguments the executable was invoked with."),
+    stdout: z.string().describe("Captured standard output (empty when capture failed — see captureError)."),
+    stderr: z.string().describe("Captured standard error (empty when capture failed — see captureError)."),
+    exitCode: z.number().int().describe("Process exit code; 0 means success. (The API omits zero values; the server normalizes an absent code to 0.)"),
+    ok: z.boolean().describe("True only when exitCode is 0 AND stdout/stderr capture succeeded."),
+    captureError: z
+        .string()
+        .optional()
+        .describe("Present when the command ran but its output could not be read back; stdout/stderr are unknown, not empty."),
+};
+/**
+ * Field drift between execOutputSchema and ExecResult must fail the build, not
+ * the tool call — at runtime the SDK rejects a mismatched result outright and
+ * the command's output is lost.
+ */
+const execOutput = z.object(execOutputSchema);
+const _execSchemaLockstep = true;
+void _execSchemaLockstep;
+/**
+ * Sandbox output is untrusted (SECURITY.md). Neutralize characters that can
+ * misrepresent output in a terminal or transcript — C0 controls except \n and
+ * \t (ANSI sequences, CR line-overwrite spoofing), DEL, C1 controls (0x80–0x9F
+ * are single-character equivalents: U+009B is CSI), bidi controls
+ * (U+202A–U+202E, U+2066–U+2069 reorder displayed text), and zero-width/
+ * invisible marks (U+200B–U+200F, U+FEFF) — into visible \xNN / \uNNNN
+ * escapes. The previous JSON.stringify rendering escaped controls implicitly;
+ * a raw text rendering must do it explicitly. structuredContent keeps the raw
+ * strings — JSON encoding neutralizes them on the wire, and typed consumers
+ * need unmodified data.
+ */
+function sanitizeForTerminal(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]/g, (c) => {
+        const code = c.charCodeAt(0);
+        return code <= 0xff ? `\\x${code.toString(16).padStart(2, "0")}` : `\\u${code.toString(16).padStart(4, "0")}`;
+    });
+}
+/**
+ * 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.
+ */
+function execText(r) {
+    const head = `exit ${r.exitCode}${r.ok ? "" : " (failed)"}`;
+    const capture = r.captureError
+        ? `\ncapture error: ${sanitizeForTerminal(r.captureError)} — stdout/stderr may be incomplete`
+        : "";
+    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}`;
+}
+/** 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.",
+        inputSchema: {
+            session_id: sessionIdSchema,
+            command: z.string().describe("Executable, e.g. 'npm' or 'python3'."),
+            args: z.array(z.string()).optional().describe("Arguments."),
+            cwd: z.string().optional().describe("Working directory (honored in-script)."),
+            env: envSchema,
+            timeout_seconds: z.number().int().positive().optional(),
+        },
+        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 });
+        return {
+            structuredContent: { ...result },
+            // Two text blocks: serialized JSON first (the MCP spec's
+            // backwards-compatibility contract for structured content — existing
+            // text-only consumers, our own test harness included, parse the first
+            // text block as JSON), then the human-readable rendering.
+            content: [
+                { type: "text", text: JSON.stringify(result, null, 2) },
+                { type: "text", text: execText(result) },
+            ],
+        };
+    });
+}

package/dist/tools/files.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/** Filesystem I/O against a sandbox's data plane. */
+export declare function registerFiles(server: McpServer, client: TenkiClient): void;

package/dist/tools/files.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { ok, pathSchema, sessionIdSchema } from "./common.js";
+/** Filesystem I/O against a sandbox's data plane. */
+export function registerFiles(server, client) {
+    server.tool("tenki_read_file", "Read a UTF-8 text file from a sandbox (paths under /home/tenki).", { session_id: sessionIdSchema, path: pathSchema }, async ({ session_id, path }) => ok({ path, content: await client.readTextFile(session_id, path) }));
+    server.tool("tenki_write_file", "Write a UTF-8 text file to a sandbox (paths under /home/tenki).", { session_id: sessionIdSchema, path: pathSchema, content: z.string() }, async ({ session_id, path, content }) => ok(await client.writeTextFile(session_id, path, content)));
+    server.tool("tenki_list_files", "List a directory in a sandbox, including dotfiles (.git, .env, .gitignore) by default — set include_hidden false to omit them.", {
+        session_id: sessionIdSchema,
+        path: pathSchema.describe("Directory path, e.g. /home/tenki"),
+        include_hidden: z
+            .boolean()
+            .optional()
+            .describe("Include dot-prefixed entries (default true). The data plane omits them unless asked, which hides .git/.env from a listing."),
+    }, async ({ session_id, path, include_hidden }) => {
+        // Default TRUE, inverting the wire default: a listing that silently omits
+        // .git/.env/.gitignore leads an agent to conclude they do not exist.
+        const resp = await client.data(session_id, "List", { path, includeHidden: include_hidden !== false });
+        // proto3 omits an empty repeated field, so an empty directory comes back
+        // as {} — indistinguishable from a malformed call. Normalize it.
+        return ok({ path, entries: Array.isArray(resp.entries) ? resp.entries : [] });
+    });
+}

package/dist/tools/files_ops.d.ts

@@ -0,0 +1,12 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/**
+ * Filesystem metadata + mutation ops against a sandbox's data plane.
+ *
+ * Extends the basic read/write/list coverage in `files.ts` with `stat`, `mkdir`,
+ * `remove`, and `move`. Stat/Mkdir/Remove are genuine unary data-plane RPCs
+ * (`SandboxSessionDataPlaneService`). The data plane exposes no `Move` method, so
+ * `tenki_move_path` is exec-backed (`mv`) — matching the live-verified n8n node.
+ * Paths are rooted at /home/tenki (the server enforces the sandbox root).
+ */
+export declare function registerFilesOps(server: McpServer, client: TenkiClient): void;

package/dist/tools/files_ops.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { ok, pathSchema, sessionIdSchema } from "./common.js";
+/**
+ * Filesystem metadata + mutation ops against a sandbox's data plane.
+ *
+ * Extends the basic read/write/list coverage in `files.ts` with `stat`, `mkdir`,
+ * `remove`, and `move`. Stat/Mkdir/Remove are genuine unary data-plane RPCs
+ * (`SandboxSessionDataPlaneService`). The data plane exposes no `Move` method, so
+ * `tenki_move_path` is exec-backed (`mv`) — matching the live-verified n8n node.
+ * Paths are rooted at /home/tenki (the server enforces the sandbox root).
+ */
+export function registerFilesOps(server, client) {
+    server.tool("tenki_stat_path", "Get metadata (size, mode, type, timestamps) for a file or directory in a sandbox. Use to check whether a path exists or inspect it before reading/removing.", {
+        session_id: sessionIdSchema,
+        path: pathSchema.describe("Absolute path under /home/tenki, e.g. /home/tenki/output.txt"),
+    }, async ({ session_id, path }) => ok(await client.data(session_id, "Stat", { path })));
+    server.tool("tenki_make_dir", "Create a directory in a sandbox. Set recursive to also create any missing parent directories (mkdir -p).", {
+        session_id: sessionIdSchema,
+        path: pathSchema.describe("Directory path under /home/tenki, e.g. /home/tenki/project/out"),
+        recursive: z.boolean().optional().describe("Create parent directories as needed (default false)."),
+    }, async ({ session_id, path, recursive }) => ok(await client.data(session_id, "Mkdir", {
+        path,
+        ...(recursive ? { recursive: true } : {}),
+    })));
+    server.tool("tenki_remove_path", "Delete a file or directory in a sandbox. Set recursive to remove a non-empty directory and its contents (rm -r).", {
+        session_id: sessionIdSchema,
+        path: pathSchema.describe("Path to delete under /home/tenki."),
+        recursive: z.boolean().optional().describe("Remove a directory and its contents (default false)."),
+    }, async ({ session_id, path, recursive }) => ok(await client.data(session_id, "Remove", {
+        path,
+        ...(recursive ? { recursive: true } : {}),
+    })));
+    server.tool("tenki_move_path", "Move or rename a file or directory within a sandbox. Both paths are under /home/tenki.", {
+        session_id: sessionIdSchema,
+        from: pathSchema.describe("Source path under /home/tenki, e.g. /home/tenki/old.txt"),
+        to: pathSchema.describe("Destination path under /home/tenki, e.g. /home/tenki/new.txt"),
+    }, async ({ session_id, from, to }) => {
+        // The data plane has no Move RPC (ReadFile/WriteFile/Stat/Mkdir/Remove/List only),
+        // so relocate with an exec-backed `mv`, mirroring the live-verified n8n node.
+        // `ok` keys off the exit code, NOT result.ok: the capture files are an
+        // internal detail here — whether mv's (empty) output could be read back
+        // says nothing about whether the file moved.
+        // `--` so a path beginning with a hyphen is an operand, not an mv option.
+        const result = await client.execCaptured(session_id, "mv", { args: ["--", from, to] });
+        return ok({
+            from,
+            to,
+            ok: result.exitCode === 0,
+            exitCode: result.exitCode,
+            ...(result.stderr ? { stderr: result.stderr } : {}),
+            ...(result.captureError ? { captureError: result.captureError } : {}),
+        });
+    });
+}

package/dist/tools/git.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/** Git operations inside a sandbox (one RPC dispatched by operation string). */
+export declare function registerGit(server: McpServer, client: TenkiClient): void;

package/dist/tools/git.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { ok, sessionIdSchema } from "./common.js";
+/**
+ * The API validates `operation` against exactly this list (GitOperationRequest's
+ * buf.validate `in` constraint) and the engine implements exactly these four —
+ * anything else (status/add/commit/push/...) is rejected server-side. For other
+ * git commands, run `git ...` via tenki_exec.
+ */
+const GIT_OPERATIONS = ["clone", "checkout", "diff", "log"];
+/** Git operations inside a sandbox (one RPC dispatched by operation string). */
+export function registerGit(server, client) {
+    server.tool("tenki_git", "Run a git operation in a sandbox. Only clone, checkout, diff, and log are supported by the API — for any other git command (status, add, commit, push, ...) use tenki_exec with `git ...`. " +
+        "clone arg keys: repo (required, the URL), branch?, depth?, directory?. " +
+        "CAVEAT (live-verified): checkout/diff/log run in the session's working directory (/home/tenki), which is not a repository and has no directory arg — so on a repo cloned into a subdirectory they fail with 'not a git repository'. Use tenki_exec with `git -C <directory> ...` instead (e.g. `git -C /home/tenki/hw log -n 2`). " +
+        "For reference, their arg keys are — checkout: ref (required), create? ('true' = -b); diff: range? or base?+head?, path?; log: max_count?, range?, path?.", {
+        session_id: sessionIdSchema,
+        operation: z.enum(GIT_OPERATIONS).describe("One of: clone, checkout, diff, log (the API rejects anything else)."),
+        // The wire type is map<string,string>, but the values models most want
+        // to send as numbers or booleans (depth, max_count, create) are
+        // 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()]))
+            .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 }) => {
+        const stringArgs = args ? Object.fromEntries(Object.entries(args).map(([k, v]) => [k, String(v)])) : undefined;
+        return ok(await client.control("GitOperation", { sessionId: session_id, operation, ...(stringArgs ? { args: stringArgs } : {}) }));
+    });
+}

package/dist/tools/identity.d.ts

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

package/dist/tools/identity.js

@@ -0,0 +1,5 @@
+import { ok } from "./common.js";
+/** Identity / credential tools. */
+export function registerIdentity(server, client) {
+    server.tool("tenki_whoami", "Return the identity and workspaces for the current API key. Cheap credential test.", {}, async () => ok(await client.control("WhoAmI", {})));
+}

package/dist/tools/ports.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/** Port exposure / preview URLs. */
+export declare function registerPorts(server: McpServer, client: TenkiClient): void;

package/dist/tools/ports.js

@@ -0,0 +1,6 @@
+import { ok, portSchema, sessionIdSchema, slugSchema } from "./common.js";
+/** Port exposure / preview URLs. */
+export function registerPorts(server, client) {
+    server.tool("tenki_expose_port", "Expose a port from a sandbox and get a public preview URL. Useful when an agent starts a web server it wants to show.", { session_id: sessionIdSchema, port: portSchema, slug: slugSchema.optional() }, async ({ session_id, port, slug }) => ok(await client.control("ExposePort", { sessionId: session_id, port, ...(slug ? { slug } : {}) })));
+    server.tool("tenki_list_exposed_ports", "List the ports currently exposed from a sandbox.", { session_id: sessionIdSchema }, async ({ session_id }) => ok(await client.control("ListExposedPorts", { sessionId: session_id })));
+}

package/dist/tools/previews.d.ts

@@ -0,0 +1,18 @@
+/**
+ * previews.ts — port preview-URL tools for tenki-mcp.
+ *
+ * Covers the preview / exposure-teardown half of Tenki's Port resource:
+ * removing an inbound exposure (UnexposePort) and the preview-URL lifecycle
+ * (CreatePreviewUrl, OpenPreview, ListPreviewUrls). Port *exposure* itself
+ * (ExposePort / ListExposedPorts) lives in ports.ts and is not re-implemented here.
+ *
+ * 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.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+export declare function registerPreviews(server: McpServer, client: TenkiClient): void;

package/dist/tools/previews.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { ok, portSchema, sessionIdSchema, slugSchema } from "./common.js";
+export function registerPreviews(server, client) {
+    // ── Unexpose a port (tear down its exposure + preview) ────────────────────────
+    server.tool("tenki_unexpose_port", "Remove an inbound port exposure from a sandbox, taking its public URL/preview offline. Use this to un-publish a port previously exposed with tenki_expose_port.", {
+        session_id: sessionIdSchema.describe("The sandbox session whose port to unexpose."),
+        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.", {
+        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 } : {}),
+        }));
+    });
+    // ── 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 } : {}),
+        }));
+    });
+    // ── 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
+            .optional()
+            .describe("Keep only preview URLs bound to this sandbox. Applied client-side to the fetched page."),
+        workspace_id: z.string().optional().describe("Workspace to list (defaults to the key's first workspace)."),
+        page_size: z.number().int().min(1).max(100).optional().describe("Rows per page (server default 20, max 100)."),
+        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
+        // 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;
+        const resp = await client.control("ListPreviewUrls", {
+            ...(workspaceId ? { workspaceId } : {}),
+            ...(page_size !== undefined ? { pageSize: page_size } : {}),
+            ...(page_token ? { pageToken: page_token } : {}),
+        });
+        const rows = Array.isArray(resp.previewUrls) ? resp.previewUrls : [];
+        const filtered = session_id ? rows.filter((r) => r?.sessionId === session_id) : rows;
+        return ok({
+            previewUrls: filtered,
+            ...(resp.nextPageToken ? { nextPageToken: resp.nextPageToken } : {}),
+            ...(session_id ? { filteredClientSide: true, fetchedOnThisPage: rows.length } : {}),
+        });
+    });
+    // ── 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 } : {}) }));
+    });
+    // ── 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).
+    async ({ preview_token }) => ok(await client.control("TouchPreview", { previewToken: preview_token })));
+    // ── Bind / unbind a named preview URL to a session+port ───────────────────────
+    // Advanced routing primitives (shapes SDK-name-verified; not exercised end-to-end here).
+    server.tool("tenki_bind_preview_url", "Bind a named preview URL to a sandbox session and port (advanced routing).", {
+        preview_url_id: z.string().describe("The preview URL id to bind."),
+        session_id: sessionIdSchema,
+        port: portSchema.describe("The port to route the preview URL to."),
+    }, async ({ preview_url_id, session_id, port }) => ok(await client.control("BindPreviewUrl", { previewUrlId: preview_url_id, sessionId: session_id, port })));
+    server.tool("tenki_unbind_preview_url", "Unbind a named preview URL from its current session/port (advanced routing).", { preview_url_id: z.string().describe("The preview URL id to unbind.") }, async ({ preview_url_id }) => ok(await client.control("UnbindPreviewUrl", { previewUrlId: preview_url_id })));
+    server.tool("tenki_resolve_preview_token", "Resolve a preview token to the sandbox/port it points at (advanced).", { token: z.string().describe("The preview token to resolve.") }, async ({ token }) => ok(await client.control("ResolvePreviewToken", { token })));
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,18 @@
+/**
+ * tenki-mcp — Registry tools (custom sandbox images).
+ *
+ * The registry lets a workspace publish a sandbox snapshot/template as a reusable
+ * custom image (`<workspace>/<artifact>[:tag]`), resolve refs, control visibility,
+ * and share images across workspaces.
+ *
+ * Request shapes are LIVE-VERIFIED against api.tenki.cloud (2026-07-21). The API
+ * is inconsistent about field names, so note the specifics:
+ *   - most methods take `ref` (a bare `<ws>/<artifact>`; grants/unshare need it TAGLESS);
+ *   - ShareImage uses `imageRef` + `targetWorkspaceId` (NOT `ref`);
+ *   - version delete + grant revoke take UUIDs (`imageId`/`snapshotId`/`grantId`);
+ *   - visibility + publish-kind are string ENUMS (`REGISTRY_VISIBILITY_*`, `REGISTRY_IMAGE_KIND_*`).
+ * (The n8n reference this was first ported from marked all of these UNVERIFIED.)
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+export declare function registerRegistry(server: McpServer, client: TenkiClient): void;