@seleniumbox/sbox-mcp 1.0.0

package/dist/controllers/session.controller.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Session controller: get, update status, delete, start manual. No business logic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listSessions = listSessions;
+exports.getSessionDetail = getSessionDetail;
+exports.updateSessionStatus = updateSessionStatus;
+exports.deleteSession = deleteSession;
+exports.startManualSession = startManualSession;
+const services_1 = require("../services");
+const session_dto_1 = require("../dto/session.dto");
+const UpdateBodySchema = session_dto_1.UpdateSessionStatusBodySchema;
+function token(req) {
+    return req.token;
+}
+function listSessions(req, res) {
+    const t = token(req);
+    if (!t) {
+        res.status(401).json({ success: false, message: "Authorization required", code: 401 });
+        return;
+    }
+    const q = req.query;
+    const limit = q.limit != null ? parseInt(q.limit, 10) : undefined;
+    const offset = q.offset != null ? parseInt(q.offset, 10) : undefined;
+    services_1.sessionService.listSessions({
+        limit: isNaN(limit) ? undefined : limit,
+        offset: isNaN(offset) ? undefined : offset,
+        projectName: q.projectName,
+        status: q.status,
+        browser: q.browser,
+        build: q.build,
+        sortBy: q.sortBy,
+        sortDirection: q.sortDirection,
+    }, t).then((out) => {
+        if (out.success) {
+            res.status(200).json({ success: true, data: out.data });
+            return;
+        }
+        res.status(out.status).json({ success: false, message: out.message, code: out.status });
+    }).catch((err) => {
+        res.status(500).json({ success: false, message: err instanceof Error ? err.message : "Error", code: 500 });
+    });
+}
+function getSessionDetail(req, res) {
+    const ekey = req.params.ekey;
+    const t = token(req);
+    if (!t) {
+        res.status(401).json({ success: false, message: "Authorization required", code: 401 });
+        return;
+    }
+    services_1.sessionService.getSessionDetail(ekey, t).then((out) => {
+        if (out.success) {
+            res.status(200).json({ success: true, data: out.data });
+            return;
+        }
+        res.status(out.status).json({ success: false, message: out.message, code: out.status });
+    }).catch((err) => {
+        res.status(500).json({ success: false, message: err instanceof Error ? err.message : "Error", code: 500 });
+    });
+}
+function updateSessionStatus(req, res) {
+    const body = UpdateBodySchema.parse(req.body);
+    const t = token(req);
+    if (!t) {
+        res.status(401).json({ success: false, message: "Authorization required", code: 401 });
+        return;
+    }
+    services_1.sessionService.updateSessionStatus(body, t).then((out) => {
+        if (out.success) {
+            res.status(out.status).json({ success: true });
+            return;
+        }
+        res.status(out.status).json({ success: false, message: out.message ?? "Update failed", code: out.status });
+    }).catch((err) => {
+        res.status(500).json({ success: false, message: err instanceof Error ? err.message : "Error", code: 500 });
+    });
+}
+function deleteSession(req, res) {
+    const sessionId = req.query.sessionId;
+    const t = token(req);
+    if (!t) {
+        res.status(401).json({ success: false, message: "Authorization required", code: 401 });
+        return;
+    }
+    if (!sessionId) {
+        res.status(400).json({ success: false, message: "sessionId required", code: 400 });
+        return;
+    }
+    services_1.sessionService.deleteSession(sessionId, t).then((out) => {
+        if (out.success) {
+            res.status(200).json({ success: true, data: out.data });
+            return;
+        }
+        res.status(out.status).json({ success: false, message: out.message, code: out.status });
+    }).catch((err) => {
+        res.status(500).json({ success: false, message: err instanceof Error ? err.message : "Error", code: 500 });
+    });
+}
+function startManualSession(req, res) {
+    const body = req.body;
+    const t = token(req);
+    if (!t) {
+        res.status(401).json({ success: false, message: "Authorization required", code: 401 });
+        return;
+    }
+    if (!body || typeof body.projectName !== "string") {
+        res.status(400).json({ success: false, message: "projectName is required", code: 400 });
+        return;
+    }
+    services_1.sessionService.startManualSession(body, t).then((out) => {
+        if (out.success) {
+            res.status(200).json({ success: true, data: out.data });
+            return;
+        }
+        res.status(out.status).json({ success: false, message: out.message, code: out.status });
+    }).catch((err) => {
+        res.status(500).json({ success: false, message: err instanceof Error ? err.message : "Error", code: 500 });
+    });
+}

package/dist/controllers/upload.controller.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Upload controller: upload mobile app (APK/IPA) to SBOX. No business logic.
+ */
+import { Request, Response } from "express";
+export declare function uploadMobileApp(req: Request, res: Response): void;

