@squidlerio/squidler-mcp 1.0.0

package/README.md

@@ -0,0 +1,99 @@
+# @squidlerio/mcp
+
+MCP proxy that sits between an AI client (Claude, Cursor, etc.) and the remote Squidler MCP server. It forwards all tools, resources, and prompts transparently, while adding local Chrome session management for testing localhost URLs.
+
+## How it works
+
+```
+AI Client (stdio) ←→ MCP Proxy ←→ Remote Squidler MCP (HTTP)
+                        ↕
+                   Local Chrome ←→ CDP Proxy (WebSocket)
+```
+
+The proxy intercepts `test_case_run` calls — when local Chrome mode is enabled, it automatically creates a CDP session and routes the test through your local browser instead of the cloud worker's Chrome.
+
+## Quick Start
+
+Run directly with npx — no install or API key needed:
+
+```bash
+npx @squidlerio/mcp
+```
+
+On first use, a browser window opens for you to sign in to Squidler. Your session is saved locally so you only need to do this once.
+
+### Claude Code
+
+```bash
+claude mcp add squidler -- npx -y @squidlerio/mcp
+```
+
+### Cursor / Other MCP Clients
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "squidler": {
+      "command": "npx",
+      "args": ["-y", "@squidlerio/mcp"]
+    }
+  }
+}
+```
+
+## CLI Commands
+
+```bash
+# Sign in to Squidler (happens automatically on first use)
+squidler-mcp login
+
+# Sign out and clear saved session
+squidler-mcp logout
+
+# Download Chrome headless shell for local testing
+squidler-mcp download-chrome
+```
+
+## Local Session Tools
+
+These tools are added by the proxy (not available on the remote server):
+
+- **`local_session_start`** — Enable local Chrome mode. Accepts `headless` (boolean, default: true). Chrome is launched on the first `test_case_run`.
+- **`local_session_stop`** — Disable local Chrome mode and stop any active session.
+- **`local_session_status`** — Check if local Chrome mode is enabled and if a session is active.
+
+When local Chrome mode is enabled, `test_case_run` automatically creates/recycles a CDP session and routes through your local Chrome. Back-to-back tests get a fresh Chrome instance each time.
+
+## Advanced: API Key Override
+
+If you prefer to use an API key instead of OAuth login, set the `SQUIDLER_API_KEY` environment variable:
+
+```json
+{
+  "mcpServers": {
+    "squidler": {
+      "command": "npx",
+      "args": ["-y", "@squidlerio/mcp"],
+      "env": {
+        "SQUIDLER_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `SQUIDLER_API_KEY` | No | — | API key override (skips OAuth login) |
+| `SQUIDLER_API_URL` | No | `https://mcp.squidler.io` | Remote MCP server URL |
+
+## Development
+
+```bash
+bun install
+bun run start          # Run CLI
+bun run mcp-proxy      # Run MCP proxy
+bun run build          # Build for npm publishing
+```

package/dist/cli-hhgt3239.js

@@ -0,0 +1,370 @@
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/chrome/download.ts
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import * as https from "https";
+import * as unzipper from "unzipper";
+var DEFAULT_CHROME_VERSION = "136.0.7103.59";
+function getPlatform() {
+  const platform2 = os.platform();
+  const arch2 = os.arch();
+  if (platform2 === "darwin") {
+    return arch2 === "arm64" ? "mac-arm64" : "mac-x64";
+  } else if (platform2 === "linux") {
+    return "linux64";
+  } else if (platform2 === "win32") {
+    return "win64";
+  }
+  throw new Error(`Unsupported platform: ${platform2} ${arch2}`);
+}
+function getChromePath(extractDir, platform2) {
+  const baseName = "chrome-headless-shell-" + platform2;
+  switch (platform2) {
+    case "mac-arm64":
+    case "mac-x64":
+      return path.join(extractDir, baseName, "chrome-headless-shell");
+    case "linux64":
+      return path.join(extractDir, baseName, "chrome-headless-shell");
+    case "win64":
+      return path.join(extractDir, baseName, "chrome-headless-shell.exe");
+    default:
+      throw new Error(`Unknown platform: ${platform2}`);
+  }
+}
+async function downloadFile(url, destPath) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(destPath);
+    const request = https.get(url, (response) => {
+      if (response.statusCode === 301 || response.statusCode === 302) {
+        const redirectUrl = response.headers.location;
+        if (redirectUrl) {
+          file.close();
+          fs.unlinkSync(destPath);
+          downloadFile(redirectUrl, destPath).then(resolve).catch(reject);
+          return;
+        }
+      }
+      if (response.statusCode !== 200) {
+        reject(new Error(`Failed to download: HTTP ${response.statusCode}`));
+        return;
+      }
+      const totalSize = parseInt(response.headers["content-length"] || "0", 10);
+      let downloadedSize = 0;
+      response.on("data", (chunk) => {
+        downloadedSize += chunk.length;
+        if (totalSize > 0) {
+          const percent = Math.round(downloadedSize / totalSize * 100);
+          process.stderr.write(`\rDownloading Chrome... ${percent}%`);
+        }
+      });
+      response.pipe(file);
+      file.on("finish", () => {
+        file.close();
+        console.error(`
+Download complete.`);
+        resolve();
+      });
+    });
+    request.on("error", (err) => {
+      fs.unlink(destPath, () => {});
+      reject(err);
+    });
+    file.on("error", (err) => {
+      fs.unlink(destPath, () => {});
+      reject(err);
+    });
+  });
+}
+async function extractZip(zipPath, destDir) {
+  console.error("Extracting Chrome...");
+  return new Promise((resolve, reject) => {
+    fs.createReadStream(zipPath).pipe(unzipper.Extract({ path: destDir })).on("close", () => {
+      console.error("Extraction complete.");
+      resolve();
+    }).on("error", reject);
+  });
+}
+async function downloadChrome(options = {}) {
+  const version = options.version || process.env.SQUIDLER_CHROME_VERSION || DEFAULT_CHROME_VERSION;
+  const defaultCacheDir = path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), "squidler", "chrome");
+  const cacheDir = options.cacheDir || defaultCacheDir;
+  const platform2 = getPlatform();
+  fs.mkdirSync(cacheDir, { recursive: true });
+  const versionDir = path.join(cacheDir, version);
+  const executablePath = getChromePath(versionDir, platform2);
+  if (fs.existsSync(executablePath)) {
+    console.error(`Using cached Chrome ${version}`);
+    return { executablePath, version };
+  }
+  const url = `https://storage.googleapis.com/chrome-for-testing-public/${version}/${platform2}/chrome-headless-shell-${platform2}.zip`;
+  const zipPath = path.join(cacheDir, `chrome-${version}-${platform2}.zip`);
+  console.error(`Downloading Chrome ${version} for ${platform2}...`);
+  try {
+    await downloadFile(url, zipPath);
+    await extractZip(zipPath, versionDir);
+    fs.unlinkSync(zipPath);
+    if (platform2 !== "win64") {
+      fs.chmodSync(executablePath, 493);
+    }
+    console.error(`Chrome ${version} installed at: ${executablePath}`);
+    return { executablePath, version };
+  } catch (error) {
+    if (fs.existsSync(zipPath)) {
+      fs.unlinkSync(zipPath);
+    }
+    throw error;
+  }
+}
+
+// src/version.ts
+import { readFileSync } from "fs";
+import { dirname, join as join2 } from "path";
+import { fileURLToPath } from "url";
+var __dirname2 = dirname(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(readFileSync(join2(__dirname2, "..", "package.json"), "utf-8"));
+var VERSION = pkg.version;
+
+// src/auth/token-store.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+import * as os2 from "os";
+function getDataDir() {
+  const base = process.env.XDG_DATA_HOME || path2.join(os2.homedir(), ".local", "share");
+  return path2.join(base, "squidler");
+}
+function getAuthFilePath() {
+  return path2.join(getDataDir(), "auth.json");
+}
+function readStore() {
+  const filePath = getAuthFilePath();
+  try {
+    const data = fs2.readFileSync(filePath, "utf-8");
+    return JSON.parse(data);
+  } catch {
+    return {};
+  }
+}
+function writeStore(store) {
+  const dir = getDataDir();
+  fs2.mkdirSync(dir, { recursive: true });
+  const filePath = getAuthFilePath();
+  fs2.writeFileSync(filePath, JSON.stringify(store, null, 2), { mode: 384 });
+}
+function loadStoredAuth(serverUrl) {
+  const store = readStore();
+  return store[serverUrl] || null;
+}
+function saveStoredAuth(auth) {
+  const store = readStore();
+  store[auth.server_url] = auth;
+  writeStore(store);
+}
+function clearStoredAuth(serverUrl) {
+  const store = readStore();
+  delete store[serverUrl];
+  writeStore(store);
+}
+
+// src/auth/oauth.ts
+import * as crypto from "crypto";
+import * as os3 from "os";
+import { spawnSync } from "child_process";
+
+// src/auth/callback-server.ts
+import * as http from "http";
+var SUCCESS_HTML = `<!DOCTYPE html>
+<html><head><title>Authentication Successful</title></head>
+<body style="font-family:system-ui,sans-serif;display:flex;justify-content:center;align-items:center;height:100vh;margin:0">
+<div style="text-align:center"><h1>Authenticated!</h1><p>You can close this tab and return to your terminal.</p></div>
+</body></html>`;
+var ERROR_HTML = (msg) => `<!DOCTYPE html>
+<html><head><title>Authentication Failed</title></head>
+<body style="font-family:system-ui,sans-serif;display:flex;justify-content:center;align-items:center;height:100vh;margin:0">
+<div style="text-align:center"><h1>Authentication Failed</h1><p>${msg}</p></div>
+</body></html>`;
+function startCallbackServer() {
+  return new Promise((resolve, reject) => {
+    let onResult;
+    let onError;
+    const resultPromise = new Promise((res, rej) => {
+      onResult = res;
+      onError = rej;
+    });
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url || "/", `http://127.0.0.1`);
+      if (url.pathname !== "/callback") {
+        res.writeHead(404);
+        res.end("Not found");
+        return;
+      }
+      const error = url.searchParams.get("error");
+      if (error) {
+        const desc = url.searchParams.get("error_description") || error;
+        res.writeHead(400, { "Content-Type": "text/html" });
+        res.end(ERROR_HTML(desc));
+        onError(new Error(`OAuth error: ${desc}`));
+        return;
+      }
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+      if (!code || !state) {
+        res.writeHead(400, { "Content-Type": "text/html" });
+        res.end(ERROR_HTML("Missing code or state parameter"));
+        onError(new Error("Missing code or state in callback"));
+        return;
+      }
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(SUCCESS_HTML);
+      onResult({ code, state });
+    });
+    server.unref();
+    const timeout = setTimeout(() => {
+      server.close();
+      onError(new Error("Authentication timed out (5 minutes)"));
+    }, 5 * 60 * 1000);
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        reject(new Error("Could not get callback server port"));
+        return;
+      }
+      resolve({
+        port: address.port,
+        waitForCallback: () => resultPromise,
+        close: () => {
+          clearTimeout(timeout);
+          server.close();
+        }
+      });
+    });
+  });
+}
+
+// src/auth/oauth.ts
+async function discover(serverUrl) {
+  const res = await fetch(`${serverUrl}/.well-known/oauth-authorization-server`);
+  if (!res.ok) {
+    throw new Error(`OAuth discovery failed: HTTP ${res.status}`);
+  }
+  const metadata = await res.json();
+  if (!metadata.authorization_endpoint || !metadata.token_endpoint || !metadata.registration_endpoint) {
+    throw new Error("OAuth discovery response missing required endpoints");
+  }
+  return metadata;
+}
+async function registerClient(registrationEndpoint, redirectUri) {
+  const res = await fetch(registrationEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_name: "squidler-mcp-cli",
+      redirect_uris: [redirectUri],
+      grant_types: ["authorization_code"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "client_secret_post"
+    })
+  });
+  if (!res.ok) {
+    throw new Error(`Client registration failed: HTTP ${res.status}`);
+  }
+  return await res.json();
+}
+function generatePKCE() {
+  const verifier = crypto.randomBytes(32).toString("base64url");
+  const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+function openBrowser(url) {
+  const platform3 = os3.platform();
+  const commands = platform3 === "darwin" ? [["open", [url]]] : platform3 === "win32" ? [["cmd", ["/c", "start", "", url]]] : [
+    ["xdg-open", [url]],
+    ["sensible-browser", [url]],
+    ["x-www-browser", [url]]
+  ];
+  for (const [cmd, args] of commands) {
+    const result = spawnSync(cmd, args, { stdio: "ignore", timeout: 5000 });
+    if (!result.error && result.status === 0) {
+      return true;
+    }
+  }
+  return false;
+}
+async function exchangeToken(tokenEndpoint, params) {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: params.code,
+    redirect_uri: params.redirectUri,
+    client_id: params.clientId,
+    client_secret: params.clientSecret,
+    code_verifier: params.codeVerifier
+  });
+  const res = await fetch(tokenEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString()
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Token exchange failed: HTTP ${res.status} - ${text}`);
+  }
+  const data = await res.json();
+  if (!data.access_token) {
+    throw new Error("Token response missing access_token");
+  }
+  return data.access_token;
+}
+async function authenticateWithOAuth(serverUrl) {
+  console.error("Discovering OAuth endpoints...");
+  const metadata = await discover(serverUrl);
+  const callback = await startCallbackServer();
+  const redirectUri = `http://127.0.0.1:${callback.port}/callback`;
+  try {
+    console.error("Registering client...");
+    const client = await registerClient(metadata.registration_endpoint, redirectUri);
+    const pkce = generatePKCE();
+    const state = crypto.randomBytes(16).toString("base64url");
+    const authUrl = new URL(metadata.authorization_endpoint);
+    authUrl.searchParams.set("response_type", "code");
+    authUrl.searchParams.set("client_id", client.client_id);
+    authUrl.searchParams.set("redirect_uri", redirectUri);
+    authUrl.searchParams.set("state", state);
+    authUrl.searchParams.set("code_challenge", pkce.challenge);
+    authUrl.searchParams.set("code_challenge_method", "S256");
+    const opened = openBrowser(authUrl.toString());
+    if (opened) {
+      console.error("Browser opened for authentication. Waiting...");
+    } else {
+      console.error(`Open this URL in your browser to authenticate:
+
+  ${authUrl.toString()}
+
+Waiting for authentication...`);
+    }
+    const result = await callback.waitForCallback();
+    if (result.state !== state) {
+      throw new Error("OAuth state mismatch — possible CSRF attack");
+    }
+    console.error("Exchanging authorization code for token...");
+    const accessToken = await exchangeToken(metadata.token_endpoint, {
+      code: result.code,
+      redirectUri,
+      clientId: client.client_id,
+      clientSecret: client.client_secret,
+      codeVerifier: pkce.verifier
+    });
+    saveStoredAuth({
+      access_token: accessToken,
+      server_url: serverUrl,
+      created_at: new Date().toISOString()
+    });
+    return accessToken;
+  } finally {
+    callback.close();
+  }
+}
+
+export { __require, downloadChrome, VERSION, loadStoredAuth, clearStoredAuth, authenticateWithOAuth };