cdp-toolkit 1.11.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-toolkit",
-  "version": "1.11.0",
+  "version": "2.1.0",
   "description": "A lightweight chrome-devtools-mcp alternative: an MCP server + CLI that drives the tabs you name, one target per call over one direct WebSocket, with a bounded timeout on every call, so a stuck page can't wedge your agent or force a /mcp restart. Chrome over CDP and Firefox over WebDriver BiDi, with tools a backend can't run absent from tools/list rather than throwing mid-task. 45 tools including built-in network mocking, a cookie group, tab leases with human-activity detection, real HTML5 drag-and-drop, raw mouse/scroll dispatch, downloads, permission grants, and tab-to-video screen recording so several agents can drive one browser without stealing each other's tabs or a human's. No Puppeteer, no all-target fan-out.",
   "type": "module",
   "license": "MIT",
@@ -86,10 +86,11 @@
     "extension:smoke": "bun run ./test/extension-smoke.ts"
   },
   "devDependencies": {
+    "@modelcontextprotocol/client": "^2.0.0",
     "@types/node": "22.10.10",
     "typescript": "5.7.3"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.29.0"
+    "@modelcontextprotocol/server": "^2.0.0"
   }
 }

package/src/bidi/driver.ts

@@ -136,6 +136,20 @@ function mapBidiError(e: unknown): DriverError {
     if (code === "unsupported operation") return driverError("unsupported", e.message);
     if (!code && /timed out/i.test(e.message)) return driverError("timeout", e.message);
     if (!code && /(disposed|not open|connection closed)/i.test(e.message)) return driverError("disconnected", e.message);
+    // NS_ERROR_FILE_ACCESS_DENIED from browsingContext.navigate means the browser process was
+    // refused at the OS level while opening the file:// target — not a protocol failure. Two
+    // mechanisms produce it (#6): (1) the automation prefs that relax file:// handling were never
+    // applied — launch.ts now seeds them via user.js, so this should not surface for a
+    // toolkit-launched Firefox; (2) kernel-level confinement of the browser itself (Ubuntu's snap
+    // Firefox is the common one: a snap process cannot see host paths outside its mount
+    // namespace), which no preference can bypass. The error must name the way out rather than
+    // relay the raw nsresult.
+    if (/NS_ERROR_FILE_ACCESS_DENIED/i.test(e.message)) {
+      return driverError(
+        "page-error",
+        `${e.message} — the browser process was not allowed to open this file:// path. For a snap- or AppArmor-confined Firefox (Ubuntu default) that is kernel-level and no preference fixes it: serve the directory over a local http server (e.g. python3 -m http.server) and navigate to the http://127.0.0.1:<port>/ URL instead. If this Firefox was launched by cdp-toolkit and still fails, please report it at https://github.com/sblattj/cdp-toolkit/issues.`,
+      );
+    }
     return driverError("page-error", e.message);
   }
   return driverError("page-error", e instanceof Error ? e.message : String(e));
@@ -655,7 +669,21 @@ class BidiPageDriver implements PageDriver {
     const sendOpts = opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {};
     try {
       if (reload) {
-        const r = await this.conn.send("browsingContext.reload", { context: this.contextId, ignoreCache: opts.ignoreCache === true, wait }, sendOpts);
+        // Firefox rejects ANY `ignoreCache` argument to browsingContext.reload — even an
+        // explicit `false` — with `Argument "ignoreCache" is not supported yet` (observed on
+        // Firefox 153.0.3): the server-side validator refuses the key unconditionally, it does
+        // not read its value. So the key is OMITTED from the params unless a hard reload was
+        // actually requested, and a requested hard reload fails fast HERE with a
+        // backend-capability error instead of an opaque mid-flight protocol rejection — the
+        // same doctrine as click()'s modifiers on this backend. If a future Firefox starts
+        // honoring the argument, re-verify and lift the guard.
+        if (opts.ignoreCache === true) {
+          throw driverError(
+            "unsupported",
+            "navigate: ignoreCache:true (hard reload) is not supported on the Firefox WebDriver-BiDi backend — Firefox rejects the ignoreCache argument outright. A plain reload (reload:true, no ignoreCache) works.",
+          );
+        }
+        const r = await this.conn.send("browsingContext.reload", { context: this.contextId, wait }, sendOpts);
         return { url: r.url, contextId: this.contextId, reloaded: true, waitedFor: waitUntil };
       }
       if (history) {

package/src/bidi/launch.ts

@@ -22,7 +22,7 @@
  * node:os and node:path.
  */
 import { spawn, type ChildProcess } from "node:child_process";
-import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createConnection, createServer } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -145,6 +145,55 @@ function waitForExit(proc: ChildProcess, deadlineMs: number): Promise<void> {
   });
 }
 
