cdpfleet-mcp 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdpfleet-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server for cdpfleet: let Claude, Cursor or any MCP client drive real remote browsers — Chrome, Edge, Firefox, Camoufox and more — with residential proxies and live-view handoff.",
   "type": "module",
   "bin": {

package/src/http.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+// Hosted cdpfleet MCP server (MCP Streamable HTTP), served at https://cdpfleet.com/mcp: the same
+// tools as `npx cdpfleet-mcp`, with nothing to install. Auth, per MCP session:
+//   - OAuth 2.1 (Claude, ChatGPT…): no credentials → 401 with WWW-Authenticate pointing to the
+//     protected-resource metadata; the client runs cdpfleet.com's OAuth flow and sends
+//     `Authorization: Bearer cdpfo_…`, checked with main (POST /internal/v1/mcp/token-info,
+//     MCP_SERVICE_TOKEN), which also returns the user's hidden MCP key to launch with;
+//   - `Authorization: Bearer <cdpfleet API key>` (or x-api-key), for scripts and headless agents.
+// The browser belongs to the key, not to the MCP session: some clients (ChatGPT) open a new MCP
+// session for every tool call, or send calls with no session at all, and must still find the
+// browser they launched. Every session of a key shares that key's browser; a key unused for
+// MCP_IDLE_MS has its browser closed (stops billing). Sessions stay bound to the key that opened them.
+//   env: PORT (8410), HOST (127.0.0.1), CDPFLEET_API_URL, MCP_SERVICE_TOKEN, MCP_IDLE_MS, MCP_MAX_PER_KEY
+import http from 'node:http';
+import crypto from 'node:crypto';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { createServer, createState } from './tools.js';
+
+const PORT = Number(process.env.PORT || 8410);
+const HOST = process.env.HOST || '127.0.0.1';
+const API = (process.env.CDPFLEET_API_URL || 'https://cdpfleet.com').replace(/\/$/, '');
+const IDLE_MS = Number(process.env.MCP_IDLE_MS || 30 * 60000);
+const MAX_PER_KEY = Number(process.env.MCP_MAX_PER_KEY || 5);
+const MAX_BODY = 1 << 20;
+const PATH = /^\/mcp\/?$/;
+
+const SERVICE_TOKEN = process.env.MCP_SERVICE_TOKEN || '';
+const sessions = new Map(); // MCP session id → { transport, keyHash (owner), lastUsed }
+// Owner (API key hash, or "grant:<id>" for an OAuth-connected app) → its browser, shared by its sessions.
+const browsers = new Map();
+const sha = (s) => crypto.createHash('sha256').update(s).digest('hex');
+const log = (msg, extra = {}) => console.log(JSON.stringify({ time: new Date().toISOString(), msg, ...extra }));
+
+const rpcError = (res, status, message, code = -32000) => {
+  res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+  res.end(JSON.stringify({ jsonrpc: '2.0', error: { code, message }, id: null }));
+};
+
+// OAuth access token → { active, grant_id, key } from main, cached a minute.
+const tokenCache = new Map();
+async function tokenInfo(token) {
+  const h = sha(token);
+  const c = tokenCache.get(h);
+  if (c && Date.now() - c.at < 60000) return c.info;
+  const r = await fetch(`${API}/internal/v1/mcp/token-info`, {
+    method: 'POST', headers: { authorization: `Bearer ${SERVICE_TOKEN}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ token }), signal: AbortSignal.timeout(10000),
+  }).catch(() => null);
+  const info = r?.ok ? await r.json() : { active: false };
+  tokenCache.set(h, { info, at: Date.now() });
+  if (tokenCache.size > 10000) tokenCache.clear();
+  return info;
+}
+
+function keyOf(req) {
+  const bearer = /^Bearer\s+(\S+)$/i.exec(req.headers.authorization || '')?.[1];
+  return bearer || req.headers['x-api-key'] || null;
+}
+
+// Is this a live cdpfleet key? Asked of main once a minute per key at most.
+const checked = new Map();
+async function keyIsValid(key) {
+  const h = sha(key);
+  const c = checked.get(h);
+  if (c && Date.now() - c.at < 60000) return c.ok;
+  const r = await fetch(`${API}/v1/me`, { headers: { 'x-api-key': key }, signal: AbortSignal.timeout(10000) }).catch(() => null);
+  const ok = r?.status === 200;
+  checked.set(h, { ok, at: Date.now() });
+  return ok;
+}
+
+function readJson(req) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on('data', (c) => { size += c.length; if (size > MAX_BODY) { reject(new Error('body too large')); req.destroy(); } else chunks.push(c); });
+    req.on('end', () => { try { resolve(chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : undefined); } catch { reject(new Error('invalid JSON')); } });
+    req.on('error', reject);
+  });
+}
+
+function browserOf(key, keyHash) {
+  let b = browsers.get(keyHash);
+  if (!b) browsers.set(keyHash, b = { state: createState({ apiKey: key }), lastUsed: Date.now() });
+  b.lastUsed = Date.now();
+  return b.state;
+}
+
+async function end(id, why) {
+  const s = sessions.get(id);
+  if (!s) return;
+  sessions.delete(id);
+  await s.transport.close?.().catch(() => {});
+  log('mcp session closed', { session: id, why, open: sessions.size });
+}
+
+async function closeBrowser(keyHash, why) {
+  const b = browsers.get(keyHash);
+  if (!b) return;
+  browsers.delete(keyHash);
+  const had = Boolean(b.state.current);
+  await b.state.close().catch(() => {});
+  if (had) log('mcp browser closed', { key: keyHash.slice(0, 12), why });
+}
+
+const server = http.createServer(async (req, res) => {
+  const path = (req.url || '').split('?')[0];
+  try {
+    if (path === '/mcp/healthz') {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      return res.end(JSON.stringify({ ok: true, sessions: sessions.size, browsers: [...browsers.values()].filter((b) => b.state.current).length }));
+    }
+    const m = PATH.exec(path);
+    if (!m) return rpcError(res, 404, 'not found');
+    // 401s point MCP clients to the OAuth flow (MCP authorization spec / RFC 9728).
+    const unauthorized = (message, invalidToken) => {
+      res.setHeader('www-authenticate', `Bearer resource_metadata="${API}/.well-known/oauth-protected-resource/mcp"${invalidToken ? ', error="invalid_token"' : ''}`);
+      return rpcError(res, 401, message, -32001);
+    };
+    const key = keyOf(req);
+    if (!key) return unauthorized('Connect with OAuth (Claude, ChatGPT, Gemini: just add https://cdpfleet.com/mcp), or send "Authorization: Bearer <API key>".');
+    let apiKey = key;
+    let keyHash = sha(key);
+    const oauth = key.startsWith('cdpfo_');
+    if (oauth) {
+      const info = await tokenInfo(key);
+      if (!info.active) return unauthorized('The access token is invalid, expired or revoked.', true);
+      apiKey = info.key;
+      keyHash = `grant:${info.grant_id}`; // refreshed tokens keep the same sessions and browser
+    }
+    const body = req.method === 'POST' ? await readJson(req) : undefined;
+    const sid = req.headers['mcp-session-id'];
+
+    if (sid) {
+      const s = sessions.get(sid);
+      if (!s) return rpcError(res, 404, 'Unknown or expired MCP session: reconnect.');
+      if (s.keyHash !== keyHash) return rpcError(res, 403, 'This MCP session belongs to another key.');
+      s.lastUsed = Date.now();
+      browserOf(apiKey, keyHash);
+      return await s.transport.handleRequest(req, res, body);
+    }
+    if (req.method !== 'POST') return rpcError(res, 405, 'POST JSON-RPC requests to this endpoint.');
+    if (!oauth && !(await keyIsValid(key))) return unauthorized('Invalid or revoked cdpfleet API key.', true);
+
+    // No session and not an initialize: serve it statelessly, with the key's browser.
+    if (!isInitializeRequest(body)) {
+      const tools = createServer({ state: browserOf(apiKey, keyHash) });
+      const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+      await tools.server.connect(transport);
+      res.on('close', () => { transport.close?.().catch(() => {}); });
+      return await transport.handleRequest(req, res, body);
+    }
+
+    // A client that reconnects often shouldn't pile up browsers: keep the newest MAX_PER_KEY.
+    const mine = [...sessions.entries()].filter(([, s]) => s.keyHash === keyHash).sort((a, b) => a[1].lastUsed - b[1].lastUsed);
+    while (mine.length >= MAX_PER_KEY) await end(mine.shift()[0], 'too many sessions for this key');
+
+    const tools = createServer({ state: browserOf(apiKey, keyHash) });
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => crypto.randomUUID(),
+      onsessioninitialized: (id) => {
+        sessions.set(id, { transport, keyHash, lastUsed: Date.now() });
+        log('mcp session opened', { session: id, key: keyHash.slice(0, 12), open: sessions.size });
+      },
+    });
+    transport.onclose = () => { if (transport.sessionId) end(transport.sessionId, 'client closed'); };
+    await tools.server.connect(transport);
+    await transport.handleRequest(req, res, body);
+  } catch (err) {
+    log('mcp request failed', { path, err: err.message });
+    if (!res.headersSent) rpcError(res, err.message === 'invalid JSON' || err.message === 'body too large' ? 400 : 500, err.message === 'invalid JSON' || err.message === 'body too large' ? err.message : 'internal error');
+  }
+});
+
+setInterval(() => {
+  for (const [id, s] of sessions) if (Date.now() - s.lastUsed > IDLE_MS) end(id, 'idle');
+  for (const [h, b] of browsers) if (Date.now() - b.lastUsed > IDLE_MS) closeBrowser(h, 'idle');
+}, 60000).unref();
+
+for (const sig of ['SIGINT', 'SIGTERM']) {
+  process.on(sig, async () => {
+    await Promise.all([...sessions.keys()].map((id) => end(id, 'server stopping')));
+    await Promise.all([...browsers.keys()].map((h) => closeBrowser(h, 'server stopping')));
+    process.exit(0);
+  });
+}
+
+server.listen(PORT, HOST, () => log('cdpfleet MCP (HTTP) listening', { host: HOST, port: PORT }));

package/src/server.js

@@ -3,166 +3,10 @@
 // cdpfleet — the browser and version of its choice, a residential or your own proxy, a live
 // view a person can take over, and a recording of what happened. One browser at a time.
 //   env: CDPFLEET_API_KEY (required), CDPFLEET_PROXY (default proxy; else cdpfleet-resi)
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+// No install needed at all: the same tools are hosted at https://cdpfleet.com/mcp (src/http.js).
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { chromium, firefox, webkit } from 'playwright-core';
-import { z } from 'zod';
-import { Cdpfleet } from 'cdpfleet';
+import { createServer } from './tools.js';
 
-const BROWSERS = ['chrome', 'edge', 'brave', 'opera', 'whale', 'yandex', 'chromium', 'patchright', 'cloakbrowser', 'camoufox', 'firefox', 'webkit'];
-const TYPE = { camoufox: firefox, firefox, webkit };
-const MAX_TEXT = 25000;
-
-const fleet = new Cdpfleet();
-let current = null; // { session, browser, page, name }
-
-const text = (t) => ({ content: [{ type: 'text', text: t }] });
-const fail = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
-const clip = (s) => (s.length > MAX_TEXT ? `${s.slice(0, MAX_TEXT)}\n… (${s.length - MAX_TEXT} more characters; snapshot a narrower selector)` : s);
-
-function need() {
-  if (!current) throw new Error('No browser is open. Call launch_browser first.');
-  return current;
-}
-
-// A tool body that turns exceptions into an MCP error result.
-const tool = (fn) => async (args) => {
-  try { return await fn(args ?? {}); } catch (err) { return fail(String(err.message || err).split('\n')[0]); }
-};
-
-// Click/type target: a CSS selector, or an ARIA role + accessible name (as in snapshot output).
-const target = { selector: z.string().optional().describe('CSS selector, or text=… / role=… Playwright selector'), role: z.string().optional().describe('ARIA role from the snapshot, e.g. button, link, textbox'), name: z.string().optional().describe('Accessible name from the snapshot') };
-function locate(page, { selector, role, name }) {
-  if (role) return page.getByRole(role, name ? { name, exact: false } : {}).first();
-  if (selector) return page.locator(selector).first();
-  throw new Error('Give a selector, or a role (and name).');
-}
-
-const server = new McpServer({ name: 'cdpfleet', version: '0.1.0' });
-
-server.registerTool('launch_browser', {
-  description: 'Start a real remote browser on cdpfleet and open a page. Pick the browser the site should see. Headful by default (2 threads; less detectable). Proxy: your own proxy URL, or cdpfleet residential (default; billed per GB from your balance), optionally by country.',
-  inputSchema: {
-    browser: z.enum(BROWSERS).default('chrome'),
-    headless: z.boolean().default(false),
-    proxy: z.string().optional().describe('Proxy URL (http/https/socks5) or a cdpfleet-resi token. Default: CDPFLEET_PROXY or cdpfleet-resi'),
-    country: z.string().length(2).optional().describe('Residential exit country (ISO code) when using the cdpfleet residential proxy'),
-    record: z.boolean().default(true).describe('Keep a video recording of the session'),
-    options: z.record(z.any()).optional().describe('Extra launch options passed unchanged (e.g. channel, version, screen_size, Camoufox os/locale)'),
-  },
-}, tool(async ({ browser, headless, proxy, country, record, options }) => {
-  if (current) await closeCurrent();
-  let p = proxy || process.env.CDPFLEET_PROXY || 'cdpfleet-resi';
-  if (country && p.startsWith('cdpfleet-resi')) p = `${p}-country-${country.toLowerCase()}`;
-  const live = headless && !['camoufox', 'firefox', 'webkit'].includes(browser) ? { live_view: true } : {};
-  const session = await fleet.launch(browser, { proxy: p, headless, record, ...live, ...(options || {}) });
-  const b = await session.connect(TYPE[browser] || chromium);
-  const context = await b.newContext({ viewport: headless ? { width: 1280, height: 800 } : null });
-  const page = await context.newPage();
-  current = { session, browser: b, page, name: browser };
-  return text(`Launched ${browser} ${b.version()} (${session.resourceClass}, ${session.weight} thread(s)), session ${session.id}. Proxy: ${p.startsWith('cdpfleet-resi') ? p : 'your proxy'}. Use navigate next.`);
-}));
-
-server.registerTool('navigate', {
-  description: 'Open a URL in the current page and wait for its HTML. Returns the title and final URL.',
-  inputSchema: { url: z.string().url() },
-}, tool(async ({ url }) => {
-  const { page } = need();
-  const res = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60000 });
-  return text(`${res?.status() ?? ''} ${page.url()}\nTitle: ${await page.title()}`);
-}));
-
-server.registerTool('snapshot', {
-  description: 'The page (or one element) as an accessibility snapshot: roles, names, text and links in YAML — compact and good for deciding what to click.',
-  inputSchema: { selector: z.string().optional().describe('Limit to this CSS selector (default: body)') },
-}, tool(async ({ selector }) => {
-  const { page } = need();
-  return text(clip(await page.locator(selector || 'body').first().ariaSnapshot({ timeout: 15000 })));
-}));
-
-server.registerTool('click', { description: 'Click an element, by CSS selector or by role + name from the snapshot.', inputSchema: target },
-  tool(async (args) => {
-    const { page } = need();
-    await locate(page, args).click({ timeout: 15000 });
-    await page.waitForLoadState('domcontentloaded').catch(() => {});
-    return text(`Clicked. Now at ${page.url()}`);
-  }));
-
-server.registerTool('type', {
-  description: 'Fill a text field, by CSS selector or role + name; optionally press Enter after.',
-  inputSchema: { ...target, text: z.string(), submit: z.boolean().default(false) },
-}, tool(async ({ text: value, submit, ...args }) => {
-  const { page } = need();
-  const el = locate(page, args);
-  await el.fill(value, { timeout: 15000 });
-  if (submit) await el.press('Enter');
-  return text(submit ? `Typed and submitted. Now at ${page.url()}` : 'Typed.');
-}));
-
-server.registerTool('press', { description: 'Press a key on the page (e.g. Enter, Escape, PageDown, ArrowDown).', inputSchema: { key: z.string() } },
-  tool(async ({ key }) => { await need().page.keyboard.press(key); return text(`Pressed ${key}.`); }));
-
-server.registerTool('wait_for', {
-  description: 'Wait until an element (CSS selector) or a text appears, up to 30 s.',
-  inputSchema: { selector: z.string().optional(), text: z.string().optional(), timeout_s: z.number().max(60).default(30) },
-}, tool(async ({ selector, text: t, timeout_s: s }) => {
-  const { page } = need();
-  const loc = selector ? page.locator(selector) : t ? page.getByText(t) : null;
-  if (!loc) throw new Error('Give a selector or a text.');
-  await loc.first().waitFor({ timeout: s * 1000 });
-  return text('It appeared.');
-}));
-
-server.registerTool('screenshot', {
-  description: 'A JPEG screenshot of the current page (viewport, or the whole page).',
-  inputSchema: { full_page: z.boolean().default(false) },
-}, tool(async ({ full_page: fullPage }) => {
-  const img = await need().page.screenshot({ type: 'jpeg', quality: 60, fullPage });
-  return { content: [{ type: 'image', data: img.toString('base64'), mimeType: 'image/jpeg' }] };
-}));
-
-server.registerTool('evaluate', {
-  description: 'Run a JavaScript expression in the page and return its JSON result (e.g. extract data).',
-  inputSchema: { expression: z.string().describe('An expression or an arrow function, e.g. () => [...document.links].map(a => a.href)') },
-}, tool(async ({ expression }) => {
-  // A function given as text must be called, or evaluate returns the function itself.
-  const isFn = /^\s*(async\s+)?(\([^)]*\)|[\w$]+)\s*=>|^\s*(async\s+)?function\b/.test(expression);
-  const v = await need().page.evaluate(isFn ? `(${expression})()` : expression);
-  return text(clip(typeof v === 'string' ? v : JSON.stringify(v, null, 2) ?? 'undefined'));
-}));
-
-server.registerTool('live_view', {
-  description: 'Hand the browser to a person: e.g. to solve a captcha or type a one-time code. Returns where to watch or take control; the agent should wait until the person says they are done.',
-  inputSchema: { mode: z.enum(['view', 'control']).default('control') },
-}, tool(async ({ mode }) => {
-  const { session, name } = need();
-  const link = await session.liveLink(mode);
-  return text(`A person can ${mode === 'control' ? 'take control of' : 'watch'} this ${name} session in the dashboard: https://cdpfleet.com/app#sessions → Live sessions → ${mode === 'control' ? 'Take control' : 'Watch'} (session ${session.id}).\nFor a custom viewer: ${link.protocol} link ${link.live_url} (single use, ${link.expires_in_s} s).`);
-}));
-
-server.registerTool('close_browser', { description: 'End the browser session (stops billing). The video recording appears in the dashboard (Sessions) shortly after.', inputSchema: {} },
-  tool(async () => { const id = need().session.id; await closeCurrent(); return text(`Session ${id} ended.`); }));
-
-server.registerTool('list_browsers', { description: 'The browsers cdpfleet offers, with their versions and channels.', inputSchema: {} },
-  tool(async () => {
-    const cat = await (await fetch('https://cdpfleet.com/api/public/browsers')).json();
-    return text(cat.engines.map((e) => `${e.key}: ${e.name} — ${e.versions.map((v) => `${v.label} ${v.version}`).join(', ')}`).join('\n'));
-  }));
-
-server.registerTool('account', { description: 'Your cdpfleet plan usage today, live sessions and residential-proxy balance.', inputSchema: {} },
-  tool(async () => {
-    const [usage, bal, threads] = await Promise.all([fleet.usage(), fleet.proxyBalance(), fleet.threads()]);
-    // The residential balance is USD, spent per GB at each tier's price (cdpfleet-resi-tier-N).
-    const usd = bal.balance_usd ?? (bal.balance_bytes / 1e9) * 5;
-    const gbAt = Object.fromEntries((bal.tiers || []).map((t) => [`tier_${t.tier}`, Math.round((usd / t.price_per_gb_usd) * 100) / 100]));
-    return text(JSON.stringify({ usage, live_sessions: threads.threads?.length ?? 0, residential_balance_usd: Math.round(usd * 100) / 100, residential_gb_at: gbAt }, null, 2));
-  }));
-
-async function closeCurrent() {
-  const c = current;
-  current = null;
-  if (c) await c.session.close().catch(() => {});
-}
-
-for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => { closeCurrent().finally(() => process.exit(0)); });
+const { server, close } = createServer({ apiKey: process.env.CDPFLEET_API_KEY, defaultProxy: process.env.CDPFLEET_PROXY });
+for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => { close().finally(() => process.exit(0)); });
 await server.connect(new StdioServerTransport());

