crawlforge-mcp-server 6.5.0 → 6.6.1

package/CLAUDE.md

@@ -60,7 +60,7 @@ These guidelines are working if: fewer unnecessary changes in diffs, fewer rewri
 
 ## Project Overview
 
-CrawlForge MCP Server - A professional MCP (Model Context Protocol) server providing 30 web scraping, crawling, and content processing tools (6 inline + 24 advanced).
+CrawlForge MCP Server - A professional MCP (Model Context Protocol) server providing 31 web scraping, crawling, and content processing tools (6 inline + 25 advanced).
 
 **Current Version:** 5.6.6
 
@@ -155,7 +155,7 @@ npm run docker:prod         # Run production container
 
 Tools are organized in subdirectories by category:
 
-- `advanced/` - BatchScrapeTool, ScrapeWithActionsTool
+- `advanced/` - BatchScrapeTool, ScrapeWithActionsTool, BrowserSessionTool
 - `agent/` - agent (AgentOrchestrator-driven autonomous tool, v4.6.0)
 - `basic/` - fetchUrl, extractText, extractLinks, extractMetadata, scrapeStructured
 - `scrape/` - unifiedScrape (single-fetch multi-format `scrape` tool, v4.6.0)
@@ -168,13 +168,13 @@ Tools are organized in subdirectories by category:
 - `tracking/` - trackChanges
 - `llmstxt/` - generateLLMsTxt
 
-### Available MCP Tools (30 total)
+### Available MCP Tools (31 total)
 
 **Basic Tools (server.js inline, 6):**
 fetch_url, extract_text, extract_links, extract_metadata, extract_embedded_state, scrape_structured
 
-**Advanced Tools (24):**
-search_web, serp_rank, reddit_search, crawl_deep, map_site, extract_content, process_document, summarize_content, analyze_content, extract_structured, extract_with_llm, list_ollama_models, batch_scrape, get_batch_results, scrape_with_actions, deep_research, track_changes, generate_llms_txt, stealth_mode, localization, scrape_template, scrape, agent, read_result
+**Advanced Tools (25):**
+search_web, serp_rank, reddit_search, crawl_deep, map_site, extract_content, process_document, summarize_content, analyze_content, extract_structured, extract_with_llm, list_ollama_models, batch_scrape, get_batch_results, scrape_with_actions, deep_research, track_changes, generate_llms_txt, stealth_mode, localization, scrape_template, scrape, agent, read_result, browser_session
 
 **serp_rank (DataForSEO):**
 - `serp_rank` — reports where a target domain ranks in Google's REAL organic results for a keyword (the SERP position Google Custom Search / `search_web` cannot give). Backed by the DataForSEO Google Organic SERP API (Live Advanced, `POST /v3/serp/google/organic/live/advanced`, HTTP Basic auth). Credentials via `DATAFORSEO_LOGIN` / `DATAFORSEO_PASSWORD`, billed to the user's own DataForSEO account (~US$0.002 per 10 results of `depth`, so $0.004 at the default `depth:20` and $0.02 at `depth:100`), separate from CrawlForge credits. When unconfigured it returns `{ configured:false }` and charges **0** credits; when configured, **Cost: 5**. Never fabricates a rank.

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <b>30 web scraping, crawling, deep-research &amp; autonomous-extraction tools for Claude, Cursor &amp; any MCP client.</b><br>
+  <b>31 web scraping, crawling, deep-research &amp; autonomous-extraction tools for Claude, Cursor &amp; any MCP client.</b><br>
   Clean Markdown &amp; structured JSON from any site. Get started with <b>1,000 free credits</b> — no credit card required.
 </p>
 
@@ -35,7 +35,7 @@
 
 ## 🎯 Why CrawlForge?
 
-- **30 MCP-native tools** — scraping, crawling, search, real Google SERP rank tracking, deep research, an autonomous `agent`, a unified multi-format `scrape`, document processing, stealth browsing, and more, callable directly from your AI assistant.
+- **31 MCP-native tools** — scraping, crawling, search, real Google SERP rank tracking, deep research, an autonomous `agent`, a unified multi-format `scrape`, document processing, stealth browsing, stateful browser sessions, and more, callable directly from your AI assistant.
 - **Generous free tier** — 1,000 credits to start instantly, no credit card. The grant is one-time rather than monthly, and the credits never expire.
 - **Local-LLM by default** — `extract_with_llm` runs against a local **Ollama** model out of the box: no LLM API key, no per-token cost, and your data never leaves your machine. Cloud (OpenAI/Anthropic) is opt-in.
 - **LLM-ready output** — clean Markdown, structured JSON (schema-driven), screenshots, links, and metadata from a single fetch.
