@tenkicloud/mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,161 @@
+# Changelog
+
+All notable changes to tenki-mcp. This project follows semantic versioning.
+
+## [0.1.0] — 2026-08-03 — First npm release: typed git, network hardening, structured output
+
+Published as **`@tenkicloud/mcp`**, matching the `@tenkicloud/sandbox` SDK. Install with `npx -y @tenkicloud/mcp`; the command it provides is still `tenki-mcp`.
+
+### Fixed by an end-to-end sweep of all 85 tools against the live API
+
+- **`tenki_create_snapshot` and `tenki_pause_sandbox` reported failure on operations that succeeded.** Both RPCs block until the underlying storage work finishes — measured at 59s and 41s — so the 30s default HTTP budget introduced with the timeout work cut them off. The caller got `timed out after 30000ms` while the snapshot (or a multi-GB pause snapshot) had in fact been created, leaving an orphaned resource whose id it never saw, and an agent that retried burned quota. Both now use a 600s budget, tunable with `TENKI_MCP_SLOW_TIMEOUT_MS` (`TENKI_MCP_TIMEOUT_MS` tunes the ordinary 30s one). Async methods that return a handle in under a second — `BuildTemplate`, `PublishRegistryImage` — deliberately keep the short budget.
+- **`tenki_update_workspace_settings` and `tenki_update_snapshot_retention_settings` did nothing at all, and reported success.** Every field they sent (`defaultIdleTimeoutMinutes`, `defaultMaxDurationSeconds`, `snapshotRetentionDays`, `retentionDays`) is absent from the API; connect-go discards unknown fields, so the server returned 200 with the settings unchanged. They now send the real contract — `pauseRetention`/`snapshotRetention` as protobuf Durations with their `clear*` companions, plus the `max*` quotas — reject a call that would change nothing, and `clear_retention` makes "keep snapshots indefinitely" expressible for the first time. The retention pair is also documented as deprecated upstream in favour of the workspace-settings pair.
+- **`tenki_list_files` hid every dotfile.** The data plane omits dot-prefixed entries unless asked, so `.git`, `.env` and `.gitignore` were invisible and an agent would conclude they did not exist. It now sends `include_hidden` (default true, overridable) and always returns an `entries` array instead of a bare `{}` for an empty directory.
+- **`tenki_list_preview_urls` advertised a filter the API does not have.** `ListPreviewUrls` takes no session id, so the one this tool sent was silently dropped and every session's preview URLs came back as if filtered. The filter is now applied client-side and says so in the result; `page_size`, `page_token` and `workspace_id` — all real fields the tool never exposed — are now available, and the deprecated `project_id` is gone.
+- **`tenki_publish_image`'s documented example could never work:** its own description showed `myws/myimage:latest`, and the API rejects any tag or `@snapshot` on publish. The tagless form is now enforced client-side with an explanatory message.
+- **`tenki_unshare_image` silently revoked nothing** when called with neither `grant_id` nor `grantee_workspace_id`, returning the image object like a success. It now refuses, matching the guard `tenki_delete_image` already had.
+- **`tenki_open_preview` hands back an unreachable URL** for any port but the web terminal (7681): the API deliberately drops the regional host for other ports and returns a fallback that has no edge route, so the URL 404s. The description now says so and points at `tenki_expose_port`/`tenki_create_preview_url`. Platform-side issue; documented rather than worked around.
+
+### A missing credential no longer looks like a broken server
+
+- **New tool `tenki_auth_status`** (85 tools total) — reports whether a usable credential is configured, which kind (`api_key` for `tk_…`, `oauth_session_token` for `ory_st_…`, or `session_cookie`), which env var it came from, the endpoint targeted, and whether a live identity probe succeeded. Never returns the token. Structured output, annotated read-only, and available under `TENKI_MCP_READONLY` (it is how you diagnose a credential problem in that posture) — `TENKI_MCP_DISABLED_TOOLS` can still drop it.
+- **The server starts without a credential instead of exiting 1.** Exiting made MCP clients report an opaque "server failed to start" while swallowing the stderr line that explained why, leaving the user with a broken server and no cause. It now boots with `tenki_auth_status` as the only registered tool, so an agent can ask what is wrong and relay the fix; the reported `toolsRegistered` count makes that degraded mode explicit. Registering all 84 API tools in that state would only offer tools that cannot work.
+- Reporting status is the whole scope: nothing here logs in, opens a browser, or writes credentials. Get a credential with `tenki login` or from the dashboard.
+
+### Tool-schema DX (git enum, shared schemas, README)
+
+- **`tenki_git` now validates `operation` as an enum of what the API actually supports: `clone`, `checkout`, `diff`, `log`.** The tool previously advertised ten operations, but six of them (status/add/commit/pull/push/fetchPR) are rejected by the API's own validation (`GitOperationRequest` allows exactly four) — a model following the old description was guaranteed a server error. Per-operation arg keys are now documented in the tool description, grounded in the engine's arg builder: clone `{repo, branch?, depth?, directory?}`, checkout `{ref, create?}`, diff `{range? | base?+head?, path?}`, log `{max_count?, range?, path?}`. Other git commands: use `tenki_exec` with `git ...`.
+- **Shared input schemas** in `common.ts`: `sessionIdSchema` (described; trimmed and non-empty, so a whitespace-only id is rejected client-side — previously bare and undescribed in 8 of 14 modules) — reused across ports/previews/files/exec/ssh/snapshots/artifacts/sandboxes/volumes/sessions-admin, including the `session_ids` array in `tenki_terminate_sandboxes`; `portSchema` (1-65535 — `tenki_expose_port` previously accepted port 99999 and learned the constraint from a server error) — ports; `slugSchema` (3-63 chars, lowercase/digits/hyphens, no leading/trailing hyphen — matching the server's shared preview-slug validation, which `ExposePort` also applies) — ports/previews.
+- `tenki_git` accepts numbers and booleans as arg values (`depth: 1`, `create: true`) and coerces them to the strings the wire expects, instead of rejecting values that would serialize identically.
+- **Shared `pathSchema`** (trimmed, non-empty) across every file-path argument (read/write/list/stat/mkdir/remove/move/upload/mount) — an empty or whitespace-only path is rejected client-side instead of by a server error.
+- **`tenki_git` description documents a live-verified caveat:** checkout/diff/log run in the session's working directory and cannot target a repo cloned into a subdirectory (the API has no directory arg for them) — use `tenki_exec` with `git -C <dir> ...` for those until the API grows one. `clone` works as documented.
+- **README**: install forms for Claude Code (`claude mcp add`), Claude Desktop, and Cursor; a consolidated environment-variable table; auth precedence documented (`TENKI_AUTH_TOKEN` wins over `TENKI_API_KEY`); the Tools table no longer lists unsupported git operations.
+
+### Network-layer hardening (timeouts, retry policy, credential cache)
+
+- **Every fetch now carries a timeout** — a hung control- or data-plane connection, or a response whose body stalls after the headers arrive, fails the tool call with a clear `timed out after Nms` error naming the method instead of blocking it forever. Unary calls default to 30s; `ExecuteCommand` follows the command's own timeout + 30s margin (630s when the command has none). Tunable via `TenkiClient` options. Each call has ONE shared deadline: retries and backoff sleeps draw from it, so a call can never stack attempts past its timeout.
+- **Retry policy is shaped by double-apply risk, not by method naming.** Methods that must never run twice (`Create*`, `Build*`, `Publish*`, `Resume*`, `Extend*`, `ExecuteCommand`) never retry transient failures — a half-applied `CreateSession` retried could boot and bill a second sandbox. Everything else — reads AND teardown (`Terminate*`/`Delete*`/`Detach*`, where a repeat lands in the same state) — retries `unavailable`, gateway-shaped 502/503/504 (HTML/empty bodies from load balancers included), and transport-level failures (timeout, connection reset, DNS). Rate-limit rejections still retry for every method, with jittered backoff and `Retry-After` honored (capped at 30s).
+- **The data plane retries too.** Read-shaped data-plane methods (`ReadFile`/`Stat`/`List*`) — the path behind every file tool and how `tenki_exec` reads back its own output — now retry rate limits, transient/gateway errors, and transport failures under the same shared deadline. Write-shaped data methods surface failures immediately.
+- **Session-credential cache can no longer go permanently stale.** A credential whose expiry the API omits (or that fails to parse) was previously cached *forever* — once the cert actually expired, every file operation for that session failed for the life of the process. Now: missing expiry → 5-minute TTL; known expiry → refreshed 30s early (floored at 5s so a short-lived credential still caches; a credential already past its expiry is not cached at all); a stale-certificate failure (401/`unauthenticated`) invalidates the cached credential and retries once with a fresh one (never loops; `permission_denied` does NOT re-mint — a denied path is a user error a fresh cert can't fix); and minting is single-flight, so concurrent cold-cache calls share one mint.
+- New offline regression suite `test/client-net.test.mjs` (local `node:http` stub, zero external network) covering all of the above; wired into `npm test` and CI.
+
+### Structured tool output (first tool: `tenki_exec`)
+
+- **`tenki_exec` now declares an `outputSchema` and returns `structuredContent`**, so MCP clients can consume `stdout`/`stderr`/`exitCode`/`ok` as typed JSON instead of re-parsing a stringified blob. The SDK validates every successful result against the schema.
+- **`tenki_exec` returns two text blocks:** the serialized JSON result first (the MCP spec's backwards-compatibility contract for structured content — existing text-parsing consumers keep working), then a human-readable rendering headed by `exit <code>` and character-count markers. Characters that can misrepresent output in a terminal — C0/C1 controls, bidi overrides, zero-width marks — are escaped to visible `\xNN`/`\uNNNN` in the rendering (sandbox output is untrusted); `structuredContent` keeps the raw strings.
+- **Registration guard extended to `registerTool`** — the modern SDK registration API (required for `outputSchema`) now passes through the same least-privilege guard as the legacy `.tool()` form: name-derived annotations, `TENKI_MCP_READONLY`, `TENKI_MCP_DISABLED_TOOLS`, and `TENKI_MCP_AUDIT` all apply. Previously a module using `registerTool` would have silently bypassed all four.
+- **Behavior change:** `tenki_exec` / `tenki_run_code` results now report `ok: false` when the command ran but its output could not be read back (`captureError` set). Previously a capture failure with exit code 0 reported `ok: true` with empty stdout/stderr, which read as a clean silent success. `tenki_move_path` (exec-backed) is unaffected: its `ok` tracks the `mv` exit code, with any `captureError` surfaced separately.
+- An unparseable exit code from the API is normalized to `-1` so the run's output is still returned instead of failing schema validation.
+- Offline regression checks: `tenki_exec` advertises the schema, still carries guard annotations via the `registerTool` path, and exactly one tool declares an `outputSchema` (bump the count when migrating more tools). A new offline suite (`test/exec-output.test.mjs`) calls the tool in-memory and locks down the content blocks, escaping, output validation, and `tenki_move_path` semantics.
+
+### Fixed
+
+- **Path validation no longer rewrites the path.** `pathSchema` used zod's `.trim()`, which is a *transform*: leading/trailing whitespace (legal in POSIX filenames) was silently stripped before sending, so `tenki_remove_path`/`tenki_move_path` on such a file operated on a *different* path than the one named. Paths now reach the API verbatim, with blank/whitespace-only values still rejected client-side. `tenki_exec`'s `cwd` had the same trim and is fixed too. (`sessionIdSchema` keeps trimming: a session id is a UUID, so surrounding whitespace is always an accident.)
+- **Importing the package no longer terminates the importing process.** `main` pointed at the CLI entrypoint, whose token check runs at module load and calls `process.exit(1)` — so `import "tenki-mcp"` killed the host process outright (and with a token set, would have booted a stdio server inside it). The package is now bin-only: `npx tenki-mcp` and every MCP client config are unaffected (they resolve `bin`), and importing raises a catchable module-not-found error instead.
+- **A path or working directory beginning with a hyphen is no longer read as a command option.** Shell-quoting doesn't prevent it: `cd '-L'` silently succeeds into `$HOME`, so `tenki_exec` with such a `cwd` ran the command in the wrong directory, and `mv '-file' …` failed outright. Both now pass `--` before their operands.
+- **Sandbox creation was broken for workspace-scoped API keys.** `resolveOwner` forwarded WhoAmI's `ownerType` verbatim into `CreateSession`, but the API validates `owner_type ∈ {SERVICE, USER}` and now returns `WORKSPACE` for workspace-scoped keys → every `tenki_create_sandbox`/`tenki_run_code` failed with `400 invalid_argument`. Fix: send the same placeholder the first-party SDKs hardcode (`"SERVICE"`/`"self"`) when WhoAmI returns a type CreateSession rejects — the server derives the real owner from the authenticated identity regardless. Verified live: create → exec (structured) → terminate, 12/12 checks.
+- `test/http-transport.test.mjs` no longer asserts `ownerType === "USER"` (stale against the same API change); it accepts any authenticated owner type.
+
+## [2.0.0-alpha.2] — 2026-07-27 — MCP security hardening + registry fixes
+
+### MCP security hardening (least privilege + annotations)
+
+Applies MCP-native security controls, mapped to the CSA MCP Server Top-10 (esp. MCP-07 excessive permissions). See SECURITY.md.
+
+- **Tool annotations** on all 84 tools (`readOnlyHint` on 36 read tools, `destructiveHint` on the 13 delete/terminate/revoke tools, `openWorldHint` on all) so clients can surface/gate dangerous tools.
+- **Least-privilege env controls:** `TENKI_MCP_READONLY=1` registers only read tools (no create/run/delete/spend); `TENKI_MCP_DISABLED_TOOLS=a,b` drops named tools. Applied centrally via a registration guard — no change to the tool modules.
+- **Audit logging:** `TENKI_MCP_AUDIT=1` logs each tool call name + arg keys (never values/content/token) to stderr.
+- **SECURITY.md** — threat model, trust boundaries (the key + endpoint are capabilities; sandbox output is untrusted), and a full CSA Top-10 mapping. README security section + disclosure policy.
+- Regression test `test/security.test.mjs` (10 offline checks).
+
+### Registry/preview/artifact request-shape fixes
+
+An API-contract review of the write paths found **11 more request-shape bugs** beyond the two already fixed — the registry module was almost entirely non-functional (it sent `reference` where the API wants `ref` / `imageId` / `imageRef`). All fixed and verified (each now reaches a clean not-found instead of a validation error); regression-guarded by test/registry-shapes.test.mjs.
+
+- **registry** (9): `get_image`, `resolve_image_ref` (needs `ref`+`workspaceId`), `set_image_visibility` (needs `ref`+`REGISTRY_VISIBILITY_*` enum), `delete_image` (whole=`ref`; version=`imageId`+`snapshotId`), `share_image` (`imageRef`+`targetWorkspaceId`), `unshare_image` (`ref`), `revoke_image_share_grant` (`grantId`), `publish_image` (needs `ref`+`kind`+`snapshotId`/`sourceTemplateId`, not a session).
+- **previews** (1): `touch_preview` takes a `previewToken`, not session/port.
+- **artifacts** (1): `get_download_url` supports download-by-artifact-id only (the API rejects a path); the non-functional `path` option was removed.
+
+## [2.0.0-alpha.1] — 2026-07-21 — Harden the HTTP transport (security)
+
+An independent security review of the v2.0.0-alpha.0 HTTP transport found three coupled HIGH issues (the endpoint holds a shared TENKI_API_KEY and exposes code-execution + credit-spend tools). All fixed:
+
+- **Loopback-only by default** — binds `127.0.0.1`, not `0.0.0.0`; the banner now shows the real host. Expose with `TENKI_MCP_HTTP_HOST`.
+- **Bearer auth** — set `TENKI_MCP_HTTP_TOKEN` (constant-time checked); the server **refuses to bind to a non-loopback host without it**.
+- **DNS-rebinding protection ON** — Host-header allowlist, so a malicious web page cannot drive the local server (verified: forged Host → 403).
+
+Also: session count cap + idle reaping (init-flood DoS), a 1 MiB request-body cap enforced on both the Content-Length header and the streamed byte count (memory DoS), malformed JSON → JSON-RPC `-32700`/400, no internals in error responses, and SIGTERM/SIGINT graceful shutdown. Offline regression `test/http-input.test.mjs` asserts the 413 + a clean init; `test/http-transport.test.mjs` asserts the auth gate + rebinding rejection (7/7). stdio + tool parity unchanged (84).
+
+## [2.0.0-alpha.0] — 2026-07-21 — HTTP transport (v2 begins)
+
+The server now speaks **Streamable HTTP** in addition to stdio, so it can be hosted for remote MCP clients (`TENKI_MCP_TRANSPORT=http PORT=3000`). Verified end-to-end (connect → tools/list → tool call over HTTP; stdio unchanged, 84 tools). Server construction refactored into a shared `createServer()` factory (src/server.ts) used by both transports.
+
+Streaming exec (`StreamCommandOutput`) and per-request HTTP auth are not yet implemented. Alpha: not for production hosting yet.
+
+## [1.0.2] — 2026-07-21 — Fixes from comprehensive testing
+
+A 34-scenario test matrix run against live Tenki found **two real request-shape bugs**, both fixed and verified end-to-end:
+
+- **tenki_attach_volume** sent a flat request; AttachVolumeRequest nests the target under a `volume` sub-message (`{sessionId, volume:{volumeId, mountPath, readOnly?}}`). Every attach was rejected — this broke the volume warm-cache workflow. Fixed.
+- **tenki_list_image_share_grants** sent `reference`; the API field is `ref` (required). It was silently ignored, 400-ing every call and making the ACL-read surface unreachable. Fixed.
+
+Also: a real MCP **test suite** (`test/`) — a cleanup-safe harness driving the actual MCP protocol + 5 suites (coverage, client-integration, errors-edge, journeys, admin-previews) — **68 checks, all green**. Doc fixes (workspace tool names; create_template setup_script). No tool count change (84).
+
+## [1.0.1] — 2026-07-20 — Fix ResizeVolume field
+
+Live-verifying the volume write path (once a workspace volume-quota block was cleared) surfaced one real bug: `tenki_resize_volume` sent `sizeBytes` but the API expects `newSizeBytes`, so resizes were rejected. Fixed. Full volume lifecycle (create → get → update → resize → delete) now live-verified end-to-end.
+
+## [1.0.0] — 2026-07-20 — Full CLI parity
+
+**84 tools — parity with the entire Tenki unary API**, enforced by a CI parity audit (scripts/parity-audit.mjs fails the build if any SandboxService / DataPlane / SSHGateway method lacks a tool; streaming methods are deferred to v2.0). This release closes the long tail on top of v0.7: binary artifact transfer (get_upload_url / get_download_url), SSH access (update_ssh_keys / issue_ssh_cert / list_ssh_gateways), the preview-URL primitives (get/delete/touch/bind/unbind/resolve), project-scoped list variants (volumes/snapshots/templates), snapshot-retention settings, and registry grant-revoke. New read paths live-verified against api.tenki.cloud; write/advanced additions are grounded in the published API surface and labeled where not exercised end-to-end.
+
+**Tools:** +18 to reach 84 (artifacts x2, ssh x3, preview extras x6, list variants x4, retention x2, revoke-grant x1)
+
+## [0.7.0] — 2026-07-20 — Workspace administration
+
+Workspace-level administration: sandbox usage reporting and get/update of workspace sandbox settings. Live-verified.
+
+**Tools:** tenki_get_workspace_usage, tenki_get_workspace_settings, tenki_update_workspace_settings
+
+## [0.6.0] — 2026-07-20 — Custom runtimes — templates & registry
+
+Bring-your-own-runtime: define an environment once and boot into it warm. Templates add the platform's first async job surface (build, poll, cancel). The registry publishes versioned custom images with a private-by-default ACL surface. List paths live-verified.
+
+**Tools:** 9 template tools (create/get/list/update/delete + build/cancel-build/get-build/list-active-builds) + 9 registry tools (publish/get/list/set-visibility/delete/delete-version/resolve-ref/share/list-share-grants)
+
+## [0.5.0] — 2026-07-20 — Persistent state — snapshots & volumes
+
+Persistent state for the iterative agent loop. Snapshots checkpoint a known-good sandbox to branch or roll back from; volumes are durable disks that carry a cache or dataset across otherwise-ephemeral sandboxes. Destructive verbs are explicit-target-only. Snapshots live-verified; volume shapes verified against the SDK (write path blocked only by a workspace volume quota during testing).
+
+**Tools:** 8 snapshot tools + 8 volume tools (create/get/list/update/delete/resize/attach/detach)
+
+## [0.4.0] — 2026-07-20 — Preview URLs — the ship surface
+
+The ship surface: turn an exposed port into a public, shareable preview URL an agent can hand back. Project-scoped (live-verified: requires projectId + a validated slug). Completes the ports resource with unexpose.
+
+**Tools:** tenki_create_preview_url, tenki_open_preview, tenki_list_preview_urls, tenki_unexpose_port
+
+## [0.3.0] — 2026-07-20 — Session lifecycle & fleet control
+
+Extended session control: extend a sandbox's wall-clock lifetime, update mutable fields (name/tags/idle-timeout/max-duration), bulk-terminate (explicit-id-only, irreversible), an activity heartbeat, and workspace/project-scoped fleet listing. Live-verified.
+
+**Tools:** tenki_extend_sandbox, tenki_update_sandbox, tenki_terminate_sandboxes, tenki_report_sandbox_activity, tenki_list_workspace_sandboxes, tenki_list_project_sandboxes
+
+## [0.2.0] — 2026-07-20 — Filesystem completion (data plane)
+
+Data-plane filesystem metadata + mutation, completing the file surface beyond read/write/list: stat, mkdir (recursive), remove (recursive), and move (exec-backed mv, since the data plane exposes no Move RPC). Live-verified against api.tenki.cloud.
+
+**Tools:** tenki_stat_path, tenki_make_dir, tenki_remove_path, tenki_move_path
+
+## [0.1.0] — 2026-07-20
+Initial release. **15 MCP tools over stdio, live-verified against `api.tenki.cloud`.**
+
+- `tenki_whoami`
+- `tenki_run_code` — ephemeral sandbox: boot → run shell/python/javascript → terminate
+- Sandbox lifecycle: `tenki_create_sandbox`, `tenki_get_sandbox`, `tenki_list_sandboxes`, `tenki_terminate_sandbox`, `tenki_pause_sandbox`, `tenki_resume_sandbox`
+- `tenki_exec` — run a command in a sandbox (stdout/stderr/exit inline)
+- Files: `tenki_read_file`, `tenki_write_file`, `tenki_list_files`
+- `tenki_git`
+- Ports: `tenki_expose_port`, `tenki_list_exposed_ports`
+
+Dependency-free ConnectRPC client (control + data plane), ported from the live-verified [n8n node](https://github.com/opencolin/n8n-nodes-tenki). Tools organized into self-registering modules under `src/tools/`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tenki Cloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# tenki-mcp — `@tenkicloud/mcp`
+
+**A [Model Context Protocol](https://modelcontextprotocol.io) server for [Tenki Cloud](https://tenki.cloud).** Give any agent — Claude, Codex, Cursor — a disposable microVM it can create, run code in, read and write files, run git, and expose to the web. Sandboxes boot in ~2 seconds and are billed per second.
+
+Part of making Tenki the execution layer coding agents reach for: the agent writes code and Tenki runs it in isolation. (Tenki's **Code Reviewer** and **Runners** — AI PR review and managed CI — are separate products; this server currently exposes the Sandbox.)
+
+```
+"Run this Python in a fresh sandbox and tell me what it prints."
+        │
+        ▼   tenki_run_code
+   boots a microVM → runs it → returns stdout → tears it down
+```
+
+## Quickstart
+
+```bash
+export TENKI_API_KEY=tk_your_key_here
+npx -y @tenkicloud/mcp     # speaks MCP over stdio
+```
+
+Nothing to clone or build. The package installs one command, `tenki-mcp`.
+
+> **Heads up — pending first npm publish.** Until `@tenkicloud/mcp` lands on npm, use [Run it from a clone](#run-it-from-a-clone-instead) below. Every `npx -y @tenkicloud/mcp` form here activates the moment it's published.
+
+### Use it in Claude Code
+
+```bash
+claude mcp add tenki --env TENKI_API_KEY=tk_your_key_here -- npx -y @tenkicloud/mcp
+```
+
+### Use it in Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "tenki": {
+      "command": "npx",
+      "args": ["-y", "@tenkicloud/mcp"],
+      "env": { "TENKI_API_KEY": "tk_your_key_here" }
+    }
+  }
+}
+```
+
+### Use it in Cursor
+
+Add the same block to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "tenki": {
+      "command": "npx",
+      "args": ["-y", "@tenkicloud/mcp"],
+      "env": { "TENKI_API_KEY": "tk_your_key_here" }
+    }
+  }
+}
+```
+
+### Use it in Codex
+
+The OpenAI Codex CLI reads MCP servers from `~/.codex/config.toml`. Add:
+
+```toml
+[mcp_servers.tenki]
+command = "npx"
+args = ["-y", "@tenkicloud/mcp"]
+env = { TENKI_API_KEY = "tk_your_key_here" }
+```
+
+### Confirm it's working
+
+After adding the server, **start a fresh session** so the client loads it, then ask your agent one of:
+
+- *"Check tenki auth status."* — confirms your credential was picked up.
+- *"Run `print(2+2)` in a fresh Tenki sandbox."* — a full boot → run → teardown round-trip.
+
+If the `tenki_*` tools don't show up, restart the client so it re-reads its config.
+
+No key yet? Start the server without one and ask the agent to check `tenki_auth_status` — it reports what to set and where. See [Auth](#auth).
+
+### Run it from a clone instead
+
+For development, or to run an unreleased change:
+
+```bash
+git clone https://github.com/LuxorLabs/tenki-mcp.git && cd tenki-mcp
+npm install && npm run build
+TENKI_API_KEY=tk_your_key_here node dist/index.js
+```
+
+Substitute `node /absolute/path/to/tenki-mcp/dist/index.js` for the `npx` command in any of the configs above. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development loop.
+
+### Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `TENKI_API_KEY` | — | API key (`tk_…`). One of this or `TENKI_AUTH_TOKEN` is required. |
+| `TENKI_AUTH_TOKEN` | — | Session token (`ory_st_…` or cookie value). **Takes precedence over `TENKI_API_KEY`** when both are set. |
+| `TENKI_API_ENDPOINT` | `https://api.tenki.cloud` | Control-plane base URL (`TENKI_API_URL` is an alias). |
+| `TENKI_MCP_READONLY` | off | `1` registers only read tools (no create/run/delete/spend). |
+| `TENKI_MCP_DISABLED_TOOLS` | — | Comma-separated tool names to skip registering. |
+| `TENKI_MCP_AUDIT` | off | `1` logs each tool call name + arg keys to stderr. |
+| `TENKI_MCP_TRANSPORT` | `stdio` | `http` serves Streamable HTTP instead (see below). |
+| `PORT` | `3000` | HTTP transport port. |
+| `TENKI_MCP_HTTP_HOST` | `127.0.0.1` | HTTP bind host; non-loopback requires `TENKI_MCP_HTTP_TOKEN`. |
+| `TENKI_MCP_HTTP_TOKEN` | — | Bearer token for the HTTP endpoint; optional on loopback, required on a non-loopback host. |
+
+## Tools
+
+**85 tools** — 84 with full parity to the Tenki unary API (enforced by a CI [parity audit](scripts/parity-audit.mjs)), plus `tenki_auth_status`. Grouped by domain:
+
+| Domain | Tools |
+|---|---|
+| **Auth** | `tenki_auth_status` (which credential is configured, and does it work — the only tool available when none is) |
+| **Identity** | `tenki_whoami` |
+| **Run** | `tenki_run_code` (one-shot: boot → run shell/python/js → tear down) |
+| **Sandboxes** | `tenki_create_sandbox` · `tenki_get_sandbox` · `tenki_list_sandboxes` · `tenki_terminate_sandbox` · `tenki_pause_sandbox` · `tenki_resume_sandbox` |
+| **Session admin** | `tenki_extend_sandbox` · `tenki_update_sandbox` · `tenki_terminate_sandboxes` (bulk) · `tenki_report_sandbox_activity` · `tenki_list_workspace_sandboxes` · `tenki_list_project_sandboxes` |
+| **Exec** | `tenki_exec` (stdout/stderr/exit inline) |
+| **Files** | `tenki_read_file` · `tenki_write_file` · `tenki_list_files` · `tenki_stat_path` · `tenki_make_dir` · `tenki_remove_path` · `tenki_move_path` |
+| **Git** | `tenki_git` (clone/checkout/diff/log — the API supports exactly these four; run other git commands via `tenki_exec`) |
+| **Ports & previews** | expose · list-exposed · unexpose · create-preview-url · open-preview · list/get/delete-preview-url · touch-preview · bind/unbind-preview-url · resolve-preview-token |
+| **Artifacts** (binary transfer) | `tenki_get_upload_url` · `tenki_get_download_url` (signed URLs for binary PUT/GET) |
+| **SSH** | `tenki_update_ssh_keys` · `tenki_issue_ssh_cert` · `tenki_list_ssh_gateways` |
+| **Snapshots** | create · get · list · list-session · list-project · list-workspace · list-dangling · update · delete · get-download-url |
+| **Volumes** | create · get · list · list-project · update · delete · resize · attach · detach |
+| **Templates** | create · get · list · list-project · update · delete · build · cancel-build · get-build · list-active-builds |
+| **Registry** (custom images) | publish · get · list · set-visibility · delete · resolve-ref · share · unshare · list-share-grants · revoke-share-grant |
+| **Workspace** | `tenki_get_workspace_usage` · `tenki_get_workspace_settings` · `tenki_update_workspace_settings` · `tenki_get_snapshot_retention_settings` · `tenki_update_snapshot_retention_settings` |
+
+Full per-release breakdown in [CHANGELOG.md](CHANGELOG.md).
+
+## Auth
+
+Set one of `TENKI_API_KEY` or `TENKI_AUTH_TOKEN` — when both are set, `TENKI_AUTH_TOKEN` wins. The header is chosen by token prefix: `tk_…` → `Authorization: Bearer`, `ory_st_…` → `X-Session-Token`, otherwise a session cookie. Override the endpoint with `TENKI_API_ENDPOINT` (default `https://api.tenki.cloud`).
+
+**Without a credential the server still starts**, registering only `tenki_auth_status` — so instead of an MCP client reporting an opaque "server failed to start", the agent can call that tool and get told what to set. Ask it "check tenki auth status" any time other tools return auth errors: it reports the credential kind (API key vs session token), the endpoint, and whether a live identity probe succeeded — never the token itself. It reports status only; get a credential with `tenki login` or from the dashboard.
+
+## Host it over HTTP (v2.0-beta)
+
+Besides stdio, the server speaks **Streamable HTTP** so it can be hosted for remote MCP clients:
+
+```bash
+TENKI_MCP_TRANSPORT=http PORT=3000 TENKI_API_KEY=… npx -y @tenkicloud/mcp
+# → tenki-mcp running on http://127.0.0.1:3000/mcp (Streamable HTTP) [loopback only, no auth]
+```
+
+**Security — this endpoint is a capability.** In HTTP mode the process holds one shared `TENKI_API_KEY` and exposes every tool, including arbitrary code execution and credit spend. So by default it:
+
+- **binds to loopback (`127.0.0.1`) only** — set `TENKI_MCP_HTTP_HOST=0.0.0.0` to expose it, but then
+- it **requires a bearer token**: set `TENKI_MCP_HTTP_TOKEN` and send `Authorization: Bearer <token>`. It **refuses to start** on a non-loopback host without one.
+- **DNS-rebinding protection** is on (Host-header allowlist), so a malicious web page can't drive your local server.
+
+```bash
+# expose to a network safely:
+TENKI_MCP_TRANSPORT=http TENKI_MCP_HTTP_HOST=0.0.0.0 PORT=3000 \
+  TENKI_MCP_HTTP_TOKEN=$(openssl rand -hex 32) TENKI_API_KEY=… npx -y @tenkicloud/mcp
+```
+
+Point an HTTP-capable MCP client at `/mcp`. v2.0-beta uses one shared `TENKI_API_KEY` for all sessions; per-request auth (multi-tenant hosting) is not yet implemented. Verified end-to-end (`test/http-transport.test.mjs`: auth gate, DNS-rebinding rejection, connect → tools/list → tool call over HTTP).
+
+## How it works
+
+Tenki's API is **ConnectRPC** — JSON over HTTP/1.1, not REST. Every control-plane call is `POST https://api.tenki.cloud/tenki.sandbox.v1.SandboxService/{Method}` with a lowerCamelCase JSON body. Per-session file I/O runs on a **separate data-plane endpoint** returned at create time, authenticated with a short-lived session certificate. This server owns both transports so the tools stay one-liners.
+
+Command output: `tenki_exec` and `tenki_run_code` capture `stdout`/`stderr` by redirecting to files (`sh -c '… > out 2> err'`) and reading them back over the data plane, so you get the output inline through a plain HTTP client.
+
+The wire details are ported from the live-verified [n8n community node](https://github.com/opencolin/n8n-nodes-tenki).
+
+## Security
+
+This server holds a Tenki API key and can run code + spend credits, so treat it as a capability. Full model + [CSA MCP Server Top-10](https://modelcontextprotocol-security.io/top10/server/) mapping in **[SECURITY.md](SECURITY.md)**. Quick controls:
+
+- **Least privilege:** every tool carries MCP annotations (`readOnlyHint` / `destructiveHint`). Run `TENKI_MCP_READONLY=1` for an inspection-only server (read tools only), or `TENKI_MCP_DISABLED_TOOLS=tenki_run_code,…` to drop specific tools.
+- **HTTP transport** is loopback-only by default and requires a bearer token to expose to a network (see [Host it over HTTP](#host-it-over-http-v20-beta)).
+- **Audit:** `TENKI_MCP_AUDIT=1` logs each tool call's name to stderr.
+- **Untrusted output:** `tenki_run_code`/`tenki_exec`/`tenki_read_file` return output from untrusted code — clients should treat tool results as data, not instructions.
+
+Report vulnerabilities via a private [security advisory](https://github.com/LuxorLabs/tenki-mcp/security/advisories/new), not a public issue.
+
+## Related
+
+- **Tenki Sandbox** — the platform: https://tenki.cloud
+- **n8n-nodes-tenki** — Tenki as an n8n node: https://github.com/opencolin/n8n-nodes-tenki
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,50 @@
+# Security
+
+`tenki-mcp` gives an AI agent a capability: a disposable microVM it can create, run code in, and spend Tenki credits with. Treat the server — and the API key it holds — accordingly. This document is the threat model and the controls, mapped to the [CSA MCP Server Top 10](https://modelcontextprotocol-security.io/top10/server/).
+
+## Reporting a vulnerability
+Please **do not** open a public issue for security reports. Open a private [GitHub security advisory](https://github.com/LuxorLabs/tenki-mcp/security/advisories/new), or email **hello@luxor.tech**. We'll acknowledge within a few business days.
+
+## Trust boundaries (read this first)
+- **The API key is a capability.** In every mode the process authenticates to Tenki with one `TENKI_API_KEY` and can create sandboxes, run arbitrary code, and spend credits. Anyone who can invoke the server can do those things. Scope the key if your Tenki plan allows it; never commit it (`.env` is gitignored).
+- **Sandbox output is untrusted.** `tenki_run_code` / `tenki_exec` / `tenki_read_file` return output produced by *untrusted, AI-generated code running in the sandbox*. That output flows back to the calling model as a tool result — a classic **indirect / output prompt-injection** vector. The microVM is the isolation boundary; the model should treat tool results as **data, not instructions**. (MCP clients are responsible for not executing instructions found in tool output.)
+- **The HTTP endpoint is a capability.** In HTTP mode the `/mcp` endpoint is equivalent to handing out the key — protect it (below).
+
+## Controls this server provides
+
+### Least privilege (MCP-07 — the main lever)
+Every tool is tagged with MCP **annotations** so clients can surface/gate danger:
+`readOnlyHint` on inspection tools, `destructiveHint` on the 13 that delete/terminate/revoke, `openWorldHint` on all (they call an external API). Plus two env controls:
+
+| Env | Effect |
+|---|---|
+| `TENKI_MCP_READONLY=1` | Register **only read-only tools** — no create, run, spend, or delete. For inspection-only deployments. |
+| `TENKI_MCP_DISABLED_TOOLS=a,b,c` | Skip the named tools (e.g. disable `tenki_run_code` where code execution isn't wanted). |
+
+Grant the smallest set that the use case needs.
+
+### Transport security (MCP-05, MCP-10)
+- **stdio** (default) has no network surface.
+- **HTTP** (`TENKI_MCP_TRANSPORT=http`) binds **loopback-only** by default, **requires a bearer token** to bind to a non-loopback host, has **DNS-rebinding protection**, and caps sessions + body size. For network exposure put it behind a **TLS-terminating proxy**. (Hardening details in the transport module, `src/http.ts`.)
+
+### Secrets & audit (MCP-04, Observability)
+- The key is read from env and sent only as an auth header — never logged, never in error responses.
+- `TENKI_MCP_AUDIT=1` logs each tool call's **name + argument keys** to stderr (never values, content, or the token) for an operator audit trail.
+
+## CSA MCP Server Top-10 mapping
+
+| # | Risk | tenki-mcp posture |
+|---|---|---|
+| MCP-01 | Prompt Injection | zod-validates every tool arg pre-network; **sandbox output is untrusted** (treat tool results as data) |
+| MCP-02 | Confused Deputy | single shared key; HTTP endpoint requires its own bearer token; `READONLY`/denylist bound the blast radius; per-request auth is not yet implemented |
+| MCP-03 | Tool Poisoning | tool descriptions are static and authored (no dynamic/remote descriptions); verify the package via its npm provenance attestation (published from GitHub Actions, linking each release to its source commit) + MCP-registry namespace ownership |
+| MCP-04 | Credential/Token Exposure | key via env only; never logged/committed/echoed; audit logs keys not values |
+| MCP-05 | Insecure Configuration | HTTP transport is loopback + token + DNS-rebinding-protected + DoS-capped by default |
+| MCP-06 | Supply Chain | 2 direct runtime deps (`@modelcontextprotocol/sdk`, `zod`) — ~91 transitive, nearly all via the MCP SDK; lockfile committed; released only from CI with npm provenance, Actions pinned to commit SHAs |
+| MCP-07 | Excessive Permissions | tool annotations + `TENKI_MCP_READONLY` + `TENKI_MCP_DISABLED_TOOLS` |
+| MCP-08 | Data Exfiltration | microVM isolation; sandbox **outbound networking is off unless `allow_outbound` is set**; the server itself stores/forwards nothing |
+| MCP-09 | Context Spoofing | tool results are raw API/sandbox output surfaced as data, not merged into instructions |
+| MCP-10 | Insecure Communication | control plane is HTTPS; run the HTTP transport behind TLS for any non-loopback use |
+
+## Cost / resource notes
+`tenki_run_code` is cost-guarded (1 vCPU, 1 GB, 10-min cap, 5-min idle) and self-terminates. `tenki_create_sandbox` and other create tools **spend real credits** — bound them with your **Tenki workspace limits**, `TENKI_MCP_READONLY`/denylist, and `TENKI_MCP_AUDIT` for visibility.

package/dist/client.d.ts

@@ -0,0 +1,152 @@
+/**
+ * TenkiClient — a dependency-free client for the Tenki Cloud API.
+ *
+ * Tenki's API is ConnectRPC (JSON over HTTP/1.1), not REST. Every control-plane
+ * call is `POST {baseUrl}/tenki.sandbox.v1.SandboxService/{Method}` with a
+ * lowerCamelCase JSON body and a JSON response. Per-session file I/O runs on a
+ * separate data-plane endpoint returned at session-create time, authenticated
+ * with a short-lived session certificate.
+ *
+ * The wire details here (headers, the control/data-plane split, and capturing
+ * command stdout/stderr via an `sh -c` redirect + data-plane ReadFile) are
+ * ported from the live-verified n8n community node
+ * (github.com/opencolin/n8n-nodes-tenki).
+ */
+export type Language = "shell" | "python" | "javascript";
+export interface ExecResult {
+    command: string;
+    args: string[];
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    ok: boolean;
+    captureError?: string;
+}
+export interface TenkiClientOptions {
+    /** Timeout for unary control/data-plane calls (default 30s). */
+    timeoutMs?: number;
+    /** Timeout for ExecuteCommand when the command itself has no timeout (default 630s). */
+    execTimeoutMs?: number;
+    /** Timeout for long storage/VM operations — see SLOW_METHOD (default 600s). */
+    slowTimeoutMs?: number;
+    /** Assumed session-credential lifetime when the API returns no parseable expiry (default 5min). */
+    credTtlMs?: number;
+}
+export declare class TenkiClient {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly credCache;
+    private readonly credInflight;
+    private readonly timeoutMs;
+    private readonly execTimeoutMs;
+    private readonly slowTimeoutMs;
+    private readonly credTtlMs;
+    constructor(token: string, baseUrl?: string, opts?: TenkiClientOptions);
+    /**
+     * ExecuteCommand blocks until the command finishes, so its timeout follows
+     * the command's own timeout (plus margin) instead of the unary default.
+     */
+    private timeoutFor;
+    /**
+     * fetch + full body read under ONE timeout, with a readable error instead of
+     * a bare AbortError. Reading the body inside the guarded section matters: a
+     * response whose headers arrive but whose body stalls must fail with the
+     * same friendly, retryable timeout as a connection that never responds.
+     */
+    private fetchTextWithTimeout;
+    /**
+     * Retry policy: rate limits always; `unavailable` and gateway-shaped
+     * 502/503/504 (load balancers and CDNs return these with an HTML or empty
+     * body, no ConnectRPC code) for every method that cannot double-apply.
+     */
+    private shouldRetry;
+    /** Exponential backoff with half-jitter; a Retry-After header (seconds) wins, capped. */
+    private backoffMs;
+    /**
+     * Unary control-plane call. The WHOLE call — every attempt plus every
+     * backoff sleep — draws from one shared deadline (the method's timeout), so
+     * retries can never stack past it: an MCP client's own 60s default would
+     * otherwise give up before our per-attempt timeouts did. Rate-limit
+     * rejections retry with jittered backoff (honoring Retry-After); transient
+     * `unavailable`/gateway errors AND transport-level failures (timeout,
+     * connection reset, DNS) retry for every method that cannot double-apply.
+     * `service` defaults to SandboxService; pass another fully-qualified ConnectRPC
+     * service (e.g. the SSH gateway service) for methods hosted elsewhere.
+     */
+    control(method: string, body?: Record<string, unknown>, service?: string): Promise<Record<string, any>>;
+    /**
+     * Mint (and cache per session) the data-plane endpoint + session certificate.
+     * A credential with no parseable expiry is cached for credTtlMs — never
+     * forever — and a known expiry is shortened by a skew so an in-flight call
+     * can't straddle the real expiry. Minting is single-flight: concurrent data
+     * calls on a cold cache share one mint instead of each paying a
+     * control-plane round trip for its own certificate.
+     */
+    private credentialFor;
+    private mintCredential;
+    /**
+     * Unary data-plane call. The inner request is wrapped as
+     * `{ request: { sessionId, ...request } }`. This is the path behind every
+     * file tool AND how tenki_exec reads back its own output, so it gets the
+     * same treatment as the control plane: one shared deadline, rate limits
+     * retried for every method, transient/gateway/transport failures retried
+     * for read-shaped methods. A stale-certificate failure (401/unauthenticated
+     * — the cert may have expired server-side regardless of its stated expiry)
+     * invalidates the cache and re-mints once; permission_denied is NOT an auth
+     * failure — a denied path is a normal user error a fresh cert can never
+     * fix, so re-minting would waste a control-plane round trip per denied call.
+     */
+    data(sessionId: string, method: string, request?: Record<string, unknown>): Promise<Record<string, any>>;
+    /**
+     * Resolve the calling identity + a default workspace/project for CreateSession
+     * (which requires a projectId). Picks the first workspace that has a project so
+     * the (workspace, project) pair stays consistent.
+     *
+     * CreateSession validates owner_type ∈ {SERVICE, USER} and requires a
+     * non-empty owner_id, but derives the real owner from the authenticated
+     * identity server-side. WhoAmI can return other owner types (e.g. WORKSPACE
+     * for workspace-scoped keys), which the validator rejects — so for those we
+     * send the same placeholder the first-party SDKs hardcode ("SERVICE"/"self").
+     */
+    resolveOwner(): Promise<{
+        ownerType?: string;
+        ownerId?: string;
+        workspaceId?: string;
+        projectId?: string;
+    }>;
+    /** Poll GetSession until it reaches (or passes into) the target state. */
+    waitForState(sessionId: string, target?: string, { timeoutMs, intervalMs }?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<Record<string, any>>;
+    readTextFile(sessionId: string, path: string): Promise<string>;
+    writeTextFile(sessionId: string, path: string, text: string): Promise<Record<string, any>>;
+    /**
+     * Run a command in a session and return stdout/stderr inline.
+     *
+     * We wrap the command in `sh -c '<cmd> > out 2> err'`, then read the capture
+     * files back over the data plane, so output is available through a plain-HTTP
+     * client. Capture-read failures degrade gracefully into `captureError` rather
+     * than losing the run — but the result is marked NOT ok, because empty
+     * stdout/stderr next to a zero exit code would otherwise read as a clean,
+     * silent success.
+     */
+    execCaptured(sessionId: string, command: string, opts?: {
+        args?: string[];
+        cwd?: string;
+        env?: Record<string, string>;
+        timeoutSeconds?: number;
+    }): Promise<ExecResult>;
+    /**
+     * One-shot: boot a throwaway sandbox, run code (shell / python / javascript),
+     * return its output, and terminate the sandbox. Cost-guarded (1 vCPU, 1 GB,
+     * 10-min cap, 5-min idle) so an ephemeral run can never leak a billing session.
+     */
+    runCode(language: Language, code: string, opts?: {
+        env?: Record<string, string>;
+        timeoutSeconds?: number;
+    }): Promise<ExecResult & {
+        sessionId: string;
+        language: Language;
+    }>;
+}