cdp-toolkit 1.0.0 → 1.2.0

package/src/manifest.ts

@@ -1,5 +1,5 @@
 /**
- * MCP tool manifest — the JSON Schemas the cdp-toolkit MCP server advertises via
+ * MCP tool manifest: the JSON Schemas the cdp-toolkit MCP server advertises via
  * `tools/list`. Each entry's `name` matches a key in the TOOLS registry
  * (src/index.ts) and its `inputSchema` mirrors that tool's TypeScript Args.
  *
@@ -29,6 +29,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "all": {
           "type": "boolean",
           "description": "Include non-page targets (service/shared workers, background pages) when true; otherwise only page-type tabs are listed."
@@ -44,9 +48,25 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "url": {
           "type": "string",
           "description": "URL to open in the new tab; defaults to about:blank."
+        },
+        "claim": {
+          "type": "boolean",
+          "description": "Claim the new tab atomically as part of creating it and return a lease token alongside {targetId,url}. Default false, which is byte-identical to the pre-1.2 behavior."
+        },
+        "label": {
+          "type": "string",
+          "description": "Agent label recorded on the lease when claim:true, surfaced in conflict errors and list_leases. Defaults to pid-<pid>."
+        },
+        "ttlMs": {
+          "type": "number",
+          "description": "How long the lease taken by claim:true survives without use before it is reclaimable. Defaults to CDP_LEASE_TTL_MS, else 900000 (15 minutes). Every checked call refreshes it, so an active agent never expires. Ignored without claim:true."
         }
       },
       "required": [],
@@ -59,6 +79,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -76,6 +100,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -93,6 +121,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -127,10 +159,14 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "wait_for",
-    "description": "Poll a target page until the given substring appears in document.body.innerText (Runtime.evaluate on a fixed interval), or throw on timeout. Text-substring waiting only — no aria/role/selector or event variants; throws rather than returning {found:false}.",
+    "description": "Poll a target page until the given substring appears in document.body.innerText (Runtime.evaluate on a fixed interval), or throw on timeout. Text-substring waiting only: no aria/role/selector or event variants; throws rather than returning {found:false}.",
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -160,6 +196,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Page selector: 'active' (or omit) -> first page-type target | '<32-hex targetId>' -> exact target by id | 'index:N' -> Nth page-type target (0-based) | 'url:<substring>' -> first page whose url contains substring | 'title:<substring>' -> first page whose title contains substring."
@@ -185,10 +225,14 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "take_snapshot",
-    "description": "Capture the page's accessibility tree (Accessibility.getFullAXTree) as a compact indented text tree where each line is prefixed with [uid] — the node's CDP backendDOMNodeId. These uids are the stateless element references that every interaction tool (click/hover/fill/etc.) feeds back to resolve a live DOM node (via DOM.resolveNode({ backendNodeId: uid })), so run this first to discover uids.",
+    "description": "Capture the page's accessibility tree (Accessibility.getFullAXTree) as a compact indented text tree where each line is prefixed with [uid], the node's CDP backendDOMNodeId. These uids are the stateless element references that every interaction tool (click/hover/fill/etc.) feeds back to resolve a live DOM node (via DOM.resolveNode({ backendNodeId: uid })), so run this first to discover uids.",
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default, = first page-type target) | 'index:N' (Nth page-type target, 0-based) | 'url:<substring>' | 'title:<substring>' | '<32-hex targetId>' (exact target by id)."
@@ -208,6 +252,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -244,6 +292,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -267,6 +319,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -315,6 +371,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -344,6 +404,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -386,6 +450,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -415,6 +483,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -443,6 +515,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -474,10 +550,14 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "take_screenshot",
-    "description": "Capture the viewport (default), the full scrollable page (fullPage), or a single element (uid or selector — exactly one, mutually exclusive) via raw CDP Page.captureScreenshot. Writes a PNG/JPEG under /tmp/cdp-toolkit (override with savePath) and returns {path,bytes,format,target}; raw base64 is only included when returnBase64 is set. quality applies to jpeg only.",
+    "description": "Capture the viewport (default), the full scrollable page (fullPage), or a single element (uid or selector, exactly one and mutually exclusive) via raw CDP Page.captureScreenshot. Writes a PNG/JPEG under /tmp/cdp-toolkit (override with savePath) and returns {path,bytes,format,target}; raw base64 is only included when returnBase64 is set. quality applies to jpeg only.",
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector. undefined or 'active' -> first page target; '<32-hex targetId>' -> exact target by id; 'index:N' -> Nth page target (0-based); 'url:<substring>' -> first page whose url contains substring; 'title:<substring>' -> first page whose title contains substring."
@@ -500,7 +580,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "uid": {
           "type": "number",
-          "description": "Element to clip to — a CDP backendDOMNodeId obtained from take_snapshot. Mutually exclusive with selector."
+          "description": "Element to clip to: a CDP backendDOMNodeId obtained from take_snapshot. Mutually exclusive with selector."
         },
         "selector": {
           "type": "string",
@@ -525,6 +605,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -621,6 +705,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -655,6 +743,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (or omitted) for the first page-type target | 'index:N' (0-based) | 'url:<substring>' | 'title:<substring>' | a 32-hex <targetId>."
@@ -688,6 +780,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
@@ -707,10 +803,14 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "get_console_message",
-    "description": "Return a single console entry by zero-based index from the target's existing console buffer. Throws if the index is out of range — run list_console_messages (optionally with reload:true) first to populate the buffer.",
+    "description": "Return a single console entry by zero-based index from the target's existing console buffer. Throws if the index is out of range; run list_console_messages (optionally with reload:true) first to populate the buffer.",
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
@@ -730,6 +830,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
@@ -753,17 +857,21 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "get_network_request",
-    "description": "Return one network request (matched by exact requestId, else by url substring) including status/headers. Requires at least one of requestId or url (throws otherwise). With includeBody:true the body fetch drives a fresh reload capture and is matched by url ONLY (reload re-mints requestIds, so a carried-over requestId cannot fetch a body — it returns metadata plus bodyUnavailableReason).",
+    "description": "Return one network request (matched by exact requestId, else by url substring) including status/headers. Requires at least one of requestId or url (throws otherwise). With includeBody:true the body fetch drives a fresh reload capture and is matched by url ONLY (reload re-mints requestIds, so a carried-over requestId cannot fetch a body, so it returns metadata plus bodyUnavailableReason).",
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
         },
         "requestId": {
           "type": "string",
-          "description": "Match by exact requestId (metadata only — cannot fetch a body, since reload re-mints requestIds)."
+          "description": "Match by exact requestId (metadata only, cannot fetch a body, since reload re-mints requestIds)."
         },
         "url": {
           "type": "string",
@@ -788,6 +896,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -806,10 +918,14 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "performance_stop_trace",
-    "description": "Stop the in-process trace started by performance_start_trace, drain buffered Tracing.dataCollected events, write the trace JSON under /tmp/cdp-toolkit, and return {path,bytes,events,metrics}. Throws if no live trace exists in this process (e.g. start ran in a different process) — use performance_trace instead. The 'target' arg is accepted only for API symmetry; at most one trace is ever live per process.",
+    "description": "Stop the in-process trace started by performance_start_trace, drain buffered Tracing.dataCollected events, write the trace JSON under /tmp/cdp-toolkit, and return {path,bytes,events,metrics}. Throws if no live trace exists in this process (e.g. start ran in a different process); use performance_trace instead. The 'target' arg is accepted only for API symmetry; at most one trace is ever live per process.",
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -821,10 +937,14 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "performance_analyze_insight",
-    "description": "CDP-native approximation of the DevTools insight analyzer: read a trace JSON file (bare array or {traceEvents:[...]}) at the given tracePath and return headline metrics (FCP/LCP/CLS/TBT, long tasks, layout shifts). Requires an explicit tracePath returned by performance_trace/performance_stop_trace — there is no implicit 'latest trace'. Numbers approximate DevTools (no main-thread attribution or frame-scoped LCP).",
+    "description": "CDP-native approximation of the DevTools insight analyzer: read a trace JSON file (bare array or {traceEvents:[...]}) at the given tracePath and return headline metrics (FCP/LCP/CLS/TBT, long tasks, layout shifts). Requires an explicit tracePath returned by performance_trace/performance_stop_trace; there is no implicit 'latest trace'. Numbers approximate DevTools (no main-thread attribution or frame-scoped LCP).",
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "tracePath": {
           "type": "string",
           "description": "Filesystem path to a trace JSON file written by performance_trace or performance_stop_trace (bare array OR {traceEvents:[...]}). Required."
@@ -836,10 +956,14 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "performance_trace",
-    "description": "PRIMARY one-shot trace: start tracing, optionally reload or navigate the page, wait durationMs (default 3000), end the trace, write the trace JSON under /tmp/cdp-toolkit, and return {path,bytes,events,metrics,target}. Holds one connection open for the whole window, so it is immune to the cross-process limitation of start/stop — the recommended entry point.",
+    "description": "PRIMARY one-shot trace: start tracing, optionally reload or navigate the page, wait durationMs (default 3000), end the trace, write the trace JSON under /tmp/cdp-toolkit, and return {path,bytes,events,metrics,target}. Holds one connection open for the whole window, so it is immune to the cross-process limitation of start/stop, and it is the recommended entry point.",
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -874,6 +998,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
@@ -893,9 +1021,13 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "url": {
           "type": "string",
-          "description": "The URL to audit. Required — never points at a user tab implicitly."
+          "description": "The URL to audit. Required, and never points at a user tab implicitly."
         },
         "categories": {
           "type": "array",
@@ -929,10 +1061,14 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "mock_request",
-    "description": "Register a mock rule on a target's persistent fake-backend session (CDP Fetch domain): intercept requests whose URL matches urlPattern and fulfill them with a canned response, fail (abort) them, or continue them — optionally with fault injection (delayMs/failRate). The session survives reloads and navigations and lives until clear_mocks. Call repeatedly to mock several endpoints on the same target. Pass reload:true to apply immediately. Persistent across calls only via the MCP server (not the one-shot CLI).",
+    "description": "Register a mock rule on a target's persistent fake-backend session (CDP Fetch domain): intercept requests whose URL matches urlPattern and fulfill them with a canned response, fail (abort) them, or continue them, optionally with fault injection (delayMs/failRate). The session survives reloads and navigations and lives until clear_mocks. Call repeatedly to mock several endpoints on the same target. Pass reload:true to apply immediately. Persistent across calls only via the MCP server (not the one-shot CLI).",
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target selector: active | index:N | url:<substr> | title:<substr> | <targetId>. Defaults to the active page."
@@ -999,6 +1135,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Unused filter placeholder; list_mocks returns all active sessions."
@@ -1014,6 +1154,10 @@ export const MANIFEST: ToolSpec[] = [
     "inputSchema": {
       "type": "object",
       "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
         "target": {
           "type": "string",
           "description": "Target selector whose mock session to clear. Defaults to the active page. Ignored when all:true."
@@ -1026,5 +1170,59 @@ export const MANIFEST: ToolSpec[] = [
       "required": [],
       "additionalProperties": false
     }
+  },
+  {
+    "name": "claim_page",
+    "description": "Take exclusive ownership of a browser tab and return an opaque lease token. With no targetId, opens a fresh tab (optionally at url) and claims it, so 'give me my own tab' is one call. Any later tool call against a leased tab must carry the matching token in its 'lease' argument or it is refused, naming the holder. The lease is reclaimable once its owning process dies, its ttlMs elapses without use, or its tab is closed. Refused from the CLI: a CLI invocation is one process per call, so its lease would be reclaimable immediately.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "targetId": {
+          "type": "string",
+          "description": "Claim this already-open page target instead of opening a new tab. Must be an exact target id, not a selector."
+        },
+        "url": {
+          "type": "string",
+          "description": "When opening a fresh tab, navigate it here. Ignored when targetId is given."
+        },
+        "label": {
+          "type": "string",
+          "description": "Agent label recorded on the lease and surfaced in conflict errors and list_leases. Defaults to pid-<pid>."
+        },
+        "ttlMs": {
+          "type": "number",
+          "description": "How long the lease survives without use before it is reclaimable. Defaults to CDP_LEASE_TTL_MS, else 900000 (15 minutes). Every checked call refreshes it, so an active agent never expires."
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "release_page",
+    "description": "Release a held lease, given its token. Idempotent: releasing an already-released, reclaimed, or expired lease reports released:false rather than erroring. Does not close the tab.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "lease": {
+          "type": "string",
+          "description": "The opaque token claim_page (or new_page with claim:true) returned."
+        }
+      },
+      "required": [
+        "lease"
+      ],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "list_leases",
+    "description": "Enumerate every active lease for diagnosis: backend, target id, agent label, pid, createdAt, lastUsedAt, ttlMs, whether the owning process is still alive, and whether the lease is reclaimable and why. Requires no token. Never returns the lease nonce, so this cannot be used to forge a token. A row for a lease file that could not be read or parsed instead carries `unreadable` (the errno, or \"unparseable\"), with label, pid, and the timestamp fields as zero placeholders and stale always false, since stale is what marks a lease free to take and an unreadable one must never read that way.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {},
+      "required": [],
+      "additionalProperties": false
+    }
   }
 ];

package/src/mcp.ts

@@ -3,7 +3,7 @@
  * cdp-toolkit MCP server (stdio).
  *
  * Exposes the toolkit's raw-CDP tools to any MCP client (Claude Code, etc.) over
- * the standard stdio transport. It does NOT connect to Chrome at startup — each
+ * the standard stdio transport. It does NOT connect to Chrome at startup: each
  * tool call lazily opens a single-target CDP connection (with its own timeout),
  * so the server loads cleanly even when Chrome isn't running; individual calls
  * then fail with a clear error if the browser is unreachable.
@@ -11,18 +11,29 @@
  * Launch: `bunx -y cdp-toolkit`  (or `bun run src/mcp.ts` from a checkout)
  * Config:  CDP_BASE (default http://127.0.0.1:9222), CDP_TIMEOUT_MS, CDP_ARTIFACT_DIR.
  *
- * stdout is the JSON-RPC channel — all diagnostics go to stderr only.
+ * stdout is the JSON-RPC channel, all diagnostics go to stderr only.
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { TOOLS, TOOL_NAMES, BASE } from "./index.ts";
 import { MANIFEST } from "./manifest.ts";
+import { resolveBrowserKind, stripBrowserFlag, getOrCreateFirefoxSession, disposeFirefoxSession } from "./backend.ts";
+import { toolAvailability } from "./capabilities.ts";
+import { FIREFOX_TOOLS } from "./firefox-tools.ts";
+import { leaseFromArgs, withLeaseScope } from "./leases.ts";
 
-const VERSION = "1.0.0";
+const VERSION = "1.2.0";
+
+// --browser is read once at startup (MCP has no per-call notion of backend): explicit flag,
+// else CDP_BROWSER env var, else "chrome" (zero behavior change for existing users/configs).
+const BROWSER = resolveBrowserKind(stripBrowserFlag(process.argv.slice(2)));
+const AVAILABILITY = toolAvailability(BROWSER);
+const AVAILABLE_NAMES = new Set<string>(AVAILABILITY.available);
 
 /** Loose dispatch view of the strongly-typed TOOLS registry. */
 const dispatch = TOOLS as Record<string, (args: unknown) => Promise<unknown>>;
