devtools-fleet-mcp 0.1.0

package/src/lib/storage.js

@@ -0,0 +1,137 @@
+import { cookieMatchesAllowlist } from './origins.js';
+
+// Moving logins in and out of a browser: cookies through the Storage domain,
+// localStorage through a throwaway background tab.
+//
+// localStorage can only be touched from a page on that origin. Rather than
+// load the real site (side effects, analytics, a service worker answering
+// instead of the network), the tab navigates to <origin>/__devtools_fleet__
+// and fleet answers that request itself with an empty page. The site's server
+// is never contacted and its service worker is bypassed.
+
+export const PLACEHOLDER_PATH = '/__devtools_fleet__';
+
+const BLANK_HTML = Buffer.from('<!doctype html><link rel=icon href="data:,"><title>devtools-fleet</title>').toString('base64');
+
+// Cookie fields as Playwright's storageState writes them.
+export function toPlaywrightCookie(c) {
+  return {
+    name: c.name,
+    value: c.value,
+    domain: c.domain,
+    path: c.path,
+    expires: c.session ? -1 : c.expires,
+    httpOnly: c.httpOnly,
+    secure: c.secure,
+    sameSite: c.sameSite ?? 'Lax',
+    ...(c.partitionKey ? { partitionKey: c.partitionKey } : {}),
+  };
+}
+
+function toCdpCookieParam(c) {
+  const param = {
+    name: c.name,
+    value: c.value,
+    domain: c.domain,
+    path: c.path ?? '/',
+    httpOnly: Boolean(c.httpOnly),
+    secure: Boolean(c.secure),
+  };
+  if (c.sameSite) param.sameSite = c.sameSite;
+  if (typeof c.expires === 'number' && c.expires > 0) param.expires = c.expires;
+  if (c.partitionKey && typeof c.partitionKey === 'object') param.partitionKey = c.partitionKey;
+  return param;
+}
+
+/** Answer a paused request with the empty placeholder page. */
+export function fulfillPlaceholder(cdp, requestId, sessionId) {
+  return cdp.send('Fetch.fulfillRequest', {
+    requestId,
+    responseCode: 200,
+    responseHeaders: [{ name: 'content-type', value: 'text/html; charset=utf-8' }],
+    body: BLANK_HTML,
+  }, sessionId).catch(() => {});
+}
+
+async function withBlankOrigin(cdp, origin, fn) {
+  const { targetId } = await cdp.send('Target.createTarget', { url: 'about:blank', background: true, newWindow: false });
+  let sessionId;
+  try {
+    ({ sessionId } = await cdp.send('Target.attachToTarget', { targetId, flatten: true }));
+    await cdp.send('Network.enable', {}, sessionId);
+    await cdp.send('Network.setBypassServiceWorker', { bypass: true }, sessionId);
+    await cdp.send('Page.enable', {}, sessionId);
+    await cdp.send('Fetch.enable', { patterns: [{ urlPattern: '*', resourceType: 'Document', requestStage: 'Request' }] }, sessionId);
+    const off = cdp.on('Fetch.requestPaused', (params, sid) => {
+      if (sid !== sessionId) return;
+      fulfillPlaceholder(cdp, params.requestId, sid);
+    });
+    try {
+      const loaded = cdp.waitFor('Page.loadEventFired', (_, sid) => sid === sessionId, 10_000);
+      await cdp.send('Page.navigate', { url: `${origin}${PLACEHOLDER_PATH}` }, sessionId);
+      await loaded;
+    } finally {
+      off();
+    }
+    return await fn(sessionId);
+  } finally {
+    await cdp.send('Target.closeTarget', { targetId }).catch(() => {});
+  }
+}
+
+async function evaluate(cdp, sessionId, expression) {
+  const { result, exceptionDetails } = await cdp.send('Runtime.evaluate', { expression, returnByValue: true }, sessionId);
+  if (exceptionDetails) throw new Error(exceptionDetails.exception?.description ?? exceptionDetails.text);
+  return result.value;
+}
+
+/** Every http(s) origin currently open in a tab. */
+export async function openOrigins(cdp) {
+  const { targetInfos } = await cdp.send('Target.getTargets');
+  const origins = new Set();
+  for (const t of targetInfos) {
+    if (t.type !== 'page') continue;
+    try {
+      const url = new URL(t.url);
+      if (url.protocol === 'http:' || url.protocol === 'https:') origins.add(url.origin);
+    } catch {
+      // about:blank, chrome-error:// and friends
+    }
+  }
+  return [...origins];
+}
+
+/**
+ * Snapshot cookies and localStorage.
+ * @param {object} opts
+ * @param {string[]|null} opts.cookieAllowlist  keep only cookies for these origins (null = all)
+ * @param {string[]} opts.storageOrigins        concrete origins to read localStorage from
+ */
+export async function captureStorage(cdp, { cookieAllowlist = null, storageOrigins = [] } = {}) {
+  const { cookies } = await cdp.send('Storage.getCookies');
+  const kept = cookieAllowlist ? cookies.filter((c) => cookieMatchesAllowlist(c.domain, cookieAllowlist)) : cookies;
+  const origins = [];
+  for (const origin of storageOrigins) {
+    const entries = await withBlankOrigin(cdp, origin, (sid) => evaluate(cdp, sid, 'Object.entries(localStorage)'));
+    if (entries.length) origins.push({ origin, localStorage: entries.map(([name, value]) => ({ name, value })) });
+  }
+  return { cookies: kept.map(toPlaywrightCookie), origins };
+}
+
+/** Load cookies and localStorage into a browser. Call before the first real navigation. */
+export async function applyStorage(cdp, { cookies = [], origins = [] }) {
+  if (cookies.length) await cdp.send('Storage.setCookies', { cookies: cookies.map(toCdpCookieParam) });
+  for (const { origin, localStorage } of origins) {
+    if (!localStorage?.length) continue;
+    const payload = JSON.stringify(localStorage.map(({ name, value }) => [name, value]));
+    await withBlankOrigin(cdp, origin, (sid) => evaluate(cdp, sid, `for (const [k, v] of ${payload}) localStorage.setItem(k, v); localStorage.length`));
+  }
+}
+
+/** Tabs worth reopening after a relaunch. */
+export async function openTabUrls(cdp) {
+  const { targetInfos } = await cdp.send('Target.getTargets');
+  return targetInfos
+    .filter((t) => t.type === 'page' && /^https?:/.test(t.url) && !t.url.includes(PLACEHOLDER_PATH))
+    .map((t) => t.url);
+}

