@tenkicloud/mcp 0.1.0

package/dist/http.js

@@ -0,0 +1,234 @@
+/**
+ * HTTP/SSE transport for tenki-mcp (v2.0) — makes the server hostable, not just
+ * local-stdio. Uses the MCP SDK's StreamableHTTPServerTransport with a stateful
+ * per-session model: one server + transport per MCP session.
+ *
+ * Enable with TENKI_MCP_TRANSPORT=http. Config:
+ *   PORT                   — listen port (default 3000)
+ *   TENKI_MCP_HTTP_HOST    — bind host (default 127.0.0.1, loopback-only)
+ *   TENKI_MCP_HTTP_TOKEN   — required Bearer token for the /mcp endpoint
+ *
+ * Security posture (the process holds one shared TENKI_API_KEY and exposes all
+ * tools, incl. arbitrary code execution + credit spend, so the endpoint is a
+ * capability): loopback-only by default; DNS-rebinding protection on (Host
+ * allowlist); optional bearer auth; and it REFUSES to bind to a non-loopback
+ * host without a token set. Per-session/global DoS caps are applied.
+ */
+import http from "node:http";
+import { randomUUID, timingSafeEqual } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { createServer } from "./server.js";
+const MAX_BODY_BYTES = 1 << 20; // 1 MiB — reject larger POST bodies (memory-DoS guard)
+const MAX_SESSIONS = 256; // cap concurrent sessions (init-flood DoS guard)
+const SESSION_IDLE_MS = 30 * 60 * 1000; // reap sessions idle longer than this
+class BodyTooLarge extends Error {
+    constructor() {
+        super(`Request body exceeds the ${MAX_BODY_BYTES}-byte limit.`);
+        this.name = "BodyTooLarge";
+    }
+}
+class BadJson extends Error {
+}
+/**
+ * Read a JSON request body with a hard size cap (never throws un-typed).
+ * Rejects early on an oversized Content-Length, and independently enforces the
+ * cap while streaming, so a lying or absent Content-Length can't slip past the
+ * byte counter. Listeners are always removed on the first settle.
+ */
+function readJson(req) {
+    return new Promise((resolve, reject) => {
+        const declared = Number(req.headers["content-length"]);
+        if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+            req.resume(); // drain so the socket can close cleanly
+            reject(new BodyTooLarge());
+            return;
+        }
+        let size = 0;
+        const chunks = [];
+        let settled = false;
+        const cleanup = () => {
+            req.off("data", onData);
+            req.off("end", onEnd);
+            req.off("error", onError);
+        };
+        const onData = (c) => {
+            if (settled)
+                return;
+            size += c.length;
+            if (size > MAX_BODY_BYTES) {
+                settled = true;
+                cleanup();
+                req.resume();
+                reject(new BodyTooLarge());
+                return;
+            }
+            chunks.push(c);
+        };
+        const onEnd = () => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            const s = Buffer.concat(chunks).toString("utf8");
+            if (!s)
+                return resolve(undefined);
+            try {
+                resolve(JSON.parse(s));
+            }
+            catch {
+                reject(new BadJson());
+            }
+        };
+        const onError = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        };
+        req.on("data", onData);
+        req.on("end", onEnd);
+        req.on("error", onError);
+    });
+}
+/** Constant-time bearer-token check. No token configured → gate is open (loopback-only enforced at bind). */
+function authOk(header, expected) {
+    if (!expected)
+        return true;
+    const m = /^Bearer (.+)$/.exec(header ?? "");
+    if (!m)
+        return false;
+    const a = Buffer.from(m[1]);
+    const b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/**
+ * Host:port values the DNS-rebinding guard accepts: the configured host plus the
+ * loopback aliases, at BOTH the configured port and the port actually bound (so
+ * an ephemeral `port: 0` bind still accepts its own address). Anything else —
+ * e.g. a rebound attacker domain — is rejected by the transport.
+ */
+function allowedHostsFor(server, host, port) {
+    const addr = server.address();
+    const bound = addr && typeof addr === "object" ? addr.port : port;
+    const ports = Array.from(new Set([port, bound]));
+    const hosts = Array.from(new Set([host, "127.0.0.1", "localhost", "[::1]", "::1"]));
+    return hosts.flatMap((h) => ports.map((p) => `${h}:${p}`));
+}
+export function startHttp(client, port) {
+    const host = process.env.TENKI_MCP_HTTP_HOST || "127.0.0.1";
+    const httpToken = process.env.TENKI_MCP_HTTP_TOKEN || "";
+    const isLoopback = host === "127.0.0.1" || host === "::1" || host === "localhost";
+    // Refuse to expose an unauthenticated capability to the network.
+    if (!isLoopback && !httpToken) {
+        console.error("tenki-mcp: refusing to bind HTTP to a non-loopback host without TENKI_MCP_HTTP_TOKEN " +
+            "(the /mcp endpoint would be unauthenticated and can spend credits / run code). " +
+            "Set TENKI_MCP_HTTP_TOKEN, or bind to 127.0.0.1.");
+        process.exit(1);
+    }
+    const sessions = new Map();
+    const sweep = setInterval(() => {
+        const now = Date.now();
+        for (const [id, s] of sessions) {
+            if (now - s.lastSeen > SESSION_IDLE_MS) {
+                try {
+                    s.transport.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                sessions.delete(id);
+            }
+        }
+    }, 60_000);
+    sweep.unref?.();
+    const httpServer = http.createServer(async (req, res) => {
+        try {
+            if (!authOk(req.headers["authorization"], httpToken)) {
+                res.writeHead(401, { "Content-Type": "text/plain" }).end("unauthorized");
+                return;
+            }
+            const url = new URL(req.url || "/", `http://${host}`);
+            if (url.pathname !== "/mcp") {
+                res.writeHead(404, { "Content-Type": "text/plain" }).end("not found — MCP endpoint is /mcp");
+                return;
+            }
+            const sid = req.headers["mcp-session-id"];
+            if (req.method === "POST") {
+                let body;
+                try {
+                    body = await readJson(req);
+                }
+                catch (e) {
+                    if (e instanceof BodyTooLarge) {
+                        res
+                            .writeHead(413, { "Content-Type": "application/json", Connection: "close" })
+                            .end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32001, message: e.message }, id: null }));
+                        return;
+                    }
+                    res
+                        .writeHead(400, { "Content-Type": "application/json" })
+                        .end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32700, message: "Parse error" }, id: null }));
+                    return;
+                }
+                let entry = sid ? sessions.get(sid) : undefined;
+                if (!entry && isInitializeRequest(body)) {
+                    if (sessions.size >= MAX_SESSIONS) {
+                        res.writeHead(503, { "Content-Type": "text/plain" }).end("too many sessions");
+                        return;
+                    }
+                    const transport = new StreamableHTTPServerTransport({
+                        sessionIdGenerator: () => randomUUID(),
+                        // DNS-rebinding defense: only accept these Host headers, so a rebound
+                        // attacker-domain request from a browser is rejected.
+                        enableDnsRebindingProtection: true,
+                        allowedHosts: allowedHostsFor(httpServer, host, port),
+                        onsessioninitialized: (id) => {
+                            sessions.set(id, { transport, lastSeen: Date.now() });
+                        },
+                    });
+                    transport.onclose = () => {
+                        const id = transport.sessionId;
+                        if (id)
+                            sessions.delete(id);
+                    };
+                    await createServer(client).connect(transport);
+                    entry = { transport, lastSeen: Date.now() };
+                }
+                if (!entry) {
+                    res.writeHead(400, { "Content-Type": "application/json" }).end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message: "No valid session; send an initialize request first." }, id: null }));
+                    return;
+                }
+                entry.lastSeen = Date.now();
+                await entry.transport.handleRequest(req, res, body);
+                return;
+            }
+            // GET opens the SSE stream; DELETE ends a session.
+            if (req.method === "GET" || req.method === "DELETE") {
+                const entry = sid ? sessions.get(sid) : undefined;
+                if (!entry) {
+                    res.writeHead(400, { "Content-Type": "text/plain" }).end("No session for the given mcp-session-id.");
+                    return;
+                }
+                entry.lastSeen = Date.now();
+                await entry.transport.handleRequest(req, res);
+                return;
+            }
+            res.writeHead(405, { "Content-Type": "text/plain" }).end("method not allowed");
+        }
+        catch (e) {
+            // Never echo internals to the client; log server-side only.
+            if (!res.headersSent)
+                res.writeHead(500, { "Content-Type": "text/plain" });
+            res.end("internal error");
+            console.error("tenki-mcp http error:", e.message);
+        }
+    });
+    httpServer.on("close", () => clearInterval(sweep));
+    httpServer.listen(port, host, () => {
+        console.error(`tenki-mcp running on http://${host}:${port}/mcp (Streamable HTTP)` +
+            (httpToken ? " [bearer auth required]" : " [loopback only, no auth]"));
+    });
+    return httpServer;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * tenki-mcp — a Model Context Protocol server for Tenki Cloud.
+ *
+ * Exposes Tenki's sandbox platform (disposable microVMs for AI agents) as MCP
+ * tools, so any agent — Claude, Codex, Cursor — can create sandboxes, run code,
+ * manage files/snapshots/volumes/templates/images, run git, and expose preview URLs.
+ *
+ * Transports:
+ *   - stdio (default) — for local MCP clients (Claude Desktop, Cursor, Claude Code).
+ *   - HTTP/SSE — set TENKI_MCP_TRANSPORT=http (+ PORT, default 3000) to host it.
+ *
+ * Tools live in self-registering modules under ./tools; the server factory is in
+ * ./server.ts. Auth: set TENKI_API_KEY (or TENKI_AUTH_TOKEN) in the environment.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { TenkiClient } from "./client.js";
+import { createServer } from "./server.js";
+import { startHttp } from "./http.js";
+// A missing credential is NOT fatal: exiting here is reported by MCP clients as
+// an opaque "server failed to start" with stderr usually swallowed, leaving the
+// user with no idea a token is needed. Instead the server boots with only
+// tenki_auth_status registered (see createServer), so an agent can ask what is
+// wrong and relay the fix.
+const token = process.env.TENKI_AUTH_TOKEN || process.env.TENKI_API_KEY;
+if (!token) {
+    console.error("tenki-mcp: no credential — starting in unauthenticated mode (only tenki_auth_status is available). " +
+        "Set TENKI_API_KEY (tk_…) or TENKI_AUTH_TOKEN (ory_st_…) in the server's env and restart, " +
+        "e.g. claude mcp add tenki --env TENKI_API_KEY=tk_… -- npx -y tenki-mcp");
+}
+const baseUrl = process.env.TENKI_API_ENDPOINT || process.env.TENKI_API_URL || undefined;
+/** Positive integer from env, or undefined so the client keeps its own default. */
+const envMs = (name) => {
+    const n = Number.parseInt(process.env[name] ?? "", 10);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+};
+const client = token
+    ? new TenkiClient(token, baseUrl, {
+        timeoutMs: envMs("TENKI_MCP_TIMEOUT_MS"),
+        slowTimeoutMs: envMs("TENKI_MCP_SLOW_TIMEOUT_MS"),
+    })
+    : null;
+async function main() {
+    if ((process.env.TENKI_MCP_TRANSPORT || "stdio").toLowerCase() === "http") {
+        const httpServer = startHttp(client, Number(process.env.PORT) || 3000);
+        for (const sig of ["SIGINT", "SIGTERM"]) {
+            process.on(sig, () => httpServer.close(() => process.exit(0)));
+        }
+        return;
+    }
+    const server = createServer(client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("tenki-mcp running on stdio");
+}
+main().catch((err) => {
+    console.error("tenki-mcp fatal:", err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared MCP server factory — builds a server with every tool module registered.
+ * Used by both transports: stdio (index.ts) and HTTP (http.ts).
+ *
+ * Security controls (see SECURITY.md; maps to CSA MCP Server Top-10 MCP-07
+ * "excessive permissions"). Every tool is registered through a guard that:
+ *   1. tags it with MCP annotations (readOnlyHint / destructiveHint / openWorldHint)
+ *      so clients can surface or gate dangerous tools;
+ *   2. enforces least-privilege via env:
+ *        TENKI_MCP_READONLY=1        → register ONLY read tools (no create/run/delete/spend)
+ *        TENKI_MCP_DISABLED_TOOLS=a,b → skip these named tools
+ *   3. optionally audit-logs each call name to stderr: TENKI_MCP_AUDIT=1
+ *      (tool name + argument KEYS only — never values, content, or the token).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "./client.js";
+export declare const VERSION = "0.1.0";
+type Cls = "read" | "write" | "destructive";
+export declare function classifyTool(name: string): Cls;
+/**
+ * Build a fresh MCP server instance with all tools registered against `client`.
+ *
+ * `client` is null when no credential was supplied. Rather than refusing to
+ * start — which MCP clients report as an opaque "server failed to start" —
+ * the server boots with ONLY tenki_auth_status registered, so an agent can
+ * discover and explain the missing credential. Registering the other tools in
+ * that state would offer 84 tools that can only fail.
+ */
+export declare function createServer(client: TenkiClient | null): McpServer;
+export {};

package/dist/server.js

@@ -0,0 +1,205 @@
+/**
+ * Shared MCP server factory — builds a server with every tool module registered.
+ * Used by both transports: stdio (index.ts) and HTTP (http.ts).
+ *
+ * Security controls (see SECURITY.md; maps to CSA MCP Server Top-10 MCP-07
+ * "excessive permissions"). Every tool is registered through a guard that:
+ *   1. tags it with MCP annotations (readOnlyHint / destructiveHint / openWorldHint)
+ *      so clients can surface or gate dangerous tools;
+ *   2. enforces least-privilege via env:
+ *        TENKI_MCP_READONLY=1        → register ONLY read tools (no create/run/delete/spend)
+ *        TENKI_MCP_DISABLED_TOOLS=a,b → skip these named tools
+ *   3. optionally audit-logs each call name to stderr: TENKI_MCP_AUDIT=1
+ *      (tool name + argument KEYS only — never values, content, or the token).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerIdentity } from "./tools/identity.js";
+import { registerRun } from "./tools/run.js";
+import { registerSandboxes } from "./tools/sandboxes.js";
+import { registerSessionsAdmin } from "./tools/sessions_admin.js";
+import { registerExec } from "./tools/exec.js";
+import { registerFiles } from "./tools/files.js";
+import { registerFilesOps } from "./tools/files_ops.js";
+import { registerGit } from "./tools/git.js";
+import { registerPorts } from "./tools/ports.js";
+import { registerPreviews } from "./tools/previews.js";
+import { registerSnapshots } from "./tools/snapshots.js";
+import { registerVolumes } from "./tools/volumes.js";
+import { registerTemplates } from "./tools/templates.js";
+import { registerRegistry } from "./tools/registry.js";
+import { registerWorkspace } from "./tools/workspace.js";
+import { registerArtifacts } from "./tools/artifacts.js";
+import { registerSsh } from "./tools/ssh.js";
+import { registerAuthStatus } from "./tools/auth_status.js";
+export const VERSION = "0.1.0";
+const modules = [
+    registerIdentity,
+    registerRun,
+    registerSandboxes,
+    registerSessionsAdmin,
+    registerExec,
+    registerFiles,
+    registerFilesOps,
+    registerGit,
+    registerPorts,
+    registerPreviews,
+    registerSnapshots,
+    registerVolumes,
+    registerTemplates,
+    registerRegistry,
+    registerWorkspace,
+    registerArtifacts,
+    registerSsh,
+];
+// Destroys/removes/revokes a resource → destructiveHint.
+const DESTRUCTIVE = /^tenki_(terminate|delete|remove|unshare|revoke|detach|unexpose|unbind)/;
+// Named exceptions that match the READ prefix below but actually grant a
+// write/spend capability, so they must never be treated as read-only.
+// tenki_get_upload_url returns a signed URL for an arbitrary PUT into the sandbox.
+const WRITE_OVERRIDE = new Set(["tenki_get_upload_url"]);
+// Named exceptions that are pure reads but don't match the READ prefix below.
+// tenki_auth_status only inspects the ambient credential + probes WhoAmI, so it
+// must stay available under TENKI_MCP_READONLY (it is how an operator diagnoses
+// a credential problem in that posture).
+const READ_OVERRIDE = new Set(["tenki_auth_status"]);
+// Pure inspection, no state change / no spend → readOnlyHint.
+const READ = /^tenki_(get|list|whoami|resolve|stat|read)/;
+export function classifyTool(name) {
+    if (DESTRUCTIVE.test(name))
+        return "destructive";
+    if (WRITE_OVERRIDE.has(name))
+        return "write";
+    if (READ_OVERRIDE.has(name) || READ.test(name))
+        return "read";
+    return "write";
+}
+function readGuardOpts() {
+    const truthy = (v) => v === "1" || (v ?? "").toLowerCase() === "true";
+    const disabled = new Set((process.env.TENKI_MCP_DISABLED_TOOLS || "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean));
+    return { readonly: truthy(process.env.TENKI_MCP_READONLY), disabled, audit: truthy(process.env.TENKI_MCP_AUDIT) };
+}
+/** Log a tool call's name + argument KEYS (never values/content/token) to stderr. */
+function auditKeys(args) {
+    if (!args || typeof args !== "object")
+        return "";
+    const keys = Object.keys(args);
+    return keys.length ? ` args=[${keys.join(",")}]` : "";
+}
+/** MCP annotations derived from a tool's classification. */
+function annotationsFor(cls) {
+    return {
+        readOnlyHint: cls === "read",
+        destructiveHint: cls === "destructive",
+        idempotentHint: cls === "read",
+        openWorldHint: true, // every tool reaches the external Tenki API
+    };
+}
+/** Wrap a handler so TENKI_MCP_AUDIT=1 logs the call name + argument keys. */
+function withAudit(name, handler, audit) {
+    if (!audit)
+        return handler;
+    return async (args, extra) => {
+        try {
+            // A tool registered WITHOUT an input schema is invoked as (extra) —
+            // one argument — so the first param would be the request context, not
+            // tool args. Log arg keys only for the two-argument (args, extra) shape.
+            console.error(`[tenki-mcp audit] ${name}${extra === undefined ? "" : auditKeys(args)}`);
+        }
+        catch {
+            /* never let logging break a call */
+        }
+        return handler(args, extra);
+    };
+}
+/**
+ * Handle returned for a tool the guard skipped (denylist / read-only posture).
+ * The real registration APIs return a RegisteredTool handle; a module that
+ * calls .enable()/.remove() on its registration must not crash only in
+ * read-only or denylist mode, so skipped registrations get an inert stand-in.
+ */
+function noopToolHandle() {
+    return {
+        enabled: false,
+        enable() { },
+        disable() { },
+        update() { },
+        remove() { },
+    };
+}
+/**
+ * Wrap a server so every tool registration from a module is annotated + subject
+ * to the least-privilege env controls above. Both registration APIs are guarded:
+ * the legacy `.tool(name, description, schema, handler)` form and the modern
+ * `.registerTool(name, config, handler)` form (the only one that accepts an
+ * outputSchema) — so neither path can bypass annotations, read-only mode, or
+ * the denylist. Other access passes through to the real server unchanged.
+ */
+function guard(server, opts) {
+    return new Proxy(server, {
+        get(target, prop, receiver) {
+            if (prop === "tool") {
+                return (name, description, schema, handler) => {
+                    const cls = classifyTool(name);
+                    if (opts.disabled.has(name))
+                        return noopToolHandle(); // explicit denylist
+                    if (opts.readonly && cls !== "read")
+                        return noopToolHandle(); // read-only posture: skip anything that mutates/spends
+                    if (opts.registered)
+                        opts.registered.count++;
+                    return target.tool(name, description, schema, annotationsFor(cls), withAudit(name, handler, opts.audit));
+                };
+            }
+            if (prop === "registerTool") {
+                return (name, config, handler) => {
+                    const cls = classifyTool(name);
+                    if (opts.disabled.has(name))
+                        return noopToolHandle(); // explicit denylist
+                    if (opts.readonly && cls !== "read")
+                        return noopToolHandle(); // read-only posture: skip anything that mutates/spends
+                    // Name-derived classification stays authoritative for the four hints so
+                    // a module cannot soften them; other annotation fields pass through.
+                    if (opts.registered)
+                        opts.registered.count++;
+                    const annotations = {
+                        ...config.annotations,
+                        ...annotationsFor(cls),
+                    };
+                    return target.registerTool(name, { ...config, annotations }, withAudit(name, handler, opts.audit));
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
+/**
+ * Build a fresh MCP server instance with all tools registered against `client`.
+ *
+ * `client` is null when no credential was supplied. Rather than refusing to
+ * start — which MCP clients report as an opaque "server failed to start" —
+ * the server boots with ONLY tenki_auth_status registered, so an agent can
+ * discover and explain the missing credential. Registering the other tools in
+ * that state would offer 84 tools that can only fail.
+ */
+export function createServer(client) {
+    const server = new McpServer({ name: "tenki", version: VERSION });
+    const opts = { ...readGuardOpts(), registered: { count: 0 } };
+    const guarded = guard(server, opts);
+    if (client)
+        for (const register of modules)
+            register(guarded, client);
+    // Registered last, through the same guard as everything else, so its
+    // toolsRegistered figure counts the tools above it (+1 for itself).
+    // READ_OVERRIDE keeps it available under TENKI_MCP_READONLY;
+    // TENKI_MCP_DISABLED_TOOLS can still drop it.
+    registerAuthStatus(guarded, client, opts.registered.count + 1);
+    if (!client)
+        console.error("tenki-mcp: no credential — only tenki_auth_status registered. Set TENKI_API_KEY or TENKI_AUTH_TOKEN and restart.");
+    if (opts.readonly)
+        console.error("tenki-mcp: TENKI_MCP_READONLY — only read-only tools registered.");
+    else if (opts.disabled.size)
+        console.error(`tenki-mcp: disabled tools — ${[...opts.disabled].join(", ")}`);
+    return server;
+}

package/dist/tools/artifacts.d.ts

@@ -0,0 +1,16 @@
+/**
+ * artifacts.ts — signed-URL binary transfer for tenki-mcp.
+ *
+ * The text file tools (read_file/write_file) round-trip UTF-8 over the data plane.
+ * For binary payloads (datasets, wheels, images, build outputs) Tenki issues short-
+ * lived signed URLs: GetArtifactUploadUrl to PUT a file into the sandbox, and
+ * GetArtifactDownloadUrl to GET one out. These tools return the signed URL; the
+ * caller performs the actual HTTP PUT/GET.
+ *
+ * GetArtifactUploadUrlRequest { sessionId, path, contentType } is verified from the
+ * published Tenki API surface. GetArtifactDownloadUrl takes an artifactId only — the API
+ * rejects a path (command stdout/stderr are surfaced as artifact ids).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+export declare function registerArtifacts(server: McpServer, client: TenkiClient): void;

package/dist/tools/artifacts.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { ok, pathSchema, sessionIdSchema } from "./common.js";
+export function registerArtifacts(server, client) {
+    server.tool("tenki_get_upload_url", "Get a short-lived signed URL to upload (HTTP PUT) a binary file to a path inside a sandbox. Use for non-text payloads too large or binary for tenki_write_file.", {
+        session_id: sessionIdSchema,
+        path: pathSchema.describe("Destination path in the sandbox, e.g. /home/tenki/data.bin"),
+        content_type: z.string().optional().describe("MIME type of the upload, e.g. application/octet-stream."),
+    }, async ({ session_id, path, content_type }) => ok(await client.control("GetArtifactUploadUrl", {
+        sessionId: session_id,
+        path,
+        ...(content_type ? { contentType: content_type } : {}),
+    })));
+    server.tool("tenki_get_download_url", "Get a short-lived signed URL to download (HTTP GET) a command artifact from a sandbox by its artifact id (e.g. a command's stdout/stderr artifact). Note: the API supports download-by-artifact-id only, not download-by-path.", {
+        session_id: sessionIdSchema,
+        artifact_id: z.string().describe("Artifact id to download (e.g. a command's stdout/stderr artifact)."),
+    }, 
+    // GetArtifactDownloadUrl only accepts an artifact UUID; a `path` is rejected (live-verified).
+    async ({ session_id, artifact_id }) => ok(await client.control("GetArtifactDownloadUrl", { sessionId: session_id, artifactId: artifact_id })));
+}

package/dist/tools/auth_status.d.ts

@@ -0,0 +1,35 @@
+/**
+ * auth_status.ts — the one tool that works without a credential.
+ *
+ * Without this, a user who installs the server before setting a token gets a
+ * process that exits 1; MCP clients surface that as "server failed to start"
+ * and usually swallow stderr, so the actual cause (no token) is invisible. The
+ * server therefore boots credential-less with ONLY this tool registered, so an
+ * agent can ask what's wrong and get an actionable answer.
+ *
+ * It reports status; it does NOT log in. Obtaining a token is out of scope for
+ * the server (see `tenki login`), and nothing here opens a browser or writes
+ * credentials anywhere.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/** How a credential was supplied, derived from the token's prefix. */
+export type CredentialKind = "none" | "api_key" | "oauth_session_token" | "session_cookie";
+export interface CredentialInfo {
+    kind: CredentialKind;
+    /** Env var the token came from, or undefined when there is none. */
+    source?: "TENKI_AUTH_TOKEN" | "TENKI_API_KEY";
+}
+/**
+ * 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 declare function describeCredential(env?: NodeJS.ProcessEnv): CredentialInfo;
+/**
+ * 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 declare function registerAuthStatus(server: McpServer, client: TenkiClient | null, toolsRegistered: number): void;