+const neutralDispatch = FIREFOX_TOOLS as Record<string, (driver: import("./driver.ts").BrowserDriver, args: unknown) => Promise<unknown>>;
 
 /** Warn (to stderr) about any registry/manifest drift, but don't fail startup. */
 function auditCoverage(): void {
@@ -37,25 +48,72 @@ function auditCoverage(): void {
 const server = new Server({ name: "cdp-toolkit", version: VERSION }, { capabilities: { tools: {} } });
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
-  tools: MANIFEST.map((s) => ({ name: s.name, description: s.description, inputSchema: s.inputSchema })),
+  // Filtered to whatever the selected backend can actually run, per REQUIRED_CAPABILITIES:
+  // under Chrome this is byte-identical to the unfiltered MANIFEST (every capability CDP needs
+  // is declared); under Firefox the performance/heap/lighthouse tools are simply absent.
+  tools: MANIFEST.filter((s) => AVAILABLE_NAMES.has(s.name)).map((s) => ({ name: s.name, description: s.description, inputSchema: s.inputSchema })),
 }));
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name } = request.params;
   const args = (request.params.arguments ?? {}) as unknown;
-  const fn = dispatch[name];
-  if (!fn) {
-    return { content: [{ type: "text" as const, text: `unknown tool: ${name}` }], isError: true };
-  }
-  try {
-    const result = await fn(args);
-    return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true };
+
+  if (!AVAILABLE_NAMES.has(name)) {
+    const gap = AVAILABILITY.unavailable.find((u) => u.name === name);
+    return {
+      content: [{ type: "text" as const, text: `unknown tool: ${name}${gap ? ` (not available under --browser ${BROWSER}, needs: ${gap.missing.join(", ")})` : ""}` }],
+      isError: true,
+    };
   }
