@luxorai/mcp 0.0.0-stage → 0.4.0

package/dist/tools/egress.d.ts

@@ -0,0 +1,38 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { TenkiClient } from "../client.js";
+export declare const policyNameSchema: z.ZodString;
+export declare const httpRuleSchema: z.ZodObject<{
+    domains: z.ZodArray<z.ZodString>;
+    methods: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    path_exact: z.ZodOptional<z.ZodString>;
+    path_prefix: z.ZodOptional<z.ZodString>;
+    path_regex: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type HttpRule = z.infer<typeof httpRuleSchema>;
+export declare const httpRuleToWire: (r: HttpRule) => Record<string, unknown>;
+export declare const allowDomainsSchema: z.ZodArray<z.ZodString>;
+export declare const allowCidrsSchema: z.ZodArray<z.ZodString>;
+export declare const interceptHttpsSchema: z.ZodBoolean;
+export declare const httpRulesSchema: z.ZodArray<z.ZodObject<{
+    domains: z.ZodArray<z.ZodString>;
+    methods: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    path_exact: z.ZodOptional<z.ZodString>;
+    path_prefix: z.ZodOptional<z.ZodString>;
+    path_regex: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export declare const allowedPortsSchema: z.ZodArray<z.ZodNumber>;
+export interface EgressBody {
+    allow_domains?: string[];
+    allow_cidrs?: string[];
+    intercept_https?: boolean;
+    http_rules?: HttpRule[];
+    allowed_ports?: number[];
+}
+/**
+ * Map an egress body to SessionEgressPolicy JSON. `requireComplete` applies the
+ * checks the API runs on a policy that stands alone; on create they are skipped
+ * when named policies are pinned, because the API merges them first.
+ */
+export declare function egressBodyToWire(tool: string, b: EgressBody, requireComplete: boolean): Record<string, unknown> | undefined;
+export declare function registerEgress(server: McpServer, client: TenkiClient): void;

package/dist/tools/egress.js

@@ -0,0 +1,153 @@
+import { z } from "zod";
+import { ok } from "./common.js";
+/**
+ * Named workspace egress policies (tenki-app #6069): reusable egress allowlists
+ * that tenki_create_sandbox pins by name via `egress_policies`. A session keeps
+ * the expansion it was created with; later edits or deletes do not change it.
+ * Wire shape: SessionEgressPolicy { allowDomains, allowCidrs, interceptHttps,
+ * httpRules[{ domains, methods, exact | prefix | regex }], allowedPorts } — the
+ * path oneof members are plain fields on the rule.
+ */
+const POLICY_NAME = /^[A-Za-z_][A-Za-z0-9_-]{0,127}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const policyNameSchema = z
+    .string()
+    .regex(POLICY_NAME, "policy names: letters, digits, _ and -, starting with a letter or _, max 128");
+const domainSchema = z.string().min(1).max(253);
+const pathSchema = z.string().min(1).max(2048).regex(/^\//, "paths start with /");
+export const httpRuleSchema = z
+    .object({
+    domains: z
+        .array(domainSchema)
+        .min(1)
+        .max(256)
+        .describe("Hosts the rule applies to: exact names, single-label '*.example.com' wildcards, or '*' for every allowed domain."),
+    methods: z
+        .array(z.string().min(1).max(32))
+        .max(16)
+        .optional()
+        .describe("HTTP methods (e.g. GET, POST; uppercased by the API). Omit to match every method."),
+    path_exact: pathSchema.optional().describe("Match only this escaped path (no query)."),
+    path_prefix: pathSchema.optional().describe("Match paths starting with this prefix."),
+    path_regex: z.string().min(1).max(1024).optional().describe("RE2 regex that must match the whole escaped path (no query)."),
+})
+    .strict()
+    .refine((r) => [r.path_exact, r.path_prefix, r.path_regex].filter((p) => p !== undefined).length <= 1, {
+    message: "set at most one of path_exact, path_prefix, path_regex",
+});
+export const httpRuleToWire = (r) => ({
+    domains: r.domains,
+    ...(r.methods?.length ? { methods: r.methods } : {}),
+    ...(r.path_exact !== undefined ? { exact: r.path_exact } : {}),
+    ...(r.path_prefix !== undefined ? { prefix: r.path_prefix } : {}),
+    ...(r.path_regex !== undefined ? { regex: r.path_regex } : {}),
+});
+export const allowDomainsSchema = z
+    .array(domainSchema)
+    .max(256)
+    .describe("Allowed hosts: exact names or single-label '*.example.com' wildcards (≤256).");
+export const allowCidrsSchema = z
+    .array(z.string().min(1).max(18))
+    .max(64)
+    .describe("Allowed IPv4 prefixes reachable without a name lookup (≤64; not 0.0.0.0/0).");
+export const interceptHttpsSchema = z
+    .boolean()
+    .describe("Terminate port-443 TLS with the sandbox's managed CA so each request's Host is checked; requires at least one allowed domain. With interception on, public egress is limited to TCP 80/443 through the proxy; other ports are blocked unless listed in allowed_ports.");
+export const httpRulesSchema = z
+    .array(httpRuleSchema)
+    .max(64)
+    .describe("Per-host HTTP method/path rules (≤64; requires intercept_https). On ports 80 and 443 a request matching no rule is refused with 403.");
+export const allowedPortsSchema = z
+    .array(z.number().int().min(1).max(65535))
+    .max(64)
+    .describe("Extra public TCP ports to open besides 80/443 (≤64; requires intercept_https). They skip HTTP inspection but still reach only allowed destinations, so 22 permits git over SSH, including pushes.");
+/**
+ * Map an egress body to SessionEgressPolicy JSON. `requireComplete` applies the
+ * checks the API runs on a policy that stands alone; on create they are skipped
+ * when named policies are pinned, because the API merges them first.
+ */
+export function egressBodyToWire(tool, b, requireComplete) {
+    const domains = b.allow_domains?.length ? b.allow_domains : undefined;
+    const cidrs = b.allow_cidrs?.length ? b.allow_cidrs : undefined;
+    const rules = b.http_rules?.length ? b.http_rules : undefined;
+    const ports = b.allowed_ports?.length ? b.allowed_ports : undefined;
+    if (requireComplete) {
+        if (!domains && !cidrs && (b.intercept_https || rules || ports))
+            throw new Error(`${tool}: an egress policy must list at least one allowed domain or CIDR.`);
+        if (b.intercept_https && !domains)
+            throw new Error(`${tool}: intercept_https requires at least one allowed domain.`);
+        if (rules && !b.intercept_https)
+            throw new Error(`${tool}: http_rules require intercept_https: true (without interception HTTPS requests would bypass them).`);
+        if (ports && !b.intercept_https)
+            throw new Error(`${tool}: allowed_ports require intercept_https: true (without interception other ports already follow the domain and CIDR allowlist).`);
+    }
+    if (!domains && !cidrs && !b.intercept_https && !rules && !ports)
+        return undefined;
+    return {
+        ...(domains ? { allowDomains: domains } : {}),
+        ...(cidrs ? { allowCidrs: cidrs } : {}),
+        ...(b.intercept_https ? { interceptHttps: true } : {}),
+        ...(rules ? { httpRules: rules.map(httpRuleToWire) } : {}),
+        ...(ports ? { allowedPorts: ports } : {}),
+    };
+}
+const workspaceIdSchema = z.string().optional().describe("Workspace (defaults to the key's workspace).");
+const policyRefSchema = z.string().min(1).describe("Policy ID or name.");
+const revisionSchema = z
+    .number()
+    .int()
+    .min(1)
+    .max(4294967295)
+    .describe("The policy's current revision (from tenki_get_egress_policy); a stale revision is refused with ABORTED.");
+const ENABLE_NOTE = "Sandboxes cannot pin policies (failed_precondition) if session egress policies are disabled for the workspace (on by default; Tenki staff can turn it off).";
+export function registerEgress(server, client) {
+    const workspace = async (workspace_id) => {
+        const id = workspace_id ?? (await client.resolveOwner()).workspaceId;
+        return id ? { workspaceId: id } : {};
+    };
+    const body = (tool, b) => {
+        const egress = egressBodyToWire(tool, b, true);
+        if (!egress)
+            throw new Error(`${tool}: an egress policy must list at least one allowed domain or CIDR.`);
+        return egress;
+    };
+    server.tool("tenki_create_egress_policy", `Save a named egress policy (allowed domains/CIDRs, optional HTTPS interception, per-host HTTP rules and extra ports) in the workspace, for tenki_create_sandbox's egress_policies to pin by name. ${ENABLE_NOTE}`, {
+        name: policyNameSchema.refine((n) => !UUID.test(n), "a policy name must not be a UUID").describe("Policy name (letters, digits, _ and -; not a UUID). Exact, never trimmed."),
+        allow_domains: allowDomainsSchema.optional(),
+        allow_cidrs: allowCidrsSchema.optional(),
+        intercept_https: interceptHttpsSchema.optional(),
+        http_rules: httpRulesSchema.optional(),
+        allowed_ports: allowedPortsSchema.optional(),
+        workspace_id: workspaceIdSchema,
+    }, async ({ name, workspace_id, ...b }) => ok(await client.control("CreateEgressPolicy", { ...(await workspace(workspace_id)), name, egress: body("tenki_create_egress_policy", b) })));
+    server.tool("tenki_update_egress_policy", "Replace a named egress policy's rules (the whole body; omitted fields are cleared). Requires the current revision. Sandboxes created earlier keep the rules they were created with.", {
+        policy_id: policyRefSchema,
+        expected_revision: revisionSchema,
+        allow_domains: allowDomainsSchema.optional(),
+        allow_cidrs: allowCidrsSchema.optional(),
+        intercept_https: interceptHttpsSchema.optional(),
+        http_rules: httpRulesSchema.optional(),
+        allowed_ports: allowedPortsSchema.optional(),
+        workspace_id: workspaceIdSchema,
+    }, async ({ policy_id, expected_revision, workspace_id, ...b }) => ok(await client.control("UpdateEgressPolicy", {
+        ...(await workspace(workspace_id)),
+        policyId: policy_id,
+        expectedRevision: expected_revision,
+        egress: body("tenki_update_egress_policy", b),
+    })));
+    server.tool("tenki_get_egress_policy", "Get one named egress policy by ID or name: its rules, current revision, and how many non-terminated sandboxes pinned it.", { policy_id: policyRefSchema, workspace_id: workspaceIdSchema }, async ({ policy_id, workspace_id }) => ok(await client.control("GetEgressPolicy", { ...(await workspace(workspace_id)), policyId: policy_id })));
+    server.tool("tenki_list_egress_policies", "List the workspace's named egress policies, ordered by name. Pass next_cursor back as cursor for the next page.", {
+        page_size: z.number().int().min(1).max(100).optional().describe("Max policies per page (≤100, default 50)."),
+        cursor: z.string().optional().describe("next_cursor from the previous page."),
+        workspace_id: workspaceIdSchema,
+    }, async ({ page_size, cursor, workspace_id }) => ok(await client.control("ListEgressPolicies", {
+        ...(await workspace(workspace_id)),
+        ...(page_size ? { pageSize: page_size } : {}),
+        ...(cursor ? { cursor } : {}),
+    })));
+    server.tool("tenki_delete_egress_policy", "Delete a named egress policy (requires its current revision). New sandboxes can no longer pin it; sandboxes that already pinned it keep its rules.", { policy_id: policyRefSchema, expected_revision: revisionSchema, workspace_id: workspaceIdSchema }, async ({ policy_id, expected_revision, workspace_id }) => ok(await client.control("DeleteEgressPolicy", {
+        ...(await workspace(workspace_id)),
+        policyId: policy_id,
+        expectedRevision: expected_revision,
+    })));
+}

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().describe("Maximum seconds the command may run before it is stopped; omit to use the API's default."),
+            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,55 @@
+import { z } from "zod";
+import { ok, pathSchema, sessionIdSchema, utf8CharEnd, utf8CharStart } from "./common.js";
+// Inline read budget, matching tenki_exec's per-stream default. The data
+// plane's ReadFile has no range support, so the whole file still crosses the
+// wire to this process; the cap bounds what is returned to the model.
+const DEFAULT_READ_BYTES = 65_536;
+const MAX_READ_BYTES = 1_048_576;
+/** 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). Returns at most max_bytes (default 65536) starting at offset, plus the file's totalBytes; when more remains the response has truncated: true and nextOffset — pass it as offset to read the next part.", {
+        session_id: sessionIdSchema,
+        path: pathSchema,
+        offset: z.number().int().min(0).optional().describe("Byte offset to start reading at (default 0). Use nextOffset from a truncated response."),
+        max_bytes: z
+            .number()
+            .int()
+            .min(1024)
+            .max(MAX_READ_BYTES)
+            .optional()
+            .describe(`Maximum bytes of content to return (default ${DEFAULT_READ_BYTES}, max ${MAX_READ_BYTES}). Cuts never split a UTF-8 character.`),
+    }, async ({ session_id, path, offset, max_bytes }) => {
+        const buf = await client.readFileBytes(session_id, path);
+        const totalBytes = buf.length;
+        const requested = offset ?? 0;
+        if (requested > totalBytes) {
+            throw new Error(`offset ${requested} is past the end of ${path} (${totalBytes} bytes).`);
+        }
+        const start = utf8CharStart(buf, requested);
+        const end = utf8CharEnd(buf, start, start + (max_bytes ?? DEFAULT_READ_BYTES));
+        const truncated = end < totalBytes;
+        return ok({
+            path,
+            content: buf.subarray(start, end).toString("utf8"),
+            totalBytes,
+            ...(start > 0 || truncated ? { offset: start, bytesReturned: end - start } : {}),
+            ...(truncated ? { truncated: true, nextOffset: end } : {}),
+        });
+    });
+    server.tool("tenki_write_file", "Write a UTF-8 text file to a sandbox (paths under /home/tenki), creating it or replacing its entire contents.", { session_id: sessionIdSchema, path: pathSchema, content: z.string().describe("Full text to write; an existing file is overwritten.") }, 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,62 @@
+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)."),
+        mode: z
+            .number()
+            .int()
+            .min(0)
+            .max(0o7777)
+            .optional()
+            .describe("Permission bits as a number (e.g. 448 for 0700). Default: the sandbox user's umask."),
+    }, async ({ session_id, path, recursive, mode }) => ok(await client.data(session_id, "Mkdir", {
+        path,
+        ...(recursive ? { recursive: true } : {}),
+        ...(mode !== undefined ? { mode } : {}),
+    })));
+    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,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+export declare function registerGit(server: McpServer, client: TenkiClient): void;

package/dist/tools/git.js

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { capText, ok, sessionIdSchema } from "./common.js";
+/**
+ * Git inside a sandbox, one tool per operation. The API exposes a single
+ * GitOperation RPC whose `operation` must be clone, checkout, diff or log
+ * (GitOperationRequest's buf.validate `in` list) with a string→string args map;
+ * these tools give each operation typed arguments and an accurate read/write
+ * classification (diff/log are reads, clone/checkout change the filesystem).
+ * For any other git command (status, add, commit, push, ...) use tenki_exec.
+ *
+ * Arg keys are the ones the engine reads (tenki-app
+ * backend/internal/domain/sandbox/service/git_operation.go, buildGitOperationArgs):
+ * checkout/diff/log run `git -C <directory>` when `directory` is set — without
+ * it they run in /home/tenki, which is not a repository unless one was cloned
+ * there. Values are argv to the engine's command, never a shell string.
+ *
+ * The engine places repo, branch, directory, ref, range, base and head in
+ * git's argv without `--end-of-options`, so a value starting with `-` would be
+ * parsed as an option: `git diff --output=<file>` truncates a file and
+ * `git clone --upload-pack=<cmd>` runs a command. Those values are refused
+ * here — which is also what keeps tenki_git_diff / tenki_git_log read-only.
+ * `path` is safe: the engine always puts it after `--`.
+ */
+// Inline output budget, matching tenki_exec and tenki_read_file.
+const MAX_OUTPUT_BYTES = 65_536;
+// The engine re-trims each value with Go's strings.TrimSpace, which also strips
+// U+0085 (NEL) — JavaScript's trim() and \s do not — so "\u0085--output=x"
+// would reach git as "--output=x". Refuse a '-' behind any such whitespace.
+const noOption = (s) => !/^[\s\u0085]*-/.test(s);
+const NO_OPTION_MSG = "must not start with '-' (git would read it as an option)";
+/** A value the engine passes to git as a bare argument. */
+const gitArg = (description) => z.string().trim().min(1).refine(noOption, NO_OPTION_MSG).describe(description);
+const directorySchema = gitArg("Repository directory in the sandbox, e.g. /home/tenki/myrepo (relative paths resolve from /home/tenki). Omit only if the repository is /home/tenki itself.").optional();
+/** How to get less output, per operation (only diff/log take narrowing args). */
+const NARROW = {
+    diff: "Narrow it with path or range/base/head, or run git through tenki_exec and page its output.",
+    log: "Narrow it with max_count, path or range, or run git through tenki_exec and page its output.",
+};
+const NARROW_DEFAULT = "Run git through tenki_exec to page the full output.";
+async function gitOperation(client, sessionId, operation, args) {
+    const stringArgs = Object.fromEntries(Object.entries(args)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => [k, String(v)]));
+    const resp = await client.control("GitOperation", { sessionId, operation, args: stringArgs });
+    if (typeof resp?.output !== "string")
+        return ok(resp);
+    const capped = capText(resp.output, MAX_OUTPUT_BYTES);
+    if (!capped.truncated)
+        return ok(resp);
+    return ok({
+        ...resp,
+        output: capped.text,
+        truncated: true,
+        totalBytes: capped.totalBytes,
+        note: `Output truncated to ${MAX_OUTPUT_BYTES} bytes. ${NARROW[operation] ?? NARROW_DEFAULT}`,
+    });
+}
+export function registerGit(server, client) {
+    server.tool("tenki_git_clone", "Clone a git repository into a sandbox and return git's output. The target directory must not already exist or must be empty. For other git commands (status, add, commit, push, ...) use tenki_exec with `git ...`.", {
+        session_id: sessionIdSchema,
+        repo: gitArg("Repository URL to clone, e.g. https://github.com/octocat/Hello-World."),
+        branch: gitArg("Branch or tag to check out after cloning (git clone --branch).").optional(),
+        depth: z.number().int().positive().optional().describe("Create a shallow clone with this many commits (git clone --depth)."),
+        directory: gitArg("Directory to clone into, e.g. /home/tenki/myrepo. Defaults to the repository name under /home/tenki.").optional(),
+    }, async ({ session_id, repo, branch, depth, directory }) => gitOperation(client, session_id, "clone", { repo, branch, depth, directory }));
+    server.tool("tenki_git_checkout", "Check out a branch, tag or commit in a repository inside a sandbox (git checkout), optionally creating a new branch. Changes the files in the working tree.", {
+        session_id: sessionIdSchema,
+        ref: gitArg("Branch, tag or commit to check out, or the name of the branch to create when create is true."),
+        create: z.boolean().optional().describe("Create ref as a new branch from the current HEAD (git checkout -b). Default false."),
+        directory: directorySchema,
+    }, async ({ session_id, ref, create, directory }) => gitOperation(client, session_id, "checkout", { ref, create: create ? "true" : undefined, directory }));
+    server.tool("tenki_git_diff", `Show a diff for a repository inside a sandbox (git diff): unstaged working-tree changes by default, or between refs. Read-only. Output over ${MAX_OUTPUT_BYTES} bytes is truncated.`, {
+        session_id: sessionIdSchema,
+        range: gitArg("Revision range, e.g. main..feature or HEAD~3. Cannot be combined with base/head.").optional(),
+        base: gitArg("Base ref to diff from (with head: git diff base..head; alone: git diff base).").optional(),
+        head: gitArg("Head ref to diff to (with base: git diff base..head; alone: git diff head).").optional(),
+        path: z.string().trim().min(1).optional().describe("Limit the diff to this file or directory, relative to the repository root."),
+        directory: directorySchema,
+    }, async ({ session_id, range, base, head, path, directory }) => {
+        if (range !== undefined && (base !== undefined || head !== undefined)) {
+            throw new Error("tenki_git_diff: pass either range or base/head, not both.");
+        }
+        return gitOperation(client, session_id, "diff", { range, base, head, path, directory });
+    });
+    server.tool("tenki_git_log", `Show commit history for a repository inside a sandbox (git log). Read-only. Output over ${MAX_OUTPUT_BYTES} bytes is truncated.`, {
+        session_id: sessionIdSchema,
+        max_count: z.number().int().positive().max(1000).optional().describe("Maximum number of commits to show (git log --max-count). Set this to keep output small."),
+        range: gitArg("Revision range, e.g. main..feature.").optional(),
+        path: z.string().trim().min(1).optional().describe("Only commits touching this file or directory, relative to the repository root."),
+        directory: directorySchema,
+    }, async ({ session_id, max_count, range, path, directory }) => gitOperation(client, session_id, "log", { max_count, range, path, directory }));
+}

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,11 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+/**
+ * Port exposure. ExposePort / ListExposedPorts (and UnexposePort in previews.ts)
+ * are marked deprecated upstream (tenki-app #5663, 2026-09-15) in favour of the
+ * preview-URL RPCs; they still work — ExposePort now creates a preview URL and
+ * auto-mints a slug when none is given, which CreatePreviewUrl cannot do (slug
+ * is required there). Kept as the convenience path; descriptions steer callers
+ * who already have a slug to tenki_create_preview_url.
+ */
+export declare function registerPorts(server: McpServer, client: TenkiClient): void;

package/dist/tools/ports.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { ok, portSchema, sessionIdSchema, slugSchema } from "./common.js";
+/**
+ * Port exposure. ExposePort / ListExposedPorts (and UnexposePort in previews.ts)
+ * are marked deprecated upstream (tenki-app #5663, 2026-09-15) in favour of the
+ * preview-URL RPCs; they still work — ExposePort now creates a preview URL and
+ * auto-mints a slug when none is given, which CreatePreviewUrl cannot do (slug
+ * is required there). Kept as the convenience path; descriptions steer callers
+ * who already have a slug to tenki_create_preview_url.
+ */
+export function registerPorts(server, client) {
+    server.tool("tenki_expose_port", "Expose a port from a sandbox and get a public preview URL (a slug is auto-generated unless you pass one). Useful when an agent starts a web server it wants to show. Requires allow_inbound. The API marks ExposePort deprecated in favour of CreatePreviewUrl — if you already have a slug, prefer tenki_create_preview_url; to take the URL down use tenki_unbind_preview_url / tenki_delete_preview_url with the returned previewUrlId.", {
+        session_id: sessionIdSchema,
+        port: portSchema,
+        slug: slugSchema.optional(),
+        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, expires_at }) => ok(await client.control("ExposePort", {
+        sessionId: session_id,
+        port,
+        ...(slug ? { slug } : {}),
+        ...(expires_at !== undefined ? { expiresAt: expires_at } : {}),
+    })));
+    server.tool("tenki_list_exposed_ports", "List the ports currently exposed from a sandbox. DEPRECATED upstream (ListExposedPorts): prefer tenki_list_preview_urls with session_id, which lists the same bindings with their ids, slugs and expiry.", { 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-08-21): projects were REMOVED from the API (every
+ * project_id field is proto-reserved and unknown fields are silently discarded),
+ * so the preview-URL methods are workspace/id-scoped. CreatePreviewUrl requires
+ * a `slug` (>=3 chars, [a-z0-9-]).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TenkiClient } from "../client.js";
+export declare function registerPreviews(server: McpServer, client: TenkiClient): void;