@seleniumbox/sbox-mcp 0.2.0

package/dist/services/session.service.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Session service: get session details, update status, delete session, start manual.
+ * Uses adapters and enrichment; never exposes internal IDs.
+ */
+import type { SessionAdapter } from "../adapters/session.adapter";
+import type { SessionDetailDto, SessionListResultDto, UpdateSessionStatusBodyDto, DeleteSessionResponseDto, StartManualSessionBodyDto } from "../dto/session.dto";
+export interface ListSessionsParams {
+    limit?: number;
+    offset?: number;
+    projectName?: string;
+    status?: string;
+    browser?: string;
+    build?: string;
+    sortBy?: string;
+    sortDirection?: string;
+}
+export interface SessionService {
+    getSessionDetail(ekey: string, token: string): Promise<{
+        success: true;
+        data: SessionDetailDto;
+    } | {
+        success: false;
+        status: number;
+        message: string;
+    }>;
+    listSessions(params: ListSessionsParams, token: string): Promise<{
+        success: true;
+        data: SessionListResultDto;
+    } | {
+        success: false;
+        status: number;
+        message: string;
+    }>;
+    /** Update a single session's result (passed/failed) via POST /e34/api/test-data?sessionId=&passed= */
+    updateSessionStatusBySessionId(sessionId: string, passed: boolean, token: string): Promise<{
+        success: boolean;
+        status: number;
+        message?: string;
+    }>;
+    updateSessionStatus(body: UpdateSessionStatusBodyDto, token: string): Promise<{
+        success: boolean;
+        status: number;
+        message?: string;
+    }>;
+    deleteSession(sessionId: string, token: string): Promise<{
+        success: true;
+        data: DeleteSessionResponseDto;
+    } | {
+        success: false;
+        status: number;
+        message: string;
+    }>;
+    startManualSession(body: StartManualSessionBodyDto, token: string): Promise<{
+        success: true;
+        data: SessionDetailDto;
+    } | {
+        success: false;
+        status: number;
+        message: string;
+    }>;
+}
+export declare function createSessionService(adapter: SessionAdapter): SessionService;