+
+  // ONE lease scope per dispatch, wrapping BOTH backend branches. This is the
+  // reason no tool takes a lease parameter: the token rides the async context
+  // down to whichever resolution path the tool eventually reaches, so a tool
+  // added tomorrow is covered with no action from whoever writes it. Reading
+  // 'lease' off args here is the only place the MCP layer knows the key exists.
+  return withLeaseScope(leaseFromArgs(args), async () => {
+    if (BROWSER === "chrome") {
+      const fn = dispatch[name];
+      if (!fn) return { content: [{ type: "text" as const, text: `unknown tool: ${name}` }], isError: true };
+      try {
+        const result = await fn(args);
+        return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true };
+      }
+    }
+
+    // Firefox: one BiDi session memoized for the life of this server process (lifetime "session",
+    // ADR-001); launched lazily on the first Firefox tool call, torn down on shutdown below.
+    const neutralFn = neutralDispatch[name];
+    if (!neutralFn) return { content: [{ type: "text" as const, text: `unknown tool: ${name}` }], isError: true };
+    try {
+      const session = await getOrCreateFirefoxSession();
+      const result = await neutralFn(session.driver, args);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true };
+    }
+  });
 });
 
 auditCoverage();
 await server.connect(new StdioServerTransport());
-console.error(`[cdp-toolkit] MCP server v${VERSION} ready — ${MANIFEST.length} tools, CDP_BASE=${BASE}`);
+console.error(`[cdp-toolkit] MCP server v${VERSION} ready, browser=${BROWSER}, ${AVAILABILITY.available.length} tools, CDP_BASE=${BASE}`);
+
+// Firefox owns a real OS process (see bidi/launch.ts): it must be reaped on every shutdown path,
+// not just a clean exit. SIGINT/SIGTERM cover ctrl-C and a supervising client killing the server;
+// stdin 'close' covers the normal MCP shutdown (the client closes the stdio pipe). All three are
+// idempotent through disposeFirefoxSession(), and a no-op entirely when Firefox was never launched.
+let shuttingDown = false;
+async function shutdown(): Promise<void> {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  await disposeFirefoxSession();
+  process.exit(0);
+}
+process.on("SIGINT", () => void shutdown());
+process.on("SIGTERM", () => void shutdown());
+process.stdin.on("close", () => void shutdown());