crawlforge-mcp-server 6.0.0 → 6.2.0

package/README.md

@@ -69,7 +69,13 @@ npm install -g crawlforge-mcp-server
 
 ### 2. Setup Your API Key (required)
 
-Every tool requires a CrawlForge API key — new accounts get 1,000 free trial credits to start:
+Every tool requires a CrawlForge API key — new accounts get 1,000 free trial credits to start. The recommended path signs you in through the browser, so the key is never pasted into a terminal (a coding agent can run this for you and relay the URL):
+
+```bash
+crawlforge login
+```
+
+It prints an approval URL; open it, approve, and the key is stored in `~/.crawlforge/config.json`. Then run `crawlforge init` to register the MCP server with your client. Or use the interactive wizard, which also configures your clients:
 
 ```bash
 npx crawlforge-setup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crawlforge-mcp-server",
-  "version": "6.0.0",
+  "version": "6.2.0",
   "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

@@ -5,7 +5,7 @@
 export { isCreatorModeVerified } from './src/core/creatorMode.js';
 
 // Import everything else
-import { McpServer, ResourceTemplate } from "@modelcontextprotocol/server";
+import { McpServer, ResourceTemplate, isInputRequiredResult } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import { logger } from "./src/utils/Logger.js";
 import { SearchWebTool } from "./src/tools/search/searchWeb.js";
@@ -23,7 +23,7 @@ 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 { DeepResearchTool } from "./src/tools/research/deepResearch.js";
-import { TrackChangesTool } from "./src/tools/tracking/trackChanges/index.js";
+import { TrackChangesTool, TRACK_CHANGES_INPUT_SHAPE } from "./src/tools/tracking/trackChanges/index.js";
 import { GenerateLLMsTxtTool } from "./src/tools/llmstxt/generateLLMsTxt.js";
 import { ScrapeTemplateTool } from "./src/tools/templates/ScrapeTemplateTool.js"; // D3.3
 import { UnifiedScrapeTool, SCRAPE_INPUT_SHAPE } from "./src/tools/scrape/unifiedScrape.js"; // D4 D1
@@ -107,7 +107,7 @@ if (configErrors.length > 0 && config.server.nodeEnv === 'production') {
 // Create the server
 const server = new McpServer({
   name: "crawlforge",
-  version: "6.0.0",
+  version: "6.2.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.",
   homepage: "https://www.crawlforge.dev",
   icon: "https://www.crawlforge.dev/icon.png",
@@ -607,12 +607,15 @@ registerToolIfEnabled("crawl_deep", {
     ...REDACT_PII_PARAM
   },
   outputSchema: OUTPUT_SCHEMAS.crawl_deep
-}, withAuth("crawl_deep", async ({ url, max_depth, max_pages, include_patterns, exclude_patterns, follow_external, respect_robots, extract_content, content_max_length, concurrency, enable_link_analysis, link_analysis_options, domain_filter, import_filter_config, session }) => {
+}, withAuth("crawl_deep", async ({ url, max_depth, max_pages, include_patterns, exclude_patterns, follow_external, respect_robots, extract_content, content_max_length, concurrency, enable_link_analysis, link_analysis_options, domain_filter, import_filter_config, session }, ctx) => {
     try {
       if (!url) {
         return { content: [{ type: "text", text: "URL parameter is required" }], isError: true };
       }
-      const result = await crawlDeepTool.execute({ url, max_depth, max_pages, include_patterns, exclude_patterns, follow_external, respect_robots, extract_content, content_max_length, concurrency, enable_link_analysis, link_analysis_options, domain_filter, import_filter_config, session });
+      const result = await crawlDeepTool.execute({ url, max_depth, max_pages, include_patterns, exclude_patterns, follow_external, respect_robots, extract_content, content_max_length, concurrency, enable_link_analysis, link_analysis_options, domain_filter, import_filter_config, session }, ctx);
+      // A confirmation round trip is the SDK's result shape, not a tool payload:
+      // it must reach the transport unwrapped (Phase 4.4).
+      if (isInputRequiredResult(result)) return result;
       return dualOutput(result);
     } catch (error) {
       return { content: [{ type: "text", text: `Crawl failed: ${error.message}` }], isError: true };
@@ -763,12 +766,13 @@ registerToolIfEnabled("extract_structured", {
     ...VERIFY_NUMBERS_PARAM
   },
   outputSchema: OUTPUT_SCHEMAS.extract_structured
-}, withAuth("extract_structured", async (params) => {
+}, withAuth("extract_structured", async (params, ctx) => {
   try {
     // Forward params whole. This wrapper used to destructure a fixed six, which
     // silently dropped respect_robots and user_agent — both declared here and
     // read by the tool, so the G5 override was accepted and ignored.
-    const result = await extractStructuredTool.execute(params);
+    const result = await extractStructuredTool.execute(params, ctx);
+    if (isInputRequiredResult(result)) return result;
     return dualOutput(result);
   } catch (error) {
     return { content: [{ type: "text", text: `Structured extraction failed: ${error.message}` }], isError: true };
@@ -855,9 +859,10 @@ registerToolIfEnabled("batch_scrape", {
     ...MAX_INLINE_CHARS_PARAM,
     ...REDACT_PII_PARAM
   }
-}, withAuth("batch_scrape", async (params) => {
+}, withAuth("batch_scrape", async (params, ctx) => {
     try {
-      const result = await batchScrapeTool.execute(params);
+      const result = await batchScrapeTool.execute(params, ctx);
+      if (isInputRequiredResult(result)) return result;
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     } catch (error) {
       return { content: [{ type: "text", text: `Batch scrape failed: ${error.message}` }], isError: true };
@@ -1056,9 +1061,10 @@ registerToolIfEnabled("deep_research", {
     }).optional().describe("Webhook for progress and completion notifications"),
     ...MAX_INLINE_CHARS_PARAM
   }
-}, withAuth("deep_research", async (params) => {
+}, withAuth("deep_research", async (params, ctx) => {
     try {
-      const result = await deepResearchTool.execute(params);
+      const result = await deepResearchTool.execute(params, ctx);
+      if (isInputRequiredResult(result)) return result;
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     } catch (error) {
       return { content: [{ type: "text", text: `Deep research failed: ${error.message}` }], isError: true };
@@ -1120,9 +1126,10 @@ registerToolIfEnabled("agent", {
     maxSteps: z.number().min(1).max(10).optional().default(5).describe("Max fetch iterations (hard cap: 10)"),
     maxUrls: z.number().min(1).max(20).optional().default(10).describe("Max URLs to fetch (hard cap: 20)")
   }
-}, withAuth("agent", async (params) => {
+}, withAuth("agent", async (params, ctx) => {
     try {
-      const result = await agentTool.execute(params);
+      const result = await agentTool.execute(params, ctx);
+      if (isInputRequiredResult(result)) return result;
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     } catch (error) {
       return { content: [{ type: "text", text: `Agent failed: ${error.message}` }], isError: true };
@@ -1131,103 +1138,11 @@ registerToolIfEnabled("agent", {
 
 // Tool: track_changes
 registerToolIfEnabled("track_changes", {
-  description: "Use this to monitor a URL for content changes over time - competitor pricing, regulation updates, product availability. Start with operation:\"create_baseline\", then periodically use operation:\"compare\" to diff; repeated compare calls on the same URL are expected. Supports webhooks and scheduled monitoring. Not for a one-off read (scrape). Cost: 3 credits. Example: track_changes({url: \"https://example.com/pricing\", operation: \"create_baseline\"})",
+  description: "Use this to monitor a URL for content changes over time - competitor pricing, regulation updates, product availability. Start with operation:\"create_baseline\", then periodically use operation:\"compare\" to diff; repeated compare calls on the same URL are expected. Supports webhooks and scheduled monitoring, and scheduledMonitorOptions.hosted:true runs the monitor on CrawlForge's servers with email and signed webhooks. Not for a one-off read (scrape). Cost: 3 credits. Example: track_changes({url: \"https://example.com/pricing\", operation: \"create_baseline\"})",
   annotations: { title: "Track Changes", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  // The tool module owns the schema (G5); this is the same shape it validates with.
   inputSchema: {
-    url: z.string().url().optional().describe("The URL to track changes for (optional for list_scheduled_monitors)"),
-    operation: z.enum([
-      'create_baseline', 'compare', 'monitor', 'get_history', 'get_stats',
-      'create_scheduled_monitor', 'stop_scheduled_monitor', 'list_scheduled_monitors', 'get_dashboard',
-      'export_history', 'create_alert_rule', 'generate_trend_report', 'get_monitoring_templates'
-    ]).default('compare').describe("Tracking operation to perform"),
-    content: z.string().optional().describe("Content to compare against baseline"),
-    html: z.string().optional().describe("HTML content to compare against baseline"),
-    trackingOptions: z.object({
-      granularity: z.enum(['page', 'section', 'element', 'text']).default('section'),
-      trackText: z.boolean().default(true),
-      trackStructure: z.boolean().default(true),
-      trackAttributes: z.boolean().default(false),
-      trackImages: z.boolean().default(false),
-      trackLinks: z.boolean().default(true),
-      ignoreWhitespace: z.boolean().default(true),
-      ignoreCase: z.boolean().default(false),
-      customSelectors: z.array(z.string()).optional(),
-      excludeSelectors: z.array(z.string()).optional(),
-      significanceThresholds: z.object({
-        minor: z.number().min(0).max(1).default(0.1),
-        moderate: z.number().min(0).max(1).default(0.3),
-        major: z.number().min(0).max(1).default(0.7)
-      }).optional()
-    }).optional().describe("Options for how changes are tracked and compared"),
-    monitoringOptions: z.object({
-      enabled: z.boolean().default(false),
-      interval: z.number().min(60000).max(24 * 60 * 60 * 1000).default(300000),
-      maxRetries: z.number().min(0).max(5).default(3),
-      retryDelay: z.number().min(1000).max(60000).default(5000),
-      notificationThreshold: z.enum(['minor', 'moderate', 'major', 'critical']).default('moderate'),
-      enableWebhook: z.boolean().default(false),
-      webhookUrl: z.string().url().optional(),
-      webhookSecret: z.string().optional()
-    }).optional().describe("Monitoring schedule and notification settings"),
-    storageOptions: z.object({
-      enableSnapshots: z.boolean().default(true),
-      retainHistory: z.boolean().default(true),
-      maxHistoryEntries: z.number().min(1).max(1000).default(100),
-      compressionEnabled: z.boolean().default(true),
-      deltaStorageEnabled: z.boolean().default(true)
-    }).optional().describe("Storage and history retention settings"),
-    queryOptions: z.object({
-      limit: z.number().min(1).max(500).default(50),
-      offset: z.number().min(0).default(0),
-      startTime: z.number().optional(),
-      endTime: z.number().optional(),
-      includeContent: z.boolean().default(false),
-      significanceFilter: z.enum(['all', 'minor', 'moderate', 'major', 'critical']).optional()
-    }).optional().describe("Query options for history and stats retrieval"),
-    notificationOptions: z.object({
-      webhook: z.object({
-        enabled: z.boolean().default(false),
-        url: z.string().url().optional(),
-        method: z.enum(['POST', 'PUT']).default('POST'),
-        headers: z.record(z.string()).optional(),
-        signingSecret: z.string().optional(),
-        includeContent: z.boolean().default(false)
-      }).optional(),
-      slack: z.object({
-        enabled: z.boolean().default(false),
-        webhookUrl: z.string().url().optional(),
-        channel: z.string().optional(),
-        username: z.string().optional()
-      }).optional()
-    }).optional().describe("Notification configuration for webhooks and Slack"),
-    scheduledMonitorOptions: z.object({
-      schedule: z.string().optional().describe("Optional cron expression (power users)"),
-      templateId: z.string().optional(),
-      enabled: z.boolean().default(true),
-      interval: z.number().min(60000).optional().describe("Polling interval in ms (default 1h)"),
-      goal: z.string().optional().describe("Plain-English alert goal; an LLM judges whether a change matches (degrades to threshold if no LLM)"),
-      monitorId: z.string().optional().describe("Monitor id for stop_scheduled_monitor"),
-      notificationThreshold: z.enum(['minor', 'moderate', 'major', 'critical']).optional()
-    }).optional().describe("Scheduled monitoring: recurring compare + notify, optional plain-English goal"),
-    alertRuleOptions: z.object({
-      ruleId: z.string().optional(),
-      condition: z.string().optional(),
-      actions: z.array(z.enum(['webhook', 'email', 'slack'])).optional(),
-      throttle: z.number().min(0).optional(),
-      priority: z.enum(['low', 'medium', 'high']).optional()
-    }).optional().describe("Alert rule configuration for change notifications"),
-    exportOptions: z.object({
-      format: z.enum(['json', 'csv']).default('json'),
-      startTime: z.number().optional(),
-      endTime: z.number().optional(),
-      includeContent: z.boolean().default(false),
-      includeSnapshots: z.boolean().default(false)
-    }).optional().describe("Export options for change history data"),
-    dashboardOptions: z.object({
-      includeRecentAlerts: z.boolean().default(true),
-      includeTrends: z.boolean().default(true),
-      includeMonitorStatus: z.boolean().default(true)
-    }).optional().describe("Dashboard display options"),
+    ...TRACK_CHANGES_INPUT_SHAPE,
     ...COMPLIANCE_PARAMS
   }
 }, withAuth("track_changes", async (params) => {

package/src/cli/commands/login.js

@@ -0,0 +1,176 @@
+/**
+ * login command — browser handoff that stores an API key in ~/.crawlforge/config.json.
+ *
+ * The CLI mints PKCE parameters, prints an approval URL for the human, and polls
+ * the website until the signed-in user approves; the key is delivered once, over
+ * the poll, and never typed into a terminal. This command stores the credential
+ * ONLY — registering the MCP server with a client is `crawlforge init`.
+ */
+import { randomBytes, createHash } from 'node:crypto';
+import { hostname } from 'node:os';
+import { existsSync } from 'node:fs';
+import authManager from '../../core/authManager.js';
+import { resolveApiEndpoint } from '../../core/endpointGuard.js';
+
+const POLL_INTERVAL_MS = 3000;
+const MAX_BACKOFF_MS = 30000;
+const MAX_CONSECUTIVE_FAILURES = 10;
+
+export function generateLoginParams() {
+  const codeVerifier = randomBytes(32).toString('base64url');
+  return {
+    sessionId: randomBytes(16).toString('hex'),
+    codeVerifier,
+    codeChallenge: createHash('sha256').update(codeVerifier).digest('base64url'),
+  };
+}
+
+export function buildApprovalUrl(endpoint, params, name) {
+  return `${endpoint}/cli-auth?session_id=${params.sessionId}` +
+    `&code_challenge=${params.codeChallenge}&name=${encodeURIComponent(name)}`;
+}
+
+function loginError(code, message) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+/**
+ * Poll the status endpoint until the key arrives. Resolves with the `complete`
+ * payload; rejects with an error whose `code` names why (CLI_AUTH_TIMEOUT,
+ * CLI_AUTH_VERIFIER_MISMATCH, CLI_AUTH_UNREACHABLE). `sleep` and `now` are
+ * injectable so tests neither wait nor hit the network.
+ */
+export async function pollStatus(fetchImpl, endpoint, params, {
+  intervalMs = POLL_INTERVAL_MS,
+  timeoutMs = 600000,
+  requestTimeoutMs = 30000,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  now = Date.now,
+} = {}) {
+  const deadline = now() + timeoutMs;
+  let interval = intervalMs;
+  let failures = 0;
+  let lastFailure = '';
+
+  while (now() < deadline) {
+    let response;
+    try {
+      response = await fetchImpl(`${endpoint}/api/auth/cli/status`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ session_id: params.sessionId, code_verifier: params.codeVerifier }),
+        signal: AbortSignal.timeout(requestTimeoutMs),
+      });
+    } catch (err) {
+      response = null;
+      lastFailure = err.message;
+    }
+
+    if (response && response.status === 200) {
+      const body = await response.json();
+      if (body.status === 'complete') return body;
+      if (body.status === 'pending') {
+        failures = 0;
+      } else {
+        failures++;
+        lastFailure = `unexpected status "${body.status}"`;
+      }
+    } else if (response && response.status === 403) {
+      let code = 'CLI_AUTH_FORBIDDEN';
+      try { code = (await response.json()).error?.code || code; } catch { /* keep default */ }
+      throw loginError(code, code === 'CLI_AUTH_VERIFIER_MISMATCH'
+        ? 'The website rejected this session\'s verifier. Run crawlforge login again and open the new URL.'
+        : `The website refused the login session (${code}).`);
+    } else if (response && response.status === 429) {
+      interval = Math.min(interval * 2, MAX_BACKOFF_MS);
+    } else if (response) {
+      failures++;
+      lastFailure = `HTTP ${response.status}`;
+    } else {
+      failures++;
+    }
+
+    if (failures >= MAX_CONSECUTIVE_FAILURES) {
+      throw loginError('CLI_AUTH_UNREACHABLE',
+        `Gave up after ${failures} consecutive failed status checks (last: ${lastFailure}).`);
+    }
+    await sleep(interval);
+  }
+
+  throw loginError('CLI_AUTH_TIMEOUT',
+    `No approval within ${Math.round(timeoutMs / 1000)} seconds. Run crawlforge login again.`);
+}
+
+export function register(program) {
+  program
+    .command('login')
+    .description('Sign in through your browser and store an API key in ~/.crawlforge/config.json (does not touch client configs)')
+    .option('--name <name>', 'Name for the API key the approval creates', `CLI on ${hostname()}`)
+    // Not `--timeout`: the program-level `--timeout <ms>` parses argv first and
+    // would swallow the value, so a subcommand option of that name never gets one.
+    .option('--wait <seconds>', 'How long to wait for approval', '600')
+    .action(async (opts, cmd) => {
+      const json = cmd.parent.opts().json;
+      const out = (msg) => process.stderr.write(msg + '\n');
+      const fail = (code, message) => {
+        if (json) {
+          process.stdout.write(JSON.stringify({ status: 'error', code, message }) + '\n', () => process.exit(1));
+        } else {
+          out('Error: ' + message);
+          process.exit(1);
+        }
+      };
+      process.on('SIGINT', () => fail('CLI_AUTH_CANCELLED', 'Login cancelled.'));
+
+      // resolveApiEndpoint() returns the origin with a trailing slash; strip it
+      // so the approval URL and the status endpoint are not `host//path`.
+      const endpoint = resolveApiEndpoint(process.env.CRAWLFORGE_API_URL || 'https://www.crawlforge.dev').replace(/\/+$/, '');
+      const params = generateLoginParams();
+      const hadConfig = existsSync(authManager.configPath);
+
+      out('Open this URL in your browser and approve the key (session ' + params.sessionId.slice(0, 8) + '):');
+      out('');
+      out('  ' + buildApprovalUrl(endpoint, params, opts.name));
+      out('');
+      out('Waiting for approval… (Ctrl-C to cancel)');
+
+      let result;
+      try {
+        result = await pollStatus(fetch, endpoint, params, {
+          timeoutMs: parseInt(opts.wait, 10) * 1000,
+          requestTimeoutMs: parseInt(process.env.CRAWLFORGE_CLI_TIMEOUT || '30000', 10),
+        });
+      } catch (err) {
+        return fail(err.code || 'CLI_AUTH_FAILED', err.message);
+      }
+
+      const validation = await authManager.validateApiKey(result.api_key);
+      if (!validation.valid) {
+        return fail('CLI_AUTH_KEY_INVALID', 'The delivered API key failed validation: ' + validation.error);
+      }
+      await authManager.saveConfig(result.api_key, validation.userId, validation.email);
+
+      if (json) {
+        const line = JSON.stringify({
+          status: 'complete',
+          email: validation.email,
+          key_name: result.key_name,
+          config_path: authManager.configPath,
+          credits_remaining: validation.creditsRemaining,
+          plan: validation.planId,
+        });
+        process.stdout.write(line + '\n', () => process.exit(0));
+        return;
+      }
+
+      out('Signed in as ' + validation.email);
+      out('Credits remaining: ' + validation.creditsRemaining);
+      out('Plan: ' + validation.planId);
+      out('API key "' + result.key_name + '" saved to ' + authManager.configPath +
+        (hadConfig ? ' (replaced the previous config)' : ''));
+      out('Next: crawlforge init --client claude-code|claude-desktop|cursor registers the MCP server with a client (this command did not modify any client config).');
+      process.exit(0);
+    });
+}