package/dist/services/session.service.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Session service: get session details, update status, delete session, start manual.
+ * Uses adapters and enrichment; never exposes internal IDs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSessionService = createSessionService;
+const enrichment_service_1 = require("./enrichment.service");
+function createSessionService(adapter) {
+    return {
+        async getSessionDetail(ekey, token) {
+            const res = await adapter.getByEkey(ekey, token);
+            if (res.status !== 200 || !res.data) {
+                return { success: false, status: res.status, message: res.error ?? "Session not found" };
+            }
+            const videoUrl = (0, enrichment_service_1.buildVideoUrl)(res.data.ekey ?? ekey);
+            const dto = (0, enrichment_service_1.enrichSessionDetail)(res.data, videoUrl);
+            return { success: true, data: dto };
+        },
+        async listSessions(params, token) {
+            const size = Math.min(Math.max(params.limit ?? 25, 1), 100);
+            const offset = Math.max(params.offset ?? 0, 0);
+            const res = await adapter.listPaginated({
+                projectId: params.projectName,
+                size,
+                offset,
+                status: params.status,
+                browser: params.browser,
+                build: params.build,
+                sortBy: params.sortBy ?? "arrival",
+                sortDirection: params.sortDirection ?? "desc",
+            }, token);
+            if (res.status !== 200) {
+                return { success: false, status: res.status, message: res.error ?? "List sessions failed" };
+            }
+            const content = res.content.map((raw) => {
+                const videoUrl = raw.ekey ? (0, enrichment_service_1.buildVideoUrl)(raw.ekey) : null;
+                return (0, enrichment_service_1.enrichSessionDetail)(raw, videoUrl);
+            });
+            return { success: true, data: { content, totalElements: res.totalElements } };
+        },
+        async updateSessionStatusBySessionId(sessionId, passed, token) {
+            const res = await adapter.updateSessionStatus(sessionId, passed, token);
+            if (res.status >= 200 && res.status < 300) {
+                return { success: true, status: res.status };
+            }
+            return { success: false, status: res.status, message: res.error };
+        },
+        async updateSessionStatus(body, token) {
+            const res = await adapter.updateStatusByBuild({ buildName: body.buildName, projectId: body.projectName, status: body.status }, token);
+            if (res.status >= 200 && res.status < 300) {
+                return { success: true, status: res.status };
+            }
+            return { success: false, status: res.status, message: res.error };
+        },
+        async deleteSession(sessionId, token) {
+            const res = await adapter.deleteManualSession(sessionId, token);
+            if (res.status >= 200 && res.status < 300) {
+                return { success: true, data: { success: true, message: "Session deleted" } };
+            }
+            return { success: false, status: res.status, message: res.error ?? "Delete failed" };
+        },
+        async startManualSession(body, token) {
+            const cap = {
+                "e34:projectId": body.projectName,
+                ...(body.browserName && { browserName: body.browserName }),
+                ...(body.browserVersion && { version: body.browserVersion }),
+                ...(body.url && { url: body.url }),
+            };
+            Object.keys(body).forEach((k) => {
+                if (!["projectName", "browserName", "browserVersion", "url"].includes(k))
+                    cap[k] = body[k];
+            });
+            const res = await adapter.startManualSession(cap, token);
+            if (res.status !== 200 || !res.sessionId) {
+                return { success: false, status: res.status, message: res.error ?? "Start manual session failed" };
+            }
+            const getRes = await adapter.getByEkey(res.sessionId, token);
+            const raw = getRes.data;
+            const videoUrl = (0, enrichment_service_1.buildVideoUrl)(res.sessionId);
+            const dto = raw ? (0, enrichment_service_1.enrichSessionDetail)(raw, videoUrl) : {
+                sessionId: res.sessionId,
+                projectName: body.projectName,
+                browserName: body.browserName ?? "",
+                browserVersion: body.browserVersion ?? "",
+                deviceName: "",
+                userName: "",
+                status: "running",
+                framework: "selenium",
+                startTime: new Date().toISOString(),
+                endTime: null,
+                durationMs: null,
+                videoUrl,
+                capabilities: {
+                    browser: body.browserName,
+                    version: body.browserVersion,
+                    "e34:projectId": body.projectName,
+                    ...(body.url && { url: body.url }),
+                },
+            };
+            return { success: true, data: dto };
+        },
+    };
+}

package/dist/services/sessions-per-project.service.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Sessions per project (last X days): totalSessions, passed, failed, running, avgDuration.
+ * Uses project and session adapters; aggregates in MCP (backend has no single endpoint).
+ */
+import type { ProjectAdapter } from "../adapters/project.adapter";
+import type { SessionAdapter } from "../adapters/session.adapter";
+import type { SessionsPerProjectDto } from "../dto/project-stats.dto";
+export interface SessionsPerProjectService {
+    getSessionsPerProject(token: string, days: number): Promise<{
+        success: true;
+        data: SessionsPerProjectDto[];
+    } | {
+        success: false;
+        status: number;
+        message: string;
+    }>;
+}
+export declare function createSessionsPerProjectService(projectAdapter: ProjectAdapter, sessionAdapter: SessionAdapter): SessionsPerProjectService;