package/dist/controllers/upload.controller.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Upload controller: upload mobile app (APK/IPA) to SBOX. No business logic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadMobileApp = uploadMobileApp;
+const services_1 = require("../services");
+const MAX_FILE_SIZE = 200 * 1024 * 1024; // 200MB
+function token(req) {
+    return req.token;
+}
+function uploadMobileApp(req, res) {
+    const t = token(req);
+    if (!t) {
+        res.status(401).json({ success: false, message: "Authorization required", code: 401 });
+        return;
+    }
+    const file = req.file;
+    if (!file || !file.buffer) {
+        res.status(400).json({ success: false, message: "Missing file (use multipart field 'file')", code: 400 });
+        return;
+    }
+    const projectName = typeof req.body?.projectName === "string" ? req.body.projectName.trim() : "";
+    if (!projectName) {
+        res.status(400).json({ success: false, message: "Missing projectName in body", code: 400 });
+        return;
+    }
+    if (file.size > MAX_FILE_SIZE) {
+        res.status(400).json({ success: false, message: "File too large (max 200MB)", code: 400 });
+        return;
+    }
+    services_1.uploadService
+        .uploadMobileApp(projectName, file.buffer, file.originalname || "app", t)
+        .then((out) => {
+        if (out.success) {
+            res.status(200).json({ success: true, data: out.data });
+            return;
+        }
+        res.status(out.status).json({ success: false, message: out.message, code: out.status });
+    })
+        .catch((err) => {
+        res.status(500).json({ success: false, message: err instanceof Error ? err.message : "Error", code: 500 });
+    });
+}

package/dist/controllers/user.controller.d.ts

@@ -0,0 +1,5 @@
+/**
+ * User controller: get active users (top N). No business logic.
+ */
+import { Request, Response } from "express";
+export declare function getActiveUsers(req: Request, res: Response): void;

package/dist/controllers/user.controller.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * User controller: get active users (top N). No business logic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getActiveUsers = getActiveUsers;
+const zod_1 = require("zod");
+const services_1 = require("../services");
+const QuerySchema = zod_1.z.object({
+    limit: zod_1.z.string().optional().transform((s) => (s ? parseInt(s, 10) : 10)),
+});
+function getActiveUsers(req, res) {
+    const token = req.token;
+    if (!token) {
+        res.status(401).json({ success: false, message: "Authorization required", code: 401 });
+        return;
+    }
+    const parsed = QuerySchema.safeParse(req.query);
+    const limit = parsed.success && !isNaN(parsed.data.limit) ? Math.min(parsed.data.limit, 50) : 10;
+    services_1.userService.getActiveUsersTopN(token, limit).then((out) => {
+        if (out.success) {
+            res.status(200).json({ success: true, data: out.data });
+            return;
+        }
+        res.status(out.status).json({ success: false, message: out.message, code: out.status });
+    }).catch((err) => {
+        res.status(500).json({ success: false, message: err instanceof Error ? err.message : "Error", code: 500 });
+    });
+}

package/dist/device-flow.store.d.ts

@@ -0,0 +1,7 @@
+/**
+ * In-memory store for device-flow poll sessions. Tracks poll_id -> deadline for GET /auth/status.
+ * Used by POST /auth/initiate and sbox_open_login so the IDE can poll until authenticated or expired.
+ */
+export declare function registerPollSession(pollId: string, expiresInSec?: number): void;
+export declare function isExpired(pollId: string): boolean;
+export declare function hasPollSession(pollId: string): boolean;

package/dist/device-flow.store.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * In-memory store for device-flow poll sessions. Tracks poll_id -> deadline for GET /auth/status.
+ * Used by POST /auth/initiate and sbox_open_login so the IDE can poll until authenticated or expired.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerPollSession = registerPollSession;
+exports.isExpired = isExpired;
+exports.hasPollSession = hasPollSession;
+const DEFAULT_EXPIRES_IN_SEC = 300;
+const store = new Map();
+function registerPollSession(pollId, expiresInSec = DEFAULT_EXPIRES_IN_SEC) {
+    store.set(pollId, Date.now() + expiresInSec * 1000);
+}
+function isExpired(pollId) {
+    const deadline = store.get(pollId);
+    if (deadline == null)
+        return true;
+    return Date.now() >= deadline;
+}
+function hasPollSession(pollId) {
+    return store.has(pollId);
+}

