@luxorai/mcp 0.0.0-stage → 0.3.1

package/dist/http.js

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/oauth.d.ts

@@ -0,0 +1,33 @@
+import type http from "node:http";
+export interface OAuthConfig {
+    issuer: string;
+    resource: string;
+    publicUrl: string;
+    metadataUrl: string;
+    identityUrl: string;
+    identityServiceToken: string;
+    scope: string;
+}
+export interface DelegatedAuthorization {
+    tokenDigest: string;
+    subject: string;
+    workspaceId: string;
+    clientId: string;
+    scope: string[];
+    expiresAt?: number;
+    apiDelegationToken: string;
+}
+export declare function loadOAuthConfig(): OAuthConfig | null;
+export declare class OAuthTokenVerifier {
+    private readonly config;
+    private readonly cache;
+    constructor(config: OAuthConfig);
+    verify(token: string): Promise<DelegatedAuthorization | null>;
+}
+export declare class OAuthResourceRoutes {
+    private readonly config;
+    constructor(config: OAuthConfig);
+    handle(_req: http.IncomingMessage, res: http.ServerResponse, url: URL): Promise<boolean>;
+}
+export declare function bearerToken(header: string | undefined): string | null;
+export declare function authorizationBinding(authorization: DelegatedAuthorization): string;

package/dist/oauth.js

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto";
+const DEFAULT_SCOPE = "mcp";
+const FETCH_TIMEOUT_MS = 8_000;
+const TOKEN_CACHE_MS = 15_000;
+const EXCHANGE_PROCEDURE = "/tenki.cloud.identity.private.v1beta1.IdentityPrivateService/ExchangeMcpOAuthToken";
+function trimUrl(value) {
+    return value.trim().replace(/\/+$/, "");
+}
+export function loadOAuthConfig() {
+    const issuer = trimUrl(process.env.TENKI_MCP_OAUTH_ISSUER || "");
+    const identityUrl = trimUrl(process.env.TENKI_MCP_IDENTITY_URL || "");
+    const identityServiceToken = (process.env.TENKI_MCP_IDENTITY_SERVICE_TOKEN || "").trim();
+    const publicUrl = trimUrl(process.env.TENKI_MCP_PUBLIC_URL || "");
+    if (!issuer && !identityUrl && !identityServiceToken && !publicUrl)
+        return null;
+    if (!issuer || !identityUrl || !identityServiceToken || !publicUrl) {
+        throw new Error("TENKI_MCP_OAUTH_ISSUER, TENKI_MCP_IDENTITY_URL, TENKI_MCP_IDENTITY_SERVICE_TOKEN, and TENKI_MCP_PUBLIC_URL must be set together.");
+    }
+    const resource = trimUrl(process.env.TENKI_MCP_OAUTH_RESOURCE || `${publicUrl}/mcp`);
+    return {
+        issuer,
+        resource,
+        publicUrl,
+        metadataUrl: `${publicUrl}/.well-known/oauth-protected-resource/mcp`,
+        identityUrl,
+        identityServiceToken,
+        scope: (process.env.TENKI_MCP_OAUTH_SCOPE || DEFAULT_SCOPE).trim(),
+    };
+}
+function tokenDigest(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+async function fetchJson(url, init = {}) {
+    const response = await fetch(url, { ...init, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    const text = await response.text();
+    let body = {};
+    try {
+        body = text ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new Error(`upstream returned non-JSON HTTP ${response.status}`);
+    }
+    if (!response.ok)
+        throw new Error(`upstream returned HTTP ${response.status}`);
+    return body;
+}
+export class OAuthTokenVerifier {
+    config;
+    cache = new Map();
+    constructor(config) {
+        this.config = config;
+    }
+    async verify(token) {
+        const digest = tokenDigest(token);
+        const cached = this.cache.get(digest);
+        if (cached && cached.cachedUntil > Date.now())
+            return cached.authorization;
+        let body;
+        try {
+            body = await fetchJson(`${this.config.identityUrl}${EXCHANGE_PROCEDURE}`, {
+                method: "POST",
+                headers: {
+                    "X-Service-Token": this.config.identityServiceToken,
+                    "Content-Type": "application/json",
+                    "Connect-Protocol-Version": "1",
+                },
+                body: JSON.stringify({ accessToken: token }),
+            });
+        }
+        catch {
+            return null;
+        }
+        const subject = typeof body.subject === "string" ? body.subject.trim() : "";
+        const workspaceId = typeof body.workspaceId === "string" ? body.workspaceId.trim() : "";
+        const clientId = typeof body.clientId === "string" ? body.clientId.trim() : "";
+        const apiDelegationToken = typeof body.apiDelegationToken === "string" ? body.apiDelegationToken.trim() : "";
+        const scope = stringArray(body.scopes);
+        const expiresAtUnix = Number(body.expiresAtUnix);
+        const expiresAt = Number.isFinite(expiresAtUnix) ? expiresAtUnix * 1000 : undefined;
+        if (!subject ||
+            !workspaceId ||
+            !clientId ||
+            !apiDelegationToken ||
+            !scope.includes(this.config.scope) ||
+            (expiresAt !== undefined && expiresAt <= Date.now())) {
+            return null;
+        }
+        const authorization = {
+            tokenDigest: digest,
+            subject,
+            workspaceId,
+            clientId,
+            scope,
+            ...(expiresAt !== undefined ? { expiresAt } : {}),
+            apiDelegationToken,
+        };
+        this.cache.set(digest, {
+            authorization,
+            cachedUntil: Math.min(Date.now() + TOKEN_CACHE_MS, expiresAt ?? Number.POSITIVE_INFINITY),
+        });
+        return authorization;
+    }
+}
+function json(res, status, body) {
+    res.writeHead(status, {
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store",
+        Pragma: "no-cache",
+    });
+    res.end(JSON.stringify(body));
+}
+export class OAuthResourceRoutes {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async handle(_req, res, url) {
+        if (url.pathname === "/.well-known/oauth-protected-resource/mcp" || url.pathname === "/.well-known/oauth-protected-resource") {
+            json(res, 200, {
+                resource: this.config.resource,
+                authorization_servers: [this.config.issuer],
+                scopes_supported: [this.config.scope, "offline_access"],
+                bearer_methods_supported: ["header"],
+                resource_name: "Tenki MCP",
+            });
+            return true;
+        }
+        if (url.pathname === "/healthz") {
+            json(res, 200, { status: "ok" });
+            return true;
+        }
+        return false;
+    }
+}
+export function bearerToken(header) {
+    const match = /^Bearer (.+)$/.exec(header ?? "");
+    return match?.[1]?.trim() || null;
+}
+export function authorizationBinding(authorization) {
+    return createHash("sha256")
+        .update(JSON.stringify([authorization.subject, authorization.workspaceId, authorization.clientId]))
+        .digest("hex");
+}

package/dist/server.d.ts

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