package/src/lib/upstream.js

@@ -0,0 +1,98 @@
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { ListRootsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+// chrome-devtools-mcp runs as a child process, pointed at a Chrome fleet
+// launched itself (--browserUrl). Fleet is an MCP client to it and passes its
+// tools through unchanged. It comes from our own node_modules at a pinned
+// range, never `npx @latest`, so startup doesn't depend on the npm registry.
+
+const require = createRequire(import.meta.url);
+const PKG_JSON = require.resolve('chrome-devtools-mcp/package.json');
+const UPSTREAM_BIN = join(dirname(PKG_JSON), 'build/src/bin/chrome-devtools-mcp.js');
+export const UPSTREAM_VERSION = require(PKG_JSON).version;
+
+// Performance traces and Lighthouse runs can take minutes.
+const CALL_TIMEOUT_MS = 10 * 60_000;
+
+export class Upstream {
+  #client = null;
+  #closed = false;
+  onClose = () => {};
+
+  /**
+   * @param {string} browserUrl  e.g. http://127.0.0.1:54288 ; null = tool listing only
+   * @param {(() => Promise<Array>)|null} rootsProvider  the MCP client's workspace roots.
+   *   Upstream only reads and writes files inside roots (plus the temp dir), so
+   *   they're passed through; without them, screenshots can't go to the project.
+   */
+  static async start({ browserUrl, extraArgs = [], rootsProvider = null }) {
+    const upstream = new Upstream();
+    // A port nothing listens on is fine for listing: upstream connects lazily.
+    const url = browserUrl ?? 'http://127.0.0.1:9';
+    const transport = new StdioClientTransport({
+      command: process.execPath,
+      args: [UPSTREAM_BIN, `--browserUrl=${url}`, ...extraArgs],
+      stderr: 'pipe',
+    });
+    transport.stderr?.on('data', (chunk) => {
+      const text = chunk.toString();
+      // Upstream prints a privacy banner on every start; keep real errors only.
+      if (/error|exception|fatal/i.test(text)) process.stderr.write(`[chrome-devtools-mcp] ${text}`);
+    });
+    const client = new Client(
+      { name: 'devtools-fleet-mcp', version: '1' },
+      { capabilities: rootsProvider ? { roots: { listChanged: true } } : {} },
+    );
+    if (rootsProvider) {
+      client.setRequestHandler(ListRootsRequestSchema, async () => ({ roots: await rootsProvider().catch(() => []) }));
+    }
+    client.onclose = () => {
+      // close() sets #closed first, so only an unexpected exit reaches onClose.
+      const unexpected = !upstream.#closed;
+      upstream.#closed = true;
+      if (unexpected) upstream.onClose();
+    };
+    await client.connect(transport);
+    upstream.#client = client;
+    return upstream;
+  }
+
+  get closed() {
+    return this.#closed;
+  }
+
+  async listTools() {
+    const tools = [];
+    let cursor;
+    do {
+      const page = await this.#client.listTools(cursor ? { cursor } : {});
+      tools.push(...page.tools);
+      cursor = page.nextCursor;
+    } while (cursor);
+    return tools;
+  }
+
+  getInstructions() {
+    return this.#client.getInstructions();
+  }
+
+  sendRootsListChanged() {
+    if (!this.#closed) this.#client.sendRootsListChanged().catch(() => {});
+  }
+
+  async callTool(name, args) {
+    return this.#client.callTool({ name, arguments: args }, undefined, {
+      timeout: CALL_TIMEOUT_MS,
+      resetTimeoutOnProgress: true,
+    });
+  }
+
+  async close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    await this.#client?.close().catch(() => {});
+  }
+}

