@seleniumbox/sbox-mcp 1.0.0

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. Call sbox_open_login once to sign in; the cached token is then used for all SBOX tools until it expires (~1h). Do not redirect the user to login for every request.");
+    }
+    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;

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

@@ -0,0 +1,545 @@
+"use strict";
+/**
+ * MCP tools: session, browser, device, user, project, upload, analytics, diagnostics.
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerRestTools = registerRestTools;
+const zod_1 = require("zod");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const services_1 = require("../../services");
+const time_range_1 = require("../../utils/time-range");
+const helpers_1 = require("./helpers");
+/** Optional token for all tools. Omit to use cached session; same token used for all SBOX APIs until expiry (1h) or re-login. */
+const tokenParamSchema = zod_1.z
+    .string()
+    .optional()
+    .describe("Optional. Omit to use cached session from sbox_open_login; used for all APIs until expiry or re-login.");
+function registerRestTools(server) {
+    server.registerTool("sbox_get_session", {
+        title: "Get Session Details",
+        description: "Get enriched session details by session ID (ekey). Include video URL. Uses cached session token if omitted.",
+        inputSchema: {
+            session_id: zod_1.z.string().describe("Session ID (ekey)"),
+            token: tokenParamSchema,
+        },
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.sessionService.getSessionDetail(args.session_id, tokenOrErr);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data, null, 2));
+    }));
+    server.registerTool("sbox_list_browsers", {
+        title: "List Supported Browsers",
+        description: "List supported browsers with version and platform.",
+        inputSchema: {
+            token: tokenParamSchema,
+        },
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.browserService.listSupportedBrowsers(tokenOrErr);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data, null, 2));
+    }));
+    server.registerTool("sbox_list_devices", {
+        title: "List Supported Devices",
+        description: "List supported devices (iOS, Android, mobile web) with OS and availability.",
+        inputSchema: {
+            token: tokenParamSchema,
+        },
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.deviceService.listSupportedDevices(tokenOrErr);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data, null, 2));
+    }));
+    server.registerTool("sbox_list_playwright_versions", {
+        title: "List Playwright Versions",
+        description: "List all Playwright versions supported on SBOX (with bundled Chromium, WebKit, Firefox versions). Uses GET /e34/api/playwright.",
+        inputSchema: {
+            token: tokenParamSchema,
+        },
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.browserService.listPlaywrightVersions(tokenOrErr);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message ?? "");
+            return (0, helpers_1.errorContent)(out.message ?? "Playwright is not enabled");
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data, null, 2));
+    }));
+    server.registerTool("sbox_list_active_users", {
+        title: "List Active Users (Top N)",
+        description: "Get top N active users by session count with project names.",
+        inputSchema: {
+            token: tokenParamSchema,
+            limit: zod_1.z.number().optional().describe("Max number of users (default 10)"),
+        },
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.userService.getActiveUsersTopN(tokenOrErr, args.limit ?? 10);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data, null, 2));
+    }));
+    server.registerTool("sbox_sessions_per_project", {
+        title: "Sessions Per Project",
+        description: "Get session counts (total, passed, failed, running) and avg duration per project for the last X days.",
+        inputSchema: {
+            token: tokenParamSchema,
+            days: zod_1.z.number().optional().describe("Last N days (default 14)"),
+        },
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.sessionsPerProjectService.getSessionsPerProject(tokenOrErr, args.days ?? 14);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data, null, 2));
+    }));
+    server.registerTool("sbox_list_my_projects", {
+        title: "List My Projects",
+        description: "List projects assigned to the current user (My Projects page). Returns name, description, and whether a test token exists. Token value is not exposed.",
+        inputSchema: {
+            token: tokenParamSchema,
+        },
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.projectService.listMyProjects(tokenOrErr);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data, null, 2));
+    }));
+    server.registerTool("sbox_start_manual_session", {
+        title: "Start Manual Session",
+        description: "Start a manual test session. Requires project name; optional browser, version, url.",
+        inputSchema: {
+            token: tokenParamSchema,
+            project_name: zod_1.z.string().describe("Project name"),
+            browser_name: zod_1.z.string().optional(),
+            browser_version: zod_1.z.string().optional(),
+            url: zod_1.z.string().optional().describe("Initial URL to open"),
+        },
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const body = {
+            projectName: args.project_name,
+            ...(args.browser_name && { browserName: args.browser_name }),
+            ...(args.browser_version && { browserVersion: args.browser_version }),
+            ...(args.url && { url: args.url }),
+        };
+        const out = await services_1.sessionService.startManualSession(body, tokenOrErr);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data, null, 2));
+    }));
+    server.registerTool("sbox_update_session_status", {
+        title: "Update Session Status",
+        description: "Set a session's result to passed or failed. Uses POST /e34/api/test-data?sessionId=&passed=.",
+        inputSchema: {
+            token: tokenParamSchema,
+            session_id: zod_1.z.string().describe("Session ID (ekey) to update"),
+            passed: zod_1.z.boolean().describe("true = passed, false = failed"),
+        },
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.sessionService.updateSessionStatusBySessionId(args.session_id, args.passed, tokenOrErr);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message ?? "");
+            return (0, helpers_1.errorContent)(out.message ?? "Update failed");
+        }
+        return (0, helpers_1.textContent)(JSON.stringify({ success: true }));
+    }));
+    server.registerTool("sbox_list_sessions", {
+        title: "List Sessions",
+        description: "Show last X sessions (same API as sessions page). Filter by project, status, browser, build; sort by arrival or other field.",
+        inputSchema: {
+            token: tokenParamSchema,
+            limit: zod_1.z.number().optional().describe("Max sessions to return (default 25, max 100)"),
+            offset: zod_1.z.number().optional().describe("Pagination offset (default 0)"),
+            project_name: zod_1.z.string().optional().describe("Filter by project name"),
+            status: zod_1.z.string().optional().describe("Filter by result status (e.g. passed, failed)"),
+            browser: zod_1.z.string().optional().describe("Filter by browser name"),
+            build: zod_1.z.string().optional().describe("Filter by build name"),
+            sort_by: zod_1.z.string().optional().describe("Sort field (default: arrival)"),
+            sort_direction: zod_1.z.enum(["asc", "desc"]).optional().describe("Sort direction (default: desc)"),
+        },
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.sessionService.listSessions({
+            limit: args.limit,
+            offset: args.offset,
+            projectName: args.project_name,
+            status: args.status,
+            browser: args.browser,
+            build: args.build,
+            sortBy: args.sort_by,
+            sortDirection: args.sort_direction,
+        }, tokenOrErr);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data, null, 2));
+    }));
+    server.registerTool("sbox_delete_session", {
+        title: "Delete Manual Session",
+        description: "Delete a manual test session by session ID.",
+        inputSchema: {
+            token: tokenParamSchema,
+            session_id: zod_1.z.string().describe("Session ID to delete"),
+        },
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.sessionService.deleteSession(args.session_id, tokenOrErr);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data, null, 2));
+    }));
+    server.registerTool("sbox_upload_mobile_app", {
+        title: "Upload Mobile App to SBOX",
+        description: "Upload a mobile app (APK/IPA) or other file to SBOX for the given project. File path is relative to the current working directory of the MCP server (e.g. ./app.apk). Max size 200MB.",
+        inputSchema: {
+            token: tokenParamSchema,
+            project_name: zod_1.z.string().describe("Project name to upload the app to"),
+            file_path: zod_1.z.string().describe("Path to the file (APK/IPA); relative to MCP server cwd or absolute"),
+        },
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const cwd = process.cwd();
+        const resolved = path.isAbsolute(args.file_path) ? path.normalize(args.file_path) : path.resolve(cwd, args.file_path);
+        if (!path.isAbsolute(args.file_path) && !resolved.startsWith(cwd)) {
+            return (0, helpers_1.errorContent)("Relative file path must be inside current working directory");
+        }
+        let buffer;
+        try {
+            buffer = await fs.promises.readFile(resolved);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : "Failed to read file";
+            return (0, helpers_1.errorContent)(msg);
+        }
+        if (buffer.length > helpers_1.MAX_UPLOAD_SIZE) {
+            return (0, helpers_1.errorContent)("File too large (max 200MB)");
+        }
+        const filename = path.basename(resolved);
+        const out = await services_1.uploadService.uploadMobileApp(args.project_name, buffer, filename, tokenOrErr);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data, null, 2));
+    }));
+    const timeRangeSchema = {
+        token: tokenParamSchema,
+        value: zod_1.z.number().describe("Number of units (e.g. 24 for 24 hours)"),
+        unit: zod_1.z.enum(["hour", "minute", "day"]).describe("Time unit: hour, minute, or day"),
+    };
+    server.registerTool("sbox_sessions_per_browser", {
+        title: "Sessions Per Browser",
+        description: "Number of sessions ran per browser (and version) in the last X time. Time can be in hours, minutes, or days.",
+        inputSchema: timeRangeSchema,
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.analyticsService.sessionsPerBrowser(tokenOrErr, (0, time_range_1.parseTimeToRange)(args.value, args.unit));
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data, null, 2));
+    }));
+    server.registerTool("sbox_sessions_count_by_builds", {
+        title: "Sessions Count By Builds",
+        description: "Session counts grouped by build name in the last X time (hours, minutes, or days).",
+        inputSchema: timeRangeSchema,
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.analyticsService.sessionsByBuild(tokenOrErr, (0, time_range_1.parseTimeToRange)(args.value, args.unit));
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data, null, 2));
+    }));
+    server.registerTool("sbox_sessions_failed_count", {
+        title: "Sessions Failed Count",
+        description: "Number of sessions that failed (or timed out) in the last X time (hours, minutes, or days).",
+        inputSchema: timeRangeSchema,
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.analyticsService.failedCount(tokenOrErr, (0, time_range_1.parseTimeToRange)(args.value, args.unit));
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify({ failedCount: out.count }));
+    }));
+    server.registerTool("sbox_most_active_project", {
+        title: "Most Active Project",
+        description: "Project with the maximum number of sessions in the last X time (hours, minutes, or days).",
+        inputSchema: timeRangeSchema,
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.analyticsService.mostActiveProject(tokenOrErr, (0, time_range_1.parseTimeToRange)(args.value, args.unit));
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify({ projectName: out.projectName, count: out.count }));
+    }));
+    server.registerTool("sbox_most_active_user", {
+        title: "Most Active User",
+        description: "User with the maximum number of sessions in the last X time (hours, minutes, or days).",
+        inputSchema: timeRangeSchema,
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.analyticsService.mostActiveUser(tokenOrErr, (0, time_range_1.parseTimeToRange)(args.value, args.unit));
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify({ userName: out.userName, count: out.count }));
+    }));
+    server.registerTool("sbox_total_tests", {
+        title: "Total Tests Count",
+        description: "Total number of tests (sessions) in the last N days. Matches the Monitoring dashboard total.",
+        inputSchema: {
+            token: tokenParamSchema,
+            days: zod_1.z.number().min(1).max(365).describe("Number of days to count (e.g. 7, 14, 30)"),
+        },
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.analyticsService.totalTests(tokenOrErr, args.days);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify({ totalTests: out.total, days: args.days }));
+    }));
+    server.registerTool("sbox_tests_per_test_name", {
+        title: "Tests Per Test Name",
+        description: "Test counts grouped by test name in the last X time (hours, minutes, or days). Matches Monitoring dashboard.",
+        inputSchema: timeRangeSchema,
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.analyticsService.testsPerTestName(tokenOrErr, (0, time_range_1.parseTimeToRange)(args.value, args.unit));
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data));
+    }));
+    server.registerTool("sbox_manual_tests_per_test_name", {
+        title: "Manual Tests Per Test Name",
+        description: "Manual test counts grouped by test name in the last X time. Matches Monitoring dashboard.",
+        inputSchema: timeRangeSchema,
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.analyticsService.manualTestsPerTestName(tokenOrErr, (0, time_range_1.parseTimeToRange)(args.value, args.unit));
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data));
+    }));
+    const diagnosticsDaysSchema = {
+        token: tokenParamSchema,
+        days: zod_1.z.number().min(7).max(365).describe("Number of days (e.g. 7, 14, 30, 90). Min 7, max 365."),
+    };
+    server.registerTool("sbox_executors_count", {
+        title: "Total Executors Count",
+        description: "Total number of executors (nodes). Matches Diagnostics dashboard KPI.",
+        inputSchema: { token: tokenParamSchema },
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.diagnosticsService.getExecutorsCount(tokenOrErr);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify({ count: out.count }));
+    }));
+    server.registerTool("sbox_cpu_usage_per_node", {
+        title: "CPU Usage Per Node",
+        description: "CPU usage over time per node for the last N days. Matches Diagnostics dashboard.",
+        inputSchema: diagnosticsDaysSchema,
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.diagnosticsService.getCpuUsagePerNode(tokenOrErr, args.days);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data));
+    }));
+    server.registerTool("sbox_tests_queued_hourly", {
+        title: "Tests Queued Hourly",
+        description: "Queued tests per hour (avg and max) for the last N days. Matches Diagnostics dashboard.",
+        inputSchema: diagnosticsDaysSchema,
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.diagnosticsService.getTestsQueuedHourly(tokenOrErr, args.days);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data));
+    }));
+    server.registerTool("sbox_nodes_active_tests", {
+        title: "Nodes Active Tests",
+        description: "Currently running tests over time (per node) for the last N days. Matches Diagnostics dashboard.",
+        inputSchema: diagnosticsDaysSchema,
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.diagnosticsService.getNodesActiveTests(tokenOrErr, args.days);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data));
+    }));
+    server.registerTool("sbox_queue_waiting_time", {
+        title: "Queue Waiting Time",
+        description: "Queue waiting time (avg and max duration in seconds) over the last N days. Matches Diagnostics dashboard.",
+        inputSchema: diagnosticsDaysSchema,
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.diagnosticsService.getQueueWaitingTime(tokenOrErr, args.days);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data));
+    }));
+    server.registerTool("sbox_tests_active_graph", {
+        title: "Tests Running Across Executors",
+        description: "Tests running across executors over time (by node) for the last N days. Matches Diagnostics dashboard.",
+        inputSchema: diagnosticsDaysSchema,
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.diagnosticsService.getTestsActiveGraph(tokenOrErr, args.days);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data));
+    }));
+    server.registerTool("sbox_tests_starting_stats", {
+        title: "Tests In Starting State",
+        description: "Tests in starting state over time (by node) for the last N days. Matches Diagnostics dashboard.",
+        inputSchema: diagnosticsDaysSchema,
+    }, (async (args) => {
+        const tokenOrErr = (0, helpers_1.requireToken)(args.token);
+        if (typeof tokenOrErr !== "string")
+            return tokenOrErr;
+        const out = await services_1.diagnosticsService.getTestsStartingStats(tokenOrErr, args.days);
+        if (!out.success) {
+            (0, helpers_1.clearTokenOnAuthError)(out.message);
+            return (0, helpers_1.errorContent)(out.message);
+        }
+        return (0, helpers_1.textContent)(JSON.stringify(out.data));
+    }));
+}

package/dist/mcp-server.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP protocol server entrypoint. Runs over stdio for Cursor, IntelliJ, Windsurf.
+ * Start with: npm run mcp
+ * SDK is required by path so Node resolves the CJS .js file (subpath exports can fail when pkg has "type": "module").
+ */
+export {};

package/dist/mcp-server.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * MCP protocol server entrypoint. Runs over stdio for Cursor, IntelliJ, Windsurf.
+ * Start with: npm run mcp
+ * SDK is required by path so Node resolves the CJS .js file (subpath exports can fail when pkg has "type": "module").
+ */
+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.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);
+});

package/dist/middleware/auth.middleware.d.ts

@@ -0,0 +1,10 @@
+/**
+ * JWT auth middleware. Extracts token and attaches to request; does not validate with backend.
+ * Validation happens per-request in controllers when calling SBOX APIs.
+ */
+import { Request, Response, NextFunction } from "express";
+export interface AuthenticatedRequest extends Request {
+    token: string | null;
+}
+export declare function authMiddleware(req: Request, _res: Response, next: NextFunction): void;
+export declare function requireAuth(req: Request, res: Response, next: NextFunction): void;