package/dist/dto/auth.dto.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+export declare const LoginBodySchema: z.ZodObject<{
+    username: z.ZodString;
+    password: z.ZodString;
+    realm: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    password: string;
+    username: string;
+    realm?: string | undefined;
+}, {
+    password: string;
+    username: string;
+    realm?: string | undefined;
+}>;
+export type LoginBody = z.infer<typeof LoginBodySchema>;
+/** Customer-facing auth type; do not expose internal realmId. */
+export type AuthType = "Local" | "LDAP" | "OIDC";
+export interface LoginResponseDto {
+    token: string;
+    principal: {
+        userId: string;
+        fullname?: string;
+        /** Customer-friendly: Local, LDAP, or OIDC. Internal realm id is not exposed. */
+        authType: AuthType;
+    };
+}

package/dist/dto/auth.dto.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoginBodySchema = void 0;
+const zod_1 = require("zod");
+exports.LoginBodySchema = zod_1.z.object({
+    username: zod_1.z.string().min(1, "username is required"),
+    password: zod_1.z.string().min(1, "password is required"),
+    realm: zod_1.z.string().optional(),
+});

package/dist/dto/browser.dto.d.ts

@@ -0,0 +1,13 @@
+export interface BrowserDto {
+    browserName: string;
+    version: string;
+    platform: string;
+    capabilities: Record<string, unknown>;
+}
+/** Playwright version with bundled browser versions (from GET /e34/api/playwright) */
+export interface PlaywrightVersionDto {
+    version: string;
+    chromium: string;
+    webkit: string;
+    firefox: string;
+}

package/dist/dto/browser.dto.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/dto/device.dto.d.ts

@@ -0,0 +1,15 @@
+export interface DeviceDto {
+    /** Short display name (e.g. "Galaxy S21 GPS") */
+    deviceName: string;
+    /** Full name (e.g. "Samsung Galaxy S21 GPS") */
+    completeDeviceName?: string;
+    /** AVD/emulator identifier (Android) */
+    avdName?: string;
+    /** Platform: Android, iOS, or MobileWeb */
+    os: string;
+    /** OS version(s) - single string or from supportedPlatformVersions */
+    version: string;
+    /** Supported platform versions (e.g. ["13.0"]) */
+    supportedPlatformVersions?: string[];
+    availability?: string;
+}

package/dist/dto/device.dto.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/dto/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./auth.dto";
+export * from "./session.dto";
+export * from "./browser.dto";
+export * from "./device.dto";
+export * from "./user.dto";
+export * from "./project-stats.dto";

package/dist/dto/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./auth.dto"), exports);
+__exportStar(require("./session.dto"), exports);
+__exportStar(require("./browser.dto"), exports);
+__exportStar(require("./device.dto"), exports);
+__exportStar(require("./user.dto"), exports);
+__exportStar(require("./project-stats.dto"), exports);

package/dist/dto/project-stats.dto.d.ts

@@ -0,0 +1,8 @@
+export interface SessionsPerProjectDto {
+    projectName: string;
+    totalSessions: number;
+    passed: number;
+    failed: number;
+    running: number;
+    avgDuration: number;
+}

package/dist/dto/project-stats.dto.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/dto/session.dto.d.ts

@@ -0,0 +1,50 @@
+export interface SessionDetailDto {
+    sessionId: string;
+    projectName: string;
+    browserName: string;
+    browserVersion: string;
+    deviceName: string;
+    userName: string;
+    status: string;
+    framework: string;
+    startTime: string | null;
+    endTime: string | null;
+    durationMs: number | null;
+    videoUrl: string | null;
+    /** All capabilities sent to the session (e34:* extras + top-level session fields). */
+    capabilities: Record<string, unknown>;
+}
+export interface SessionListResultDto {
+    content: SessionDetailDto[];
+    totalElements: number;
+}
+import { z } from "zod";
+export declare const UpdateSessionStatusBodySchema: z.ZodObject<{
+    buildName: z.ZodString;
+    projectName: z.ZodString;
+    status: z.ZodEnum<["passed", "failed", "timeout"]>;
+}, "strip", z.ZodTypeAny, {
+    status: "timeout" | "passed" | "failed";
+    buildName: string;
+    projectName: string;
+}, {
+    status: "timeout" | "passed" | "failed";
+    buildName: string;
+    projectName: string;
+}>;
+export interface UpdateSessionStatusBodyDto {
+    buildName: string;
+    projectName: string;
+    status: "passed" | "failed" | "timeout";
+}
+export interface DeleteSessionResponseDto {
+    success: boolean;
+    message: string;
+}
+export interface StartManualSessionBodyDto {
+    projectName: string;
+    browserName?: string;
+    browserVersion?: string;
+    url?: string;
+    [key: string]: unknown;
+}