package/src/cli/commands/monitor.js

@@ -61,19 +61,33 @@ export function register(program) {
     .option('--threshold <level>', 'Notification threshold: minor|moderate|major|critical', 'moderate')
     .option('--cron <expr>', 'Optional cron expression (advanced)')
     .option('--selector <css>', 'CSS selector to scope monitoring')
+    .option('--hosted', "Run the monitor on CrawlForge's servers (fires without this process; email + signed webhooks; 3 credits per compared target per check)")
+    .option('--email <addresses>', 'Comma-separated notification emails (sent by hosted monitors only)')
+    .option('--name <text>', 'Display name for a hosted monitor (default: the URL host)')
     .action(async (url, opts) => {
       const tool = new TrackChangesTool(getToolConfig('track_changes'));
+      const notificationOptions = {
+        ...(opts.webhook ? { webhook: { enabled: true, url: opts.webhook } } : {}),
+        ...(opts.email ? { email: { enabled: true, recipients: opts.email.split(',').map((s) => s.trim()).filter(Boolean) } } : {})
+      };
+      if (opts.email && !opts.hosted) {
+        process.stderr.write('Warning: local monitors do not send email; add --hosted for --email to take effect.\n');
+      }
       try {
         const res = await tool.execute({
           url,
           operation: 'create_scheduled_monitor',
           ...(opts.selector ? { trackingOptions: { customSelectors: [opts.selector] } } : {}),
-          ...(opts.webhook ? { notificationOptions: { webhook: { enabled: true, url: opts.webhook } } } : {}),
+          ...(Object.keys(notificationOptions).length ? { notificationOptions } : {}),
           scheduledMonitorOptions: {
             interval: Math.max(parseInt(opts.every, 10), 60) * 1000,
             ...(opts.goal ? { goal: opts.goal } : {}),
             ...(opts.cron ? { schedule: opts.cron } : {}),
-            notificationThreshold: opts.threshold
+            ...(opts.hosted ? { hosted: true } : {}),
+            ...(opts.name ? { name: opts.name } : {}),
+            // Local only: a hosted check has no significance threshold, and
+            // the option's default would otherwise warn on every hosted create.
+            ...(opts.hosted ? {} : { notificationThreshold: opts.threshold })
           }
         });
         emit(res);
@@ -86,7 +100,7 @@ export function register(program) {
 
   program
     .command('monitor:list')
-    .description('List persisted scheduled monitors')
+    .description('List scheduled monitors (local and hosted)')
     .action(async () => {
       const tool = new TrackChangesTool(getToolConfig('track_changes'));
       try {
@@ -100,7 +114,7 @@ export function register(program) {
 
   program
     .command('monitor:stop <id>')
-    .description('Stop and remove a scheduled monitor by id')
+    .description('Stop and remove a scheduled monitor by id (local or hosted)')
     .action(async (id) => {
       const tool = new TrackChangesTool(getToolConfig('track_changes'));
       try {

package/src/cli/index.js

@@ -59,6 +59,7 @@ import { register as registerMonitor } from './commands/monitor.js';
 import { register as registerInstallSkills } from './commands/install-skills.js';
 import { register as registerUninstallSkills } from './commands/uninstall-skills.js';
 import { register as registerInit } from './commands/init.js';
+import { register as registerLogin } from './commands/login.js';
 
 // ─── MCP stdio server mode (backward compatibility) ──────────────────────────
 // Before v4.1.0 the `crawlforge` bin WAS the MCP server. v4.1.0 turned it into
@@ -138,6 +139,7 @@ registerMonitor(program);
 registerInstallSkills(program);
 registerUninstallSkills(program);
 registerInit(program);
+registerLogin(program);
 
 // `crawlforge mcp` / `crawlforge serve` — explicitly start the MCP server over
 // stdio. Extra args (e.g. --http) are read directly by server.js from argv.

package/src/core/AuthManager.js

@@ -241,9 +241,16 @@ class AuthManager {
   }
 
   /**
-   * Check if user has enough credits for a tool
+   * Check if user has enough credits for a tool.
+   *
+   * @param {number} estimatedCredits
+   * @param {object} [ctx] the SDK per-request context, so the low-credit
+   *   warning can ask as a multi-round-trip step (Phase 4.4).
+   * @returns {Promise<boolean|object>} `true`/`false` as before, or an
+   *   `input_required` result the caller must RETURN verbatim — `withAuth`
+   *   detects it, bills nothing and lets the SDK gather the answer.
    */
-  async checkCredits(estimatedCredits = 1) {
+  async checkCredits(estimatedCredits = 1, ctx) {
     // Creator mode has unlimited credits
     if (this.isCreatorMode()) {
       return true;
@@ -277,10 +284,16 @@ class AuthManager {
         this.lastCreditCheck = now;
         this.lastSuccessfulCreditCheck.set(this.config.userId, now);
 
-        // D1.4: If credits are close to running out, elicit confirmation instead of hard-failing
+        // D1.4: If credits are close to running out, elicit confirmation instead
+        // of hard-failing. Phase 4.4: the ask is a round trip now — `ask` hands
+        // an `input_required` result back to withAuth, which returns it unbilled
+        // and is re-entered here with the answer. A client that cannot be asked
+        // still proceeds, which is what the inline helper did.
         if (data.creditsRemaining < estimatedCredits) {
           if (this._elicitation) {
-            const proceed = await this._elicitation.confirm(
+            const gate = this._elicitation.confirm(
+              ctx,
+              'credits:low',
               `Low credits: ${data.creditsRemaining} remaining, this tool needs ~${estimatedCredits}. Proceed anyway?`,
               {
                 credits_remaining: data.creditsRemaining,
@@ -288,8 +301,8 @@ class AuthManager {
                 note: 'Top up at https://www.crawlforge.dev/dashboard',
               }
             );
-            if (!proceed) return false;
-            return true; // user confirmed — let tool attempt it
+            if (gate.status === 'ask') return gate.result;
+            return gate.status === 'proceed'; // confirmed (or unaskable) — let tool attempt it
           }
           return false; // no elicitation — standard hard-fail behavior
         }