@arabold/docs-mcp-server 1.25.0 → 1.25.2

package/dist/index.js

@@ -541,32 +541,15 @@ class PostHogClient {
 }
 class TelemetryConfig {
   static instance;
-  enabled;
+  enabled = true;
+  // Default to enabled
   constructor() {
-    this.enabled = this.determineEnabledState();
-  }
-  /**
-   * Determines if telemetry should be enabled based on CLI flags and environment variables.
-   * Priority: CLI flags > environment variables > default (true)
-   */
-  determineEnabledState() {
-    if (process.env.DOCS_MCP_TELEMETRY === "false") {
-      return false;
-    }
-    const args = process.argv;
-    if (args.includes("--no-telemetry")) {
-      return false;
-    }
-    return true;
   }
   isEnabled() {
     return this.enabled;
   }
-  disable() {
-    this.enabled = false;
-  }
-  enable() {
-    this.enabled = true;
+  setEnabled(enabled) {
+    this.enabled = enabled;
   }
   static getInstance() {
     if (!TelemetryConfig.instance) {
@@ -575,10 +558,9 @@ class TelemetryConfig {
     return TelemetryConfig.instance;
   }
 }
-function generateInstallationId() {
+function generateInstallationId(storePath) {
   try {
-    const envStorePath = process.env.DOCS_MCP_STORE_PATH;
-    const dataDir = envStorePath || envPaths("docs-mcp-server", { suffix: "" }).data;
+    const dataDir = storePath || envPaths("docs-mcp-server", { suffix: "" }).data;
     const installationIdPath = path.join(dataDir, "installation.id");
     if (fs.existsSync(installationIdPath)) {
       const existingId = fs.readFileSync(installationIdPath, "utf8").trim();
@@ -602,10 +584,10 @@ var TelemetryEvent = /* @__PURE__ */ ((TelemetryEvent2) => {
   TelemetryEvent2["APP_SHUTDOWN"] = "app_shutdown";
   TelemetryEvent2["CLI_COMMAND"] = "cli_command";
   TelemetryEvent2["TOOL_USED"] = "tool_used";
-  TelemetryEvent2["HTTP_REQUEST_COMPLETED"] = "http_request_completed";
-  TelemetryEvent2["PIPELINE_JOB_PROGRESS"] = "pipeline_job_progress";
   TelemetryEvent2["PIPELINE_JOB_COMPLETED"] = "pipeline_job_completed";
   TelemetryEvent2["DOCUMENT_PROCESSED"] = "document_processed";
+  TelemetryEvent2["WEB_SEARCH_PERFORMED"] = "web_search_performed";
+  TelemetryEvent2["WEB_SCRAPE_STARTED"] = "web_scrape_started";
   return TelemetryEvent2;
 })(TelemetryEvent || {});
 class Analytics {
@@ -623,6 +605,8 @@ class Analytics {
     const analytics2 = new Analytics(shouldEnable);
     if (analytics2.isEnabled()) {
       logger.debug("Analytics enabled");
+    } else if (!config.isEnabled()) {
+      logger.debug("Analytics disabled (user preference)");
     } else {
       logger.debug("Analytics disabled");
     }
@@ -682,38 +666,29 @@ class Analytics {
   isEnabled() {
     return this.enabled;
   }
-  /**
-   * Track tool usage with error handling and automatic timing
-   */
-  async trackTool(toolName, operation, getProperties) {
-    const startTime = Date.now();
-    try {
-      const result = await operation();
-      this.track("tool_used", {
-        tool: toolName,
-        success: true,
-        durationMs: Date.now() - startTime,
-        ...getProperties ? getProperties(result) : {}
-      });
-      return result;
-    } catch (error) {
-      this.track("tool_used", {
-        tool: toolName,
-        success: false,
-        durationMs: Date.now() - startTime
-      });
-      if (error instanceof Error) {
-        this.captureException(error, {
-          tool: toolName,
-          context: "tool_execution",
-          durationMs: Date.now() - startTime
-        });
-      }
-      throw error;
-    }
+}
+let analyticsInstance = null;
+function getAnalytics() {
+  if (!analyticsInstance) {
+    analyticsInstance = Analytics.create();
   }
+  return analyticsInstance;
 }
-const analytics = Analytics.create();
+function initTelemetry(options) {
+  TelemetryConfig.getInstance().setEnabled(options.enabled);
+  generateInstallationId(options.storePath);
+  analyticsInstance = Analytics.create();
+}
+const analytics = new Proxy({}, {
+  get(target, prop) {
+    if (!target.isEnabled) {
+      const instance = getAnalytics();
+      Object.setPrototypeOf(target, Object.getPrototypeOf(instance));
+      Object.assign(target, instance);
+    }
+    return target[prop];
+  }
+});
 function extractHostname(url) {
   try {
     const parsed = new URL(url);
@@ -734,7 +709,7 @@ function extractProtocol(urlOrPath) {
   }
 }
 const name = "@arabold/docs-mcp-server";
-const version = "1.24.0";
+const version = "1.25.1";
 const description = "MCP server for fetching and searching documentation";
 const type = "module";
 const bin = { "docs-mcp-server": "dist/index.js" };
@@ -4839,6 +4814,98 @@ class MarkdownMetadataExtractorMiddleware {
     await next();
   }
 }
+class HtmlNormalizationMiddleware {
+  async process(context, next) {
+    if (!context.dom) {
+      logger.debug(
+        `Skipping HTML normalization for ${context.source} - no DOM available`
+      );
+      await next();
+      return;
+    }
+    try {
+      logger.debug(`Normalizing HTML URLs and links for ${context.source}`);
+      const $ = context.dom;
+      const baseUrl = context.source;
+      this.normalizeImageUrls($, baseUrl);
+      this.normalizeLinks($, baseUrl);
+      logger.debug(`Successfully normalized HTML content for ${context.source}`);
+    } catch (error) {
+      logger.error(`❌ Failed to normalize HTML for ${context.source}: ${error}`);
+      context.errors.push(
+        error instanceof Error ? error : new Error(`HTML normalization failed: ${String(error)}`)
+      );
+    }
+    await next();
+  }
+  /**
+   * Normalizes image URLs by converting relative URLs to absolute URLs.
+   */
+  normalizeImageUrls($, baseUrl) {
+    $("img").each((_index, element) => {
+      const $img = $(element);
+      const src = $img.attr("src");
+      if (!src) return;
+      try {
+        new URL(src);
+      } catch {
+        try {
+          const absoluteUrl = new URL(src, baseUrl).href;
+          $img.attr("src", absoluteUrl);
+          logger.debug(`Converted relative image URL: ${src} → ${absoluteUrl}`);
+        } catch (error) {
+          logger.debug(`Failed to resolve relative image URL: ${src} - ${error}`);
+        }
+      }
+    });
+  }
+  /**
+   * Normalizes links by:
+   * - Converting relative URLs to absolute URLs
+   * - Unwrapping anchor links (preserving text content)
+   * - Unwrapping non-HTTP links (preserving text content)
+   */
+  normalizeLinks($, baseUrl) {
+    $("a").each((_index, element) => {
+      const $link = $(element);
+      const href = $link.attr("href");
+      if (!href) {
+        this.unwrapElement($, $link);
+        return;
+      }
+      if (href.startsWith("#")) {
+        logger.debug(`Removing anchor link: ${href}`);
+        this.unwrapElement($, $link);
+        return;
+      }
+      try {
+        const url = new URL(href);
+        if (url.protocol !== "http:" && url.protocol !== "https:") {
+          logger.debug(`Removing non-HTTP link: ${href}`);
+          this.unwrapElement($, $link);
+          return;
+        }
+      } catch {
+        try {
+          const absoluteUrl = new URL(href, baseUrl).href;
+          $link.attr("href", absoluteUrl);
+          logger.debug(`Converted relative link URL: ${href} → ${absoluteUrl}`);
+        } catch (error) {
+          logger.debug(`Failed to resolve relative link URL: ${href} - ${error}`);
+          this.unwrapElement($, $link);
+        }
+      }
+    });
+  }
+  /**
+   * Unwraps an element by replacing it with its HTML content.
+   * This preserves the inner HTML (including nested elements) while removing the wrapping tag.
+   */
+  unwrapElement(_$, $element) {
+    const htmlContent = $element.html() || $element.text();
+    $element.replaceWith(htmlContent);
+  }
+}
 function detectCharsetFromHtml(htmlContent) {
   const charsetMatch = htmlContent.match(
     /<meta\s+charset\s*=\s*["']?([^"'>\s]+)["']?[^>]*>/i
@@ -4962,6 +5029,7 @@ class HtmlPipeline extends BasePipeline {
       new HtmlMetadataExtractorMiddleware(),
       new HtmlLinkExtractorMiddleware(),
       new HtmlSanitizerMiddleware(),
+      new HtmlNormalizationMiddleware(),
       new HtmlToMarkdownMiddleware()
     ];
     const semanticSplitter = new SemanticMarkdownSplitter(
@@ -7118,7 +7186,7 @@ class EmbeddingConfig {
     }
   }
   /**
-   * Parse embedding model configuration from environment variables.
+   * Parse embedding model configuration from a provided model specification.
    * This is a synchronous operation that extracts provider, model, and known dimensions.
    *
    * Supports various providers:
@@ -7129,11 +7197,11 @@ class EmbeddingConfig {
    * - microsoft: Azure OpenAI
    * - sagemaker: AWS SageMaker hosted models
    *
-   * @param modelSpec Optional model specification, defaults to DOCS_MCP_EMBEDDING_MODEL env var
+   * @param modelSpec Model specification (e.g., "openai:text-embedding-3-small"), defaults to "text-embedding-3-small"
    * @returns Parsed embedding model configuration
    */
   parse(modelSpec) {
-    const spec = modelSpec || process.env.DOCS_MCP_EMBEDDING_MODEL || "text-embedding-3-small";
+    const spec = modelSpec || "text-embedding-3-small";
     const colonIndex = spec.indexOf(":");
     let provider;
     let model;
@@ -7331,16 +7399,13 @@ const CLI_DEFAULTS = {
   TELEMETRY: true
 };
 function parseAuthConfig(options) {
-  const enabled = options.authEnabled ?? (process.env.DOCS_MCP_AUTH_ENABLED?.toLowerCase() === "true" || false);
-  if (!enabled) {
+  if (!options.authEnabled) {
     return void 0;
   }
-  const issuerUrl = options.authIssuerUrl ?? process.env.DOCS_MCP_AUTH_ISSUER_URL;
-  const audience = options.authAudience ?? process.env.DOCS_MCP_AUTH_AUDIENCE;
   return {
-    enabled,
-    issuerUrl,
-    audience,
+    enabled: true,
+    issuerUrl: options.authIssuerUrl,
+    audience: options.authAudience,
     scopes: ["openid", "profile"]
     // Default scopes for OAuth2/OIDC
   };
@@ -7405,12 +7470,23 @@ function warnHttpUsage(authConfig, port) {
     );
   }
 }
-function resolveEmbeddingContext(cliArgs) {
+function resolveEmbeddingContext(embeddingModel) {
   try {
-    const modelSpec = cliArgs?.embeddingModel || process.env.DOCS_MCP_EMBEDDING_MODEL;
-    logger.debug("Resolving embedding configuration");
-    const config = EmbeddingConfig.parseEmbeddingConfig(modelSpec);
-    return config;
+    let modelSpec = embeddingModel;
+    if (!modelSpec && process.env.OPENAI_API_KEY) {
+      modelSpec = "text-embedding-3-small";
+      logger.debug(
+        "Using default OpenAI embedding model due to OPENAI_API_KEY presence."
+      );
+    }
+    if (!modelSpec) {
+      logger.debug(
+        "No embedding model specified and OPENAI_API_KEY not found. Embeddings are disabled."
+      );
+      return null;
+    }
+    logger.debug(`Resolving embedding configuration for model: ${modelSpec}`);
+    return EmbeddingConfig.parseEmbeddingConfig(modelSpec);
   } catch (error) {
     logger.debug(`Failed to resolve embedding configuration: ${error}`);
     return null;
@@ -7431,55 +7507,42 @@ class CancelJobTool {
    * @returns A promise that resolves with the outcome message.
    */
   async execute(input) {
-    return analytics.trackTool(
-      "cancel_job",
-      async () => {
-        try {
-          const job = await this.pipeline.getJob(input.jobId);
-          if (!job) {
-            logger.warn(`❓ [CancelJobTool] Job not found: ${input.jobId}`);
-            return {
-              message: `Job with ID ${input.jobId} not found.`,
-              success: false
-            };
-          }
-          if (job.status === PipelineJobStatus.COMPLETED || // Use enum member
-          job.status === PipelineJobStatus.FAILED || // Use enum member
-          job.status === PipelineJobStatus.CANCELLED) {
-            logger.debug(
-              `Job ${input.jobId} is already in a final state: ${job.status}.`
-            );
-            return {
-              message: `Job ${input.jobId} is already ${job.status}. No action taken.`,
-              success: true
-              // Considered success as no cancellation needed
-            };
-          }
-          await this.pipeline.cancelJob(input.jobId);
-          const updatedJob = await this.pipeline.getJob(input.jobId);
-          const finalStatus = updatedJob?.status ?? "UNKNOWN (job disappeared?)";
-          logger.debug(
-            `Cancellation requested for job ${input.jobId}. Current status: ${finalStatus}`
-          );
-          return {
-            message: `Cancellation requested for job ${input.jobId}. Current status: ${finalStatus}.`,
-            success: true
-          };
-        } catch (error) {
-          logger.error(`❌ Error cancelling job ${input.jobId}: ${error}`);
-          return {
-            message: `Failed to cancel job ${input.jobId}: ${error instanceof Error ? error.message : String(error)}`,
-            success: false
-          };
-        }
-      },
-      (result) => {
+    try {
+      const job = await this.pipeline.getJob(input.jobId);
+      if (!job) {
+        logger.warn(`❓ [CancelJobTool] Job not found: ${input.jobId}`);
         return {
-          success: result.success
-          // Note: success flag already indicates if cancellation was successful
+          message: `Job with ID ${input.jobId} not found.`,
+          success: false
         };
       }
-    );
+      if (job.status === PipelineJobStatus.COMPLETED || // Use enum member
+      job.status === PipelineJobStatus.FAILED || // Use enum member
+      job.status === PipelineJobStatus.CANCELLED) {
+        logger.debug(`Job ${input.jobId} is already in a final state: ${job.status}.`);
+        return {
+          message: `Job ${input.jobId} is already ${job.status}. No action taken.`,
+          success: true
+          // Considered success as no cancellation needed
+        };
+      }
+      await this.pipeline.cancelJob(input.jobId);
+      const updatedJob = await this.pipeline.getJob(input.jobId);
+      const finalStatus = updatedJob?.status ?? "UNKNOWN (job disappeared?)";
+      logger.debug(
+        `Cancellation requested for job ${input.jobId}. Current status: ${finalStatus}`
+      );
+      return {
+        message: `Cancellation requested for job ${input.jobId}. Current status: ${finalStatus}.`,
+        success: true
+      };
+    } catch (error) {
+      logger.error(`❌ Error cancelling job ${input.jobId}: ${error}`);
+      return {
+        message: `Failed to cancel job ${input.jobId}: ${error instanceof Error ? error.message : String(error)}`,
+        success: false
+      };
+    }
   }
 }
 class ClearCompletedJobsTool {
@@ -7497,33 +7560,24 @@ class ClearCompletedJobsTool {
    * @returns A promise that resolves with the outcome of the clear operation.
    */
   async execute(_input) {
-    return analytics.trackTool(
-      "clear_completed_jobs",
-      async () => {
-        try {
-          const clearedCount = await this.pipeline.clearCompletedJobs();
-          const message = clearedCount > 0 ? `Successfully cleared ${clearedCount} completed job${clearedCount === 1 ? "" : "s"} from the queue.` : "No completed jobs to clear.";
-          logger.debug(message);
-          return {
-            message,
-            success: true,
-            clearedCount
-          };
-        } catch (error) {
-          const errorMessage = `Failed to clear completed jobs: ${error instanceof Error ? error.message : String(error)}`;
-          logger.error(`❌ ${errorMessage}`);
-          return {
-            message: errorMessage,
-            success: false,
-            clearedCount: 0
-          };
-        }
-      },
-      (result) => ({
-        success: result.success,
-        clearedCount: result.clearedCount
-      })
-    );
+    try {
+      const clearedCount = await this.pipeline.clearCompletedJobs();
+      const message = clearedCount > 0 ? `Successfully cleared ${clearedCount} completed job${clearedCount === 1 ? "" : "s"} from the queue.` : "No completed jobs to clear.";
+      logger.debug(message);
+      return {
+        message,
+        success: true,
+        clearedCount
+      };
+    } catch (error) {
+      const errorMessage = `Failed to clear completed jobs: ${error instanceof Error ? error.message : String(error)}`;
+      logger.error(`❌ ${errorMessage}`);
+      return {
+        message: errorMessage,
+        success: false,
+        clearedCount: 0
+      };
+    }
   }
 }
 class ToolError extends Error {
@@ -7583,103 +7637,88 @@ class FetchUrlTool {
    * @throws {ToolError} If fetching or processing fails
    */
   async execute(options) {
-    return analytics.trackTool(
-      "fetch_url",
-      async () => {
-        const { url, scrapeMode = ScrapeMode.Auto, headers } = options;
-        const canFetchResults = this.fetchers.map((f) => f.canFetch(url));
-        const fetcherIndex = canFetchResults.indexOf(true);
-        if (fetcherIndex === -1) {
-          throw new ToolError(
-            `Invalid URL: ${url}. Must be an HTTP/HTTPS URL or a file:// URL.`,
-            this.constructor.name
-          );
-        }
-        const fetcher = this.fetchers[fetcherIndex];
-        logger.debug(`Using fetcher "${fetcher.constructor.name}" for URL: ${url}`);
-        try {
-          logger.info(`📡 Fetching ${url}...`);
-          const rawContent = await fetcher.fetch(url, {
-            followRedirects: options.followRedirects ?? true,
-            maxRetries: 3,
-            headers
-            // propagate custom headers
-          });
-          logger.info("🔄 Processing content...");
-          let processed;
-          for (const pipeline of this.pipelines) {
-            if (pipeline.canProcess(rawContent)) {
-              processed = await pipeline.process(
-                rawContent,
-                {
-                  url,
-                  library: "",
-                  version: "",
-                  maxDepth: 0,
-                  maxPages: 1,
-                  maxConcurrency: 1,
-                  scope: "subpages",
-                  followRedirects: options.followRedirects ?? true,
-                  excludeSelectors: void 0,
-                  ignoreErrors: false,
-                  scrapeMode,
-                  headers
-                  // propagate custom headers
-                },
-                fetcher
-              );
-              break;
-            }
-          }
-          if (!processed) {
-            logger.warn(
-              `⚠️  Unsupported content type "${rawContent.mimeType}" for ${url}. Returning raw content.`
-            );
-            const resolvedCharset = resolveCharset(
-              rawContent.charset,
-              rawContent.content,
-              rawContent.mimeType
-            );
-            const contentString = convertToString(rawContent.content, resolvedCharset);
-            return contentString;
-          }
-          for (const err of processed.errors) {
-            logger.warn(`⚠️  Processing error for ${url}: ${err.message}`);
-          }
-          if (typeof processed.textContent !== "string" || !processed.textContent.trim()) {
-            throw new ToolError(
-              `Processing resulted in empty content for ${url}`,
-              this.constructor.name
-            );
-          }
-          logger.info(`✅ Successfully processed ${url}`);
-          return processed.textContent;
-        } catch (error) {
-          if (error instanceof ScraperError || error instanceof ToolError) {
-            throw new ToolError(
-              `Failed to fetch or process URL: ${error.message}`,
-              this.constructor.name
-            );
-          }
-          throw new ToolError(
-            `Failed to fetch or process URL: ${error instanceof Error ? error.message : String(error)}`,
-            this.constructor.name
+    const { url, scrapeMode = ScrapeMode.Auto, headers } = options;
+    const canFetchResults = this.fetchers.map((f) => f.canFetch(url));
+    const fetcherIndex = canFetchResults.indexOf(true);
+    if (fetcherIndex === -1) {
+      throw new ToolError(
+        `Invalid URL: ${url}. Must be an HTTP/HTTPS URL or a file:// URL.`,
+        this.constructor.name
+      );
+    }
+    const fetcher = this.fetchers[fetcherIndex];
+    logger.debug(`Using fetcher "${fetcher.constructor.name}" for URL: ${url}`);
+    try {
+      logger.info(`📡 Fetching ${url}...`);
+      const rawContent = await fetcher.fetch(url, {
+        followRedirects: options.followRedirects ?? true,
+        maxRetries: 3,
+        headers
+        // propagate custom headers
+      });
+      logger.info("🔄 Processing content...");
+      let processed;
+      for (const pipeline of this.pipelines) {
+        if (pipeline.canProcess(rawContent)) {
+          processed = await pipeline.process(
+            rawContent,
+            {
+              url,
+              library: "",
+              version: "",
+              maxDepth: 0,
+              maxPages: 1,
+              maxConcurrency: 1,
+              scope: "subpages",
+              followRedirects: options.followRedirects ?? true,
+              excludeSelectors: void 0,
+              ignoreErrors: false,
+              scrapeMode,
+              headers
+              // propagate custom headers
+            },
+            fetcher
           );
-        } finally {
-          await Promise.allSettled(this.pipelines.map((pipeline) => pipeline.close()));
+          break;
         }
-      },
-      (result) => {
-        const { url, scrapeMode, followRedirects, headers } = options;
-        return {
-          url,
-          scrapeMode,
-          followRedirects,
-          contentLength: result.length,
-          hasHeaders: !!headers
-        };
       }
-    );
+      if (!processed) {
+        logger.warn(
+          `⚠️  Unsupported content type "${rawContent.mimeType}" for ${url}. Returning raw content.`
+        );
+        const resolvedCharset = resolveCharset(
+          rawContent.charset,
+          rawContent.content,
+          rawContent.mimeType
+        );
+        const contentString = convertToString(rawContent.content, resolvedCharset);
+        return contentString;
+      }
+      for (const err of processed.errors) {
+        logger.warn(`⚠️  Processing error for ${url}: ${err.message}`);
+      }
+      if (typeof processed.textContent !== "string" || !processed.textContent.trim()) {
+        throw new ToolError(
+          `Processing resulted in empty content for ${url}`,
+          this.constructor.name
+        );
+      }
+      logger.info(`✅ Successfully processed ${url}`);
+      return processed.textContent;
+    } catch (error) {
+      if (error instanceof ScraperError || error instanceof ToolError) {
+        throw new ToolError(
+          `Failed to fetch or process URL: ${error.message}`,
+          this.constructor.name
+        );
+      }
+      throw new ToolError(
+        `Failed to fetch or process URL: ${error instanceof Error ? error.message : String(error)}`,
+        this.constructor.name
+      );
+    } finally {
+      await Promise.allSettled(this.pipelines.map((pipeline) => pipeline.close()));
+    }
   }
 }
 class FindVersionTool {
@@ -7692,50 +7731,36 @@ class FindVersionTool {
    * @returns A descriptive string indicating the best match and unversioned status, or an error message.
    */
   async execute(options) {
-    return analytics.trackTool(
-      "find_version",
-      async () => {
-        const { library, targetVersion } = options;
-        const libraryAndVersion = `${library}${targetVersion ? `@${targetVersion}` : ""}`;
-        try {
-          const { bestMatch, hasUnversioned } = await this.docService.findBestVersion(
-            library,
-            targetVersion
-          );
-          let message = "";
-          if (bestMatch) {
-            message = `Best match: ${bestMatch}.`;
-            if (hasUnversioned) {
-              message += " Unversioned docs also available.";
-            }
-          } else if (hasUnversioned) {
-            message = `No matching version found for ${libraryAndVersion}, but unversioned docs exist.`;
-          } else {
-            message = `No matching version or unversioned documents found for ${libraryAndVersion}.`;
-          }
-          return { message, bestMatch, hasUnversioned };
-        } catch (error) {
-          if (error instanceof VersionNotFoundError) {
-            logger.info(`ℹ️ Version not found: ${error.message}`);
-            const message = `No matching version or unversioned documents found for ${libraryAndVersion}. Available: ${error.availableVersions.length > 0 ? error.availableVersions.map((v) => v.version).join(", ") : "None"}.`;
-            return { message, bestMatch: null, hasUnversioned: false };
-          }
-          logger.error(
-            `❌ Error finding version for ${libraryAndVersion}: ${error instanceof Error ? error.message : error}`
-          );
-          throw error;
-        }
-      },
-      (result) => {
-        const { library, targetVersion } = options;
-        return {
-          library,
-          targetVersion,
-          foundMatch: !!result.bestMatch,
-          hasUnversioned: result.hasUnversioned
-        };
+    const { library, targetVersion } = options;
+    const libraryAndVersion = `${library}${targetVersion ? `@${targetVersion}` : ""}`;
+    try {
+      const { bestMatch, hasUnversioned } = await this.docService.findBestVersion(
+        library,
+        targetVersion
+      );
+      let message = "";
+      if (bestMatch) {
+        message = `Best match: ${bestMatch}.`;
+        if (hasUnversioned) {
+          message += " Unversioned docs also available.";
+        }
+      } else if (hasUnversioned) {
+        message = `No matching version found for ${libraryAndVersion}, but unversioned docs exist.`;
+      } else {
+        message = `No matching version or unversioned documents found for ${libraryAndVersion}.`;
       }
-    ).then((result) => result.message);
+      return message;
+    } catch (error) {
+      if (error instanceof VersionNotFoundError) {
+        logger.info(`ℹ️ Version not found: ${error.message}`);
+        const message = `No matching version or unversioned documents found for ${libraryAndVersion}. Available: ${error.availableVersions.length > 0 ? error.availableVersions.map((v) => v.version).join(", ") : "None"}.`;
+        return message;
+      }
+      logger.error(
+        `❌ Error finding version for ${libraryAndVersion}: ${error instanceof Error ? error.message : error}`
+      );
+      throw error;
+    }
   }
 }
 class GetJobInfoTool {
@@ -7753,41 +7778,29 @@ class GetJobInfoTool {
    * @returns A promise that resolves with the simplified job info or null if not found.
    */
   async execute(input) {
-    return analytics.trackTool(
-      "get_job_info",
-      async () => {
-        const job = await this.pipeline.getJob(input.jobId);
-        if (!job) {
-          return { job: null };
-        }
-        const jobInfo = {
-          id: job.id,
-          library: job.library,
-          version: job.version,
-          status: job.status,
-          dbStatus: job.versionStatus,
-          createdAt: job.createdAt.toISOString(),
-          startedAt: job.startedAt?.toISOString() ?? null,
-          finishedAt: job.finishedAt?.toISOString() ?? null,
-          error: job.error?.message ?? null,
-          progress: job.progressMaxPages && job.progressMaxPages > 0 ? {
-            pages: job.progressPages || 0,
-            totalPages: job.progressMaxPages,
-            totalDiscovered: job.progress?.totalDiscovered || job.progressMaxPages
-          } : void 0,
-          updatedAt: job.updatedAt?.toISOString(),
-          errorMessage: job.errorMessage ?? void 0
-        };
-        return { job: jobInfo };
-      },
-      (result) => {
-        return {
-          found: result.job !== null,
-          library: result.job?.library,
-          version: result.job?.version
-        };
-      }
-    );
+    const job = await this.pipeline.getJob(input.jobId);
+    if (!job) {
+      return { job: null };
+    }
+    const jobInfo = {
+      id: job.id,
+      library: job.library,
+      version: job.version,
+      status: job.status,
+      dbStatus: job.versionStatus,
+      createdAt: job.createdAt.toISOString(),
+      startedAt: job.startedAt?.toISOString() ?? null,
+      finishedAt: job.finishedAt?.toISOString() ?? null,
+      error: job.error?.message ?? null,
+      progress: job.progressMaxPages && job.progressMaxPages > 0 ? {
+        pages: job.progressPages || 0,
+        totalPages: job.progressMaxPages,
+        totalDiscovered: job.progress?.totalDiscovered || job.progressMaxPages
+      } : void 0,
+      updatedAt: job.updatedAt?.toISOString(),
+      errorMessage: job.errorMessage ?? void 0
+    };
+    return { job: jobInfo };
   }
 }
 class ListJobsTool {
@@ -7805,45 +7818,28 @@ class ListJobsTool {
    * @returns A promise that resolves with the list of simplified job objects.
    */
   async execute(input) {
-    return analytics.trackTool(
-      "list_jobs",
-      async () => {
-        const jobs = await this.pipeline.getJobs(input.status);
-        const simplifiedJobs = jobs.map((job) => {
-          return {
-            id: job.id,
-            library: job.library,
-            version: job.version,
-            status: job.status,
-            dbStatus: job.versionStatus,
-            createdAt: job.createdAt.toISOString(),
-            startedAt: job.startedAt?.toISOString() ?? null,
-            finishedAt: job.finishedAt?.toISOString() ?? null,
-            error: job.error?.message ?? null,
-            progress: job.progressMaxPages && job.progressMaxPages > 0 ? {
-              pages: job.progressPages || 0,
-              totalPages: job.progressMaxPages,
-              totalDiscovered: job.progress?.totalDiscovered || job.progressMaxPages
-            } : void 0,
-            updatedAt: job.updatedAt?.toISOString(),
-            errorMessage: job.errorMessage ?? void 0
-          };
-        });
-        return { jobs: simplifiedJobs };
-      },
-      (result) => {
-        return {
-          jobCount: result.jobs.length,
-          statusCounts: result.jobs.reduce(
-            (acc, job) => {
-              acc[job.status] = (acc[job.status] || 0) + 1;
-              return acc;
-            },
-            {}
-          )
-        };
-      }
-    );
+    const jobs = await this.pipeline.getJobs(input.status);
+    const simplifiedJobs = jobs.map((job) => {
+      return {
+        id: job.id,
+        library: job.library,
+        version: job.version,
+        status: job.status,
+        dbStatus: job.versionStatus,
+        createdAt: job.createdAt.toISOString(),
+        startedAt: job.startedAt?.toISOString() ?? null,
+        finishedAt: job.finishedAt?.toISOString() ?? null,
+        error: job.error?.message ?? null,
+        progress: job.progressMaxPages && job.progressMaxPages > 0 ? {
+          pages: job.progressPages || 0,
+          totalPages: job.progressMaxPages,
+          totalDiscovered: job.progress?.totalDiscovered || job.progressMaxPages
+        } : void 0,
+        updatedAt: job.updatedAt?.toISOString(),
+        errorMessage: job.errorMessage ?? void 0
+      };
+    });
+    return { jobs: simplifiedJobs };
   }
 }
 class ListLibrariesTool {
@@ -7852,32 +7848,20 @@ class ListLibrariesTool {
     this.docService = docService;
   }
   async execute(_options) {
-    return analytics.trackTool(
-      "list_libraries",
-      async () => {
-        const rawLibraries = await this.docService.listLibraries();
-        const libraries = rawLibraries.map(({ library, versions }) => ({
-          name: library,
-          versions: versions.map((v) => ({
-            version: v.ref.version,
-            documentCount: v.counts.documents,
-            uniqueUrlCount: v.counts.uniqueUrls,
-            indexedAt: v.indexedAt,
-            status: v.status,
-            ...v.progress ? { progress: v.progress } : void 0,
-            sourceUrl: v.sourceUrl
-          }))
-        }));
-        return { libraries };
-      },
-      (result) => ({
-        libraryCount: result.libraries.length,
-        totalVersions: result.libraries.reduce(
-          (sum, lib) => sum + lib.versions.length,
-          0
-        )
-      })
-    );
+    const rawLibraries = await this.docService.listLibraries();
+    const libraries = rawLibraries.map(({ library, versions }) => ({
+      name: library,
+      versions: versions.map((v) => ({
+        version: v.ref.version,
+        documentCount: v.counts.documents,
+        uniqueUrlCount: v.counts.uniqueUrls,
+        indexedAt: v.indexedAt,
+        status: v.status,
+        ...v.progress ? { progress: v.progress } : void 0,
+        sourceUrl: v.sourceUrl
+      }))
+    }));
+    return { libraries };
   }
 }
 class RemoveTool {
@@ -7891,42 +7875,29 @@ class RemoveTool {
    * Removes all documents, the version record, and the library if no other versions exist.
    */
   async execute(args) {
-    return analytics.trackTool(
-      "remove_docs",
-      async () => {
-        const { library, version: version2 } = args;
-        logger.info(`🗑️ Removing library: ${library}${version2 ? `@${version2}` : ""}`);
-        try {
-          const allJobs = await this.pipeline.getJobs();
-          const jobs = allJobs.filter(
-            (job) => job.library === library && job.version === (version2 ?? "") && (job.status === PipelineJobStatus.QUEUED || job.status === PipelineJobStatus.RUNNING)
-          );
-          for (const job of jobs) {
-            logger.info(
-              `🚫 Aborting job for ${library}@${version2 ?? ""} before deletion: ${job.id}`
-            );
-            await this.pipeline.cancelJob(job.id);
-            await this.pipeline.waitForJobCompletion(job.id);
-          }
-          await this.documentManagementService.removeVersion(library, version2);
-          const message = `Successfully removed ${library}${version2 ? `@${version2}` : ""}.`;
-          logger.info(`✅ ${message}`);
-          return { message };
-        } catch (error) {
-          const errorMessage = `Failed to remove ${library}${version2 ? `@${version2}` : ""}: ${error instanceof Error ? error.message : String(error)}`;
-          logger.error(`❌ Error removing library: ${errorMessage}`);
-          throw new ToolError(errorMessage, this.constructor.name);
-        }
-      },
-      () => {
-        const { library, version: version2 } = args;
-        return {
-          library,
-          version: version2
-          // Success is implicit since if this callback runs, no exception was thrown
-        };
+    const { library, version: version2 } = args;
+    logger.info(`🗑️ Removing library: ${library}${version2 ? `@${version2}` : ""}`);
+    try {
+      const allJobs = await this.pipeline.getJobs();
+      const jobs = allJobs.filter(
+        (job) => job.library === library && job.version === (version2 ?? "") && (job.status === PipelineJobStatus.QUEUED || job.status === PipelineJobStatus.RUNNING)
+      );
+      for (const job of jobs) {
+        logger.info(
+          `🚫 Aborting job for ${library}@${version2 ?? ""} before deletion: ${job.id}`
+        );
+        await this.pipeline.cancelJob(job.id);
+        await this.pipeline.waitForJobCompletion(job.id);
       }
-    );
+      await this.documentManagementService.removeVersion(library, version2);
+      const message = `Successfully removed ${library}${version2 ? `@${version2}` : ""}.`;
+      logger.info(`✅ ${message}`);
+      return { message };
+    } catch (error) {
+      const errorMessage = `Failed to remove ${library}${version2 ? `@${version2}` : ""}: ${error instanceof Error ? error.message : String(error)}`;
+      logger.error(`❌ Error removing library: ${errorMessage}`);
+      throw new ToolError(errorMessage, this.constructor.name);
+    }
   }
 }
 class ScrapeTool {
@@ -7942,80 +7913,66 @@ class ScrapeTool {
       options: scraperOptions,
       waitForCompletion = true
     } = options;
-    return analytics.trackTool(
-      "scrape_docs",
-      async () => {
-        let internalVersion;
-        const partialVersionRegex = /^\d+(\.\d+)?$/;
-        if (version2 === null || version2 === void 0) {
-          internalVersion = "";
+    let internalVersion;
+    const partialVersionRegex = /^\d+(\.\d+)?$/;
+    if (version2 === null || version2 === void 0) {
+      internalVersion = "";
+    } else {
+      const validFullVersion = semver.valid(version2);
+      if (validFullVersion) {
+        internalVersion = validFullVersion;
+      } else if (partialVersionRegex.test(version2)) {
+        const coercedVersion = semver.coerce(version2);
+        if (coercedVersion) {
+          internalVersion = coercedVersion.version;
         } else {
-          const validFullVersion = semver.valid(version2);
-          if (validFullVersion) {
-            internalVersion = validFullVersion;
-          } else if (partialVersionRegex.test(version2)) {
-            const coercedVersion = semver.coerce(version2);
-            if (coercedVersion) {
-              internalVersion = coercedVersion.version;
-            } else {
-              throw new Error(
-                `Invalid version format for scraping: '${version2}'. Use 'X.Y.Z', 'X.Y.Z-prerelease', 'X.Y', 'X', or omit.`
-              );
-            }
-          } else {
-            throw new Error(
-              `Invalid version format for scraping: '${version2}'. Use 'X.Y.Z', 'X.Y.Z-prerelease', 'X.Y', 'X', or omit.`
-            );
-          }
-        }
-        internalVersion = internalVersion.toLowerCase();
-        const pipeline = this.pipeline;
-        const enqueueVersion = internalVersion === "" ? null : internalVersion;
-        const jobId = await pipeline.enqueueJob(library, enqueueVersion, {
-          url,
-          library,
-          version: internalVersion,
-          scope: scraperOptions?.scope ?? "subpages",
-          followRedirects: scraperOptions?.followRedirects ?? true,
-          maxPages: scraperOptions?.maxPages ?? DEFAULT_MAX_PAGES,
-          maxDepth: scraperOptions?.maxDepth ?? DEFAULT_MAX_DEPTH$1,
-          maxConcurrency: scraperOptions?.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY,
-          ignoreErrors: scraperOptions?.ignoreErrors ?? true,
-          scrapeMode: scraperOptions?.scrapeMode ?? ScrapeMode.Auto,
-          // Pass scrapeMode enum
-          includePatterns: scraperOptions?.includePatterns,
-          excludePatterns: scraperOptions?.excludePatterns,
-          headers: scraperOptions?.headers
-          // <-- propagate headers
-        });
-        if (waitForCompletion) {
-          try {
-            await pipeline.waitForJobCompletion(jobId);
-            const finalJob = await pipeline.getJob(jobId);
-            const finalPagesScraped = finalJob?.progress?.pagesScraped ?? 0;
-            logger.debug(
-              `Job ${jobId} finished with status ${finalJob?.status}. Pages scraped: ${finalPagesScraped}`
-            );
-            return {
-              pagesScraped: finalPagesScraped
-            };
-          } catch (error) {
-            logger.error(`❌ Job ${jobId} failed or was cancelled: ${error}`);
-            throw error;
-          }
+          throw new Error(
+            `Invalid version format for scraping: '${version2}'. Use 'X.Y.Z', 'X.Y.Z-prerelease', 'X.Y', 'X', or omit.`
+          );
         }
-        return { jobId };
-      },
-      (result) => ({
-        library,
-        version: version2,
-        url,
-        waitForCompletion,
-        ...scraperOptions,
-        isBackgroundJob: "jobId" in result,
-        pagesScraped: "pagesScraped" in result ? result.pagesScraped : void 0
-      })
-    );
+      } else {
+        throw new Error(
+          `Invalid version format for scraping: '${version2}'. Use 'X.Y.Z', 'X.Y.Z-prerelease', 'X.Y', 'X', or omit.`
+        );
+      }
+    }
+    internalVersion = internalVersion.toLowerCase();
+    const pipeline = this.pipeline;
+    const enqueueVersion = internalVersion === "" ? null : internalVersion;
+    const jobId = await pipeline.enqueueJob(library, enqueueVersion, {
+      url,
+      library,
+      version: internalVersion,
+      scope: scraperOptions?.scope ?? "subpages",
+      followRedirects: scraperOptions?.followRedirects ?? true,
+      maxPages: scraperOptions?.maxPages ?? DEFAULT_MAX_PAGES,
+      maxDepth: scraperOptions?.maxDepth ?? DEFAULT_MAX_DEPTH$1,
+      maxConcurrency: scraperOptions?.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY,
+      ignoreErrors: scraperOptions?.ignoreErrors ?? true,
+      scrapeMode: scraperOptions?.scrapeMode ?? ScrapeMode.Auto,
+      // Pass scrapeMode enum
+      includePatterns: scraperOptions?.includePatterns,
+      excludePatterns: scraperOptions?.excludePatterns,
+      headers: scraperOptions?.headers
+      // <-- propagate headers
+    });
+    if (waitForCompletion) {
+      try {
+        await pipeline.waitForJobCompletion(jobId);
+        const finalJob = await pipeline.getJob(jobId);
+        const finalPagesScraped = finalJob?.progress?.pagesScraped ?? 0;
+        logger.debug(
+          `Job ${jobId} finished with status ${finalJob?.status}. Pages scraped: ${finalPagesScraped}`
+        );
+        return {
+          pagesScraped: finalPagesScraped
+        };
+      } catch (error) {
+        logger.error(`❌ Job ${jobId} failed or was cancelled: ${error}`);
+        throw error;
+      }
+    }
+    return { jobId };
   }
 }
 class SearchTool {
@@ -8025,56 +7982,43 @@ class SearchTool {
   }
   async execute(options) {
     const { library, version: version2, query, limit = 5, exactMatch = false } = options;
-    return analytics.trackTool(
-      "search_docs",
-      async () => {
-        if (exactMatch && (!version2 || version2 === "latest")) {
-          await this.docService.validateLibraryExists(library);
-          const allLibraries = await this.docService.listLibraries();
-          const libraryInfo = allLibraries.find((lib) => lib.library === library);
-          const detailedVersions = libraryInfo ? libraryInfo.versions.map((v) => ({
-            version: v.ref.version,
-            documentCount: v.counts.documents,
-            uniqueUrlCount: v.counts.uniqueUrls,
-            indexedAt: v.indexedAt
-          })) : [];
-          throw new VersionNotFoundError(library, version2 ?? "latest", detailedVersions);
-        }
-        const resolvedVersion = version2 || "latest";
-        logger.info(
-          `🔍 Searching ${library}@${resolvedVersion} for: ${query}${exactMatch ? " (exact match)" : ""}`
-        );
-        try {
-          await this.docService.validateLibraryExists(library);
-          let versionToSearch = resolvedVersion;
-          if (!exactMatch) {
-            const versionResult = await this.docService.findBestVersion(library, version2);
-            versionToSearch = versionResult.bestMatch;
-          }
-          const results = await this.docService.searchStore(
-            library,
-            versionToSearch,
-            query,
-            limit
-          );
-          logger.info(`✅ Found ${results.length} matching results`);
-          return { results };
-        } catch (error) {
-          logger.error(
-            `❌ Search failed: ${error instanceof Error ? error.message : "Unknown error"}`
-          );
-          throw error;
-        }
-      },
-      (result) => ({
+    if (exactMatch && (!version2 || version2 === "latest")) {
+      await this.docService.validateLibraryExists(library);
+      const allLibraries = await this.docService.listLibraries();
+      const libraryInfo = allLibraries.find((lib) => lib.library === library);
+      const detailedVersions = libraryInfo ? libraryInfo.versions.map((v) => ({
+        version: v.ref.version,
+        documentCount: v.counts.documents,
+        uniqueUrlCount: v.counts.uniqueUrls,
+        indexedAt: v.indexedAt
+      })) : [];
+      throw new VersionNotFoundError(library, version2 ?? "latest", detailedVersions);
+    }
+    const resolvedVersion = version2 || "latest";
+    logger.info(
+      `🔍 Searching ${library}@${resolvedVersion} for: ${query}${exactMatch ? " (exact match)" : ""}`
+    );
+    try {
+      await this.docService.validateLibraryExists(library);
+      let versionToSearch = resolvedVersion;
+      if (!exactMatch) {
+        const versionResult = await this.docService.findBestVersion(library, version2);
+        versionToSearch = versionResult.bestMatch;
+      }
+      const results = await this.docService.searchStore(
         library,
-        version: version2,
+        versionToSearch,
         query,
-        limit,
-        exactMatch,
-        resultCount: result.results.length
-      })
-    );
+        limit
+      );
+      logger.info(`✅ Found ${results.length} matching results`);
+      return { results };
+    } catch (error) {
+      logger.error(
+        `❌ Search failed: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+      throw error;
+    }
   }
 }
 function createResponse(text) {
@@ -8133,6 +8077,17 @@ function createMcpServerInstance(tools, readOnly = false) {
         // requires internet access
       },
       async ({ url, library, version: version2, maxPages, maxDepth, scope, followRedirects }) => {
+        analytics.track(TelemetryEvent.TOOL_USED, {
+          tool: "scrape_docs",
+          context: "mcp_server",
+          library,
+          version: version2,
+          url: new URL(url).hostname,
+          // Privacy-safe URL tracking
+          maxPages,
+          maxDepth,
+          scope
+        });
         try {
           const result = await tools.scrape.execute({
             url,
@@ -8177,6 +8132,15 @@ function createMcpServerInstance(tools, readOnly = false) {
       destructiveHint: false
     },
     async ({ library, version: version2, query, limit }) => {
+      analytics.track(TelemetryEvent.TOOL_USED, {
+        tool: "search_docs",
+        context: "mcp_server",
+        library,
+        version: version2,
+        query: query.substring(0, 100),
+        // Truncate query for privacy
+        limit
+      });
       try {
         const result = await tools.search.execute({
           library,
@@ -8236,6 +8200,10 @@ ${r.content}
       destructiveHint: false
     },
     async () => {
+      analytics.track(TelemetryEvent.TOOL_USED, {
+        tool: "list_libraries",
+        context: "mcp_server"
+      });
       try {
         const result = await tools.listLibraries.execute();
         if (result.libraries.length === 0) {
@@ -8266,6 +8234,12 @@ ${result.libraries.map((lib) => `- ${lib.name}`).join("\n")}`
       destructiveHint: false
     },
     async ({ library, targetVersion }) => {
+      analytics.track(TelemetryEvent.TOOL_USED, {
+        tool: "find_version",
+        context: "mcp_server",
+        library,
+        targetVersion
+      });
       try {
         const message = await tools.findVersion.execute({
           library,
@@ -8295,6 +8269,11 @@ ${result.libraries.map((lib) => `- ${lib.name}`).join("\n")}`
         destructiveHint: false
       },
       async ({ status }) => {
+        analytics.track(TelemetryEvent.TOOL_USED, {
+          tool: "list_jobs",
+          context: "mcp_server",
+          status
+        });
         try {
           const result = await tools.listJobs.execute({
             status
@@ -8333,6 +8312,11 @@ ${formattedJobs}` : "No jobs found."
         destructiveHint: false
       },
       async ({ jobId }) => {
+        analytics.track(TelemetryEvent.TOOL_USED, {
+          tool: "get_job_info",
+          context: "mcp_server",
+          jobId
+        });
         try {
           const result = await tools.getJobInfo.execute({ jobId });
           if (!result.job) {
@@ -8367,6 +8351,11 @@ ${formattedJob}`);
         destructiveHint: true
       },
       async ({ jobId }) => {
+        analytics.track(TelemetryEvent.TOOL_USED, {
+          tool: "cancel_job",
+          context: "mcp_server",
+          jobId
+        });
         try {
           const result = await tools.cancelJob.execute({ jobId });
           if (result.success) {
@@ -8392,6 +8381,12 @@ ${formattedJob}`);
         destructiveHint: true
       },
       async ({ library, version: version2 }) => {
+        analytics.track(TelemetryEvent.TOOL_USED, {
+          tool: "remove_docs",
+          context: "mcp_server",
+          library,
+          version: version2
+        });
         try {
           const result = await tools.remove.execute({ library, version: version2 });
           return createResponse(result.message);
@@ -8418,6 +8413,13 @@ ${formattedJob}`);
       // requires internet access
     },
     async ({ url, followRedirects }) => {
+      analytics.track(TelemetryEvent.TOOL_USED, {
+        tool: "fetch_url",
+        context: "mcp_server",
+        url: new URL(url).hostname,
+        // Privacy-safe URL tracking
+        followRedirects
+      });
       try {
         const result = await tools.fetchUrl.execute({ url, followRedirects });
         return createResponse(result);
@@ -8677,6 +8679,18 @@ function createPipelineRouter(trpc) {
           input.version ?? null,
           input.options
         );
+        analytics.track(TelemetryEvent.WEB_SCRAPE_STARTED, {
+          library: input.library,
+          version: input.version || void 0,
+          url: input.options.url,
+          scope: input.options.scope || "subpages",
+          maxDepth: input.options.maxDepth || 3,
+          maxPages: input.options.maxPages || 1e3,
+          maxConcurrency: input.options.maxConcurrency,
+          ignoreErrors: input.options.ignoreErrors,
+          scrapeMode: input.options.scrapeMode,
+          hasCustomHeaders: !!(input.options.headers && Object.keys(input.options.headers).length > 0)
+        });
         return { jobId };
       }
     ),
@@ -8760,6 +8774,13 @@ function createDataRouter(trpc) {
           input.query,
           input.limit ?? 5
         );
+        analytics.track(TelemetryEvent.WEB_SEARCH_PERFORMED, {
+          library: input.library,
+          version: input.version || void 0,
+          queryLength: input.query.length,
+          resultCount: results.length,
+          limit: input.limit ?? 5
+        });
         return results;
       }
     ),
@@ -10300,22 +10321,6 @@ async function registerWorkerService(pipeline) {
       logger.debug(
         `Job ${job.id} progress: ${progress.pagesScraped}/${progress.totalPages} pages`
       );
-      analytics.track(TelemetryEvent.PIPELINE_JOB_PROGRESS, {
-        jobId: job.id,
-        // Job IDs are already anonymous
-        library: job.library,
-        pagesScraped: progress.pagesScraped,
-        totalPages: progress.totalPages,
-        totalDiscovered: progress.totalDiscovered,
-        progressPercent: Math.round(progress.pagesScraped / progress.totalPages * 100),
-        currentDepth: progress.depth,
-        maxDepth: progress.maxDepth,
-        discoveryRatio: Math.round(
-          progress.totalDiscovered / progress.totalPages * 100
-        ),
-        // How much we discovered vs limited total
-        queueEfficiency: progress.totalPages > 0 ? Math.round(progress.pagesScraped / progress.totalPages * 100) : 0
-      });
     },
     onJobStatusChange: async (job) => {
       logger.debug(`Job ${job.id} status changed to: ${job.status}`);
@@ -11731,9 +11736,9 @@ class DocumentStore {
     return [...vector, ...new Array(this.dbDimension - vector.length).fill(0)];
   }
   /**
-   * Initialize the embeddings client using either provided config or environment variables.
-   * If no embedding config is provided (null), embeddings will not be initialized.
-   * This allows DocumentStore to be used without embeddings for operations that don't need them.
+   * Initialize the embeddings client using the provided config.
+   * If no embedding config is provided (null or undefined), embeddings will not be initialized.
+   * This allows DocumentStore to be used without embeddings for FTS-only operations.
    *
    * Environment variables per provider:
    * - openai: OPENAI_API_KEY (and optionally OPENAI_API_BASE, OPENAI_ORG_ID)
@@ -11743,11 +11748,13 @@ class DocumentStore {
    * - microsoft: Azure OpenAI credentials (AZURE_OPENAI_API_*)
    */
   async initializeEmbeddings() {
-    if (this.embeddingConfig === null) {
-      logger.debug("Embedding initialization skipped (explicitly disabled)");
+    if (this.embeddingConfig === null || this.embeddingConfig === void 0) {
+      logger.debug(
+        "Embedding initialization skipped (no config provided - FTS-only mode)"
+      );
       return;
     }
-    const config = this.embeddingConfig || EmbeddingConfig.parseEmbeddingConfig();
+    const config = this.embeddingConfig;
     if (!areCredentialsAvailable(config.provider)) {
       logger.warn(
         `⚠️ No credentials found for ${config.provider} embedding provider. Vector search is disabled.
@@ -12057,7 +12064,7 @@ class DocumentStore {
 `;
           return `${header}${doc.pageContent}`;
         });
-        const maxBatchChars = Number(process.env.DOCS_MCP_EMBEDDING_BATCH_CHARS) || EMBEDDING_BATCH_CHARS;
+        const maxBatchChars = EMBEDDING_BATCH_CHARS;
         const rawEmbeddings = [];
         let currentBatch = [];
         let currentBatchSize = 0;
@@ -12533,14 +12540,13 @@ class DocumentManagementService {
   normalizeVersion(version2) {
     return (version2 ?? "").toLowerCase();
   }
-  constructor(embeddingConfig, pipelineConfig) {
+  constructor(embeddingConfig, pipelineConfig, storePath) {
     let dbPath;
     let dbDir;
-    const envStorePath = process.env.DOCS_MCP_STORE_PATH;
-    if (envStorePath) {
-      dbDir = envStorePath;
+    if (storePath) {
+      dbDir = storePath;
       dbPath = path.join(dbDir, "documents.db");
-      logger.debug(`Using database directory from DOCS_MCP_STORE_PATH: ${dbDir}`);
+      logger.debug(`Using database directory from storePath parameter: ${dbDir}`);
     } else {
       const projectRoot2 = getProjectRoot();
       const oldDbDir = path.join(projectRoot2, ".store");
@@ -12916,41 +12922,72 @@ async function createDocumentManagement(options = {}) {
     await client.initialize();
     return client;
   }
-  const service = new DocumentManagementService(options.embeddingConfig);
+  const service = new DocumentManagementService(
+    options.embeddingConfig,
+    void 0,
+    options.storePath
+  );
   await service.initialize();
   return service;
 }
-async function createLocalDocumentManagement(embeddingConfig) {
-  const service = new DocumentManagementService(embeddingConfig);
+async function createLocalDocumentManagement(embeddingConfig, storePath) {
+  const service = new DocumentManagementService(embeddingConfig, void 0, storePath);
   await service.initialize();
   return service;
 }
 function createDefaultAction(program) {
   return program.addOption(
-    new Option("--protocol <protocol>", "Protocol for MCP server").choices(["auto", "stdio", "http"]).default("auto")
+    new Option("--protocol <protocol>", "Protocol for MCP server").env("DOCS_MCP_PROTOCOL").default("auto").choices(["auto", "stdio", "http"])
   ).addOption(
-    new Option("--port <number>", "Port for the server").argParser((v) => {
+    new Option("--port <number>", "Port for the server").env("DOCS_MCP_PORT").env("PORT").default(CLI_DEFAULTS.HTTP_PORT.toString()).argParser((v) => {
       const n = Number(v);
       if (!Number.isInteger(n) || n < 1 || n > 65535) {
         throw new Error("Port must be an integer between 1 and 65535");
       }
       return String(n);
-    }).default(CLI_DEFAULTS.HTTP_PORT.toString())
+    })
+  ).addOption(
+    new Option("--host <host>", "Host to bind the server to").env("DOCS_MCP_HOST").env("HOST").default(CLI_DEFAULTS.HOST).argParser(validateHost)
   ).addOption(
-    new Option("--host <host>", "Host to bind the server to").argParser(validateHost).default(CLI_DEFAULTS.HOST)
+    new Option(
+      "--embedding-model <model>",
+      "Embedding model configuration (e.g., 'openai:text-embedding-3-small')"
+    ).env("DOCS_MCP_EMBEDDING_MODEL")
   ).option("--resume", "Resume interrupted jobs on startup", false).option("--no-resume", "Do not resume jobs on startup").option(
     "--read-only",
     "Run in read-only mode (only expose read tools, disable write/job tools)",
     false
-  ).option(
-    "--auth-enabled",
-    "Enable OAuth2/OIDC authentication for MCP endpoints",
-    false
-  ).option("--auth-issuer-url <url>", "Issuer/discovery URL for OAuth2/OIDC provider").option(
-    "--auth-audience <id>",
-    "JWT audience claim (identifies this protected resource)"
+  ).addOption(
+    new Option(
+      "--auth-enabled",
+      "Enable OAuth2/OIDC authentication for MCP endpoints"
+    ).env("DOCS_MCP_AUTH_ENABLED").argParser((value) => {
+      if (value === void 0) {
+        return process.env.DOCS_MCP_AUTH_ENABLED === "true" || process.env.DOCS_MCP_AUTH_ENABLED === "1";
+      }
+      return value;
+    }).default(false)
+  ).addOption(
+    new Option(
+      "--auth-issuer-url <url>",
+      "Issuer/discovery URL for OAuth2/OIDC provider"
+    ).env("DOCS_MCP_AUTH_ISSUER_URL")
+  ).addOption(
+    new Option(
+      "--auth-audience <id>",
+      "JWT audience claim (identifies this protected resource)"
+    ).env("DOCS_MCP_AUTH_AUDIENCE")
   ).action(
     async (options) => {
+      await analytics.track(TelemetryEvent.CLI_COMMAND, {
+        command: "default",
+        protocol: options.protocol,
+        port: options.port,
+        host: options.host,
+        resume: options.resume,
+        readOnly: options.readOnly,
+        authEnabled: !!options.authEnabled
+      });
       const resolvedProtocol = resolveProtocol(options.protocol);
       if (resolvedProtocol === "stdio") {
         setLogLevel(LogLevel.ERROR);
@@ -12967,9 +13004,13 @@ function createDefaultAction(program) {
         validateAuthConfig(authConfig);
         warnHttpUsage(authConfig, port);
       }
+      const globalOptions = program.parent?.opts() || {};
       ensurePlaywrightBrowsersInstalled();
-      const embeddingConfig = resolveEmbeddingContext();
-      const docService = await createLocalDocumentManagement(embeddingConfig);
+      const embeddingConfig = resolveEmbeddingContext(options.embeddingModel);
+      const docService = await createLocalDocumentManagement(
+        embeddingConfig,
+        globalOptions.storePath
+      );
       const pipelineOptions = {
         recoverJobs: options.resume || false,
         // Use --resume flag for job recovery
@@ -13021,6 +13062,13 @@ function createDefaultAction(program) {
   );
 }
 async function fetchUrlAction(url, options) {
+  await analytics.track(TelemetryEvent.CLI_COMMAND, {
+    command: "fetch-url",
+    url,
+    scrapeMode: options.scrapeMode,
+    followRedirects: options.followRedirects,
+    hasHeaders: options.header.length > 0
+  });
   const headers = parseHeaders(options.header);
   const fetchUrlTool = new FetchUrlTool(new HttpFetcher(), new FileFetcher());
   const content = await fetchUrlTool.execute({
@@ -13057,6 +13105,12 @@ function createFetchUrlCommand(program) {
   ).action(fetchUrlAction);
 }
 async function findVersionAction(library, options) {
+  await analytics.track(TelemetryEvent.CLI_COMMAND, {
+    command: "find-version",
+    library,
+    version: options.version,
+    useServerUrl: !!options.serverUrl
+  });
   const serverUrl = options.serverUrl;
   const docService = await createDocumentManagement({
     serverUrl,
@@ -13081,6 +13135,10 @@ function createFindVersionCommand(program) {
   ).action(findVersionAction);
 }
 async function listAction(options) {
+  await analytics.track(TelemetryEvent.CLI_COMMAND, {
+    command: "list",
+    useServerUrl: !!options.serverUrl
+  });
   const { serverUrl } = options;
   const docService = await createDocumentManagement({
     serverUrl,
@@ -13102,17 +13160,22 @@ function createListCommand(program) {
 }
 function createMcpCommand(program) {
   return program.command("mcp").description("Start MCP server only").addOption(
-    new Option("--protocol <protocol>", "Protocol for MCP server").choices(["auto", "stdio", "http"]).default(CLI_DEFAULTS.PROTOCOL)
+    new Option("--protocol <protocol>", "Protocol for MCP server").env("DOCS_MCP_PROTOCOL").default(CLI_DEFAULTS.PROTOCOL).choices(["auto", "stdio", "http"])
   ).addOption(
-    new Option("--port <number>", "Port for the MCP server").argParser((v) => {
+    new Option("--port <number>", "Port for the MCP server").env("DOCS_MCP_PORT").env("PORT").default(CLI_DEFAULTS.HTTP_PORT.toString()).argParser((v) => {
       const n = Number(v);
       if (!Number.isInteger(n) || n < 1 || n > 65535) {
         throw new Error("Port must be an integer between 1 and 65535");
       }
       return String(n);
-    }).default(CLI_DEFAULTS.HTTP_PORT.toString())
+    })
   ).addOption(
-    new Option("--host <host>", "Host to bind the MCP server to").argParser(validateHost).default(CLI_DEFAULTS.HOST)
+    new Option("--host <host>", "Host to bind the MCP server to").env("DOCS_MCP_HOST").env("HOST").default(CLI_DEFAULTS.HOST).argParser(validateHost)
+  ).addOption(
+    new Option(
+      "--embedding-model <model>",
+      "Embedding model configuration (e.g., 'openai:text-embedding-3-small')"
+    ).env("DOCS_MCP_EMBEDDING_MODEL")
   ).option(
     "--server-url <url>",
     "URL of external pipeline worker RPC (e.g., http://localhost:6280/api)"
@@ -13120,15 +13183,37 @@ function createMcpCommand(program) {
     "--read-only",
     "Run in read-only mode (only expose read tools, disable write/job tools)",
     false
-  ).option(
-    "--auth-enabled",
-    "Enable OAuth2/OIDC authentication for MCP endpoints",
-    false
-  ).option("--auth-issuer-url <url>", "Issuer/discovery URL for OAuth2/OIDC provider").option(
-    "--auth-audience <id>",
-    "JWT audience claim (identifies this protected resource)"
+  ).addOption(
+    new Option(
+      "--auth-enabled",
+      "Enable OAuth2/OIDC authentication for MCP endpoints"
+    ).env("DOCS_MCP_AUTH_ENABLED").argParser((value) => {
+      if (value === void 0) {
+        return process.env.DOCS_MCP_AUTH_ENABLED === "true" || process.env.DOCS_MCP_AUTH_ENABLED === "1";
+      }
+      return value;
+    }).default(false)
+  ).addOption(
+    new Option(
+      "--auth-issuer-url <url>",
+      "Issuer/discovery URL for OAuth2/OIDC provider"
+    ).env("DOCS_MCP_AUTH_ISSUER_URL")
+  ).addOption(
+    new Option(
+      "--auth-audience <id>",
+      "JWT audience claim (identifies this protected resource)"
+    ).env("DOCS_MCP_AUTH_AUDIENCE")
   ).action(
     async (cmdOptions) => {
+      await analytics.track(TelemetryEvent.CLI_COMMAND, {
+        command: "mcp",
+        protocol: cmdOptions.protocol,
+        port: cmdOptions.port,
+        host: cmdOptions.host,
+        useServerUrl: !!cmdOptions.serverUrl,
+        readOnly: cmdOptions.readOnly,
+        authEnabled: !!cmdOptions.authEnabled
+      });
       const port = validatePort(cmdOptions.port);
       const host = validateHost(cmdOptions.host);
       const serverUrl = cmdOptions.serverUrl;
@@ -13144,8 +13229,9 @@ function createMcpCommand(program) {
       if (authConfig) {
         validateAuthConfig(authConfig);
       }
+      const globalOptions = program.parent?.opts() || {};
       try {
-        const embeddingConfig = resolveEmbeddingContext();
+        const embeddingConfig = resolveEmbeddingContext(cmdOptions.embeddingModel);
         if (!serverUrl && !embeddingConfig) {
           logger.error(
             "❌ Embedding configuration is required for local mode. Configure an embedding provider with CLI options or environment variables."
@@ -13154,7 +13240,8 @@ function createMcpCommand(program) {
         }
         const docService = await createDocumentManagement({
           serverUrl,
-          embeddingConfig
+          embeddingConfig,
+          storePath: globalOptions.storePath
         });
         const pipelineOptions = {
           recoverJobs: false,
@@ -13216,6 +13303,12 @@ function createMcpCommand(program) {
   );
 }
 async function removeAction(library, options) {
+  await analytics.track(TelemetryEvent.CLI_COMMAND, {
+    command: "remove",
+    library,
+    version: options.version,
+    useServerUrl: !!options.serverUrl
+  });
   const serverUrl = options.serverUrl;
   const docService = await createDocumentManagement({
     serverUrl,
@@ -13244,9 +13337,26 @@ function createRemoveCommand(program) {
     "URL of external pipeline worker RPC (e.g., http://localhost:6280/api)"
   ).action(removeAction);
 }
-async function scrapeAction(library, url, options) {
+async function scrapeAction(library, url, options, command) {
+  await analytics.track(TelemetryEvent.CLI_COMMAND, {
+    command: "scrape",
+    library,
+    version: options.version,
+    url,
+    maxPages: Number.parseInt(options.maxPages, 10),
+    maxDepth: Number.parseInt(options.maxDepth, 10),
+    maxConcurrency: Number.parseInt(options.maxConcurrency, 10),
+    scope: options.scope,
+    scrapeMode: options.scrapeMode,
+    followRedirects: options.followRedirects,
+    hasHeaders: options.header.length > 0,
+    hasIncludePatterns: options.includePattern.length > 0,
+    hasExcludePatterns: options.excludePattern.length > 0,
+    useServerUrl: !!options.serverUrl
+  });
   const serverUrl = options.serverUrl;
-  const embeddingConfig = resolveEmbeddingContext();
+  const globalOptions = command?.parent?.opts() || {};
+  const embeddingConfig = resolveEmbeddingContext(options.embeddingModel);
   if (!serverUrl && !embeddingConfig) {
     throw new Error(
       "Embedding configuration is required for local scraping. Please set DOCS_MCP_EMBEDDING_MODEL environment variable or use --server-url for remote execution."
@@ -13254,7 +13364,8 @@ async function scrapeAction(library, url, options) {
   }
   const docService = await createDocumentManagement({
     serverUrl,
-    embeddingConfig
+    embeddingConfig,
+    storePath: globalOptions.storePath
   });
   let pipeline = null;
   try {
@@ -13356,14 +13467,28 @@ function createScrapeCommand(program) {
     "Custom HTTP header to send with each request (can be specified multiple times)",
     (val, prev = []) => prev.concat([val]),
     []
+  ).addOption(
+    new Option(
+      "--embedding-model <model>",
+      "Embedding model configuration (e.g., 'openai:text-embedding-3-small')"
+    ).env("DOCS_MCP_EMBEDDING_MODEL")
   ).option(
     "--server-url <url>",
     "URL of external pipeline worker RPC (e.g., http://localhost:6280/api)"
   ).action(scrapeAction);
 }
 async function searchAction(library, query, options) {
+  await analytics.track(TelemetryEvent.CLI_COMMAND, {
+    command: "search",
+    library,
+    version: options.version,
+    query,
+    limit: Number.parseInt(options.limit, 10),
+    exactMatch: options.exactMatch,
+    useServerUrl: !!options.serverUrl
+  });
   const serverUrl = options.serverUrl;
-  const embeddingConfig = resolveEmbeddingContext();
+  const embeddingConfig = resolveEmbeddingContext(options.embeddingModel);
   if (!serverUrl && !embeddingConfig) {
     throw new Error(
       "Embedding configuration is required for local search. Please set DOCS_MCP_EMBEDDING_MODEL environment variable or use --server-url for remote execution."
@@ -13393,139 +13518,185 @@ function createSearchCommand(program) {
   ).option(
     "-v, --version <string>",
     "Version of the library (optional, supports ranges)"
-  ).option("-l, --limit <number>", "Maximum number of results", "5").option("-e, --exact-match", "Only use exact version match (default: false)", false).option(
+  ).option("-l, --limit <number>", "Maximum number of results", "5").option("-e, --exact-match", "Only use exact version match (default: false)", false).addOption(
+    new Option(
+      "--embedding-model <model>",
+      "Embedding model configuration (e.g., 'openai:text-embedding-3-small')"
+    ).env("DOCS_MCP_EMBEDDING_MODEL")
+  ).option(
     "--server-url <url>",
     "URL of external pipeline worker RPC (e.g., http://localhost:6280/api)"
   ).action(searchAction);
 }
 function createWebCommand(program) {
   return program.command("web").description("Start web interface only").addOption(
-    new Option("--port <number>", "Port for the web interface").argParser((v) => {
+    new Option("--port <number>", "Port for the web interface").env("DOCS_MCP_WEB_PORT").env("DOCS_MCP_PORT").env("PORT").default(CLI_DEFAULTS.WEB_PORT.toString()).argParser((v) => {
       const n = Number(v);
       if (!Number.isInteger(n) || n < 1 || n > 65535) {
         throw new Error("Port must be an integer between 1 and 65535");
       }
       return String(n);
-    }).default(CLI_DEFAULTS.WEB_PORT.toString())
+    })
+  ).addOption(
+    new Option("--host <host>", "Host to bind the web interface to").env("DOCS_MCP_HOST").env("HOST").default(CLI_DEFAULTS.HOST).argParser(validateHost)
   ).addOption(
-    new Option("--host <host>", "Host to bind the web interface to").argParser(validateHost).default(CLI_DEFAULTS.HOST)
+    new Option(
+      "--embedding-model <model>",
+      "Embedding model configuration (e.g., 'openai:text-embedding-3-small')"
+    ).env("DOCS_MCP_EMBEDDING_MODEL")
   ).option(
     "--server-url <url>",
     "URL of external pipeline worker RPC (e.g., http://localhost:6280/api)"
-  ).action(async (cmdOptions) => {
-    const port = validatePort(cmdOptions.port);
-    const host = validateHost(cmdOptions.host);
-    const serverUrl = cmdOptions.serverUrl;
-    try {
-      const embeddingConfig = resolveEmbeddingContext();
-      if (!serverUrl && !embeddingConfig) {
-        logger.error(
-          "❌ Embedding configuration is required for local mode. Configure an embedding provider with CLI options or environment variables."
+  ).action(
+    async (cmdOptions) => {
+      await analytics.track(TelemetryEvent.CLI_COMMAND, {
+        command: "web",
+        port: cmdOptions.port,
+        host: cmdOptions.host,
+        useServerUrl: !!cmdOptions.serverUrl
+      });
+      const port = validatePort(cmdOptions.port);
+      const host = validateHost(cmdOptions.host);
+      const serverUrl = cmdOptions.serverUrl;
+      try {
+        const embeddingConfig = resolveEmbeddingContext(cmdOptions.embeddingModel);
+        if (!serverUrl && !embeddingConfig) {
+          logger.error(
+            "❌ Embedding configuration is required for local mode. Configure an embedding provider with CLI options or environment variables."
+          );
+          process.exit(1);
+        }
+        const docService = await createDocumentManagement({
+          serverUrl,
+          embeddingConfig
+        });
+        const pipelineOptions = {
+          recoverJobs: false,
+          // Web command doesn't support job recovery
+          serverUrl,
+          concurrency: 3
+        };
+        const pipeline = await createPipelineWithCallbacks(
+          serverUrl ? void 0 : docService,
+          pipelineOptions
         );
+        const config = createAppServerConfig({
+          enableWebInterface: true,
+          enableMcpServer: false,
+          enableApiServer: false,
+          enableWorker: !serverUrl,
+          port,
+          host,
+          externalWorkerUrl: serverUrl,
+          startupContext: {
+            cliCommand: "web"
+          }
+        });
+        logger.info(
+          `🚀 Starting web interface${serverUrl ? ` connecting to worker at ${serverUrl}` : ""}`
+        );
+        const appServer = await startAppServer(docService, pipeline, config);
+        registerGlobalServices({
+          appServer,
+          docService
+          // pipeline is owned by AppServer - don't register globally to avoid double shutdown
+        });
+        await new Promise(() => {
+        });
+      } catch (error) {
+        logger.error(`❌ Failed to start web interface: ${error}`);
         process.exit(1);
       }
-      const docService = await createDocumentManagement({
-        serverUrl,
-        embeddingConfig
-      });
-      const pipelineOptions = {
-        recoverJobs: false,
-        // Web command doesn't support job recovery
-        serverUrl,
-        concurrency: 3
-      };
-      const pipeline = await createPipelineWithCallbacks(
-        serverUrl ? void 0 : docService,
-        pipelineOptions
-      );
-      const config = createAppServerConfig({
-        enableWebInterface: true,
-        enableMcpServer: false,
-        enableApiServer: false,
-        enableWorker: !serverUrl,
-        port,
-        host,
-        externalWorkerUrl: serverUrl,
-        startupContext: {
-          cliCommand: "web"
-        }
-      });
-      logger.info(
-        `🚀 Starting web interface${serverUrl ? ` connecting to worker at ${serverUrl}` : ""}`
-      );
-      const appServer = await startAppServer(docService, pipeline, config);
-      registerGlobalServices({
-        appServer,
-        docService
-        // pipeline is owned by AppServer - don't register globally to avoid double shutdown
-      });
-      await new Promise(() => {
-      });
-    } catch (error) {
-      logger.error(`❌ Failed to start web interface: ${error}`);
-      process.exit(1);
     }
-  });
+  );
 }
 function createWorkerCommand(program) {
   return program.command("worker").description("Start external pipeline worker (HTTP API)").addOption(
-    new Option("--port <number>", "Port for worker API").argParser((v) => {
+    new Option("--port <number>", "Port for worker API").env("DOCS_MCP_PORT").env("PORT").default("8080").argParser((v) => {
       const n = Number(v);
       if (!Number.isInteger(n) || n < 1 || n > 65535) {
         throw new Error("Port must be an integer between 1 and 65535");
       }
       return String(n);
-    }).default("8080")
+    })
   ).addOption(
-    new Option("--host <host>", "Host to bind the worker API to").argParser(validateHost).default(CLI_DEFAULTS.HOST)
-  ).option("--resume", "Resume interrupted jobs on startup", true).option("--no-resume", "Do not resume jobs on startup").action(async (cmdOptions) => {
-    const port = validatePort(cmdOptions.port);
-    const host = validateHost(cmdOptions.host);
-    try {
-      logger.info(`🚀 Starting external pipeline worker on port ${port}`);
-      ensurePlaywrightBrowsersInstalled();
-      const embeddingConfig = resolveEmbeddingContext();
-      const docService = await createLocalDocumentManagement(embeddingConfig);
-      const pipelineOptions = {
-        recoverJobs: cmdOptions.resume,
-        // Use the resume option
-        concurrency: CLI_DEFAULTS.MAX_CONCURRENCY
-      };
-      const pipeline = await createPipelineWithCallbacks(docService, pipelineOptions);
-      const config = createAppServerConfig({
-        enableWebInterface: false,
-        enableMcpServer: false,
-        enableApiServer: true,
-        enableWorker: true,
-        port,
-        host,
-        startupContext: {
-          cliCommand: "worker"
-        }
-      });
-      const appServer = await startAppServer(docService, pipeline, config);
-      registerGlobalServices({
-        appServer,
-        docService
-        // pipeline is owned by AppServer - don't register globally to avoid double shutdown
-      });
-      await new Promise(() => {
+    new Option("--host <host>", "Host to bind the worker API to").env("DOCS_MCP_HOST").env("HOST").default(CLI_DEFAULTS.HOST).argParser(validateHost)
+  ).addOption(
+    new Option(
+      "--embedding-model <model>",
+      "Embedding model configuration (e.g., 'openai:text-embedding-3-small')"
+    ).env("DOCS_MCP_EMBEDDING_MODEL")
+  ).option("--resume", "Resume interrupted jobs on startup", true).option("--no-resume", "Do not resume jobs on startup").action(
+    async (cmdOptions) => {
+      await analytics.track(TelemetryEvent.CLI_COMMAND, {
+        command: "worker",
+        port: cmdOptions.port,
+        host: cmdOptions.host,
+        resume: cmdOptions.resume
       });
-    } catch (error) {
-      logger.error(`❌ Failed to start external pipeline worker: ${error}`);
-      process.exit(1);
+      const port = validatePort(cmdOptions.port);
+      const host = validateHost(cmdOptions.host);
+      try {
+        logger.info(`🚀 Starting external pipeline worker on port ${port}`);
+        ensurePlaywrightBrowsersInstalled();
+        const embeddingConfig = resolveEmbeddingContext(cmdOptions.embeddingModel);
+        const docService = await createLocalDocumentManagement(embeddingConfig);
+        const pipelineOptions = {
+          recoverJobs: cmdOptions.resume,
+          // Use the resume option
+          concurrency: CLI_DEFAULTS.MAX_CONCURRENCY
+        };
+        const pipeline = await createPipelineWithCallbacks(docService, pipelineOptions);
+        const config = createAppServerConfig({
+          enableWebInterface: false,
+          enableMcpServer: false,
+          enableApiServer: true,
+          enableWorker: true,
+          port,
+          host,
+          startupContext: {
+            cliCommand: "worker"
+          }
+        });
+        const appServer = await startAppServer(docService, pipeline, config);
+        registerGlobalServices({
+          appServer,
+          docService
+          // pipeline is owned by AppServer - don't register globally to avoid double shutdown
+        });
+        await new Promise(() => {
+        });
+      } catch (error) {
+        logger.error(`❌ Failed to start external pipeline worker: ${error}`);
+        process.exit(1);
+      }
     }
-  });
+  );
 }
 function createCliProgram() {
   const program = new Command();
   const commandStartTimes = /* @__PURE__ */ new Map();
   program.name("docs-mcp-server").description("Unified CLI, MCP Server, and Web Interface for Docs MCP Server.").version(packageJson.version).addOption(
     new Option("--verbose", "Enable verbose (debug) logging").conflicts("silent")
-  ).addOption(new Option("--silent", "Disable all logging except errors")).addOption(new Option("--no-telemetry", "Disable telemetry collection")).enablePositionalOptions().allowExcessArguments(false).showHelpAfterError(true);
+  ).addOption(new Option("--silent", "Disable all logging except errors")).addOption(
+    new Option("--telemetry", "Enable telemetry collection").env("DOCS_MCP_TELEMETRY").argParser((value) => {
+      if (value === void 0) {
+        return process.env.DOCS_MCP_TELEMETRY !== "false" && process.env.DOCS_MCP_TELEMETRY !== "0";
+      }
+      return value;
+    }).default(true)
+  ).addOption(new Option("--no-telemetry", "Disable telemetry collection")).addOption(
+    new Option("--store-path <path>", "Custom path for data storage directory").env(
+      "DOCS_MCP_STORE_PATH"
+    )
+  ).enablePositionalOptions().allowExcessArguments(false).showHelpAfterError(true);
   program.hook("preAction", async (thisCommand, actionCommand) => {
     const globalOptions = thisCommand.opts();
     setupLogging(globalOptions);
+    initTelemetry({
+      enabled: globalOptions.telemetry ?? true,
+      storePath: globalOptions.storePath
+    });
     if (shouldEnableTelemetry()) {
       if (analytics.isEnabled()) {
         analytics.setGlobalContext({
@@ -13539,8 +13710,6 @@ function createCliProgram() {
         commandStartTimes.set(commandKey, Date.now());
         actionCommand._trackingKey = commandKey;
       }
-    } else {
-      TelemetryConfig.getInstance().disable();
     }
   });
   program.hook("postAction", async (_thisCommand, actionCommand) => {