+/**
+ * Automation prefs seeded into every THROWAWAY profile this toolkit launches (#6).
+ *
+ * Firefox's Remote Agent has its own recommended automation-pref bundle, but it is gated on
+ * `remote.prefs.recommended`, which DEFAULTS TO FALSE — a bare `--remote-debugging-port`
+ * launch therefore runs with consumer prefs (verified in mozilla-central's
+ * remote/shared/RecommendedPreferences.sys.mjs; `defineLazyPreferenceGetter(..., "remote.prefs.recommended", false)`).
+ * The two file://-relevant consequences, and the reason each pref is here:
+ *
+ * - `remote.prefs.recommended: true` — flips on Firefox's own bundle at BiDi session start. This
+ *   is the same mechanism geckodriver/Marionette automation leans on.
+ * - `security.fileuri.strict_origin_policy: false` — a member of that bundle, also set explicitly
+ *   so the behavior does not depend on the bundle's exact contents per Firefox version. Without
+ *   it, file:// documents get unique opaque origins and sibling file:// subresources fail.
+ * - `dom.file.createInChild: true` — the bundle's file-API automation companion pref.
+ *
+ * Only the throwaway profile is seeded. An explicit `profilePath` belongs to its owner: writing
+ * prefs into someone's real profile (where `security.fileuri.strict_origin_policy: false` would
+ * persist as a security relaxation of their daily browsing) is not this toolkit's call to make.
+ */
+const LAUNCH_USER_JS_PREFS: Record<string, boolean> = {
+  "remote.prefs.recommended": true,
+  "security.fileuri.strict_origin_policy": false,
+  "dom.file.createInChild": true,
+};
+
+/**
+ * Seed `user.js` in a profile directory with the toolkit's automation prefs. Firefox reads
+ * user.js exactly once, at profile startup — which is why this runs BEFORE spawn, never after.
+ * Merges with an existing user.js (never rewrites a pref that file already sets, never drops a
+ * line it did not write) so the function is idempotent and safe on a reused profile dir.
+ * Exported for unit tests; returns the file's final content.
+ */
+export function writeLaunchUserJs(profilePath: string): string {
+  const target = join(profilePath, "user.js");
+  const existing = existsSync(target) ? readFileSync(target, "utf8") : "";
+  const present = new Set<string>();
+  for (const line of existing.split("\n")) {
+    const m = /^user_pref\("([^"]+)"\s*,/.exec(line.trim());
+    if (m) present.add(m[1]!);
+  }
+  const additions = Object.entries(LAUNCH_USER_JS_PREFS)
+    .filter(([k]) => !present.has(k))
+    .map(([k, v]) => `user_pref("${k}", ${JSON.stringify(v)});`);
+  const content = (existing.length > 0 ? existing.replace(/\n*$/, "\n") : "") + additions.join("\n") + (additions.length > 0 ? "\n" : "");
+  if (content !== existing) writeFileSync(target, content, "utf-8");
+  return content;
+}
+
 /**
  * Launch Firefox with the BiDi debug port enabled and resolve once the port
  * actually accepts a TCP connection. Never resolves on a fixed sleep.
@@ -156,6 +205,7 @@ export async function launchFirefox(opts: LaunchFirefoxOptions = {}): Promise<La
 
   const isThrowaway = opts.profilePath === undefined;
   const profilePath = opts.profilePath ?? mkdtempSync(join(tmpdir(), "cdp-toolkit-ff-profile-"));
+  if (isThrowaway) writeLaunchUserJs(profilePath);
 
   const args = ["--profile", profilePath, "--remote-debugging-port", String(port), "--no-remote"];
   if (opts.headless) args.push("--headless");