package/dist/services/sessions-per-project.service.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Sessions per project (last X days): totalSessions, passed, failed, running, avgDuration.
+ * Uses project and session adapters; aggregates in MCP (backend has no single endpoint).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSessionsPerProjectService = createSessionsPerProjectService;
+const PAGE_SIZE = 500;
+function createSessionsPerProjectService(projectAdapter, sessionAdapter) {
+    return {
+        async getSessionsPerProject(token, days) {
+            const countRes = await projectAdapter.getCountPerProject(days, token);
+            if (countRes.status !== 200) {
+                return { success: false, status: countRes.status, message: countRes.error ?? "Failed to get project counts" };
+            }
+            const projects = countRes.items.map((p) => p.project).filter(Boolean);
+            const results = [];
+            const maxAgeDays = Math.max(0, days);
+            for (const projectName of projects) {
+                const listRes = await sessionAdapter.listPaginated({ projectId: projectName, size: PAGE_SIZE, offset: 0, maxAgeDays }, token);
+                if (listRes.status !== 200)
+                    continue;
+                const content = listRes.content;
+                let passed = 0;
+                let failed = 0;
+                let running = 0;
+                let totalDuration = 0;
+                let countWithDuration = 0;
+                for (const s of content) {
+                    const r = (s.result ?? "").toLowerCase();
+                    if (r === "passed")
+                        passed++;
+                    else if (r === "failed" || r === "timeout")
+                        failed++;
+                    else
+                        running++;
+                    const d = s.duration ?? s.duration;
+                    if (typeof d === "number" && d >= 0) {
+                        totalDuration += d;
+                        countWithDuration++;
+                    }
+                }
+                const totalSessions = content.length;
+                const avgDuration = countWithDuration > 0 ? Math.round(totalDuration / countWithDuration) : 0;
+                results.push({
+                    projectName,
+                    totalSessions,
+                    passed,
+                    failed,
+                    running,
+                    avgDuration,
+                });
+            }
+            return { success: true, data: results };
+        },
+    };
+}

package/dist/services/upload.service.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Upload service: upload mobile apps (APK/IPA) to SBOX. Resolves project name to id; no business logic beyond delegation.
+ */
+import type { UploadAdapter } from "../adapters/upload.adapter";
+import type { ProjectAdapter } from "../adapters/project.adapter";
+export interface UploadResultDto {
+    uploadedAppIdentifier: string;
+    projectName: string;
+}
+export interface UploadService {
+    uploadMobileApp(projectName: string, fileBuffer: Buffer, filename: string, token: string): Promise<{
+        success: true;
+        data: UploadResultDto;
+    } | {
+        success: false;
+        status: number;
+        message: string;
+    }>;
+}
+export declare function createUploadService(uploadAdapter: UploadAdapter, projectAdapter: ProjectAdapter): UploadService;

package/dist/services/upload.service.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Upload service: upload mobile apps (APK/IPA) to SBOX. Resolves project name to id; no business logic beyond delegation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUploadService = createUploadService;
+function createUploadService(uploadAdapter, projectAdapter) {
+    return {
+        async uploadMobileApp(projectName, fileBuffer, filename, token) {
+            const listRes = await projectAdapter.listProjects(token);
+            if (listRes.status !== 200) {
+                return { success: false, status: listRes.status, message: listRes.error ?? "Failed to list projects" };
+            }
+            const project = listRes.projects.find((p) => (p.name ?? "").toLowerCase() === projectName.toLowerCase());
+            if (!project || project.id == null) {
+                return { success: false, status: 404, message: `Project not found: ${projectName}` };
+            }
+            const projectId = String(project.id);
+            const res = await uploadAdapter.uploadMobileApp(projectId, fileBuffer, filename, token);
+            if (res.status !== 200 || !res.uploadedAppIdentifier) {
+                return { success: false, status: res.status, message: res.error ?? "Upload failed" };
+            }
+            return {
+                success: true,
+                data: { uploadedAppIdentifier: res.uploadedAppIdentifier, projectName: project.name ?? projectName },
+            };
+        },
+    };
+}

package/dist/services/user.service.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Active users (top N) with session counts and project names.
+ * Uses user adapter and session list; returns business-friendly DTOs.
+ */
+import type { SessionAdapter } from "../adapters/session.adapter";
+import type { ActiveUserDto } from "../dto/user.dto";
+export interface UserService {
+    getActiveUsersTopN(token: string, limit: number): Promise<{
+        success: true;
+        data: ActiveUserDto[];
+    } | {
+        success: false;
+        status: number;
+        message: string;
+    }>;
+}
+export declare function createUserService(sessionAdapter: SessionAdapter): UserService;

