@seleniumbox/sbox-mcp 0.2.0

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, {
+    username: string;
+    password: string;
+    realm?: string | undefined;
+}, {
+    username: string;
+    password: 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,34 @@
+#!/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");
+const sdkServerDir = path_1.default.join(__dirname, "..", "node_modules", "@modelcontextprotocol", "sdk", "dist", "cjs", "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 authenticate/log in to SBOX, or when other SBOX tools return 'Not authenticated' or 'Invalid or expired session'. Do NOT call for every SBOX query—use the cached token for other tools.",
+        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. Token cached for subsequent SBOX tools.",
+                    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; you can use SBOX tools now.",
+                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>;

package/dist/mcp/tools/helpers.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Shared helpers for MCP tool responses and token handling.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_UPLOAD_SIZE = void 0;
+exports.textContent = textContent;
+exports.friendlyError = friendlyError;
+exports.errorContent = errorContent;
+exports.requireToken = requireToken;
+exports.isAuthError = isAuthError;
+exports.clearTokenOnAuthError = clearTokenOnAuthError;
+exports.sleep = sleep;
+const token_cache_1 = require("../../token-cache");
+exports.MAX_UPLOAD_SIZE = 200 * 1024 * 1024; // 200MB
+function textContent(text) {
+    return { content: [{ type: "text", text }] };
+}
+function friendlyError(message) {
+    const m = (message || "").toLowerCase();
+    if (m.includes("unauthorized") || (m.includes("invalid") && m.includes("token")))
+        return "Invalid or expired session. Please log in again.";
+    if (m.includes("forbidden"))
+        return "You don't have permission for this action.";
+    if (m.includes("not found"))
+        return "The requested resource was not found.";
+    if (m.includes("timeout") || m.includes("econnrefused"))
+        return "The request timed out or the service is unavailable. Please try again.";
+    return message || "Something went wrong. Please try again.";
+}
+function errorContent(message) {
+    return { content: [{ type: "text", text: `Error: ${friendlyError(message)}` }] };
+}
+function requireToken(provided) {
+    const token = (0, token_cache_1.resolveToken)(provided);
+    if (!token) {
+        return errorContent("Not authenticated. Use sbox_open_login to sign in first, then retry.");
+    }
+    return token;
+}
+function isAuthError(message) {
+    const m = (message || "").toLowerCase();
+    return (m.includes("unauthorized") ||
+        (m.includes("invalid") && m.includes("token")) ||
+        m.includes("expired"));
+}
+function clearTokenOnAuthError(message) {
+    if (isAuthError(message))
+        (0, token_cache_1.clearCachedToken)();
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

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

@@ -0,0 +1,5 @@
+/**
+ * MCP tools entrypoint. Composes auth and rest tool registration.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
+export declare function registerSboxTools(server: McpServer): void;

package/dist/mcp/tools/index.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * MCP tools entrypoint. Composes auth and rest tool registration.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSboxTools = registerSboxTools;
+const auth_tools_1 = require("./auth-tools");
+const rest_tools_1 = require("./rest-tools");
+function registerSboxTools(server) {
+    (0, auth_tools_1.registerAuthTools)(server);
+    (0, rest_tools_1.registerRestTools)(server);
+}

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

@@ -0,0 +1,5 @@
+/**
+ * MCP tools: session, browser, device, user, project, upload, analytics, diagnostics.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
+export declare function registerRestTools(server: McpServer): void;