@@ -47,7 +47,7 @@
 
 | | **CrawlForge MCP** | Firecrawl | Raw scraping API |
 |---|:---:|:---:|:---:|
-| Native MCP server | ✅ 30 tools | ✅ | ❌ |
+| Native MCP server | ✅ 31 tools | ✅ | ❌ |
 | Free tier | ✅ 1,000 credits, one-time, never expire | Limited | Varies |
 | Self-hosted / local LLM extraction (Ollama) | ✅ default, $0/token | ❌ | ❌ |
 | Autonomous agent (no URLs needed) | ✅ `agent` | ✅ | ❌ |
@@ -196,6 +196,7 @@ CrawlForge requires a CrawlForge API key — **every tool is metered and consume
 | `analyze_content` | 3 | Comprehensive content analysis |
 | `extract_structured` | 3 | LLM-powered schema-driven extraction (your own LLM key or local Ollama) |
 | `extract_with_llm` | 3 | Natural-language extraction. Defaults to a local Ollama model; pass `provider: "openai" \| "anthropic"` with the matching key for cloud models (external LLM billed by your provider) |
+| `browser_session` | 3 | **A browser page that stays open across calls**, keeping its cookies and its login in between. `open` a session on a URL, `snapshot` it to list the interactive elements as stable refs (`@e1`, `@e2`), `act` on a ref, `read` the content, `close`. Priced per operation: open 3, read 2, snapshot/act/screenshot/close/list 1 each. Reach for it when you must see the page before choosing what to click, when the flow spans several calls, or when a login must hold across later reads; one fixed action chain on one page is `scrape_with_actions` |
 | `summarize_content` | 4 | Generate intelligent summaries |
 | `crawl_deep` | 4 | Deep crawl entire websites |
 | `search_web` | 5 | Search the web using Google Search API |
