crawlforge-mcp-server 3.0.17 → 3.3.1

package/src/core/LocalizationManager.js

@@ -63,47 +63,11 @@ const LANGUAGE_MAPPINGS = {
 // RTL Languages Configuration
 const RTL_LANGUAGES = new Set(['ar', 'he', 'fa', 'ur', 'ku', 'dv']);
 
-// Proxy Provider Configuration
-const PROXY_PROVIDERS = {
-  regions: {
-    'us-east': { endpoint: 'proxy-us-east.example.com', port: 8080 },
-    'us-west': { endpoint: 'proxy-us-west.example.com', port: 8080 },
-    'eu-west': { endpoint: 'proxy-eu-west.example.com', port: 8080 },
-    'eu-central': { endpoint: 'proxy-eu-central.example.com', port: 8080 },
-    'eu-north': { endpoint: 'proxy-eu-north.example.com', port: 8080 },
-    'eu-east': { endpoint: 'proxy-eu-east.example.com', port: 8080 },
-    'asia-pacific': { endpoint: 'proxy-asia-pacific.example.com', port: 8080 },
-    'middle-east': { endpoint: 'proxy-middle-east.example.com', port: 8080 },
-    'south-america': { endpoint: 'proxy-south-america.example.com', port: 8080 },
-    'north-america': { endpoint: 'proxy-north-america.example.com', port: 8080 },
-    'africa': { endpoint: 'proxy-africa.example.com', port: 8080 }
-  },
-  fallbackStrategies: {
-    'geo-blocked': ['rotate-proxy', 'change-user-agent', 'delay-request'],
-    'rate-limited': ['change-proxy', 'exponential-backoff'],
-    'detection': ['rotate-fingerprint', 'change-proxy', 'human-delay']
-  }
-};
-
-// Translation Service Configuration
-const TRANSLATION_SERVICES = {
-  google: {
-    enabled: process.env.GOOGLE_TRANSLATE_API_KEY ? true : false,
-    apiKey: process.env.GOOGLE_TRANSLATE_API_KEY,
-    endpoint: 'https://translation.googleapis.com/language/translate/v2'
-  },
-  azure: {
-    enabled: process.env.AZURE_TRANSLATE_KEY ? true : false,
-    key: process.env.AZURE_TRANSLATE_KEY,
-    region: process.env.AZURE_TRANSLATE_REGION || 'global',
-    endpoint: 'https://api.cognitive.microsofttranslator.com/translate'
-  },
-  libre: {
-    enabled: process.env.LIBRE_TRANSLATE_URL ? true : false,
-    url: process.env.LIBRE_TRANSLATE_URL,
-    apiKey: process.env.LIBRE_TRANSLATE_API_KEY
-  }
-};
+// NOTE (v3.0.19 cleanup): PROXY_PROVIDERS and TRANSLATION_SERVICES configs were
+// removed. They pointed at `*.example.com` endpoints and translation services
+// that were never wired up — pure dead code. If/when real proxy rotation or
+// translation lands, configure providers explicitly rather than reviving these
+// placeholders. See IMPROVEMENT_PLAN.md §A3.
 
 const LocalizationSchema = z.object({
   countryCode: z.string().length(2).optional(),
@@ -237,27 +201,21 @@ export class LocalizationManager extends EventEmitter {
     try {
       // Pre-populate timezone mappings
       await this.loadTimezoneData();
-      
+
       // Initialize geo-location data
       await this.loadGeoLocationData();
-      
-      // Initialize proxy configurations
-      await this.initializeProxySystem();
-      
-      // Initialize translation services
-      await this.initializeTranslationServices();
-      
+
       // Load cultural browsing patterns
       await this.loadCulturalPatterns();
-      
+
       // Setup periodic health checks
       this.setupHealthChecks();
-      
+
       this.emit('initialized');
     } catch (error) {
-      this.emit('error', { 
-        type: 'initialization_failed', 
-        error: error.message 
+      this.emit('error', {
+        type: 'initialization_failed',
+        error: error.message
       });
       throw error;
     }
@@ -958,76 +916,6 @@ export class LocalizationManager extends EventEmitter {
     
     return null;
   }
-  /**
-   * Initialize proxy system with regional configurations
-   */
-  async initializeProxySystem() {
-    try {
-      // Load proxy configurations from environment or config
-      for (const [region, config] of Object.entries(PROXY_PROVIDERS.regions)) {
-        if (process.env[`PROXY_${region.toUpperCase().replace('-', '_')}_ENABLED`] === 'true') {
-          this.proxyManager.activeProxies.set(region, {
-            ...config,
-            username: process.env[`PROXY_${region.toUpperCase().replace('-', '_')}_USERNAME`],
-            password: process.env[`PROXY_${region.toUpperCase().replace('-', '_')}_PASSWORD`],
-            healthScore: 100,
-            lastCheck: 0,
-            failureCount: 0
-          });
-        }
-      }
-      
-      // Setup proxy health monitoring
-      if (this.proxyManager.activeProxies.size > 0) {
-        await this.performProxyHealthChecks();
-      }
-      
-    } catch (error) {
-      console.warn('Failed to initialize proxy system:', error.message);
-    }
-  }
-  
-  /**
-   * Initialize translation services
-   */
-  async initializeTranslationServices() {
-    try {
-      // Google Translate
-      if (TRANSLATION_SERVICES.google.enabled) {
-        this.translationProviders.set('google', {
-          type: 'google',
-          apiKey: TRANSLATION_SERVICES.google.apiKey,
-          endpoint: TRANSLATION_SERVICES.google.endpoint,
-          available: true
-        });
-      }
-      
-      // Azure Translator
-      if (TRANSLATION_SERVICES.azure.enabled) {
-        this.translationProviders.set('azure', {
-          type: 'azure',
-          key: TRANSLATION_SERVICES.azure.key,
-          region: TRANSLATION_SERVICES.azure.region,
-          endpoint: TRANSLATION_SERVICES.azure.endpoint,
-          available: true
-        });
-      }
-      
-      // LibreTranslate
-      if (TRANSLATION_SERVICES.libre.enabled) {
-        this.translationProviders.set('libre', {
-          type: 'libre',
-          url: TRANSLATION_SERVICES.libre.url,
-          apiKey: TRANSLATION_SERVICES.libre.apiKey,
-          available: true
-        });
-      }
-      
-    } catch (error) {
-      console.warn('Failed to initialize translation services:', error.message);
-    }
-  }
-  
   /**
    * Load cultural browsing patterns for different regions
    */
@@ -1612,4 +1500,5 @@ export class LocalizationManager extends EventEmitter {
 export default LocalizationManager;
 
 // Export constants for external use
-export { SUPPORTED_COUNTRIES, RTL_LANGUAGES, PROXY_PROVIDERS, TRANSLATION_SERVICES };
+// (PROXY_PROVIDERS / TRANSLATION_SERVICES removed in v3.0.19 — see §A3 of IMPROVEMENT_PLAN.md)
+export { SUPPORTED_COUNTRIES, RTL_LANGUAGES };

package/src/core/ResearchOrchestrator.js

@@ -120,30 +120,35 @@ export class ResearchOrchestrator extends EventEmitter {
       
       // Stage 1: Initial topic exploration and query expansion
       const expandedQueries = await this.expandResearchTopic(topic);
+      this.researchState.currentDepth = 1;
       this.logActivity('topic_expansion', { originalTopic: topic, expandedQueries });
 
       // Stage 2: Broad information gathering
       const initialSources = await this.gatherInitialSources(expandedQueries, options);
+      this.researchState.currentDepth = 2;
       this.logActivity('initial_gathering', { sourcesFound: initialSources.length });
 
       // Stage 3: Deep exploration of promising sources
       const detailedFindings = await this.exploreSourcesInDepth(initialSources, options);
+      this.researchState.currentDepth = 3;
       this.logActivity('deep_exploration', { findingsCount: detailedFindings.length });
 
       // Stage 4: Source credibility assessment
-      const verifiedSources = this.enableSourceVerification ? 
+      const verifiedSources = this.enableSourceVerification ?
         await this.verifySourceCredibility(detailedFindings) : detailedFindings;
+      this.researchState.currentDepth = 4;
       this.logActivity('source_verification', { verifiedCount: verifiedSources.length });
 
       // Stage 5: Information synthesis and conflict detection
       const synthesizedResults = await this.synthesizeInformation(verifiedSources, topic);
+      this.researchState.currentDepth = 5;
       this.logActivity('information_synthesis', { conflictsFound: synthesizedResults.conflicts.length });
 
-      // Stage 6: Final result compilation
-      const finalResults = this.compileResearchResults(topic, synthesizedResults, options);
-      
       const totalTime = Date.now() - startTime;
       this.metrics.totalProcessingTime = totalTime;
+
+      // Stage 6: Final result compilation
+      const finalResults = this.compileResearchResults(topic, synthesizedResults, options);
       
       this.logger.info('Research completed', { 
         sessionId, 
@@ -636,10 +641,22 @@ export class ResearchOrchestrator extends EventEmitter {
       consensus: [],
       gaps: [],
       recommendations: [],
-      llmSynthesis: null
+      llmSynthesis: null,
+      rawEvidence: null,
+      synthesisMode: this.enableLLMFeatures ? 'llm' : 'raw_evidence'
     };
 
     try {
+      // Without an LLM the keyword/frequency-based synthesis produces
+      // unreadable output. Skip it and return raw evidence for the calling
+      // LLM (e.g. Claude Code) to synthesize.
+      if (!this.enableLLMFeatures) {
+        synthesis.rawEvidence = this.buildRawEvidence(sources);
+        synthesis.supportingEvidence = this.compileSupportingEvidence(sources);
+        this.metrics.synthesisTime += Date.now() - startTime;
+        return synthesis;
+      }
+
       // Extract key claims and facts from each source
       const extractedClaims = await this.extractKeyClaims(sources);
       
@@ -1110,6 +1127,36 @@ export class ResearchOrchestrator extends EventEmitter {
       .slice(0, 15);
   }
 
+  buildRawEvidence(sources) {
+    return sources
+      .filter(s => s.extractedContent && s.extractedContent.length > 0)
+      .map(s => ({
+        title: s.title,
+        url: s.link,
+        credibility: s.overallCredibility ?? 0.5,
+        contentSnippet: s.extractedContent.substring(0, 4000),
+        topSentences: this.extractTopSentences(s.extractedContent, 5)
+      }))
+      .slice(0, 20);
+  }
+
+  extractTopSentences(text, n = 5) {
+    if (!text) return [];
+    const sentences = text
+      .split(/(?<=[.!?])\s+/)
+      .map(s => s.trim())
+      .filter(s => s.length >= 40 && s.length <= 500);
+
+    return sentences
+      .map(s => ({
+        text: s,
+        score: s.length * 0.5 + (s.match(/[A-Z][a-z]+/g)?.length || 0) * 5
+      }))
+      .sort((a, b) => b.score - a.score)
+      .slice(0, n)
+      .map(item => item.text);
+  }
+
   identifyResearchGaps(claimGroups, topic) {
     const gaps = [];
     
@@ -1158,6 +1205,40 @@ export class ResearchOrchestrator extends EventEmitter {
   }
 
   compileResearchResults(topic, synthesis, options) {
+    if (synthesis.synthesisMode === 'raw_evidence') {
+      const sources = synthesis.rawEvidence || [];
+      return {
+        sessionId: this.researchState.sessionId,
+        topic,
+        synthesisMode: 'raw_evidence',
+        note: "This response contains raw research evidence with no AI synthesis. The calling LLM (you) should synthesize these sources to answer the user's question. To enable internal LLM synthesis instead, set OPENAI_API_KEY or ANTHROPIC_API_KEY in the MCP server environment.",
+        sources,
+        findings: [],
+        researchSummary: {
+          totalSources: this.metrics.urlsProcessed,
+          verifiedSources: this.metrics.sourcesVerified,
+          sourcesReturned: sources.length,
+          llmEnhanced: false
+        },
+        activityLog: this.researchState.activityLog,
+        performance: {
+          ...this.metrics,
+          timeLimit: this.timeLimit,
+          completedWithinLimit: this.metrics.totalProcessingTime < this.timeLimit
+        },
+        metadata: {
+          generatedAt: new Date().toISOString(),
+          researchDepth: this.researchState.currentDepth,
+          configuration: {
+            maxDepth: this.maxDepth,
+            maxUrls: this.maxUrls,
+            timeLimit: this.timeLimit,
+            llmEnabled: false
+          }
+        }
+      };
+    }
+
     const baseResults = {
       sessionId: this.researchState.sessionId,
       topic,

package/src/core/StealthBrowserManager.js

@@ -12,6 +12,7 @@ import { chromium } from 'playwright';
 import { z } from 'zod';
 import crypto from 'crypto';
 import HumanBehaviorSimulator from '../utils/HumanBehaviorSimulator.js';
+import { BrowserContextPool } from './BrowserContextPool.js';
 
 const StealthConfigSchema = z.object({
   level: z.enum(['basic', 'medium', 'advanced']).default('medium'),
@@ -59,7 +60,15 @@ const StealthConfigSchema = z.object({
 export class StealthBrowserManager {
   constructor(options = {}) {
     this.browser = null;
-    this.contexts = new Map();
+    this.contexts = new BrowserContextPool({
+      maxContexts: parseInt(process.env.MAX_BROWSER_CONTEXTS || '10', 10),
+      periodicRefreshAfter: 200,
+      closeIdleAfterMs: 30 * 60 * 1000,
+      waitTimeoutMs: 10_000,
+      onContextExpired: (contextId) => {
+        this.fingerprints.delete(contextId);
+      }
+    });
     this.fingerprints = new Map();
     
     // Enhanced stealth components
@@ -367,7 +376,7 @@ export class StealthBrowserManager {
     // Apply stealth scripts and configurations
     await this.applyAdvancedStealthConfigurations(context, validatedConfig, fingerprint);
     
-    this.contexts.set(contextId, { context, fingerprint, config: validatedConfig });
+    await this.contexts.set(contextId, { context, fingerprint, config: validatedConfig });
     this.fingerprints.set(contextId, fingerprint);
 
     return { context, contextId, fingerprint };
@@ -1493,11 +1502,20 @@ export class StealthBrowserManager {
       throw new Error('Context not found');
     }
 
+    // Record use and check if context needs periodic refresh
+    const needsRefresh = this.contexts.recordUse(contextId);
+    if (needsRefresh) {
+      // Dispose old context; caller should create a fresh one
+      await this.contexts.dispose(contextId);
+      this.fingerprints.delete(contextId);
+      throw new Error(`StealthBrowserManager: context ${contextId} has reached its use limit and was recycled. Create a new context.`);
+    }
+
     const page = await contextData.context.newPage();
-    
+
     // Apply additional page-level stealth measures
     await this.applyPageStealthMeasures(page, contextData.config, contextData.fingerprint);
-    
+
     return page;
   }
 
@@ -1678,10 +1696,8 @@ export class StealthBrowserManager {
    * Close specific context
    */
   async closeContext(contextId) {
-    const contextData = this.contexts.get(contextId);
-    if (contextData) {
-      await contextData.context.close();
-      this.contexts.delete(contextId);
+    if (this.contexts.has(contextId)) {
+      await this.contexts.dispose(contextId);
       this.fingerprints.delete(contextId);
     }
   }
@@ -1690,16 +1706,8 @@ export class StealthBrowserManager {
    * Close all contexts and browser
    */
   async cleanup() {
-    // Close all contexts
-    for (const [contextId, contextData] of this.contexts.entries()) {
-      try {
-        await contextData.context.close();
-      } catch (error) {
-        console.warn(`Failed to close context ${contextId}:`, error.message);
-      }
-    }
-
-    this.contexts.clear();
+    // Close all contexts via pool (handles idle timer cleanup + wait queue drain)
+    await this.contexts.destroy();
     this.fingerprints.clear();
 
     // Reset human behavior simulator

package/src/core/cache/CacheManager.js

@@ -82,10 +82,12 @@ export class CacheManager extends EventEmitter {
       this.startMonitoring(monitoringInterval);
     }
     
-    // Initialize auto cleanup
+    // Initialize auto cleanup. .unref() so the timer never blocks process exit
+    // — short-lived CLI invocations and tests don't need an explicit destroy().
     this.cleanupTimer = setInterval(() => {
       this.cleanupExpired();
     }, autoCleanupInterval);
+    if (typeof this.cleanupTimer.unref === 'function') this.cleanupTimer.unref();
     
     // Eviction tracking is handled in the LRU cache dispose callback above
   }
@@ -546,6 +548,7 @@ export class CacheManager extends EventEmitter {
       this.updateStats();
       this.emit('monitoring', this.getDetailedStats());
     }, interval);
+    if (typeof this.monitoringTimer.unref === 'function') this.monitoringTimer.unref();
   }
 
   /**

package/src/core/crawlers/BFSCrawler.js

@@ -19,7 +19,8 @@ export class BFSCrawler {
       concurrency = 10,
       domainFilter = null,
       enableLinkAnalysis = true,
-      linkAnalyzerOptions = {}
+      linkAnalyzerOptions = {},
+      sessionContext = null
     } = options;
 
     this.maxDepth = maxDepth;
@@ -28,6 +29,8 @@ export class BFSCrawler {
     this.respectRobots = respectRobots;
     this.userAgent = userAgent;
     this.timeout = timeout;
+    // Session context for cookie jar + persistent headers (null = stateless)
+    this.sessionContext = sessionContext;
 
     this.visited = new Set();
     this.results = [];
@@ -254,21 +257,32 @@ export class BFSCrawler {
         'Connection': 'keep-alive',
         'Upgrade-Insecure-Requests': '1'
       };
-      
-      const headers = { ...defaultHeaders, ...domainRules.customHeaders };
+
+      let headers = { ...defaultHeaders, ...domainRules.customHeaders };
+
+      // If a session is active, layer in session headers + cookie jar
+      if (this.sessionContext) {
+        headers = this.sessionContext.applyToHeaders(url, headers);
+      }
+
       const effectiveTimeout = domainRules.timeout || this.timeout;
-      
+
       // Update timeout if different
       if (effectiveTimeout !== this.timeout) {
         clearTimeout(timeoutId);
         setTimeout(() => controller.abort(), effectiveTimeout);
       }
-      
+
       const response = await fetch(url, {
         signal: controller.signal,
         headers
       });
 
+      // Capture any cookies the server sets during the crawl
+      if (this.sessionContext) {
+        this.sessionContext.recordCookies(response, url);
+      }
+
       clearTimeout(timeoutId);
 
       if (!response.ok) {

package/src/core/endpointGuard.js

@@ -0,0 +1,37 @@
+import { isCreatorModeVerified } from './creatorMode.js';
+
+export const ALLOWED_HOSTS = ['www.crawlforge.dev', 'crawlforge.dev', 'api.crawlforge.dev'];
+
+const LOCALHOST_HOSTS = new Set(['localhost', '127.0.0.1', '::1']);
+
+export function resolveApiEndpoint(rawUrl) {
+  let parsed;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    throw new Error(`Invalid API endpoint URL: "${rawUrl}"`);
+  }
+
+  const hostname = parsed.hostname;
+
+  if (LOCALHOST_HOSTS.has(hostname)) {
+    if (!isCreatorModeVerified()) {
+      throw new Error(`Refusing to use API endpoint "${rawUrl}" — not in allow-list`);
+    }
+    // Strip trailing slash from pathname
+    parsed.pathname = parsed.pathname.replace(/\/+$/, '');
+    return parsed.toString();
+  }
+
+  if (parsed.protocol !== 'https:') {
+    throw new Error(`Refusing to use API endpoint "${rawUrl}" — not in allow-list`);
+  }
+
+  if (!ALLOWED_HOSTS.includes(hostname)) {
+    throw new Error(`Refusing to use API endpoint "${rawUrl}" — not in allow-list`);
+  }
+
+  // Strip trailing slash from pathname
+  parsed.pathname = parsed.pathname.replace(/\/+$/, '');
+  return parsed.toString();
+}

package/src/observability/metrics.js

@@ -0,0 +1,137 @@
+/**
+ * Prometheus metrics — dependency-free implementation.
+ *
+ * Why no prom-client? CrawlForge is shipped via npm and runs in stdio mode
+ * by default. Pulling in prom-client (and its dependency tree) just to
+ * expose four counters/gauges is overkill. This 150 LOC implementation
+ * conforms to the Prometheus exposition format 0.0.4.
+ *
+ * Disabled by default. Enable via `CRAWLFORGE_METRICS=true` in HTTP mode.
+ *
+ * Counters/gauges exposed:
+ *   - crawlforge_tool_requests_total{tool,outcome}
+ *   - crawlforge_tool_errors_total{tool,error_class}
+ *   - crawlforge_tool_duration_ms{tool}    (histogram, summed)
+ *   - crawlforge_credits_consumed_total{tool}
+ *   - crawlforge_browser_pool_in_use       (gauge)
+ *   - crawlforge_browser_pool_capacity     (gauge)
+ */
+
+const CONTENT_TYPE = 'text/plain; version=0.0.4; charset=utf-8';
+
+export function createMetricsRegistry() {
+  const counters = new Map();   // name|labels -> number
+  const gauges = new Map();     // name|labels -> number
+  const histograms = new Map(); // name|labels -> { count, sum, buckets:{le->count} }
+
+  const HISTOGRAM_BUCKETS_MS = [10, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 30000];
+
+  function key(name, labels) {
+    const labelStr = Object.entries(labels ?? {})
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([k, v]) => `${k}="${escapeLabel(String(v))}"`)
+      .join(',');
+    return labelStr ? `${name}{${labelStr}}` : name;
+  }
+
+  return {
+    contentType: CONTENT_TYPE,
+
+    incCounter(name, labels, by = 1) {
+      const k = key(name, labels);
+      counters.set(k, (counters.get(k) ?? 0) + by);
+    },
+
+    setGauge(name, labels, value) {
+      gauges.set(key(name, labels), value);
+    },
+
+    observeHistogram(name, labels, valueMs) {
+      const k = key(name, labels);
+      let h = histograms.get(k);
+      if (!h) {
+        h = { count: 0, sum: 0, buckets: Object.fromEntries(HISTOGRAM_BUCKETS_MS.map(b => [b, 0])) };
+        histograms.set(k, h);
+      }
+      h.count += 1;
+      h.sum += valueMs;
+      for (const b of HISTOGRAM_BUCKETS_MS) {
+        if (valueMs <= b) h.buckets[b] += 1;
+      }
+    },
+
+    async render() {
+      const lines = [];
+
+      // Counters
+      const counterNames = new Set();
+      for (const k of counters.keys()) counterNames.add(k.split('{')[0]);
+      for (const name of counterNames) {
+        lines.push(`# HELP ${name} ${describe(name)}`);
+        lines.push(`# TYPE ${name} counter`);
+        for (const [k, v] of counters.entries()) {
+          if (k.split('{')[0] === name) lines.push(`${k} ${v}`);
+        }
+      }
+
+      // Gauges
+      const gaugeNames = new Set();
+      for (const k of gauges.keys()) gaugeNames.add(k.split('{')[0]);
+      for (const name of gaugeNames) {
+        lines.push(`# HELP ${name} ${describe(name)}`);
+        lines.push(`# TYPE ${name} gauge`);
+        for (const [k, v] of gauges.entries()) {
+          if (k.split('{')[0] === name) lines.push(`${k} ${v}`);
+        }
+      }
+
+      // Histograms
+      const histNames = new Set();
+      for (const k of histograms.keys()) histNames.add(k.split('{')[0]);
+      for (const name of histNames) {
+        lines.push(`# HELP ${name} ${describe(name)}`);
+        lines.push(`# TYPE ${name} histogram`);
+        for (const [k, h] of histograms.entries()) {
+          if (k.split('{')[0] !== name) continue;
+          // Reconstruct base labels (everything inside { })
+          const baseLabels = k.includes('{') ? k.slice(k.indexOf('{') + 1, -1) : '';
+          const sep = baseLabels ? ',' : '';
+          for (const b of HISTOGRAM_BUCKETS_MS) {
+            lines.push(`${name}_bucket{${baseLabels}${sep}le="${b}"} ${h.buckets[b]}`);
+          }
+          lines.push(`${name}_bucket{${baseLabels}${sep}le="+Inf"} ${h.count}`);
+          lines.push(`${name}_sum${baseLabels ? `{${baseLabels}}` : ''} ${h.sum}`);
+          lines.push(`${name}_count${baseLabels ? `{${baseLabels}}` : ''} ${h.count}`);
+        }
+      }
+
+      return lines.join('\n') + '\n';
+    },
+
+    // Snapshot for tests
+    _snapshot() {
+      return {
+        counters: Object.fromEntries(counters.entries()),
+        gauges: Object.fromEntries(gauges.entries()),
+        histograms: Object.fromEntries(histograms.entries())
+      };
+    }
+  };
+}
+
+const HELP = {
+  crawlforge_tool_requests_total: 'Total number of MCP tool invocations',
+  crawlforge_tool_errors_total: 'Total number of MCP tool errors',
+  crawlforge_tool_duration_ms: 'MCP tool invocation duration in milliseconds',
+  crawlforge_credits_consumed_total: 'Total CrawlForge credits consumed',
+  crawlforge_browser_pool_in_use: 'Number of browser contexts currently leased from the pool',
+  crawlforge_browser_pool_capacity: 'Maximum browser context pool capacity'
+};
+
+function describe(name) {
+  return HELP[name] ?? name;
+}
+
+function escapeLabel(v) {
+  return v.replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/"/g, '\\"');
+}