package/dist/services/user.service.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Active users (top N) with session counts and project names.
+ * Uses user adapter and session list; returns business-friendly DTOs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUserService = createUserService;
+function createUserService(sessionAdapter) {
+    return {
+        async getActiveUsersTopN(token, limit) {
+            const sessionsRes = await sessionAdapter.listPaginated({ size: 500, offset: 0, sortBy: "arrival", sortDirection: "desc" }, token);
+            if (sessionsRes.status !== 200) {
+                return { success: false, status: sessionsRes.status, message: sessionsRes.error ?? "Failed to list sessions" };
+            }
+            const byUser = new Map();
+            for (const s of sessionsRes.content) {
+                const uid = (s.extras ?? {})["e34:userId"];
+                const project = (s.extras ?? {})["e34:projectId"];
+                const userKey = uid ?? "unknown";
+                if (!byUser.has(userKey))
+                    byUser.set(userKey, { count: 0, projects: new Set() });
+                const entry = byUser.get(userKey);
+                entry.count += 1;
+                if (project)
+                    entry.projects.add(project);
+            }
+            const sorted = [...byUser.entries()]
+                .sort((a, b) => b[1].count - a[1].count)
+                .slice(0, limit);
+            const dtos = sorted.map(([userName, { count, projects }]) => ({
+                userName,
+                email: null,
+                activeSessionCount: count,
+                projectNames: [...projects],
+            }));
+            return { success: true, data: dtos };
+        },
+    };
+}

package/dist/token-cache.d.ts

@@ -0,0 +1,12 @@
+/**
+ * In-memory cache for the SBOX session token. Set on successful sbox_open_login,
+ * used by other tools when token is not passed. Cleared on 401/invalid token.
+ * lastPollId is set when we return device-flow (browser didn't open) so sbox_complete_login can use it.
+ */
+export declare function getCachedToken(): string | null;
+export declare function setCachedToken(token: string): void;
+export declare function clearCachedToken(): void;
+export declare function setLastPollId(pollId: string): void;
+export declare function getLastPollId(): string | null;
+/** Resolve token: prefer provided token, else cached. Returns null if neither. */
+export declare function resolveToken(provided: string | undefined | null): string | null;