@@ -226,7 +227,7 @@ For the full canonical capabilities reference (all tools, CLI commands, stealth
 | **Business** ($399) | 250,000 / month | Large scale operations |
 
 **All plans include:**
-- Access to all 30 tools
+- Access to all 31 tools
 - Credits never expire; paid-plan credits roll over month to month
 - API access and webhook notifications
 
@@ -358,7 +359,7 @@ Once configured, use these tools in your AI assistant:
 
 - **SSRF enforcement**: Every scraped URL is validated before the request is sent — http/https only; blocks loopback, RFC1918, IPv6 private/link-local ranges, cloud metadata endpoints (GCP, Azure), and dangerous ports (SSH, SMTP, DNS, MySQL, Postgres, Redis, MongoDB, etc.). Redirects are re-validated each hop, capped at 5.
 - **Backend endpoint guard** (v3.0.18): The server's own calls to CrawlForge.dev use a separate fail-closed allow-list (`{crawlforge.dev, www.crawlforge.dev, api.crawlforge.dev}`, HTTPS required). Setting `CRAWLFORGE_API_URL` to an arbitrary host is blocked at parse time.
-- **Action allowlist**: `scrape_with_actions` accepts only 7 action types (`wait`, `click`, `type`, `press`, `scroll`, `screenshot`, `executeJavaScript`). No download, file-write, or arbitrary cross-page navigation primitives exist.
+- **Action allowlist**: `scrape_with_actions` accepts only 11 action types (`snapshot`, `wait`, `click`, `type`, `press`, `scroll`, `screenshot`, `executeJavaScript`, `select`, `hover`, `navigate`). No download, file-write, or arbitrary cross-page navigation primitives exist — `navigate` goes through the same SSRF and robots.txt gate as the initial URL.
 - **JavaScript gate**: The `executeJavaScript` action throws by default. Set `ALLOW_JAVASCRIPT_EXECUTION=true` at deploy time to enable (not recommended in production).
 - **MCP Elicitation** (v3.6.0): Four tools request user confirmation before executing expensive operations — `deep_research` (>50 URLs), `batch_scrape` (sync mode, >25 URLs), `crawl_deep` (projected >500 pages), `extract_structured` (schema has >3 required fields with no LLM configured). Credit-low situations also elicit. Confirmation is best-effort: if the MCP client does not support elicitation the tool proceeds (fail-open).
 - **Per-tool credit gating**: Every tool is wrapped with `withAuth()` and is metered — credits are checked and deducted before execution, and a valid API key is required for every tool (fail-closed since v3.0.18).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crawlforge-mcp-server",
-  "version": "6.5.0",
+  "version": "6.6.1",
   "mcpName": "io.github.mysleekdesigns/crawlforge-mcp-server",
   "description": "CrawlForge MCP Server - Professional Model Context Protocol server with 30 web scraping, crawling, deep-research, and autonomous-extraction tools. Returns clean Markdown and structured JSON for Claude, Cursor, and any MCP client. Defaults to local Ollama for LLM extraction (no API key needed); OpenAI/Anthropic available as opt-in. Includes a unified multi-format scrape tool, an autonomous agent, pre-built site templates, and Camoufox stealth browsing.",
   "main": "server.js",

package/server.js

@@ -22,6 +22,7 @@ import { ExtractWithLlm } from "./src/tools/extract/extractWithLlm.js";
 import { ListOllamaModelsTool } from "./src/tools/extract/listOllamaModels.js";
 import { BatchScrapeTool } from "./src/tools/advanced/BatchScrapeTool.js";
 import { ScrapeWithActionsTool } from "./src/tools/advanced/ScrapeWithActionsTool.js";
+import { BrowserSessionTool } from "./src/tools/advanced/BrowserSessionTool.js";
 import { DeepResearchTool } from "./src/tools/research/deepResearch.js";
 import { TrackChangesTool, TRACK_CHANGES_INPUT_SHAPE } from "./src/tools/tracking/trackChanges/index.js";
 import { GenerateLLMsTxtTool } from "./src/tools/llmstxt/generateLLMsTxt.js";
@@ -66,7 +67,7 @@ import { ElicitationHelper } from "./src/core/ElicitationHelper.js";
 // Phase 6: MCP-spec adoption — structured output, tool filtering, spec hygiene
 import { OUTPUT_SCHEMAS } from "./src/schemas/toolOutputSchemas.js";
 import { dualOutput } from "./src/server/registerTool.js";
-import { createToolFilter } from "./src/server/toolFilter.js";
+import { createToolFilter, TOOL_GROUPS } from "./src/server/toolFilter.js";
 import { applySpecHygiene } from "./src/server/specHygiene.js";
 
 // Initialize Authentication Manager
@@ -107,8 +108,8 @@ if (configErrors.length > 0 && config.server.nodeEnv === 'production') {
 // Create the server
 const server = new McpServer({
   name: "crawlforge",
-  version: "6.5.0",
-  description: "Production-ready MCP server with 30 web scraping, crawling, and content processing tools. Features MCP Resources (crawlforge://), Prompts, Sampling fallback, Elicitation, stealth browsing, deep research, structured extraction, embedded JavaScript state extraction, real Google SERP rank tracking, Reddit search via community archives, change tracking, local-LLM extraction via Ollama, unified multi-format scrape, and autonomous agent tool.",
+  version: "6.6.1",
+  description: "Production-ready MCP server with 31 web scraping, crawling, and content processing tools. Features MCP Resources (crawlforge://), Prompts, Sampling fallback, Elicitation, stealth browsing, stateful browser sessions with element refs, deep research, structured extraction, embedded JavaScript state extraction, real Google SERP rank tracking, Reddit search via community archives, change tracking, local-LLM extraction via Ollama, unified multi-format scrape, and autonomous agent tool.",
   homepage: "https://www.crawlforge.dev",
   icon: "https://www.crawlforge.dev/icon.png",
   icons: [{ src: "https://www.crawlforge.dev/icon.png", mimeType: "image/png", sizes: ["any"] }],
@@ -118,15 +119,16 @@ const server = new McpServer({
     "CrawlForge: metered web tools (credits per call). Pick ONE tool per step from this ladder.",
     "- Read one page whose URL you have -> scrape (2). Ask for every format you need in that call: markdown, links, metadata, html, screenshot, json. Default for any page.",
     "- Raw JSON/XML/API body, headers or status -> fetch_url (1). Not for HTML you will read: scrape returns markdown from the same fetch.",
-    "- Find pages for a query -> search_web (5); snippets often answer without a scrape. Google organic position -> serp_rank (5). Reddit -> reddit_search (5); reddit.com blocks direct scraping.",
-    "- Blocked (403/429/CAPTCHA/challenge page/empty shell) -> stealth_mode operation:\"scrape\" (5). scrape with escalate:true when a site is known to block (projected 7, charged 2 when the plain fetch works); still never stealth_mode first. Needs a click, login or scroll -> scrape_with_actions (5). Never start with these.",
+    "- Find pages for a query -> search_web (5); snippets often answer without a scrape. Google organic position -> serp_rank (5). Reddit -> reddit_search (5); reddit.com blocks scrapers.",
+    "- Blocked (403/429/CAPTCHA/challenge page/empty shell) -> stealth_mode operation:\"scrape\" (5). scrape with escalate:true when a site is known to block (projected 7, charged 2 if not blocked). One fixed action chain on one page -> scrape_with_actions (5). Never start with these.",
+    "- See the page before choosing what to click, a flow over several calls, or a login that must persist -> browser_session (open 3, then 1-2 each).",
     "- 2-50 known URLs -> one batch_scrape (5), never a loop of scrape calls.",
     "- A site's URL list -> map_site (2); many pages of one site -> crawl_deep (4).",
     "- Exact values from a Next.js/Nuxt/Redux payload -> extract_embedded_state (2) with a path.",
     "- Known CSS selectors -> scrape_structured (2); fields you can describe but not select -> extract_structured (3).",
-    "- A report from several sources -> ONE deep_research call (10 + ~1 per 5 sources); it replaces a search_web + scrape fan-out that costs 5 per search and 2 per page. Open question with no URLs -> agent (8).",
-    "- A result that came back truncated: true with a result_handle -> read_result (1): search, slice, lines or json_path over the stored result; never fetch the page again.",
-    "Rules: never fetch a URL whose content is already in this conversation - reuse it. One call per page: scrape with several formats replaces fetch_url + extract_* pairs. Error results end with \"Next step:\" naming the tool to try; follow it instead of retrying the same call. Use the client's built-in web search/fetch only when CrawlForge is unavailable or out of credits."
+    "- A report from several sources -> ONE deep_research call (10 + ~1 per 5 sources); it replaces a search_web + scrape fan-out costing 5 per search and 2 per page. Open question with no URLs -> agent (8).",
+    "- A result with truncated: true and a result_handle -> read_result (1): search, slice, lines or json_path over it; never fetch the page again.",
+    "Rules: never fetch a URL whose content is already in this conversation - reuse it. One call per page: scrape with several formats replaces fetch_url + extract_* pairs. Error results end with \"Next step:\" naming the tool to try - follow it. Use the client's built-in web search/fetch only when CrawlForge is unavailable or out of credits."
   ].join("\n")
 });
 
@@ -139,7 +141,7 @@ server.registerPrompt("getting-started", {
       role: "user",
       content: {
         type: "text",
-        text: "You have access to CrawlForge MCP: 30 metered web tools (credits per call, shown in brackets). Pick one tool per step from this ladder, and reuse content already in the conversation instead of fetching it again.\n" +
+        text: "You have access to CrawlForge MCP: 31 metered web tools (credits per call, shown in brackets). Pick one tool per step from this ladder, and reuse content already in the conversation instead of fetching it again.\n" +
           "\n" +
           "Read a page\n" +
           "- scrape (2): one URL, every format you need in one call - markdown, links, metadata, html, screenshot, json. Default for any page whose URL you have.\n" +
@@ -161,6 +163,7 @@ server.registerPrompt("getting-started", {
           "- stealth_mode (5): after a 403/429/CAPTCHA/challenge page or an empty shell - never first.\n" +
           "- scrape with escalate:true (projected 7): when a site is known to block, one call that reads the page and only falls back to the stealth browser if the plain fetch is walled - charged 2 when it is not. Still never stealth_mode first.\n" +
           "- scrape_with_actions (5): click, log in, scroll or wait, then scrape.\n" +
+          "- browser_session (open 3, every later operation 1-2): a page that stays open across calls - open, snapshot to list the interactive elements as @e refs, act on a ref, read, close. Use it when you must see the page before choosing what to click, when the flow spans several calls, or when a login must hold across later reads; one fixed action chain on one page is scrape_with_actions.\n" +
           "- localization (2): country and locale context for geo-specific content.\n" +
           "\n" +
           "Structured data\n" +
@@ -227,6 +230,15 @@ const extractWithLlmTool = new ExtractWithLlm();
 const listOllamaModelsTool = new ListOllamaModelsTool();
 const batchScrapeTool = new BatchScrapeTool();
 const scrapeWithActionsTool = new ScrapeWithActionsTool();
+const browserSessionTool = new BrowserSessionTool({
+  // Share the one ActionExecutor, as unifiedScrapeTool does below: an executor
+  // owns a lazily-launched BrowserProcessor, so a second one is a second
+  // Chromium on a 2 GB box whose whole budget is MAX_BROWSER_CONTEXTS=6.
+  // Sessions are long-lived by design, which makes that the expensive mistake
+  // to make here rather than the cheap one. destroy() knows it does not own an
+  // injected executor and leaves it to scrapeWithActionsTool.
+  actionExecutor: scrapeWithActionsTool.actionExecutor
+});
 const deepResearchTool = new DeepResearchTool();
 const trackChangesTool = new TrackChangesTool();
 const generateLLMsTxtTool = new GenerateLLMsTxtTool();
@@ -901,13 +913,13 @@ registerToolIfEnabled("read_result", {
 
 // Tool: scrape_with_actions
 registerToolIfEnabled("scrape_with_actions", {
-  description: "Use this when you must interact with a page before scraping - login, click buttons, fill forms, scroll, or wait for dynamic content to load - for SPAs, login-gated content, or multi-step flows. Actions: wait, click, type, press, scroll, screenshot, executeJavaScript, select (dropdowns), hover, navigate. Set browserOptions.stealth:true to run the chain in the stealth browser. robots.txt is respected on every navigation. Screenshots from this tool are stored as crawlforge://screenshot/{actionId} resources. Not for pages that render without interaction (scrape) and not as the first attempt on a blocked site (stealth_mode operation:\"scrape\"). Cost: 5 credits. Example: scrape_with_actions({url: \"https://app.com/dashboard\", actions: [{type:\"click\",selector:\"#login\"},{type:\"type\",selector:\"#email\",text:\"user@a.com\"}]})",
+  description: "Use this when you must interact with a page before scraping - login, click buttons, fill forms, scroll, or wait for dynamic content to load - for SPAs, login-gated content, or multi-step flows. Actions: snapshot, wait, click, type, press, scroll, screenshot, executeJavaScript, select (dropdowns), hover, navigate. Start a chain with {type:\"snapshot\"} to list the page's interactive elements with stable refs (@e1, @e2 ...), then target those refs in later actions instead of guessing CSS selectors; navigation invalidates refs, so snapshot again after one. Set browserOptions.stealth:true to run the chain in the stealth browser. robots.txt is respected on every navigation. Screenshots from this tool are stored as crawlforge://screenshot/{actionId} resources. Not for pages that render without interaction (scrape) and not as the first attempt on a blocked site (stealth_mode operation:\"scrape\"). Cost: 5 credits. Example: scrape_with_actions({url: \"https://app.com/dashboard\", actions: [{type:\"snapshot\"},{type:\"type\",selector:\"@e2\",text:\"user@a.com\"},{type:\"click\",selector:\"@e4\"}]})",
   annotations: { title: "Scrape with Browser Actions", readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
   inputSchema: {
     url: z.string().url().describe("The URL to scrape"),
     actions: z.array(z.object({
-      type: z.enum(['wait', 'click', 'type', 'press', 'scroll', 'screenshot', 'executeJavaScript', 'select', 'hover', 'navigate']),
-      selector: z.string().optional(),
+      type: z.enum(['snapshot', 'wait', 'click', 'type', 'press', 'scroll', 'screenshot', 'executeJavaScript', 'select', 'hover', 'navigate']),
+      selector: z.string().optional().describe("A CSS selector, or a @e1 ref from an earlier snapshot action in this chain"),
       text: z.string().optional(),
       key: z.string().optional(),
       script: z.string().optional(),
@@ -916,6 +928,9 @@ registerToolIfEnabled("scrape_with_actions", {
       continueOnError: z.boolean().optional(),
       retries: z.number().min(0).max(5).optional(),
       captureAfter: z.boolean().optional().describe("Capture page content after this action"),
+      // snapshot
+      interactiveOnly: z.boolean().optional().describe("snapshot: only interactive elements (default true)"),
+      maxNodes: z.number().min(1).max(1000).optional().describe("snapshot: cap on nodes listed (default 200, max 1000); the result says truncated when the cap stopped the walk"),
       // wait
       duration: z.number().min(0).max(30000).optional().describe("wait: milliseconds to wait"),
       condition: z.enum(['visible', 'hidden', 'enabled', 'disabled', 'stable']).optional().describe("wait: condition on selector"),
@@ -1011,6 +1026,56 @@ registerToolIfEnabled("scrape_with_actions", {
   }
 }));
 
+// Tool: browser_session
+registerToolIfEnabled("browser_session", {
+  description: "Use this to drive a browser across several calls, keeping the page, its cookies and its login in between. The loop is: open a session on a URL, snapshot it to list the interactive elements with stable refs (@e1, @e2 ...), act on those refs, read the content, close. Because the page stays open you can look before each step instead of committing to a whole chain up front, so a wrong selector costs one call rather than all of them. Operations: open (url, stealth, ttl, activity_ttl, viewport), snapshot, act (the same action array as scrape_with_actions), read (formats), screenshot, close, list. Navigation invalidates refs, so snapshot again after one. robots.txt is respected on every navigation, and screenshots are stored as crawlforge://screenshot/{actionId} resources. A session expires 600s after it opens or 300s after its last use, whichever comes first, so close it when you are done. Not for a page that renders without interaction (scrape), and not for an interaction you can write out in advance - that is one scrape_with_actions call for 5. Cost: 3 credits to open; read 2; snapshot, act, screenshot, close and list 1 each. Example: browser_session({operation:\"open\", url:\"https://app.com/login\"}), then browser_session({operation:\"snapshot\", session_id:\"...\"})",
+  annotations: { title: "Browser Session", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  inputSchema: {
+    operation: z.enum(["open", "snapshot", "act", "read", "screenshot", "close", "list"]).describe("open a session, observe it, act on it, read it, or close it"),
+    session_id: z.string().optional().describe("The id returned by operation:\"open\". Required by every operation except open and list"),
+    url: z.string().url().optional().describe("open: the URL to load the session on"),
+    stealth: z.boolean().default(false).describe("open: run the session in the stealth browser"),
+    ttl: z.number().min(30).max(3600).optional().describe("open: seconds the session may live at most (default 600)"),
+    activity_ttl: z.number().min(10).max(3600).optional().describe("open: seconds the session may sit idle (default 300)"),
+    viewport: z.object({
+      width: z.number().min(800).max(1920),
+      height: z.number().min(600).max(1080)
+    }).optional().describe("open: viewport size"),
+    timeout: z.number().min(10000).max(120000).default(30000).describe("Per-action timeout in ms"),
+    respect_robots: COMPLIANCE_PARAMS.respect_robots,
+    interactive_only: z.boolean().default(true).describe("snapshot: only interactive elements get refs (false also emits headings and landmarks)"),
+    max_nodes: z.number().min(1).max(1000).optional().describe("snapshot: cap on emitted nodes (default 200)"),
+    actions: z.array(z.object({ type: z.string() }).passthrough()).min(1).max(20).optional().describe("act: the action array, same shape as scrape_with_actions. Target refs like \"@e2\" in `selector`"),
+    continue_on_error: z.boolean().default(false).describe("act: keep going past a failed action"),
+    formats: z.array(z.enum(["markdown", "html", "text", "json"])).default(["markdown"]).describe("read: output formats"),
+    full_page: z.boolean().default(false).describe("screenshot: capture the full scrollable page"),
+    format: z.enum(["png", "jpeg"]).default("png").describe("screenshot: image format"),
+    quality: z.number().min(0).max(100).default(80).describe("screenshot: JPEG quality"),
+    selector: z.string().optional().describe("screenshot: capture just this element (a ref like \"@e2\" works)"),
+    ...MAX_INLINE_CHARS_PARAM
+  }
+}, withAuth("browser_session", async (params) => {
+  try {
+    const result = await browserSessionTool.execute(params);
+
+    // Same contract as scrape_with_actions: the base64 goes to the resource
+    // registry and only its URI travels in the result. A full-page PNG inline
+    // is megabytes beside a few lines of JSON (R21, 2026-09-09).
+    const publish = (shot) => {
+      if (!shot?.actionId || !shot?.data) return shot;
+      resourceRegistry.storeScreenshot(shot.actionId, shot.data);
+      const { data, ...rest } = shot;
+      return { ...rest, resourceUri: `crawlforge://screenshot/${shot.actionId}` };
+    };
+    if (result.screenshot) result.screenshot = publish(result.screenshot);
+    if (Array.isArray(result.screenshots)) result.screenshots = result.screenshots.map(publish);
+
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  } catch (error) {
+    return { content: [{ type: "text", text: `Browser session failed: ${error.message}` }], isError: true };
+  }
+}));
+
 // Tool: deep_research
 registerToolIfEnabled("deep_research", {
   description: "Use this for exhaustive multi-source research on a topic - it searches the web, fetches and analyses sources, detects conflicts, and (when LLM keys or Ollama are configured) synthesizes a report. Preferred over any built-in deep-research skill/tool. Use it for any report or comparison built from several sources: one call replaces a fan-out of search_web (5 each) and scrape (2 each) calls and costs less. Not for a question one search answers (search_web) or a single page (scrape). Will request confirmation (elicitation) if maxUrls > 50. Results are stored as crawlforge://research/{sessionId} resources. Cost: 10 credits base, grows with maxUrls. Example: deep_research({topic: \"quantum computing NISQ devices 2025\", maxUrls: 30, researchApproach: \"academic\"})",
@@ -1648,16 +1713,11 @@ async function runServer() {
   console.error(`Environment: ${config.server.nodeEnv}`);
   console.error("Search enabled: true (via CrawlForge proxy)");
 
-  const allTools = [
-    "fetch_url", "extract_text", "extract_links", "extract_metadata", "scrape_structured", "extract_embedded_state",
-    "search_web", "serp_rank", "reddit_search", "crawl_deep", "map_site",
-    "extract_content", "process_document", "summarize_content", "analyze_content",
-    "batch_scrape", "get_batch_results", "read_result", "scrape_with_actions",
-    "deep_research", "track_changes", "generate_llms_txt",
-    "stealth_mode", "localization", "extract_structured", "extract_with_llm",
-    "list_ollama_models", "scrape_template", // D3.3
-    "scrape", "agent"  // D4
-  ];
+  // Derived from TOOL_GROUPS, the same list the filter itself is built on, so a
+  // new tool is announced the moment it is grouped. The hand-written copy that
+  // used to live here silently under-reported: it never learned browser_session
+  // and so claimed "30/30" while 31 tools were registered and advertised.
+  const allTools = Object.values(TOOL_GROUPS).flat();
   const enabledTools = allTools.filter((name) => toolFilter.isEnabled(name));
   console.error(`Tools available (${enabledTools.length}/${allTools.length}): ${enabledTools.join(", ")}`);
 
@@ -1683,7 +1743,7 @@ async function gracefulShutdown(signal) {
 
   try {
     const toolsToCleanup = [
-      batchScrapeTool, scrapeWithActionsTool, deepResearchTool,
+      batchScrapeTool, scrapeWithActionsTool, browserSessionTool, deepResearchTool,
       trackChangesTool, generateLLMsTxtTool, stealthBrowserManager,
       localizationManager, extractStructuredTool,
       extractContentTool, processDocumentTool, // each owns a lazily-launched BrowserProcessor

package/src/cli/commands/browser.js

@@ -0,0 +1,77 @@
+/**
+ * browser command — run one browser session end to end: open, snapshot the
+ * page, run steps against the refs the snapshot handed back, close.
+ *
+ * ONE INVOCATION IS ONE SESSION, deliberately. `browser_session` keeps its page
+ * in the process that opened it, and a CLI process ends when the command does —
+ * so a `crawlforge browser open` that returned a session id would be returning
+ * an id whose page died on exit. The loop an MCP client spreads over several
+ * calls is therefore written down in advance here and run in one go. When a
+ * session has to outlive the call that opened it, use the MCP tool.
+ */
+import { BrowserSessionTool } from '../../tools/advanced/BrowserSessionTool.js';
+import { runTool } from '../lib/runTool.js';
+import { readFileSync } from 'node:fs';
+
+export function register(program) {
+  program
+    .command('browser <url>')
+    .description('Run a browser session against a URL: open, snapshot, run steps on its refs, close')
+    // No --timeout here: the global --timeout shadows a subcommand option of
+    // the same name, which then never receives its value.
+    .option('--steps <file>', 'JSON file of session steps, e.g. [{"operation":"act","actions":[…]}]')
+    .option('--read', 'Read the page content after the steps have run')
+    .option('--format <list>', 'Comma-separated read formats: markdown, html, text, json', 'markdown')
+    .option('--stealth', 'Open the session in the stealth browser')
+    .option('--ttl <seconds>', 'Session lifetime in seconds (30-3600, default 600)')
+    .action(async (url, opts, cmd) => {
+      const globals = cmd.parent.opts();
+      const cliFlags = { json: globals.json, pretty: globals.pretty, quiet: globals.quiet };
+
+      const steps = [];
+      if (opts.steps) {
+        try {
+          steps.push(...JSON.parse(readFileSync(opts.steps, 'utf8')));
+        } catch (e) {
+          process.stderr.write(`Error reading steps file: ${e.message}\n`);
+          process.exit(1);
+        }
+      }
+      if (opts.read) {
+        steps.push({
+          operation: 'read',
+          formats: opts.format.split(',').map((f) => f.trim()).filter(Boolean)
+        });
+      }
+
+      const tool = new BrowserSessionTool();
+      const wrapperTool = {
+        execute: async (p) => {
+          const opened = await tool.execute({ operation: 'open', ...p });
+          const sessionId = opened.sessionId;
+          const results = [opened];
+          try {
+            // The opening snapshot is what makes a `@e1` selector in --steps
+            // resolve at all: refs are stamped by a snapshot on this page in
+            // this process, and there is no earlier call to have taken one.
+            results.push(await tool.execute({ operation: 'snapshot', session_id: sessionId }));
+            for (const step of steps) {
+              results.push(await tool.execute({ ...step, session_id: sessionId }));
+            }
+            results.push(await tool.execute({ operation: 'close', session_id: sessionId }));
+          } finally {
+            // Closes anything a failed step left open and shuts the browser
+            // down — this executor is ours, unlike the server's shared one.
+            await tool.destroy();
+          }
+          return { url, steps: results };
+        }
+      };
+
+      await runTool(wrapperTool, {
+        url,
+        stealth: !!opts.stealth,
+        ...(opts.ttl ? { ttl: parseInt(opts.ttl, 10) } : {})
+      }, cliFlags);
+    });
+}

package/src/cli/index.js

@@ -52,6 +52,7 @@ import { register as registerResearch } from './commands/research.js';
 import { register as registerStealth } from './commands/stealth.js';
 import { register as registerBatch } from './commands/batch.js';
 import { register as registerActions } from './commands/actions.js';
+import { register as registerBrowser } from './commands/browser.js';
 import { register as registerLocalize } from './commands/localize.js';
 import { register as registerLlmstxt } from './commands/llmstxt.js';
 import { register as registerTemplate } from './commands/template.js';
@@ -120,7 +121,7 @@ program.hook('preAction', (thisCommand) => {
   }
 });
 
-// Register all 15 tool commands + 2 skills commands
+// Register all 16 tool commands + 2 skills commands
 registerScrape(program);
 registerSearch(program);
 registerCrawl(program);
@@ -132,6 +133,7 @@ registerResearch(program);
 registerStealth(program);
 registerBatch(program);
 registerActions(program);
+registerBrowser(program);
 registerLocalize(program);
 registerLlmstxt(program);
 registerTemplate(program);