@luxorai/mcp 0.0.0-stage → 0.3.1

package/dist/server.js

@@ -0,0 +1,203 @@
+/**
+ * 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 { 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.3.1";
+const modules = [
+    registerIdentity,
+    registerRun,
+    registerSandboxes,
+    registerSessionsAdmin,
+    registerExec,
+    registerFiles,
+    registerFilesOps,
+    registerGit,
+    registerPorts,
+    registerPreviews,
+    registerSnapshots,
+    registerVolumes,
+    registerTemplates,
+    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 70 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 the server authenticates API calls. */
+export type CredentialKind = "none" | "api_key" | "oauth_session_token" | "session_cookie" | "hosted_oauth";
+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;

package/dist/tools/auth_status.js

@@ -0,0 +1,109 @@
+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 && env.TENKI_MCP_OAUTH_ISSUER?.trim())
+        return { kind: "hosted_oauth" };
+    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 @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", "hosted_oauth"])
+        .describe("Kind of credential the server is running with. 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: 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

@@ -0,0 +1,35 @@
+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: {
+        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.ZodString;
+/**
+ * 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,60 @@
+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(publicValue(value), null, 2) }],
+});
+/** Shared env-map schema used by tools that accept environment variables. */
+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
+ * 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,120 @@
+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."),
+    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
+ * 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 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)"}`;
+    const capture = r.captureError
+        ? `\ncapture error: ${sanitizeForTerminal(r.captureError)} — stdout/stderr may be incomplete`
+        : "";
+    const stdout = sanitizeForTerminal(r.stdout);
+    const stderr = sanitizeForTerminal(r.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. 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'."),
+            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(),
+            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, 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
+            // 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;