package/dist/token-cache.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * In-memory cache for the SBOX session token. Set on successful sbox_open_login,
+ * used by other tools when token is not passed. Cleared on 401/invalid token.
+ * lastPollId is set when we return device-flow (browser didn't open) so sbox_complete_login can use it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCachedToken = getCachedToken;
+exports.setCachedToken = setCachedToken;
+exports.clearCachedToken = clearCachedToken;
+exports.setLastPollId = setLastPollId;
+exports.getLastPollId = getLastPollId;
+exports.resolveToken = resolveToken;
+let cachedToken = null;
+let lastPollId = null;
+function getCachedToken() {
+    return cachedToken;
+}
+function setCachedToken(token) {
+    cachedToken = token;
+}
+function clearCachedToken() {
+    cachedToken = null;
+}
+function setLastPollId(pollId) {
+    lastPollId = pollId;
+}
+function getLastPollId() {
+    return lastPollId;
+}
+/** Resolve token: prefer provided token, else cached. Returns null if neither. */
+function resolveToken(provided) {
+    const t = (provided ?? "").trim();
+    if (t)
+        return t;
+    return getCachedToken();
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Simple logger for MCP module. Can be replaced with a shared SBOX logger if one exists.
+ */
+export interface Logger {
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+    debug(msg: string, meta?: Record<string, unknown>): void;
+}
+export declare const logger: Logger;

package/dist/utils/logger.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Simple logger for MCP module. Can be replaced with a shared SBOX logger if one exists.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+const isProd = process.env.NODE_ENV === "production";
+function format(level, msg, meta) {
+    const ts = new Date().toISOString();
+    const m = meta && Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : "";
+    return `${ts} [${level}] ${msg}${m}`;
+}
+exports.logger = {
+    info(msg, meta) {
+        console.info(format("INFO", msg, meta));
+    },
+    warn(msg, meta) {
+        console.warn(format("WARN", msg, meta));
+    },
+    error(msg, meta) {
+        console.error(format("ERROR", msg, meta));
+    },
+    debug(msg, meta) {
+        if (!isProd)
+            console.debug(format("DEBUG", msg, meta));
+    },
+};

package/dist/utils/open-browser.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Open a URL in the system default browser. Cross-platform via spawn (no shell).
+ * Returns true if open succeeded, false otherwise (e.g. headless environment).
+ * Never throws; callers can continue (e.g. return auth_url for IDE to open).
+ */
+export declare function openUrlInBrowser(url: string): Promise<boolean>;

package/dist/utils/open-browser.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Open a URL in the system default browser. Cross-platform via spawn (no shell).
+ * Returns true if open succeeded, false otherwise (e.g. headless environment).
+ * Never throws; callers can continue (e.g. return auth_url for IDE to open).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openUrlInBrowser = openUrlInBrowser;
+const child_process_1 = require("child_process");
+const os_1 = require("os");
+function openUrlInBrowser(url) {
+    return new Promise((resolve) => {
+        const plat = (0, os_1.platform)();
+        const [cmd, args] = plat === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : plat === "darwin"
+                ? ["open", [url]]
+                : ["xdg-open", [url]];
+        const child = (0, child_process_1.spawn)(cmd, args, { stdio: "ignore" });
+        child.on("error", () => resolve(false));
+        child.on("close", (code) => resolve(code === 0));
+    });
+}

package/dist/utils/time-range.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Builds query string for SBOX time-range params. Backend accepts either days or unit+value.
+ */
+export type TimeRange = {
+    days: number;
+} | {
+    unit: "hour" | "minute" | "day";
+    value: number;
+};
+export declare function buildTimeQuery(timeRange: TimeRange): string;
+export declare function parseTimeToRange(value: number, unit: "hour" | "minute" | "day"): TimeRange;

package/dist/utils/time-range.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTimeQuery = buildTimeQuery;
+exports.parseTimeToRange = parseTimeToRange;
+function buildTimeQuery(timeRange) {
+    if ("days" in timeRange) {
+        const days = Math.max(1, Math.min(365, timeRange.days));
+        return `days=${days}`;
+    }
+    const value = Math.max(1, timeRange.value);
+    const unit = timeRange.unit;
+    return `unit=${encodeURIComponent(unit)}&value=${value}`;
+}
+function parseTimeToRange(value, unit) {
+    return { unit, value };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@seleniumbox/sbox-mcp",
+  "version": "0.2.0",
+  "description": "SBOX MCP – Model Context Protocol server for Selenium Box.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/seleniumbox/selenium-box"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "sbox-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": ["dist", "README.md", "LICENSE", "PUBLISHING.md"],
+  "scripts": {
+    "build": "node --max-old-space-size=4096 ./node_modules/typescript/bin/tsc && node scripts/add-shebang.js",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "rebuild": "npm run clean && npm run build",
+    "start": "node dist/index.js",
+    "dev": "ts-node-dev --respawn --transpile-only src/index.ts",
+    "server": "node dist/server.js",
+    "dev:server": "ts-node-dev --respawn --transpile-only src/server.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "axios": "^1.7.7",
+    "express": "^4.21.0",
+    "form-data": "^4.0.0",
+    "multer": "^1.4.5-lts.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/multer": "^1.4.11",
+    "@types/node": "^22.5.0",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.5.4"
+  }
+}