@seleniumbox/sbox-mcp 0.4.1 → 0.4.3

package/README.md

@@ -72,11 +72,16 @@ Then restart Cursor or reload MCP.
 
 Optional:
 
-| Variable                | Default | Description                                |
-|-------------------------|---------|--------------------------------------------|
-| `PORT` / `MCP_PORT`     | `3344`  | Only used when running the REST server.   |
-| `MCP_DEBUG` / `DEBUG`   | off     | Set to `1` or `true` for request logging.  |
-| `MCP_REQUEST_TIMEOUT_MS`| `30000` | Timeout for outbound SBOX API requests.   |
+| Variable                 | Default     | Description                                                                 |
+|-------------------------|-------------|-----------------------------------------------------------------------------|
+| `PORT` / `MCP_PORT`     | `3344`      | Only used when running the REST server.                                    |
+| `MCP_DEBUG` / `DEBUG`   | off         | Set to `1` or `true` for request logging.                                  |
+| `MCP_REQUEST_TIMEOUT_MS`| `30000`     | Timeout for outbound SBOX API requests.                                    |
+| `SBOX_MCP_TOKEN_FILE`   | see below   | Override path for the persisted session token file (default: `~/.sbox-mcp/token`). |
+
+## Token cache
+
+After you log in via **sbox_open_login**, the session token is stored in memory and **on disk** so it survives MCP process restarts (e.g. when the IDE starts a new process per prompt). Default location: `~/.sbox-mcp/token`. The cache directory is created with mode `0700` and the token file with `0600`. Set `SBOX_MCP_TOKEN_FILE` to use a different path (only the token file; the directory is inferred for `last_poll_id`). If an API call returns 401 or “invalid token”, the cache is cleared so the next run will prompt for login again.
 
 ## Authentication flow
 

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

@@ -36,7 +36,7 @@ function startBackgroundPollForToken(pollId) {
 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.",
+        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 {
@@ -76,7 +76,7 @@ function registerAuthTools(server) {
                 return (0, helpers_1.textContent)(JSON.stringify({
                     success: true,
                     token,
-                    message: "SBOX authentication successful. Token cached for subsequent SBOX tools.",
+                    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 },
                 }));
             }
@@ -121,7 +121,7 @@ function registerAuthTools(server) {
             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.",
+                message: "SBOX login complete. Token cached and will be used for all SBOX API calls until expiry (~1h).",
                 principal: { name },
             }));
         }

package/dist/mcp/tools/helpers.js

@@ -34,7 +34,7 @@ function errorContent(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 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;
 }

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