package/src/reaper-main.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// Detached background process that closes abandoned fleet browsers. Started
+// by devtools-fleet-mcp on demand; exits by itself when there is nothing left.
+import { loadConfig } from './lib/config.js';
+import { runReaper } from './lib/reaper.js';
+
+runReaper({ loadConfig }).catch((err) => {
+  console.error(`${new Date().toISOString()} reaper crashed: ${err.stack ?? err.message}`);
+  process.exit(1);
+});

package/src/server.js

@@ -0,0 +1,85 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, RootsListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
+import { createRequire } from 'node:module';
+import { loadConfig } from './lib/config.js';
+import { findSessionAnchor } from './lib/process-tree.js';
+import { FleetSession } from './lib/session.js';
+import { Upstream, UPSTREAM_VERSION } from './lib/upstream.js';
+import { toolDefinitions, findFleetTool } from './tools/fleet-tools.js';
+
+const { version } = createRequire(import.meta.url)('../package.json');
+
+const INSTRUCTIONS = `devtools-fleet gives this session its own isolated Chrome with the full chrome-devtools-mcp toolset (${UPSTREAM_VERSION}).
+- Any browser tool starts the browser on first use. Other agents have their own browsers; nothing is shared.
+- To work logged in, call state_list, then browser_start({ state: "<name>" }). A person creates states with \`devtools-fleet login\`.
+- A browser started from a state can only reach that state's allowed origins. Blocked navigations say so; don't try to work around them, ask the person.
+- browser_restart({ headless: false }) shows a window, e.g. for the person to watch or solve a captcha.`;
+
+export async function startServer() {
+  const config = loadConfig();
+  const anchor = findSessionAnchor();
+  const session = new FleetSession(config, anchor);
+
+  // Upstream's tool list, fetched once from a browserless child (~0.3s).
+  const lister = await Upstream.start({ browserUrl: null, extraArgs: config.upstreamArgs });
+  const upstreamTools = await lister.listTools();
+  await lister.close();
+
+  const fleetDefs = toolDefinitions();
+  const clash = upstreamTools.find((t) => fleetDefs.some((f) => f.name === t.name));
+  if (clash) throw new Error(`chrome-devtools-mcp now has a tool named "${clash.name}", which clashes with devtools-fleet. Please report this.`);
+  const tools = [...fleetDefs, ...upstreamTools];
+
+  const server = new Server(
+    { name: 'devtools-fleet-mcp', version },
+    { capabilities: { tools: {} }, instructions: INSTRUCTIONS },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+
+  // Pass the client's workspace roots through to chrome-devtools-mcp (see upstream.js).
+  server.oninitialized = () => {
+    if (server.getClientCapabilities()?.roots) {
+      session.setRootsProvider(async () => (await server.listRoots(undefined, { timeout: 5000 })).roots);
+      server.setNotificationHandler(RootsListChangedNotificationSchema, async () => session.rootsChanged());
+    }
+  };
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    try {
+      const fleetTool = findFleetTool(name);
+      if (fleetTool) {
+        const parsed = fleetTool.schema.safeParse(args);
+        if (!parsed.success) return errorResult(`Invalid arguments for ${name}: ${parsed.error.message}`);
+        return await fleetTool.handler(session, parsed.data);
+      }
+      if (!upstreamTools.some((t) => t.name === name)) return errorResult(`Unknown tool: ${name}`);
+      return await session.callUpstream(name, args);
+    } catch (err) {
+      return errorResult(err.message);
+    }
+  });
+
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    // Leave the browser running for re-adoption; the reaper handles the rest.
+    await session.detach().catch(() => {});
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+  process.on('SIGHUP', shutdown);
+  process.stdin.on('close', shutdown);
+
+  const transport = new StdioServerTransport();
+  transport.onclose = shutdown;
+  await server.connect(transport);
+}
+
+function errorResult(text) {
+  return { content: [{ type: 'text', text }], isError: true };
+}