package/dist/dto/session.dto.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpdateSessionStatusBodySchema = void 0;
+const zod_1 = require("zod");
+exports.UpdateSessionStatusBodySchema = zod_1.z.object({
+    buildName: zod_1.z.string().min(1),
+    projectName: zod_1.z.string().min(1),
+    status: zod_1.z.enum(["passed", "failed", "timeout"]),
+});

package/dist/dto/user.dto.d.ts

@@ -0,0 +1,6 @@
+export interface ActiveUserDto {
+    userName: string;
+    email: string | null;
+    activeSessionCount: number;
+    projectNames: string[];
+}

package/dist/dto/user.dto.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * CLI entrypoint for @seleniumbox/sbox-mcp. Started by IDE via npx; runs MCP over stdio.
+ * Reads SBOX_API (or SBOX_API_BASE_URL) and optional PORT from env. No Docker assumptions.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * CLI entrypoint for @seleniumbox/sbox-mcp. Started by IDE via npx; runs MCP over stdio.
+ * Reads SBOX_API (or SBOX_API_BASE_URL) and optional PORT from env. No Docker assumptions.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = __importDefault(require("path"));
+const index_1 = require("./mcp/tools/index");
+// Resolve SDK server dir via the package's "server" export (dist/cjs/server) so it works when npx hoists deps
+const sdkServerDir = path_1.default.dirname(require.resolve("@modelcontextprotocol/sdk/server"));
+const { McpServer } = require(path_1.default.join(sdkServerDir, "mcp.js"));
+const { StdioServerTransport } = require(path_1.default.join(sdkServerDir, "stdio.js"));
+const server = new McpServer({
+    name: "sbox-mcp",
+    version: "1.0.0",
+});
+(0, index_1.registerSboxTools)(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`SBOX MCP error: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+process.on("SIGINT", () => {
+    process.exit(0);
+});
+process.on("SIGTERM", () => {
+    process.exit(0);
+});

package/dist/mcp/tools/auth-tools.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Auth MCP tools: sbox_open_login, sbox_complete_login.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
+export declare function registerAuthTools(server: McpServer): void;

package/dist/mcp/tools/auth-tools.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * Auth MCP tools: sbox_open_login, sbox_complete_login.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAuthTools = registerAuthTools;
+const zod_1 = require("zod");
+const crypto_1 = require("crypto");
+const services_1 = require("../../services");
+const open_browser_1 = require("../../utils/open-browser");
+const config_1 = require("../../config");
+const device_flow_store_1 = require("../../device-flow.store");
+const token_cache_1 = require("../../token-cache");
+const helpers_1 = require("./helpers");
+const DEVICE_FLOW_EXPIRES_IN_SEC = 300;
+const POLL_INTERVAL_MS = 3000;
+const POLL_TIMEOUT_MS = 60000;
+const BACKGROUND_POLL_TIMEOUT_MS = 300000;
+const COMPLETE_LOGIN_POLL_MS = 60000;
+function startBackgroundPollForToken(pollId) {
+    const deadline = Date.now() + BACKGROUND_POLL_TIMEOUT_MS;
+    const poll = async () => {
+        while (Date.now() < deadline) {
+            const token = await services_1.authService.pollForToken(pollId);
+            if (token) {
+                const out = await services_1.authService.validateToken(token);
+                if (out.success)
+                    (0, token_cache_1.setCachedToken)(token);
+                return;
+            }
+            await (0, helpers_1.sleep)(POLL_INTERVAL_MS);
+        }
+    };
+    poll().catch(() => { });
+}
+function registerAuthTools(server) {
+    server.registerTool("sbox_open_login", {
+        title: "Open SBOX Login in Browser",
+        description: "Sign in to SBOX (opens browser, polls for token, caches it). Call ONLY when the user explicitly asks to log in, or when another SBOX tool returns 'Not authenticated' or 'Invalid or expired session'. After successful login, the same cached token is used for ALL SBOX API calls until it expires (~1h). Do NOT call for every SBOX query. If the user logs in again, the new token replaces the old one and is used for all subsequent API calls.",
+        inputSchema: {},
+    }, (async () => {
+        try {
+            const enabled = await services_1.authService.isMcpAddonEnabled();
+            if (!enabled) {
+                return (0, helpers_1.errorContent)("MCP add-on is not configured or not enabled on this SBOX hub. Please enable the MCP add-on to log in via the browser.");
+            }
+            const pollId = (0, crypto_1.randomUUID)();
+            const authUrl = (0, config_1.getPublicLoginPageUrl)() + "?mcp_poll_id=" + encodeURIComponent(pollId);
+            (0, device_flow_store_1.registerPollSession)(pollId, DEVICE_FLOW_EXPIRES_IN_SEC);
+            const opened = await (0, open_browser_1.openUrlInBrowser)(authUrl);
+            if (!opened) {
+                (0, token_cache_1.setLastPollId)(pollId);
+                startBackgroundPollForToken(pollId);
+                return (0, helpers_1.textContent)(JSON.stringify({
+                    auth_url: authUrl,
+                    poll_id: pollId,
+                    expires_in: DEVICE_FLOW_EXPIRES_IN_SEC,
+                    message: "Open the URL above in your browser to sign in. The IDE may open it automatically. After signing in, you can use SBOX tools; if you see 'not authenticated', say 'complete SBOX login' with the same session or try again in a few seconds.",
+                }));
+            }
+            const deadline = Date.now() + POLL_TIMEOUT_MS;
+            let token = null;
+            while (Date.now() < deadline) {
+                token = await services_1.authService.pollForToken(pollId);
+                if (token)
+                    break;
+                await (0, helpers_1.sleep)(POLL_INTERVAL_MS);
+            }
+            if (token) {
+                const out = await services_1.authService.validateToken(token);
+                if (!out.success)
+                    return (0, helpers_1.errorContent)(out.message);
+                (0, token_cache_1.setCachedToken)(token);
+                const name = out.data.principal?.fullname || out.data.principal?.userId || "—";
+                const authType = out.data.principal?.authType || "Local";
+                return (0, helpers_1.textContent)(JSON.stringify({
+                    success: true,
+                    token,
+                    message: "SBOX authentication successful. This token is cached and will be used for all SBOX API calls until it expires (~1h). No need to log in again for each request.",
+                    principal: { name, authType },
+                }));
+            }
+            return (0, helpers_1.textContent)(JSON.stringify({
+                success: false,
+                auth_url: authUrl,
+                message: "Sign-in did not complete within 1 minute. The login link is still valid for 5 minutes. Open the URL below in your browser to sign in, then use SBOX tools again.",
+            }));
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : "Something went wrong while initiating login.";
+            return (0, helpers_1.errorContent)(msg);
+        }
+    }));
+    server.registerTool("sbox_complete_login", {
+        title: "Complete SBOX Login (after signing in in browser)",
+        description: "Call after the user has signed in in the browser. Polls for the token by poll_id and caches it so subsequent SBOX tools work. Pass the poll_id from the previous sbox_open_login response, or omit to use the last poll_id.",
+        inputSchema: {
+            poll_id: zod_1.z.string().optional().describe("Poll ID from sbox_open_login response; omit to use last poll"),
+        },
+    }, (async (args) => {
+        try {
+            const pollId = (args.poll_id ?? (0, token_cache_1.getLastPollId)() ?? "").trim();
+            if (!pollId) {
+                return (0, helpers_1.errorContent)("No poll_id provided and no recent login session. Run sbox_open_login first, then open the URL and sign in, then call this tool with the poll_id from that response.");
+            }
+            const deadline = Date.now() + COMPLETE_LOGIN_POLL_MS;
+            let token = null;
+            while (Date.now() < deadline) {
+                token = await services_1.authService.pollForToken(pollId);
+                if (token)
+                    break;
+                await (0, helpers_1.sleep)(POLL_INTERVAL_MS);
+            }
+            if (!token) {
+                return (0, helpers_1.errorContent)("Token not received yet. Make sure you completed sign-in in the browser, then try again.");
+            }
+            const out = await services_1.authService.validateToken(token);
+            if (!out.success)
+                return (0, helpers_1.errorContent)(out.message);
+            (0, token_cache_1.setCachedToken)(token);
+            const name = out.data.principal?.fullname || out.data.principal?.userId || "—";
+            return (0, helpers_1.textContent)(JSON.stringify({
+                success: true,
+                message: "SBOX login complete. Token cached and will be used for all SBOX API calls until expiry (~1h).",
+                principal: { name },
+            }));
+        }
+        catch (e) {
+            return (0, helpers_1.errorContent)(e instanceof Error ? e.message : "Failed to complete login.");
+        }
+    }));
+}

package/dist/mcp/tools/helpers.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared helpers for MCP tool responses and token handling.
+ */
+export declare const MAX_UPLOAD_SIZE: number;
+export declare function textContent(text: string): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+};
+export declare function friendlyError(message: string): string;
+export declare function errorContent(message: string): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+};
+export declare function requireToken(provided: string | undefined): string | {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+};
+export declare function isAuthError(message: string): boolean;
+export declare function clearTokenOnAuthError(message: string): void;
+export declare function sleep(ms: number): Promise<void>;