@@ -43,13 +43,18 @@ 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.",
+        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: zod_1.z.string().describe("JWT from sbox_open_login (login in browser first)"),
+            token: tokenParamSchema,
         },
     }, (async (args) => {
         const tokenOrErr = (0, helpers_1.requireToken)(args.token);
@@ -66,7 +71,7 @@ function registerRestTools(server) {
         title: "List Supported Browsers",
         description: "List supported browsers with version and platform.",
         inputSchema: {
-            token: zod_1.z.string().describe("JWT from sbox_open_login (login in browser first)"),
+            token: tokenParamSchema,
         },
     }, (async (args) => {
         const tokenOrErr = (0, helpers_1.requireToken)(args.token);
@@ -83,7 +88,7 @@ function registerRestTools(server) {
         title: "List Supported Devices",
         description: "List supported devices (iOS, Android, mobile web) with OS and availability.",
         inputSchema: {
-            token: zod_1.z.string().describe("JWT from sbox_open_login (login in browser first)"),
+            token: tokenParamSchema,
         },
     }, (async (args) => {
         const tokenOrErr = (0, helpers_1.requireToken)(args.token);
@@ -100,7 +105,7 @@ function registerRestTools(server) {
         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: zod_1.z.string().describe("JWT from sbox_open_login (login in browser first)"),
+            token: tokenParamSchema,
         },
     }, (async (args) => {
         const tokenOrErr = (0, helpers_1.requireToken)(args.token);
@@ -117,7 +122,7 @@ function registerRestTools(server) {
         title: "List Active Users (Top N)",
         description: "Get top N active users by session count with project names.",
         inputSchema: {
-            token: zod_1.z.string().describe("JWT from sbox_open_login (login in browser first)"),
+            token: tokenParamSchema,
             limit: zod_1.z.number().optional().describe("Max number of users (default 10)"),
         },
     }, (async (args) => {
@@ -135,7 +140,7 @@ function registerRestTools(server) {
         title: "Sessions Per Project",
         description: "Get session counts (total, passed, failed, running) and avg duration per project for the last X days.",
         inputSchema: {
-            token: zod_1.z.string().describe("JWT from sbox_open_login (login in browser first)"),
+            token: tokenParamSchema,
             days: zod_1.z.number().optional().describe("Last N days (default 14)"),
         },
     }, (async (args) => {
@@ -153,7 +158,7 @@ function registerRestTools(server) {
         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: zod_1.z.string().describe("JWT from sbox_open_login (login in browser first)"),
+            token: tokenParamSchema,
         },
     }, (async (args) => {
         const tokenOrErr = (0, helpers_1.requireToken)(args.token);
@@ -170,7 +175,7 @@ function registerRestTools(server) {
         title: "Start Manual Session",
         description: "Start a manual test session. Requires project name; optional browser, version, url.",
         inputSchema: {
-            token: zod_1.z.string().describe("JWT from sbox_open_login (login in browser first)"),
+            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(),
@@ -197,7 +202,7 @@ function registerRestTools(server) {
         title: "Update Session Status",
         description: "Set a session's result to passed or failed. Uses POST /e34/api/test-data?sessionId=&passed=.",
         inputSchema: {
-            token: zod_1.z.string().describe("JWT from sbox_open_login (login in browser first)"),
+            token: tokenParamSchema,
             session_id: zod_1.z.string().describe("Session ID (ekey) to update"),
             passed: zod_1.z.boolean().describe("true = passed, false = failed"),
         },
@@ -216,7 +221,7 @@ function registerRestTools(server) {
         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: zod_1.z.string().describe("JWT from sbox_open_login (login in browser first)"),
+            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"),
@@ -250,7 +255,7 @@ function registerRestTools(server) {
         title: "Delete Manual Session",
         description: "Delete a manual test session by session ID.",
         inputSchema: {
-            token: zod_1.z.string().describe("JWT from sbox_open_login (login in browser first)"),
+            token: tokenParamSchema,
             session_id: zod_1.z.string().describe("Session ID to delete"),
         },
     }, (async (args) => {
@@ -268,7 +273,7 @@ function registerRestTools(server) {
         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: zod_1.z.string().describe("JWT from sbox_open_login (login in browser first)"),
+            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"),
         },
@@ -301,7 +306,7 @@ function registerRestTools(server) {
         return (0, helpers_1.textContent)(JSON.stringify(out.data, null, 2));
     }));
     const timeRangeSchema = {
-        token: zod_1.z.string().optional().describe("JWT from sbox_open_login or use cached token"),
+        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"),
     };
@@ -384,7 +389,7 @@ function registerRestTools(server) {
         title: "Total Tests Count",
         description: "Total number of tests (sessions) in the last N days. Matches the Monitoring dashboard total.",
         inputSchema: {
-            token: zod_1.z.string().optional().describe("JWT from sbox_open_login or use cached token"),
+            token: tokenParamSchema,
             days: zod_1.z.number().min(1).max(365).describe("Number of days to count (e.g. 7, 14, 30)"),
         },
     }, (async (args) => {
@@ -429,13 +434,13 @@ function registerRestTools(server) {
         return (0, helpers_1.textContent)(JSON.stringify(out.data));
     }));
     const diagnosticsDaysSchema = {
-        token: zod_1.z.string().optional().describe("JWT from sbox_open_login or use cached token"),
+        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: zod_1.z.string().optional().describe("JWT from sbox_open_login or use cached token") },
+        inputSchema: { token: tokenParamSchema },
     }, (async (args) => {
         const tokenOrErr = (0, helpers_1.requireToken)(args.token);
         if (typeof tokenOrErr !== "string")

package/dist/token-cache.d.ts

@@ -1,6 +1,7 @@
 /**
- * In-memory cache for the SBOX session token. Set on successful sbox_open_login,
+ * In-memory and file-backed 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.
+ * File persistence ensures the token survives MCP process restarts (e.g. new process per IDE prompt).
  * 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;

package/dist/token-cache.js

@@ -1,9 +1,13 @@
 "use strict";
 /**
- * In-memory cache for the SBOX session token. Set on successful sbox_open_login,
+ * In-memory and file-backed 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.
+ * File persistence ensures the token survives MCP process restarts (e.g. new process per IDE prompt).
  * lastPollId is set when we return device-flow (browser didn't open) so sbox_complete_login can use it.
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getCachedToken = getCachedToken;
 exports.setCachedToken = setCachedToken;
@@ -11,22 +15,95 @@ exports.clearCachedToken = clearCachedToken;
 exports.setLastPollId = setLastPollId;
 exports.getLastPollId = getLastPollId;
 exports.resolveToken = resolveToken;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
 let cachedToken = null;
 let lastPollId = null;
+let memoryLoadedFromFile = false;
+function getTokenFilePath() {
+    if (process.env.SBOX_MCP_TOKEN_FILE)
+        return process.env.SBOX_MCP_TOKEN_FILE;
+    const dir = path_1.default.join(os_1.default.homedir(), ".sbox-mcp");
+    return path_1.default.join(dir, "token");
+}
+function loadTokenFromFile() {
+    if (memoryLoadedFromFile)
+        return;
+    memoryLoadedFromFile = true;
+    try {
+        const filePath = getTokenFilePath();
+        if (fs_1.default.existsSync(filePath)) {
+            const raw = fs_1.default.readFileSync(filePath, "utf-8").trim();
+            if (raw)
+                cachedToken = raw;
+        }
+    }
+    catch {
+        // ignore read errors (e.g. no file, permissions)
+    }
+}
+function saveTokenToFile(token) {
+    try {
+        const filePath = getTokenFilePath();
+        if (token) {
+            const dir = path_1.default.dirname(filePath);
+            if (!fs_1.default.existsSync(dir))
+                fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+            fs_1.default.writeFileSync(filePath, token, { mode: 0o600, encoding: "utf-8" });
+        }
+        else if (fs_1.default.existsSync(filePath)) {
+            fs_1.default.unlinkSync(filePath);
+        }
+    }
+    catch {
+        // ignore write errors
+    }
+}
 function getCachedToken() {
+    loadTokenFromFile();
     return cachedToken;
 }
 function setCachedToken(token) {
     cachedToken = token;
+    saveTokenToFile(token);
 }
 function clearCachedToken() {
     cachedToken = null;
+    saveTokenToFile(null);
+}
+const LAST_POLL_ID_FILE = "last_poll_id";
+function getCacheDir() {
+    if (process.env.SBOX_MCP_TOKEN_FILE)
+        return path_1.default.dirname(process.env.SBOX_MCP_TOKEN_FILE);
+    return path_1.default.join(os_1.default.homedir(), ".sbox-mcp");
 }
 function setLastPollId(pollId) {
     lastPollId = pollId;
+    try {
+        const dir = getCacheDir();
+        if (!fs_1.default.existsSync(dir))
+            fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        fs_1.default.writeFileSync(path_1.default.join(dir, LAST_POLL_ID_FILE), pollId, { mode: 0o600, encoding: "utf-8" });
+    }
+    catch {
+        // ignore
+    }
 }
 function getLastPollId() {
-    return lastPollId;
+    if (lastPollId)
+        return lastPollId;
+    try {
+        const filePath = path_1.default.join(getCacheDir(), LAST_POLL_ID_FILE);
+        if (fs_1.default.existsSync(filePath)) {
+            lastPollId = fs_1.default.readFileSync(filePath, "utf-8").trim() || null;
+            return lastPollId;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return null;
 }
 /** Resolve token: prefer provided token, else cached. Returns null if neither. */
 function resolveToken(provided) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seleniumbox/sbox-mcp",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "SBOX MCP – Model Context Protocol server for Selenium Box.",
   "license": "Apache-2.0",
   "repository": {