package/src/tools/fleet-tools.js

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+import { listStates } from '../lib/states.js';
+
+// devtools-fleet's own tools. Everything else the agent sees is
+// chrome-devtools-mcp's, passed through with its original names.
+
+const viewport = z.string().regex(/^\d{2,5}x\d{2,5}$/).describe('Window size, e.g. "1280x720"');
+
+export const FLEET_TOOLS = [
+  {
+    name: 'browser_start',
+    description:
+      'Start this session\'s own Chrome (isolated from every other agent). Optional: the first browser tool call starts one with defaults anyway. ' +
+      'Call it explicitly to load a saved login (`state`), to pick headless/viewport/channel, or to open a URL. ' +
+      'A browser started from a state can only visit that state\'s allowed origins. ' +
+      'If this session already had a browser before a reconnect, it is picked up again with its tabs.',
+    schema: z.object({
+      state: z.string().optional().describe('Name of a saved login state (see state_list)'),
+      headless: z.boolean().optional().describe('Run without a window (default from config, normally true)'),
+      viewport: viewport.optional(),
+      channel: z.enum(['stable', 'beta', 'dev', 'canary']).optional(),
+      url: z.string().url().optional().describe('Open this URL in the first tab'),
+      allowedOrigins: z.array(z.string()).optional().describe('Without a state: restrict this browser to these origins, e.g. ["http://localhost:3000"]'),
+    }).strict(),
+    async handler(session, args) {
+      const { adopted, alreadyRunning } = await session.start(args);
+      const status = await session.status();
+      const how = alreadyRunning ? 'Already running' : adopted ? 'Re-attached to this session\'s existing browser' : 'Started';
+      return text(`${how}: ${describe(status)}`);
+    },
+  },
+  {
+    name: 'browser_status',
+    description: 'Show this session\'s browser: id, saved state, allowlist, headless, open tabs, uptime.',
+    schema: z.object({}).strict(),
+    async handler(session) {
+      const status = await session.status();
+      return text(status.running ? describe(status) : 'No browser running in this session. Any browser tool call (or browser_start) starts one.');
+    },
+  },
+  {
+    name: 'browser_restart',
+    description:
+      'Relaunch this session\'s browser keeping cookies, localStorage and open tabs. Pass headless: false to get a visible window ' +
+      '(e.g. so the human can watch or solve a captcha), headless: true to hide it again. Pages reload.',
+    schema: z.object({ headless: z.boolean().optional() }).strict(),
+    async handler(session, args) {
+      const { headless, reopenedTabs } = await session.restart(args);
+      return text(`Restarted ${headless ? 'headless' : 'with a visible window'}; reopened ${reopenedTabs} tab(s). Page ids have changed: call list_pages.`);
+    },
+  },
+  {
+    name: 'browser_stop',
+    description: 'Close this session\'s browser and delete its temporary profile.',
+    schema: z.object({}).strict(),
+    async handler(session) {
+      const { stopped, id } = await session.stop();
+      return text(stopped ? `Closed browser ${id}.` : 'No browser was running.');
+    },
+  },
+  {
+    name: 'state_save',
+    description:
+      'Save the current browser\'s login (cookies + localStorage) as a named state, so other sessions can start already logged in. ' +
+      'Only cookies for the allowed origins are kept. allowedOrigins defaults to the http(s) origins open in tabs; ' +
+      'it can never be wider than this browser\'s own allowlist. States a person created with `devtools-fleet login` cannot be overwritten.',
+    schema: z.object({
+      name: z.string().describe('State name: letters, digits, . _ -'),
+      allowedOrigins: z.array(z.string()).optional().describe('Origins this state may be used on, e.g. ["https://staging.example.com"]'),
+      strict: z.boolean().optional().describe('Block every request (not just navigations) outside the allowlist when the state is used'),
+      overwrite: z.boolean().optional(),
+    }).strict(),
+    async handler(session, args) {
+      const s = await session.saveState(args);
+      return text(`Saved state "${s.name}": ${s.cookies} cookie(s), localStorage for ${s.localStorageOrigins.length} origin(s). Allowed: ${s.allowedOrigins.join(', ')}${s.strict ? ' (strict)' : ''}.`);
+    },
+  },
+  {
+    name: 'state_list',
+    description: 'List saved login states: name, allowed origins, cookie counts, when saved and when the first cookie expires. Never shows cookie values.',
+    schema: z.object({}).strict(),
+    async handler() {
+      const states = listStates();
+      if (!states.length) return text('No saved states. A person can create one with `devtools-fleet login <name> <url>`.');
+      return text(states.map((s) => s.error
+        ? `${s.name}: unreadable (${s.error})`
+        : `${s.name}: ${s.allowedOrigins.join(', ')}${s.strict ? ' [strict]' : ''} | ${s.cookies} cookies (${s.expiredCookies} expired) | saved ${s.savedAt} by ${s.createdBy}`).join('\n'));
+    },
+  },
+];
+
+export function toolDefinitions() {
+  return FLEET_TOOLS.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: z.toJSONSchema(t.schema, { target: 'draft-7' }),
+  }));
+}
+
+export function findFleetTool(name) {
+  return FLEET_TOOLS.find((t) => t.name === name);
+}
+
+function describe(s) {
+  const lines = [
+    `browser ${s.id}${s.state ? `, state "${s.state}"` : ''}, ${s.headless ? 'headless' : 'visible window'}${s.viewport ? `, ${s.viewport}` : ''}, ${s.channel}`,
+    s.allowedOrigins ? `allowed origins: ${s.allowedOrigins.join(', ')}${s.strict ? ' (strict)' : ''}` : 'allowed origins: any',
+    `tabs: ${s.tabs.length ? s.tabs.join(' | ') : 'none with a web page'}`,
+    `uptime ${s.uptimeSeconds}s${s.blockedRequests ? `, ${s.blockedRequests} request(s) blocked so far` : ''}`,
+  ];
+  return lines.join('\n');
+}
+
+function text(value) {
+  return { content: [{ type: 'text', text: value }] };
+}