package/src/tools.js

@@ -0,0 +1,222 @@
+// cdpfleet MCP tools, as a factory. The browser lives in a `state` object, so several MCP
+// servers can share one: the hosted server (src/http.js) keeps one state per API key, because
+// some clients (ChatGPT) open a new MCP session for every tool call. The stdio server
+// (src/server.js, `npx cdpfleet-mcp`) has one state of its own. One browser at a time per state.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { chromium, firefox, webkit } from 'playwright-core';
+import { z } from 'zod';
+import { Cdpfleet } from 'cdpfleet';
+
+const BROWSERS = ['chrome', 'edge', 'brave', 'opera', 'whale', 'yandex', 'chromium', 'patchright', 'camoufox', 'firefox', 'webkit'];
+const TYPE = { camoufox: firefox, firefox, webkit };
+const MAX_TEXT = 25000;
+
+// The free Community plan: a short note at launch and after a session, and with the errors its
+// limits cause, saying what a paid plan adds (same wording as main's public/shared/upgrade.js).
+const UPGRADE_URL = 'https://cdpfleet.com/app#subscriptions';
+const UPGRADE_LINE = 'You\'re on the free Community plan. Ready for more? Paid plans unlock more threads, longer sessions, priority capacity, recordings and persistent profiles — from $5 a month';
+const NUDGE_EVERY_MS = 30 * 60000;
+const HINTS = {
+  community_capacity_full: 'The free Community capacity is busy right now — paid plans get priority capacity and aren\'t affected.',
+  daily_quota_exhausted: 'That\'s today\'s free minutes used — paid plans give you 60 to 480 minutes per thread a day, or unlimited on dedicated threads.',
+  hourly_quota_exhausted: 'That\'s this hour\'s share of your free minutes — paid plans come with many more.',
+  threads_exceeded: 'The free plan runs 2 threads at a time — paid plans start at 5, and scale to thousands.',
+  profiles_disabled: 'Persistent profiles (stay logged in across sessions) come with every paid plan.',
+  keep_alive_requires_dedicated: 'keep_alive (reconnect to a running browser) comes with dedicated threads.',
+};
+
+// The browser a client works with: { fleet, current: { session, browser, page, name } | null }.
+export function createState({ apiKey, defaultProxy } = {}) {
+  const state = { fleet: new Cdpfleet(apiKey ? { apiKey } : {}), defaultProxy, current: null, plan: undefined, nudgedAt: 0 };
+  state.close = async () => {
+    const c = state.current;
+    state.current = null;
+    if (c) await c.session.close().catch(() => {});
+  };
+  return state;
+}
+
+// → { server, close, state }: close() ends the open browser session (stops billing).
+export function createServer({ apiKey, defaultProxy, state = createState({ apiKey, defaultProxy }) } = {}) {
+  const { fleet } = state;
+
+  const text = (t) => ({ content: [{ type: 'text', text: t }] });
+  const fail = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
+  const clip = (s) => (s.length > MAX_TEXT ? `${s.slice(0, MAX_TEXT)}\n… (${s.length - MAX_TEXT} more characters; snapshot a narrower selector)` : s);
+
+  // The key's plan, asked once per browser state: Community or not, and the longest idle time it allows.
+  async function plan() {
+    if (state.plan === undefined) {
+      state.plan = await fleet.me().then((m) => ({ community: Boolean(m.subscription?.features?.community), maxIdle: m.subscription?.max_inactivity_seconds || null }), () => null);
+    }
+    return state.plan;
+  }
+  const community = async () => Boolean((await plan())?.community);
+  // The upgrade note, at most every 30 minutes per key, for Community only.
+  async function nudge() {
+    if (!(await community()) || Date.now() - state.nudgedAt < NUDGE_EVERY_MS) return '';
+    state.nudgedAt = Date.now();
+    return `\n\n${UPGRADE_LINE}: ${UPGRADE_URL}`;
+  }
+
+  function need() {
+    if (!state.current) throw new Error('No browser is open. Call launch_browser first.');
+    return state.current;
+  }
+
+  // A tool body that turns exceptions into an MCP error result.
+  const tool = (fn) => async (args) => {
+    try { return await fn(args ?? {}); } catch (err) { return fail(String(err.message || err).split('\n')[0]); }
+  };
+
+  // Click/type target: a CSS selector, or an ARIA role + accessible name (as in snapshot output).
+  const target = { selector: z.string().optional().describe('CSS selector, or text=… / role=… Playwright selector'), role: z.string().optional().describe('ARIA role from the snapshot, e.g. button, link, textbox'), name: z.string().optional().describe('Accessible name from the snapshot') };
+  function locate(page, { selector, role, name }) {
+    if (role) return page.getByRole(role, name ? { name, exact: false } : {}).first();
+    if (selector) return page.locator(selector).first();
+    throw new Error('Give a selector, or a role (and name).');
+  }
+
+  const server = new McpServer({ name: 'cdpfleet', version: '0.1.2' });
+
+  server.registerTool('launch_browser', {
+    description: 'Start a real remote browser on cdpfleet and open a page. Pick the browser the site should see. Headful by default (2 threads; less detectable). Proxy: your own proxy URL, or cdpfleet residential (default; billed per GB from your balance), optionally by country.',
+    inputSchema: {
+      browser: z.enum(BROWSERS).default('chrome'),
+      headless: z.boolean().default(false),
+      proxy: z.string().optional().describe('Proxy URL (http/https/socks5) or a cdpfleet-resi token. Default: CDPFLEET_PROXY or cdpfleet-resi'),
+      country: z.string().length(2).optional().describe('Residential exit country (ISO code) when using the cdpfleet residential proxy'),
+      record: z.boolean().default(true).describe('Keep a video recording of the session'),
+      options: z.record(z.any()).optional().describe('Extra launch options passed unchanged (e.g. channel, version, screen_size, Camoufox os/locale)'),
+    },
+  }, tool(async (args) => {
+    try { return await launch(args); } catch (err) {
+      const hint = HINTS[err.code] && (await community()) ? ` ${HINTS[err.code]} See plans: ${UPGRADE_URL}` : '';
+      return fail(`${String(err.message || err).split('\n')[0]}${hint}`);
+    }
+  }));
+
+  async function launch({ browser, headless, proxy, country, record, options }) {
+    if (state.current) await closeCurrent();
+    let p = proxy || state.defaultProxy || 'cdpfleet-resi';
+    if (country && p.startsWith('cdpfleet-resi')) p = `${p}-country-${country.toLowerCase()}`;
+    const live = headless && !['camoufox', 'firefox', 'webkit'].includes(browser) ? { live_view: true } : {};
+    // A conversation pauses between tool calls: keep the browser for the plan's longest idle time
+    // (shared 10 min, Community 5 min; dedicated capped at 30 min here, like the server's own idle).
+    const maxIdle = (await plan())?.maxIdle;
+    const idle = maxIdle ? { inactivity_timeout: Math.min(maxIdle, 1800) } : {};
+    // A key created moments ago reaches the starters with the next accounts sync (about a
+    // second): retry a refused key briefly instead of failing the first launch.
+    let session;
+    for (let i = 0; ; i++) {
+      try { session = await fleet.launch(browser, { proxy: p, headless, record, ...live, ...idle, ...(options || {}) }); break; } catch (err) {
+        if (i >= 15 || !/invalid_api_key/.test(String(err.message || err))) throw err;
+        await new Promise((r) => setTimeout(r, 1000));
+      }
+    }
+    const b = await session.connect(TYPE[browser] || chromium);
+    const context = await b.newContext({ viewport: headless ? { width: 1280, height: 800 } : null });
+    const page = await context.newPage();
+    state.current = { session, browser: b, page, name: browser };
+    return text(`Launched ${browser} ${b.version()} (${session.resourceClass}, ${session.weight} thread(s)), session ${session.id}. Proxy: ${p.startsWith('cdpfleet-resi') ? p : p.startsWith('cdpfleet-plan') ? 'the Community proxy' : 'your proxy'}. Use navigate next.${await nudge()}`);
+  }
+
+  server.registerTool('navigate', {
+    description: 'Open a URL in the current page and wait for its HTML. Returns the title and final URL.',
+    inputSchema: { url: z.string().url() },
+  }, tool(async ({ url }) => {
+    const { page } = need();
+    const res = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60000 });
+    return text(`${res?.status() ?? ''} ${page.url()}\nTitle: ${await page.title()}`);
+  }));
+
+  server.registerTool('snapshot', {
+    description: 'The page (or one element) as an accessibility snapshot: roles, names, text and links in YAML — compact and good for deciding what to click.',
+    inputSchema: { selector: z.string().optional().describe('Limit to this CSS selector (default: body)') },
+  }, tool(async ({ selector }) => {
+    const { page } = need();
+    return text(clip(await page.locator(selector || 'body').first().ariaSnapshot({ timeout: 15000 })));
+  }));
+
+  server.registerTool('click', { description: 'Click an element, by CSS selector or by role + name from the snapshot.', inputSchema: target },
+    tool(async (args) => {
+      const { page } = need();
+      await locate(page, args).click({ timeout: 15000 });
+      await page.waitForLoadState('domcontentloaded').catch(() => {});
+      return text(`Clicked. Now at ${page.url()}`);
+    }));
+
+  server.registerTool('type', {
+    description: 'Fill a text field, by CSS selector or role + name; optionally press Enter after.',
+    inputSchema: { ...target, text: z.string(), submit: z.boolean().default(false) },
+  }, tool(async ({ text: value, submit, ...args }) => {
+    const { page } = need();
+    const el = locate(page, args);
+    await el.fill(value, { timeout: 15000 });
+    if (submit) await el.press('Enter');
+    return text(submit ? `Typed and submitted. Now at ${page.url()}` : 'Typed.');
+  }));
+
+  server.registerTool('press', { description: 'Press a key on the page (e.g. Enter, Escape, PageDown, ArrowDown).', inputSchema: { key: z.string() } },
+    tool(async ({ key }) => { await need().page.keyboard.press(key); return text(`Pressed ${key}.`); }));
+
+  server.registerTool('wait_for', {
+    description: 'Wait until an element (CSS selector) or a text appears, up to 30 s.',
+    inputSchema: { selector: z.string().optional(), text: z.string().optional(), timeout_s: z.number().max(60).default(30) },
+  }, tool(async ({ selector, text: t, timeout_s: s }) => {
+    const { page } = need();
+    const loc = selector ? page.locator(selector) : t ? page.getByText(t) : null;
+    if (!loc) throw new Error('Give a selector or a text.');
+    await loc.first().waitFor({ timeout: s * 1000 });
+    return text('It appeared.');
+  }));
+
+  server.registerTool('screenshot', {
+    description: 'A JPEG screenshot of the current page (viewport, or the whole page).',
+    inputSchema: { full_page: z.boolean().default(false) },
+  }, tool(async ({ full_page: fullPage }) => {
+    const img = await need().page.screenshot({ type: 'jpeg', quality: 60, fullPage });
+    return { content: [{ type: 'image', data: img.toString('base64'), mimeType: 'image/jpeg' }] };
+  }));
+
+  server.registerTool('evaluate', {
+    description: 'Run a JavaScript expression in the page and return its JSON result (e.g. extract data).',
+    inputSchema: { expression: z.string().describe('An expression or an arrow function, e.g. () => [...document.links].map(a => a.href)') },
+  }, tool(async ({ expression }) => {
+    // A function given as text must be called, or evaluate returns the function itself.
+    const isFn = /^\s*(async\s+)?(\([^)]*\)|[\w$]+)\s*=>|^\s*(async\s+)?function\b/.test(expression);
+    const v = await need().page.evaluate(isFn ? `(${expression})()` : expression);
+    return text(clip(typeof v === 'string' ? v : JSON.stringify(v, null, 2) ?? 'undefined'));
+  }));
+
+  server.registerTool('live_view', {
+    description: 'Hand the browser to a person: e.g. to solve a captcha or type a one-time code. Returns where to watch or take control; the agent should wait until the person says they are done.',
+    inputSchema: { mode: z.enum(['view', 'control']).default('control') },
+  }, tool(async ({ mode }) => {
+    const { session, name } = need();
+    const link = await session.liveLink(mode);
+    return text(`A person can ${mode === 'control' ? 'take control of' : 'watch'} this ${name} session in the dashboard: https://cdpfleet.com/app#sessions → Live sessions → ${mode === 'control' ? 'Take control' : 'Watch'} (session ${session.id}).\nFor a custom viewer: ${link.protocol} link ${link.live_url} (single use, ${link.expires_in_s} s).`);
+  }));
+
+  server.registerTool('close_browser', { description: 'End the browser session (stops billing). The video recording appears in the dashboard (Sessions) shortly after.', inputSchema: {} },
+    tool(async () => { const id = need().session.id; await closeCurrent(); return text(`Session ${id} ended.${await nudge()}`); }));
+
+  server.registerTool('list_browsers', { description: 'The browsers cdpfleet offers, with their versions and channels.', inputSchema: {} },
+    tool(async () => {
+      const cat = await (await fetch('https://cdpfleet.com/api/public/browsers')).json();
+      return text(cat.engines.map((e) => `${e.key}: ${e.name} — ${e.versions.map((v) => `${v.label} ${v.version}`).join(', ')}`).join('\n'));
+    }));
+
+  server.registerTool('account', { description: 'Your cdpfleet plan usage today, live sessions and residential-proxy balance.', inputSchema: {} },
+    tool(async () => {
+      const [usage, bal, threads] = await Promise.all([fleet.usage(), fleet.proxyBalance(), fleet.threads()]);
+      // The residential balance is USD, spent per GB at each tier's price (cdpfleet-resi-tier-N).
+      const usd = bal.balance_usd ?? (bal.balance_bytes / 1e9) * 5;
+      const gbAt = Object.fromEntries((bal.tiers || []).map((t) => [`tier_${t.tier}`, Math.round((usd / t.price_per_gb_usd) * 100) / 100]));
+      return text(JSON.stringify({ usage, live_sessions: threads.threads?.length ?? 0, residential_balance_usd: Math.round(usd * 100) / 100, residential_gb_at: gbAt }, null, 2));
+    }));
+
+  const closeCurrent = state.close;
+
+  return { server, close: closeCurrent, state };
+}