@arabold/docs-mcp-server 1.36.0 → 2.0.0

package/dist/index.js

@@ -64,11 +64,12 @@ import { escapeHtml } from "@kitajs/html";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { v4 } from "uuid";
 import { minimatch } from "minimatch";
+import { exec, execSync } from "node:child_process";
+import { promisify } from "node:util";
 import { Readable } from "node:stream";
 import * as tar from "tar";
 import yauzl from "yauzl";
 import os from "node:os";
-import { execSync } from "node:child_process";
 class StoreError extends Error {
   constructor(message, cause) {
     super(cause ? `${message} caused by ${cause}` : message);
@@ -919,6 +920,10 @@ const DEFAULT_CONFIG = {
       baseDelayMs: 1e3,
       maxCacheItems: 200,
       maxCacheItemSizeBytes: 500 * 1024
+    },
+    document: {
+      maxSize: 10 * 1024 * 1024
+      // 10MB max size for PDF/Office documents
     }
   },
   splitter: {
@@ -957,10 +962,6 @@ const DEFAULT_CONFIG = {
     precedingSiblingsLimit: 1,
     subsequentSiblingsLimit: 2,
     maxChunkDistance: 3
-  },
-  document: {
-    maxSize: 10 * 1024 * 1024
-    // 10MB max size for PDF/Office documents
   }
 };
 const AppConfigSchema = z.object({
@@ -997,7 +998,10 @@ const AppConfigSchema = z.object({
       baseDelayMs: z.coerce.number().int().default(DEFAULT_CONFIG.scraper.fetcher.baseDelayMs),
       maxCacheItems: z.coerce.number().int().default(DEFAULT_CONFIG.scraper.fetcher.maxCacheItems),
       maxCacheItemSizeBytes: z.coerce.number().int().default(DEFAULT_CONFIG.scraper.fetcher.maxCacheItemSizeBytes)
-    }).default(DEFAULT_CONFIG.scraper.fetcher)
+    }).default(DEFAULT_CONFIG.scraper.fetcher),
+    document: z.object({
+      maxSize: z.coerce.number().int().default(DEFAULT_CONFIG.scraper.document.maxSize)
+    }).default(DEFAULT_CONFIG.scraper.document)
   }).default(DEFAULT_CONFIG.scraper),
   splitter: z.object({
     minChunkSize: z.coerce.number().int().default(DEFAULT_CONFIG.splitter.minChunkSize),
@@ -1035,10 +1039,7 @@ const AppConfigSchema = z.object({
     precedingSiblingsLimit: z.coerce.number().int().default(DEFAULT_CONFIG.assembly.precedingSiblingsLimit),
     subsequentSiblingsLimit: z.coerce.number().int().default(DEFAULT_CONFIG.assembly.subsequentSiblingsLimit),
     maxChunkDistance: z.coerce.number().int().min(0).default(DEFAULT_CONFIG.assembly.maxChunkDistance)
-  }).default(DEFAULT_CONFIG.assembly),
-  document: z.object({
-    maxSize: z.coerce.number().int().default(DEFAULT_CONFIG.document.maxSize)
-  }).default(DEFAULT_CONFIG.document)
+  }).default(DEFAULT_CONFIG.assembly)
 });
 const defaults = AppConfigSchema.parse({});
 const configMappings = [
@@ -1159,6 +1160,12 @@ function mapEnvToConfig() {
       }
     }
   }
+  for (const pathArr of ALL_CONFIG_LEAF_PATHS) {
+    const envVar = pathToEnvVar(pathArr);
+    if (process.env[envVar] !== void 0) {
+      setAtPath(config, pathArr, process.env[envVar]);
+    }
+  }
   return config;
 }
 function mapCliToConfig(args) {
@@ -1170,6 +1177,25 @@ function mapCliToConfig(args) {
   }
   return config;
 }
+function camelToUpperSnake(str) {
+  return str.replace(/([a-z])([A-Z])/g, "$1_$2").toUpperCase();
+}
+function pathToEnvVar(pathArr) {
+  return `DOCS_MCP_${pathArr.map(camelToUpperSnake).join("_")}`;
+}
+function collectLeafPaths(obj, prefix = []) {
+  const paths = [];
+  for (const [key, value] of Object.entries(obj)) {
+    const currentPath = [...prefix, key];
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      paths.push(...collectLeafPaths(value, currentPath));
+    } else {
+      paths.push(currentPath);
+    }
+  }
+  return paths;
+}
+const ALL_CONFIG_LEAF_PATHS = collectLeafPaths(DEFAULT_CONFIG);
 function setAtPath(obj, pathArr, value) {
   let current = obj;
   for (let i = 0; i < pathArr.length - 1; i++) {
@@ -1206,17 +1232,168 @@ function deepMerge(target, source) {
   }
   return output;
 }
+function isValidConfigPath(path2) {
+  const pathArr = path2.split(".");
+  return getAtPath(DEFAULT_CONFIG, pathArr) !== void 0;
+}
+function getConfigValue(config, path2) {
+  const pathArr = path2.split(".");
+  return getAtPath(config, pathArr);
+}
+function parseConfigValue(value) {
+  const num = Number(value);
+  if (!Number.isNaN(num) && value.trim() !== "") {
+    return num;
+  }
+  const lower = value.toLowerCase();
+  if (lower === "true") return true;
+  if (lower === "false") return false;
+  return value;
+}
+function setConfigValue(path2, value) {
+  const configPath = getDefaultConfigPath();
+  const fileConfig = loadConfigFile(configPath) || {};
+  const pathArr = path2.split(".");
+  const parsedValue = parseConfigValue(value);
+  const updatedConfig = JSON.parse(JSON.stringify(fileConfig));
+  setAtPath(updatedConfig, pathArr, parsedValue);
+  try {
+    AppConfigSchema.parse(updatedConfig);
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Invalid config value for "${path2}": ${errorMsg}`);
+  }
+  saveConfigFile(configPath, updatedConfig);
+  return configPath;
+}
+function getDefaultConfigPath() {
+  return path.join(systemPaths.config, "config.yaml");
+}
+function formatOutput$1(value, format) {
+  if (format === "auto") {
+    if (typeof value === "object" && value !== null) {
+      return JSON.stringify(value, null, 2);
+    }
+    return String(value);
+  }
+  if (format === "yaml") {
+    return yaml.stringify(value).trim();
+  }
+  return JSON.stringify(value, null, 2);
+}
 function createConfigCommand(cli) {
   cli.command(
     "config",
-    "Fetch a URL and transform it into Markdown format",
-    (yargs2) => yargs2,
+    "View or modify configuration",
+    (yargs2) => {
+      return yargs2.option("json", {
+        type: "boolean",
+        description: "Output in JSON format",
+        conflicts: "yaml"
+      }).option("yaml", {
+        type: "boolean",
+        description: "Output in YAML format",
+        conflicts: "json"
+      }).command(
+        "get <path>",
+        "Get a configuration value",
+        (y) => y.positional("path", {
+          type: "string",
+          description: "Dot-separated config path (e.g., scraper.maxPages)",
+          demandOption: true
+        }).option("json", {
+          type: "boolean",
+          description: "Output in JSON format",
+          conflicts: "yaml"
+        }).option("yaml", {
+          type: "boolean",
+          description: "Output in YAML format",
+          conflicts: "json"
+        }),
+        (argv) => {
+          const path2 = argv.path;
+          if (!isValidConfigPath(path2)) {
+            console.error(`Error: Invalid config path '${path2}'`);
+            console.error("Use 'docs-mcp-server config' to see all available paths.");
+            process.exitCode = 1;
+            return;
+          }
+          const config = loadConfig(argv, {
+            configPath: argv.config,
+            searchDir: argv.storePath
+          });
+          const value = getConfigValue(config, path2);
+          const format = argv.json ? "json" : argv.yaml ? "yaml" : "auto";
+          console.log(formatOutput$1(value, format));
+        }
+      ).command(
+        "set <path> <value>",
+        "Set a configuration value",
+        (y) => y.positional("path", {
+          type: "string",
+          description: "Dot-separated config path (e.g., scraper.maxPages)",
+          demandOption: true
+        }).positional("value", {
+          type: "string",
+          description: "Value to set",
+          demandOption: true
+        }),
+        (argv) => {
+          const configPath = argv.config;
+          const path2 = argv.path;
+          const value = argv.value;
+          if (configPath) {
+            console.error(
+              "Error: Cannot modify configuration when using explicit --config file."
+            );
+            console.error(
+              "Remove the --config flag to modify the default configuration."
+            );
+            process.exitCode = 1;
+            return;
+          }
+          if (!isValidConfigPath(path2)) {
+            console.error(`Error: Invalid config path '${path2}'`);
+            console.error("Use 'docs-mcp-server config' to see all available paths.");
+            process.exitCode = 1;
+            return;
+          }
+          const config = loadConfig(argv, {
+            configPath: argv.config,
+            searchDir: argv.storePath
+          });
+          const currentValue = getConfigValue(config, path2);
+          if (currentValue !== void 0 && currentValue !== null && typeof currentValue === "object" && !Array.isArray(currentValue)) {
+            console.error(
+              `Error: Config path '${path2}' refers to an object. Use a more specific leaf path to set a scalar value.`
+            );
+            console.error(
+              "Hint: Run 'docs-mcp-server config' to inspect the current structure."
+            );
+            process.exitCode = 1;
+            return;
+          }
+          try {
+            const savedPath = setConfigValue(path2, value);
+            const parsedValue = parseConfigValue(value);
+            console.log(`Updated ${path2} = ${JSON.stringify(parsedValue)}`);
+            console.log(`Saved to: ${savedPath}`);
+          } catch (error) {
+            console.error(
+              `Error: Failed to save configuration: ${error instanceof Error ? error.message : String(error)}`
+            );
+            process.exitCode = 1;
+          }
+        }
+      );
+    },
     (argv) => {
       const config = loadConfig(argv, {
         configPath: argv.config,
         searchDir: argv.storePath
       });
-      console.log(JSON.stringify(config, null, 2));
+      const format = argv.json ? "json" : argv.yaml ? "yaml" : "json";
+      console.log(formatOutput$1(config, format));
     }
   );
 }
@@ -2443,42 +2620,135 @@ class MimeTypeUtils {
   static detectMimeTypeFromPath(filePath) {
     const extension = filePath.toLowerCase().split(".").pop();
     const customMimeTypes = {
+      // JavaScript/TypeScript family
       ts: "text/x-typescript",
       tsx: "text/x-tsx",
+      mts: "text/x-typescript",
+      // TypeScript ES modules
+      cts: "text/x-typescript",
+      // TypeScript CommonJS modules
       js: "text/javascript",
       jsx: "text/x-jsx",
       cjs: "text/javascript",
       // CommonJS modules
       mjs: "text/javascript",
       // ES modules
+      // Python family
       py: "text/x-python",
       pyw: "text/x-python",
       pyi: "text/x-python",
+      pyx: "text/x-cython",
+      // Cython
+      pxd: "text/x-cython",
+      // Cython
+      // Systems languages
       go: "text/x-go",
       rs: "text/x-rust",
+      c: "text/x-csrc",
+      h: "text/x-chdr",
+      cpp: "text/x-c++src",
+      cxx: "text/x-c++src",
+      cc: "text/x-c++src",
+      hpp: "text/x-c++hdr",
+      hxx: "text/x-c++hdr",
+      zig: "text/x-zig",
+      nim: "text/x-nim",
+      v: "text/x-v",
+      cr: "text/x-crystal",
+      // JVM languages
       kt: "text/x-kotlin",
+      kts: "text/x-kotlin",
+      // Kotlin script
       scala: "text/x-scala",
+      groovy: "text/x-groovy",
+      gradle: "text/x-gradle",
+      // Apple/Mobile
       swift: "text/x-swift",
+      dart: "text/x-dart",
+      // Scripting languages
       rb: "text/x-ruby",
+      rake: "text/x-ruby",
+      // Rakefile
       php: "text/x-php",
+      lua: "text/x-lua",
+      pl: "text/x-perl",
+      pm: "text/x-perl",
+      r: "text/x-r",
+      // Also handles .R since extension is lowercased
+      // Functional languages
+      hs: "text/x-haskell",
+      lhs: "text/x-haskell",
+      // Literate Haskell
+      elm: "text/x-elm",
+      erl: "text/x-erlang",
+      ex: "text/x-elixir",
+      exs: "text/x-elixir",
+      clj: "text/x-clojure",
+      cljs: "text/x-clojure",
+      cljc: "text/x-clojure",
+      jl: "text/x-julia",
+      // .NET
       cs: "text/x-csharp",
-      cpp: "text/x-c++src",
-      cxx: "text/x-c++src",
-      cc: "text/x-c++src",
-      hpp: "text/x-c++hdr",
-      hxx: "text/x-c++hdr",
-      h: "text/x-chdr",
-      c: "text/x-csrc",
+      // Web3/Smart contracts
+      sol: "text/x-solidity",
+      move: "text/x-move",
+      cairo: "text/x-cairo",
+      // Modern web frameworks
+      vue: "text/x-vue",
+      svelte: "text/x-svelte",
+      astro: "text/x-astro",
+      // Shell scripting
       sh: "text/x-shellscript",
       bash: "text/x-shellscript",
       zsh: "text/x-shellscript",
       fish: "text/x-shellscript",
       ps1: "text/x-powershell",
+      // Documentation formats
+      rst: "text/x-rst",
+      // reStructuredText
+      adoc: "text/x-asciidoc",
+      asciidoc: "text/x-asciidoc",
+      textile: "text/x-textile",
+      org: "text/x-org",
+      // Org-mode
+      pod: "text/x-pod",
+      // Perl documentation
+      rdoc: "text/x-rdoc",
+      // Ruby documentation
+      wiki: "text/x-wiki",
+      rmd: "text/x-rmarkdown",
+      // R Markdown
+      // Configuration files
+      toml: "text/x-toml",
+      ini: "text/x-ini",
+      cfg: "text/x-ini",
+      conf: "text/x-conf",
+      properties: "text/x-properties",
+      env: "text/x-dotenv",
+      // Build systems
+      dockerfile: "text/x-dockerfile",
+      containerfile: "text/x-dockerfile",
+      makefile: "text/x-makefile",
+      cmake: "text/x-cmake",
+      bazel: "text/x-bazel",
+      bzl: "text/x-bazel",
+      buck: "text/x-buck",
+      // Infrastructure as Code
+      tf: "text/x-terraform",
+      tfvars: "text/x-terraform",
+      hcl: "text/x-hcl",
+      // Data/Query languages
       sql: "text/x-sql",
       graphql: "text/x-graphql",
       gql: "text/x-graphql",
+      // Schema/API definitions
       proto: "text/x-proto",
-      dockerfile: "text/x-dockerfile"
+      prisma: "text/x-prisma",
+      thrift: "text/x-thrift",
+      avro: "text/x-avro",
+      // TeX/LaTeX
+      tex: "text/x-tex",
+      latex: "text/x-latex"
     };
     if (extension && customMimeTypes[extension]) {
       return customMimeTypes[extension];
@@ -2498,8 +2768,24 @@ class MimeTypeUtils {
       return null;
     }
     const mimeTypeNormalization = {
-      "application/node": "text/javascript"
-      // .cjs files are detected as this
+      "application/node": "text/javascript",
+      // .cjs files
+      "video/mp2t": "text/x-typescript",
+      // .ts/.mts files (MPEG-2 transport stream conflict)
+      "application/rls-services+xml": "text/x-rust",
+      // .rs files
+      "application/vnd.lotus-organizer": "text/x-org",
+      // .org files (Lotus Organizer conflict)
+      "application/vnd.dart": "text/x-dart",
+      // .dart files
+      "application/x-perl": "text/x-perl",
+      // .pl/.pm files
+      "application/x-tex": "text/x-tex",
+      // .tex files
+      "application/x-latex": "text/x-latex",
+      // .latex files
+      "application/toml": "text/x-toml"
+      // .toml files
     };
     return mimeTypeNormalization[mimeType] || mimeType;
   }
@@ -2511,6 +2797,7 @@ class MimeTypeUtils {
    */
   static extractLanguageFromMimeType(mimeType) {
     const mimeToLanguage = {
+      // JavaScript/TypeScript
       "text/x-typescript": "typescript",
       "text/typescript": "typescript",
       "application/typescript": "typescript",
@@ -2519,22 +2806,84 @@ class MimeTypeUtils {
       "application/javascript": "javascript",
       "application/x-javascript": "javascript",
       "text/x-jsx": "jsx",
+      // Python
       "text/x-python": "python",
-      "text/x-java": "java",
+      "text/x-cython": "cython",
+      // Systems languages
       "text/x-c": "c",
       "text/x-csrc": "c",
       "text/x-chdr": "c",
       "text/x-c++": "cpp",
       "text/x-c++src": "cpp",
       "text/x-c++hdr": "cpp",
-      "text/x-csharp": "csharp",
       "text/x-go": "go",
       "text/x-rust": "rust",
-      "text/x-php": "php",
-      "text/x-ruby": "ruby",
-      "text/x-swift": "swift",
+      "text/x-zig": "zig",
+      "text/x-nim": "nim",
+      "text/x-v": "v",
+      "text/x-crystal": "crystal",
+      // JVM languages
+      "text/x-java": "java",
       "text/x-kotlin": "kotlin",
       "text/x-scala": "scala",
+      "text/x-groovy": "groovy",
+      "text/x-gradle": "groovy",
+      // Apple/Mobile
+      "text/x-swift": "swift",
+      "text/x-dart": "dart",
+      // .NET
+      "text/x-csharp": "csharp",
+      // Scripting languages
+      "text/x-ruby": "ruby",
+      "text/x-php": "php",
+      "text/x-lua": "lua",
+      "text/x-perl": "perl",
+      "text/x-r": "r",
+      // Functional languages
+      "text/x-haskell": "haskell",
+      "text/x-elm": "elm",
+      "text/x-erlang": "erlang",
+      "text/x-elixir": "elixir",
+      "text/x-clojure": "clojure",
+      "text/x-julia": "julia",
+      // Web3/Smart contracts
+      "text/x-solidity": "solidity",
+      "text/x-move": "move",
+      "text/x-cairo": "cairo",
+      // Modern web frameworks
+      "text/x-vue": "vue",
+      "text/x-svelte": "svelte",
+      "text/x-astro": "astro",
+      // Shell
+      "text/x-sh": "bash",
+      "text/x-shellscript": "bash",
+      "application/x-sh": "bash",
+      "text/x-powershell": "powershell",
+      // Documentation formats
+      "text/x-rst": "rst",
+      "text/x-asciidoc": "asciidoc",
+      "text/x-textile": "textile",
+      "text/x-org": "org",
+      "text/x-pod": "pod",
+      "text/x-rdoc": "rdoc",
+      "text/x-wiki": "wiki",
+      "text/x-rmarkdown": "rmarkdown",
+      // Configuration files
+      "text/x-toml": "toml",
+      "text/x-ini": "ini",
+      "text/x-conf": "conf",
+      "text/x-properties": "properties",
+      "text/x-dotenv": "dotenv",
+      // Build systems
+      "text/x-dockerfile": "dockerfile",
+      "text/x-makefile": "makefile",
+      "text/x-cmake": "cmake",
+      "text/x-bazel": "bazel",
+      "text/x-buck": "buck",
+      // Infrastructure as Code
+      "text/x-terraform": "hcl",
+      "text/x-hcl": "hcl",
+      // Data formats
       "text/x-yaml": "yaml",
       "application/x-yaml": "yaml",
       "application/yaml": "yaml",
@@ -2544,13 +2893,15 @@ class MimeTypeUtils {
       "text/xml": "xml",
       "application/xml": "xml",
       "text/x-sql": "sql",
-      "text/x-sh": "bash",
-      "text/x-shellscript": "bash",
-      "application/x-sh": "bash",
-      "text/x-powershell": "powershell",
       "text/x-graphql": "graphql",
+      // Schema/API definitions
       "text/x-proto": "protobuf",
-      "text/x-dockerfile": "dockerfile"
+      "text/x-prisma": "prisma",
+      "text/x-thrift": "thrift",
+      "text/x-avro": "avro",
+      // TeX/LaTeX
+      "text/x-tex": "tex",
+      "text/x-latex": "latex"
     };
     return mimeToLanguage[mimeType] || "";
   }
@@ -2672,22 +3023,29 @@ class BrowserFetcher {
     }
   }
   /**
-   * Close the browser and clean up resources
+   * Close the browser and clean up resources.
+   * Always attempts cleanup even if browser is disconnected to reap zombie processes.
    */
   async close() {
-    try {
-      if (this.page) {
+    if (this.page) {
+      try {
         await this.page.close();
+      } catch (error) {
+        logger.warn(`⚠️  Error closing browser page: ${error}`);
+      } finally {
         this.page = null;
       }
-      if (this.browser) {
+    }
+    if (this.browser) {
+      try {
         await this.browser.close();
+      } catch (error) {
+        logger.warn(`⚠️  Error closing browser: ${error}`);
+      } finally {
         this.browser = null;
       }
-      logger.debug("Browser closed successfully");
-    } catch (error) {
-      logger.warn(`⚠️  Error closing browser: ${error}`);
     }
+    logger.debug("Browser closed successfully");
   }
 }
 class FileFetcher {
@@ -4019,7 +4377,7 @@ class DocumentPipeline extends BasePipeline {
   constructor(config) {
     super();
     this.markitdown = new MarkItDown();
-    this.maxSize = config.document.maxSize;
+    this.maxSize = config.scraper.document.maxSize;
     const semanticSplitter = new SemanticMarkdownSplitter(
       config.splitter.preferredChunkSize,
       config.splitter.maxChunkSize
@@ -4505,12 +4863,18 @@ class HtmlPlaywrightMiddleware {
   /**
    * Closes the Playwright browser instance if it exists.
    * Should be called during application shutdown.
+   * Attempts to close even if the browser is disconnected to ensure proper cleanup of zombie processes.
    */
   async closeBrowser() {
-    if (this.browser?.isConnected()) {
-      logger.debug("Closing Playwright browser instance...");
-      await this.browser.close();
-      this.browser = null;
+    if (this.browser) {
+      try {
+        logger.debug("Closing Playwright browser instance...");
+        await this.browser.close();
+      } catch (error) {
+        logger.warn(`⚠️  Error closing Playwright browser: ${error}`);
+      } finally {
+        this.browser = null;
+      }
     }
   }
   /**
@@ -5615,10 +5979,15 @@ class HtmlPipeline extends BasePipeline {
   }
   /**
    * Cleanup resources used by this pipeline, specifically the Playwright browser instance.
+   * Errors during cleanup are logged but not propagated to ensure graceful shutdown.
    */
   async close() {
     await super.close();
-    await this.playwrightMiddleware.closeBrowser();
+    try {
+      await this.playwrightMiddleware.closeBrowser();
+    } catch (error) {
+      logger.warn(`⚠️  Error during browser cleanup: ${error}`);
+    }
   }
 }
 class TextDocumentSplitter {
@@ -6643,6 +7012,11 @@ class TypeScriptParser {
     ".cjs"
   ];
   mimeTypes = [
+    // text/x-* variants (output by MimeTypeUtils.detectMimeTypeFromPath)
+    "text/x-typescript",
+    "text/x-tsx",
+    "text/x-jsx",
+    // Standard variants
     "text/typescript",
     "application/typescript",
     "text/tsx",
@@ -6984,6 +7358,8 @@ class LanguageParserRegistry {
       // Narrow advertised extensions/mime types for the alias (informational only).
       fileExtensions: [".js", ".jsx", ".mjs", ".cjs"],
       mimeTypes: [
+        "text/x-jsx",
+        // Output by MimeTypeUtils.detectMimeTypeFromPath
         "text/javascript",
         "application/javascript",
         "text/jsx",
@@ -6996,6 +7372,8 @@ class LanguageParserRegistry {
       this.extensionMap.set(ext.toLowerCase(), "javascript");
     }
     const jsMimes = [
+      "text/x-jsx",
+      // Output by MimeTypeUtils.detectMimeTypeFromPath
       "text/javascript",
       "application/javascript",
       "text/jsx",
@@ -10897,6 +11275,7 @@ async function registerMcpService(server, docService, pipeline, config, authMana
   const mcpServer = createMcpServerInstance(mcpTools, config);
   const authMiddleware = authManager ? createAuthMiddleware(authManager) : null;
   const sseTransports = {};
+  const sseServers = {};
   const heartbeatIntervals = {};
   server.route({
     method: "GET",
@@ -10906,6 +11285,8 @@ async function registerMcpService(server, docService, pipeline, config, authMana
       try {
         const transport = new SSEServerTransport("/messages", reply.raw);
         sseTransports[transport.sessionId] = transport;
+        const sessionServer = createMcpServerInstance(mcpTools, config);
+        sseServers[transport.sessionId] = sessionServer;
         if (telemetry.isEnabled()) {
           logger.info(`🔗 MCP client connected: ${transport.sessionId}`);
         }
@@ -10924,6 +11305,13 @@ async function registerMcpService(server, docService, pipeline, config, authMana
             clearInterval(interval);
             delete heartbeatIntervals[transport.sessionId];
           }
+          const serverToClose = sseServers[transport.sessionId];
+          if (serverToClose) {
+            delete sseServers[transport.sessionId];
+            void serverToClose.close().catch((error) => {
+              logger.error(`❌ Failed to close SSE server instance: ${error}`);
+            });
+          }
           delete sseTransports[transport.sessionId];
           transport.close();
           if (telemetry.isEnabled()) {
@@ -10935,7 +11323,7 @@ async function registerMcpService(server, docService, pipeline, config, authMana
           logger.debug(`SSE connection error: ${error}`);
           cleanupConnection();
         });
-        await mcpServer.connect(transport);
+        await sessionServer.connect(transport);
       } catch (error) {
         logger.error(`❌ Error in SSE endpoint: ${error}`);
         reply.code(500).send({
@@ -10995,7 +11383,16 @@ async function registerMcpService(server, docService, pipeline, config, authMana
       }
     }
   });
+  server.route({
+    method: "GET",
+    url: "/mcp",
+    preHandler: authMiddleware ? [authMiddleware] : void 0,
+    handler: async (_request, reply) => {
+      reply.code(405).header("Allow", "POST").send();
+    }
+  });
   mcpServer._sseTransports = sseTransports;
+  mcpServer._sseServers = sseServers;
   mcpServer._heartbeatIntervals = heartbeatIntervals;
   return mcpServer;
 }
@@ -11013,6 +11410,12 @@ async function cleanupMcpService(mcpServer) {
         await transport.close();
       }
     }
+    const sseServers = mcpServer._sseServers;
+    if (sseServers) {
+      for (const server of Object.values(sseServers)) {
+        await server.close();
+      }
+    }
     await mcpServer.close();
     logger.debug("MCP service cleaned up");
   } catch (error) {
@@ -11610,7 +12013,7 @@ const Layout = ({
   children,
   eventClientConfig
 }) => {
-  const versionString = version || "1.36.0";
+  const versionString = version || "2.0.0";
   const versionInitializer = `versionUpdate({ currentVersion: ${`'${versionString}'`} })`;
   return /* @__PURE__ */ jsxs("html", { lang: "en", children: [
     /* @__PURE__ */ jsxs("head", { children: [
@@ -13903,6 +14306,15 @@ async function stopWorkerService(pipeline) {
   await pipeline.stop();
   logger.debug("Worker service stopped");
 }
+const BANNER = [
+  "\x1B[90m  █▀▀ █▀█ █▀█ █ █ █▄ █ █▀▄ █▀▀ █▀▄   █▀▄ █▀█ █▀▀ █▀▀\x1B[0m",
+  "\x1B[97m  █▄█ █▀▄ █▄█ █▄█ █ ▀█ █▄▀ ██▄ █▄▀   █▄▀ █▄█ █▄▄ ▄▄█\x1B[0m"
+].join("\n");
+function printBanner() {
+  console.log();
+  console.log(BANNER);
+  console.log();
+}
 class AppServer {
   constructor(docService, pipeline, eventBus, serverConfig, appConfig) {
     this.docService = docService;
@@ -13951,7 +14363,7 @@ class AppServer {
       try {
         if (telemetry.isEnabled()) {
           telemetry.setGlobalContext({
-            appVersion: "1.36.0",
+            appVersion: "2.0.0",
             appPlatform: process.platform,
             appNodeVersion: process.version,
             appServicesEnabled: this.getActiveServicesList(),
@@ -14280,6 +14692,9 @@ class AppServer {
    * Log startup information showing which services are enabled.
    */
   logStartupInfo(address) {
+    if (this.serverConfig.showLogo !== false) {
+      printBanner();
+    }
     const isWorkerOnly = this.serverConfig.enableWorker && !this.serverConfig.enableWebInterface && !this.serverConfig.enableMcpServer;
     const isWebOnly = this.serverConfig.enableWebInterface && !this.serverConfig.enableWorker && !this.serverConfig.enableMcpServer;
     const isMcpOnly = this.serverConfig.enableMcpServer && !this.serverConfig.enableWebInterface && !this.serverConfig.enableWorker;
@@ -14691,6 +15106,9 @@ class BaseScraperStrategy {
             return null;
           }).filter((item2) => item2 !== null);
         } catch (error) {
+          if (item.depth === 0) {
+            throw error;
+          }
           if (options.ignoreErrors) {
             logger.error(`❌ Failed to process ${item.url}: ${error}`);
             return [];
@@ -14805,10 +15223,10 @@ class GitHubRepoProcessor {
   /**
    * Fetches the raw content of a file from GitHub.
    */
-  async fetchFileContent(repoInfo, filePath, etag, signal) {
+  async fetchFileContent(repoInfo, filePath, etag, headers, signal) {
     const { owner, repo, branch } = repoInfo;
     const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${filePath}`;
-    const rawContent = await this.httpFetcher.fetch(rawUrl, { signal, etag });
+    const rawContent = await this.httpFetcher.fetch(rawUrl, { signal, etag, headers });
     const detectedMimeType = MimeTypeUtils.detectMimeTypeFromPath(filePath);
     if (detectedMimeType && (rawContent.mimeType === "text/plain" || rawContent.mimeType === "application/octet-stream")) {
       return {
@@ -14821,13 +15239,14 @@ class GitHubRepoProcessor {
   /**
    * Processes a single GitHub repository file from an HTTPS blob URL.
    */
-  async process(item, options, signal) {
+  async process(item, options, headers, signal) {
     const repoInfo = this.parseHttpsBlobUrl(item.url);
     const { owner, repo, branch, filePath } = repoInfo;
     const rawContent = await this.fetchFileContent(
       { owner, repo, branch },
       filePath,
       item.etag,
+      headers,
       signal
     );
     if (rawContent.status !== FetchStatus.SUCCESS) {
@@ -14918,12 +15337,13 @@ class GitHubWikiProcessor {
   /**
    * Processes a single GitHub wiki page.
    */
-  async process(item, options, signal) {
+  async process(item, options, headers, signal) {
     const currentUrl = item.url;
     try {
       const rawContent = await this.httpFetcher.fetch(currentUrl, {
         signal,
-        etag: item.etag
+        etag: item.etag,
+        headers
       });
       if (rawContent.status !== FetchStatus.SUCCESS) {
         return { url: currentUrl, links: [], status: rawContent.status };
@@ -14994,10 +15414,52 @@ class GitHubWikiProcessor {
     await Promise.allSettled(this.pipelines.map((pipeline) => pipeline.close()));
   }
 }
+const execAsync = promisify(exec);
+async function resolveGitHubAuth(explicitHeaders) {
+  if (explicitHeaders) {
+    const hasAuthHeader = Object.keys(explicitHeaders).some(
+      (key) => key.toLowerCase() === "authorization"
+    );
+    if (hasAuthHeader) {
+      return explicitHeaders;
+    }
+  }
+  const githubToken = process.env.GITHUB_TOKEN;
+  if (githubToken) {
+    logger.debug("Using GitHub token from GITHUB_TOKEN environment variable");
+    return {
+      ...explicitHeaders,
+      Authorization: `Bearer ${githubToken}`
+    };
+  }
+  const ghToken = process.env.GH_TOKEN;
+  if (ghToken) {
+    logger.debug("Using GitHub token from GH_TOKEN environment variable");
+    return {
+      ...explicitHeaders,
+      Authorization: `Bearer ${ghToken}`
+    };
+  }
+  try {
+    const { stdout } = await execAsync("gh auth token", { timeout: 5e3 });
+    const cliToken = stdout.trim();
+    if (cliToken) {
+      logger.debug("Using GitHub token from local gh CLI");
+      return {
+        ...explicitHeaders,
+        Authorization: `Bearer ${cliToken}`
+      };
+    }
+  } catch {
+  }
+  return explicitHeaders ?? {};
+}
 class GitHubScraperStrategy extends BaseScraperStrategy {
   httpFetcher;
   wikiProcessor;
   repoProcessor;
+  resolvedAuthHeaders;
+  resolvedAuthKey;
   constructor(config) {
     super(config);
     this.httpFetcher = new HttpFetcher(config.scraper);
@@ -15054,31 +15516,117 @@ class GitHubScraperStrategy extends BaseScraperStrategy {
     }
     return { owner, repo };
   }
+  buildAuthCacheKey(explicitHeaders) {
+    const normalizedHeaders = explicitHeaders ? Object.keys(explicitHeaders).sort().map((key) => [key, explicitHeaders[key]]) : [];
+    const envKey = `${process.env.GITHUB_TOKEN ?? ""}|${process.env.GH_TOKEN ?? ""}`;
+    return JSON.stringify({ headers: normalizedHeaders, env: envKey });
+  }
+  async getResolvedAuthHeaders(explicitHeaders) {
+    const cacheKey = this.buildAuthCacheKey(explicitHeaders);
+    if (this.resolvedAuthHeaders && this.resolvedAuthKey === cacheKey) {
+      return this.resolvedAuthHeaders;
+    }
+    const resolved = await resolveGitHubAuth(explicitHeaders);
+    this.resolvedAuthHeaders = resolved;
+    this.resolvedAuthKey = cacheKey;
+    return resolved;
+  }
   /**
    * Fetches the repository tree structure from GitHub API.
    */
-  async fetchRepositoryTree(repoInfo, signal) {
+  async fetchRepositoryTree(repoInfo, headers, signal) {
     const { owner, repo, branch } = repoInfo;
     let targetBranch = branch;
     if (!targetBranch) {
+      const repoUrl = `https://api.github.com/repos/${owner}/${repo}`;
+      logger.debug(`Fetching repository info: ${repoUrl}`);
+      let repoContent;
+      try {
+        repoContent = await this.httpFetcher.fetch(repoUrl, { signal, headers });
+      } catch (error) {
+        if (error instanceof ScraperError) {
+          if (error.message.includes("401")) {
+            throw new ScraperError(
+              `GitHub authentication failed for "${owner}/${repo}". Your token is invalid or expired. Please check your GITHUB_TOKEN or GH_TOKEN environment variable.`,
+              false,
+              error
+            );
+          }
+          if (error.message.includes("403")) {
+            throw new ScraperError(
+              `GitHub access denied for "${owner}/${repo}". Your token may lack the required permissions, or you may be rate-limited. Please check your GITHUB_TOKEN or GH_TOKEN.`,
+              false,
+              error
+            );
+          }
+        }
+        throw error;
+      }
+      if (repoContent.status === FetchStatus.NOT_FOUND) {
+        throw new ScraperError(
+          `Repository "${owner}/${repo}" not found or not accessible. For private repositories, set the GITHUB_TOKEN environment variable.`,
+          false
+        );
+      }
       try {
-        const repoUrl = `https://api.github.com/repos/${owner}/${repo}`;
-        logger.debug(`Fetching repository info: ${repoUrl}`);
-        const repoContent = await this.httpFetcher.fetch(repoUrl, { signal });
         const content2 = typeof repoContent.content === "string" ? repoContent.content : repoContent.content.toString("utf-8");
         const repoData = JSON.parse(content2);
-        targetBranch = repoData.default_branch;
-        logger.debug(`Using default branch: ${targetBranch}`);
-      } catch (error) {
-        logger.warn(`⚠️  Could not fetch default branch, using 'main': ${error}`);
+        const defaultBranch = typeof repoData.default_branch === "string" ? repoData.default_branch.trim() : "";
+        if (!defaultBranch) {
+          logger.warn(
+            `⚠️  Repository info missing default_branch for ${owner}/${repo}, using 'main'`
+          );
+          targetBranch = "main";
+        } else {
+          targetBranch = defaultBranch;
+          logger.debug(`Using default branch: ${targetBranch}`);
+        }
+      } catch (parseError) {
+        logger.warn(`⚠️  Could not parse repository info, using 'main': ${parseError}`);
         targetBranch = "main";
       }
     }
     const treeUrl = `https://api.github.com/repos/${owner}/${repo}/git/trees/${targetBranch}?recursive=1`;
     logger.debug(`Fetching repository tree: ${treeUrl}`);
-    const rawContent = await this.httpFetcher.fetch(treeUrl, { signal });
+    let rawContent;
+    try {
+      rawContent = await this.httpFetcher.fetch(treeUrl, { signal, headers });
+    } catch (error) {
+      if (error instanceof ScraperError) {
+        if (error.message.includes("401")) {
+          throw new ScraperError(
+            `GitHub authentication failed for "${owner}/${repo}". Your token is invalid or expired. Please check your GITHUB_TOKEN or GH_TOKEN environment variable.`,
+            false,
+            error
+          );
+        }
+        if (error.message.includes("403")) {
+          throw new ScraperError(
+            `GitHub access denied for "${owner}/${repo}". Your token may lack the required permissions, or you may be rate-limited. Please check your GITHUB_TOKEN or GH_TOKEN.`,
+            false,
+            error
+          );
+        }
+      }
+      throw error;
+    }
+    if (rawContent.status === FetchStatus.NOT_FOUND) {
+      throw new ScraperError(
+        `Repository "${owner}/${repo}" not found or not accessible. For private repositories, set the GITHUB_TOKEN environment variable.`,
+        false
+      );
+    }
     const content = typeof rawContent.content === "string" ? rawContent.content : rawContent.content.toString("utf-8");
-    const treeData = JSON.parse(content);
+    let treeData;
+    try {
+      treeData = JSON.parse(content);
+    } catch (parseError) {
+      throw new ScraperError(
+        `Failed to parse GitHub API response for "${owner}/${repo}". The repository may be inaccessible or the API returned an unexpected response.`,
+        false,
+        parseError instanceof Error ? parseError : void 0
+      );
+    }
     if (treeData.truncated) {
       logger.warn(
         `⚠️  Repository tree was truncated for ${owner}/${repo}. Some files may be missing.`
@@ -15217,7 +15765,7 @@ class GitHubScraperStrategy extends BaseScraperStrategy {
     if (hasTextExtension || hasDocumentExtension || hasCompoundExtension || isCommonTextFile) {
       return shouldIncludeUrl(path2, options.includePatterns, options.excludePatterns);
     }
-    const mimeType = mime.getType(path2);
+    const mimeType = MimeTypeUtils.detectMimeTypeFromPath(path2);
     if (mimeType?.startsWith("text/")) {
       logger.debug(`Including file with text MIME type: ${path2} (${mimeType})`);
       return shouldIncludeUrl(path2, options.includePatterns, options.excludePatterns);
@@ -15252,10 +15800,11 @@ class GitHubScraperStrategy extends BaseScraperStrategy {
         status: FetchStatus.NOT_FOUND
       };
     }
+    const headers = await this.getResolvedAuthHeaders(options.headers);
     try {
       const parsedUrl = new URL(item.url);
       if (/^\/[^/]+\/[^/]+\/wiki($|\/)/.test(parsedUrl.pathname)) {
-        return await this.wikiProcessor.process(item, options, signal);
+        return await this.wikiProcessor.process(item, options, headers, signal);
       }
     } catch {
     }
@@ -15281,7 +15830,11 @@ class GitHubScraperStrategy extends BaseScraperStrategy {
       const wikiUrl = `${options.url.replace(/\/$/, "")}/wiki`;
       discoveredLinks.push(wikiUrl);
       logger.debug(`Discovered wiki URL: ${wikiUrl}`);
-      const { tree, resolvedBranch } = await this.fetchRepositoryTree(repoInfo, signal);
+      const { tree, resolvedBranch } = await this.fetchRepositoryTree(
+        repoInfo,
+        headers,
+        signal
+      );
       const fileItems = tree.tree.filter((treeItem) => this.isWithinSubPath(treeItem.path, repoInfo.subPath)).filter((treeItem) => this.shouldProcessFile(treeItem, options));
       logger.debug(
         `Discovered ${fileItems.length} processable files in repository (branch: ${resolvedBranch})`
@@ -15299,7 +15852,7 @@ class GitHubScraperStrategy extends BaseScraperStrategy {
       const parsedUrl = new URL(item.url);
       if (/^\/[^/]+\/[^/]+\/blob\//.test(parsedUrl.pathname)) {
         logger.debug(`Processing HTTPS blob URL at depth ${item.depth}: ${item.url}`);
-        return await this.repoProcessor.process(item, options, signal);
+        return await this.repoProcessor.process(item, options, headers, signal);
       }
     } catch (error) {
       logger.warn(`⚠️  Failed to parse blob URL ${item.url}: ${error}`);
@@ -15313,7 +15866,13 @@ class GitHubScraperStrategy extends BaseScraperStrategy {
     if (!url.hostname.includes("github.com")) {
       throw new Error("URL must be a GitHub URL");
     }
-    await super.scrape(options, progressCallback, signal);
+    await this.getResolvedAuthHeaders(options.headers);
+    try {
+      await super.scrape(options, progressCallback, signal);
+    } finally {
+      this.resolvedAuthHeaders = void 0;
+      this.resolvedAuthKey = void 0;
+    }
   }
   async cleanup() {
     await Promise.all([this.wikiProcessor.cleanup(), this.repoProcessor.cleanup()]);
@@ -15689,7 +16248,7 @@ class LocalFileStrategy extends BaseScraperStrategy {
     logger.debug(`Reading archive entry: ${innerPath} inside ${archivePath}`);
     try {
       const contentBuffer = await adapter.getContent(innerPath);
-      const mimeType = mime.getType(innerPath) || "application/octet-stream";
+      const mimeType = MimeTypeUtils.detectMimeTypeFromPath(innerPath) || "application/octet-stream";
       const rawContent = {
         source: item.url,
         content: contentBuffer,
@@ -15976,31 +16535,90 @@ class PyPiScraperStrategy {
   }
 }
 class ScraperRegistry {
-  strategies;
+  config;
   constructor(config) {
-    this.strategies = [
-      new NpmScraperStrategy(config),
-      new PyPiScraperStrategy(config),
-      new GitHubScraperStrategy(config),
-      new WebScraperStrategy(config, {}),
-      new LocalFileStrategy(config)
-    ];
+    this.config = config;
   }
+  /**
+   * Creates and returns a fresh strategy instance for the given URL.
+   * Each call returns a new instance to ensure state isolation between parallel scrapes.
+   */
   getStrategy(url) {
-    validateUrl(url);
-    const strategy = this.strategies.find((s) => s.canHandle(url));
-    if (!strategy) {
-      throw new ScraperError(`No strategy found for URL: ${url}`);
+    if (!url.startsWith("github-file://")) {
+      validateUrl(url);
     }
-    logger.debug(`Using strategy "${strategy.constructor.name}" for URL: ${url}`);
-    return strategy;
+    if (isLocalFileUrl(url)) {
+      logger.debug(`Using strategy "LocalFileStrategy" for URL: ${url}`);
+      return new LocalFileStrategy(this.config);
+    }
+    if (isNpmUrl(url)) {
+      logger.debug(`Using strategy "NpmScraperStrategy" for URL: ${url}`);
+      return new NpmScraperStrategy(this.config);
+    }
+    if (isPyPiUrl(url)) {
+      logger.debug(`Using strategy "PyPiScraperStrategy" for URL: ${url}`);
+      return new PyPiScraperStrategy(this.config);
+    }
+    if (isGitHubUrl(url)) {
+      logger.debug(`Using strategy "GitHubScraperStrategy" for URL: ${url}`);
+      return new GitHubScraperStrategy(this.config);
+    }
+    if (isWebUrl(url)) {
+      logger.debug(`Using strategy "WebScraperStrategy" for URL: ${url}`);
+      return new WebScraperStrategy(this.config, {});
+    }
+    throw new ScraperError(`No strategy found for URL: ${url}`);
   }
-  /**
-   * Cleanup all registered strategies to prevent resource leaks.
-   * Should be called when the registry is no longer needed.
-   */
-  async cleanup() {
-    await Promise.allSettled(this.strategies.map((strategy) => strategy.cleanup?.()));
+}
+function isLocalFileUrl(url) {
+  return url.startsWith("file://");
+}
+function isNpmUrl(url) {
+  try {
+    const { hostname } = new URL(url);
+    return ["npmjs.org", "npmjs.com", "www.npmjs.com"].includes(hostname);
+  } catch {
+    return false;
+  }
+}
+function isPyPiUrl(url) {
+  try {
+    const { hostname } = new URL(url);
+    return ["pypi.org", "www.pypi.org"].includes(hostname);
+  } catch {
+    return false;
+  }
+}
+function isGitHubUrl(url) {
+  if (url.startsWith("github-file://")) {
+    return true;
+  }
+  try {
+    const parsedUrl = new URL(url);
+    const { hostname, pathname } = parsedUrl;
+    if (!["github.com", "www.github.com"].includes(hostname)) {
+      return false;
+    }
+    if (pathname.match(/^\/[^/]+\/[^/]+\/?$/)) {
+      return true;
+    }
+    if (pathname.match(/^\/[^/]+\/[^/]+\/tree\//)) {
+      return true;
+    }
+    if (pathname.match(/^\/[^/]+\/[^/]+\/blob\//)) {
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+function isWebUrl(url) {
+  try {
+    const parsedUrl = new URL(url);
+    return parsedUrl.protocol === "http:" || parsedUrl.protocol === "https:";
+  } catch {
+    return false;
   }
 }
 class ScraperService {
@@ -16011,20 +16629,35 @@ class ScraperService {
   /**
    * Scrapes content from the provided URL using the appropriate strategy.
    * Reports progress via callback and handles errors.
+   * Cleans up strategy resources after scrape completes (success or failure).
    */
   async scrape(options, progressCallback, signal) {
     const strategy = this.registry.getStrategy(options.url);
-    if (!strategy) {
-      throw new ScraperError(`No scraper strategy found for URL: ${options.url}`, false);
+    let scrapeError = null;
+    let cleanupErrorToThrow = null;
+    try {
+      await strategy.scrape(options, progressCallback, signal);
+    } catch (error) {
+      scrapeError = error instanceof Error ? error : new ScraperError(`Scrape failed for URL: ${options.url}`, false);
+    } finally {
+      try {
+        await strategy.cleanup?.();
+      } catch (cleanupError) {
+        logger.error(`❌ Strategy cleanup failed for ${options.url}: ${cleanupError}`);
+        if (!scrapeError) {
+          cleanupErrorToThrow = cleanupError instanceof Error ? cleanupError : new ScraperError(
+            `Strategy cleanup failed for URL: ${options.url}`,
+            false
+          );
+        }
+      }
+    }
+    if (scrapeError) {
+      throw scrapeError;
+    }
+    if (cleanupErrorToThrow) {
+      throw cleanupErrorToThrow;
     }
-    await strategy.scrape(options, progressCallback, signal);
-  }
-  /**
-   * Cleanup the scraper registry and all its strategies.
-   * Should be called when the service is no longer needed.
-   */
-  async cleanup() {
-    await this.registry.cleanup();
   }
 }
 class PipelineWorker {
@@ -16187,7 +16820,7 @@ class PipelineManager {
     if (this.shouldRecoverJobs) {
       await this.recoverPendingJobs();
     } else {
-      logger.debug("Job recovery disabled for this PipelineManager instance");
+      await this.markInterruptedJobsAsFailed();
     }
     this._processQueue().catch((error) => {
       logger.error(`❌ Error in processQueue during start: ${error}`);
@@ -16195,79 +16828,69 @@ class PipelineManager {
   }
   /**
    * Recovers pending jobs from the database after server restart.
-   * Finds versions with RUNNING status and resets them to QUEUED for re-processing.
-   * Also loads all QUEUED versions back into the pipeline queue.
+   * Uses enqueueRefreshJob() to properly continue interrupted jobs,
+   * leveraging existing pages and ETags when available.
    */
   async recoverPendingJobs() {
     try {
-      const runningVersions = await this.store.getVersionsByStatus([
-        VersionStatus.RUNNING
+      const interruptedVersions = await this.store.getVersionsByStatus([
+        VersionStatus.RUNNING,
+        VersionStatus.QUEUED
       ]);
-      for (const version of runningVersions) {
-        await this.store.updateVersionStatus(version.id, VersionStatus.QUEUED);
-        logger.info(
-          `🔄 Reset interrupted job to QUEUED: ${version.library_name}@${version.name || "latest"}`
-        );
+      if (interruptedVersions.length === 0) {
+        logger.debug("No pending jobs to recover from database");
+        return;
       }
-      const queuedVersions = await this.store.getVersionsByStatus([VersionStatus.QUEUED]);
-      for (const version of queuedVersions) {
-        const jobId = v4();
-        const abortController = new AbortController();
-        let resolveCompletion;
-        let rejectCompletion;
-        const completionPromise = new Promise((resolve, reject) => {
-          resolveCompletion = resolve;
-          rejectCompletion = reject;
-        });
-        completionPromise.catch(() => {
-        });
-        let parsedScraperOptions = null;
-        if (version.scraper_options) {
-          try {
-            parsedScraperOptions = JSON.parse(version.scraper_options);
-          } catch (error) {
-            logger.warn(
-              `⚠️  Failed to parse scraper options for ${version.library_name}@${version.name || "latest"}: ${error}`
-            );
-          }
+      logger.info(
+        `📥 Recovering ${interruptedVersions.length} pending job(s) from database`
+      );
+      for (const version of interruptedVersions) {
+        const versionLabel = `${version.library_name}@${version.name || "latest"}`;
+        try {
+          await this.enqueueRefreshJob(version.library_name, version.name);
+          logger.info(`🔄 Recovering job: ${versionLabel}`);
+        } catch (error) {
+          const errorMessage = `Recovery failed: ${error instanceof Error ? error.message : String(error)}`;
+          await this.store.updateVersionStatus(
+            version.id,
+            VersionStatus.FAILED,
+            errorMessage
+          );
+          logger.warn(`⚠️  Failed to recover job ${versionLabel}: ${error}`);
         }
-        const job = {
-          id: jobId,
-          library: version.library_name,
-          version: version.name || "",
-          status: PipelineJobStatus.QUEUED,
-          progress: null,
-          error: null,
-          createdAt: new Date(version.created_at),
-          // For recovered QUEUED jobs, startedAt must be null to reflect queued state.
-          startedAt: null,
-          finishedAt: null,
-          abortController,
-          completionPromise,
-          resolveCompletion,
-          rejectCompletion,
-          // Database fields (single source of truth)
-          versionId: version.id,
-          versionStatus: version.status,
-          progressPages: version.progress_pages,
-          progressMaxPages: version.progress_max_pages,
-          errorMessage: version.error_message,
-          updatedAt: new Date(version.updated_at),
-          sourceUrl: version.source_url,
-          scraperOptions: parsedScraperOptions
-        };
-        this.jobMap.set(jobId, job);
-        this.jobQueue.push(jobId);
-      }
-      if (queuedVersions.length > 0) {
-        logger.info(`📥 Recovered ${queuedVersions.length} pending job(s) from database`);
-      } else {
-        logger.debug("No pending jobs to recover from database");
       }
     } catch (error) {
       logger.error(`❌ Failed to recover pending jobs: ${error}`);
     }
   }
+  /**
+   * Marks all interrupted jobs (RUNNING/QUEUED) as FAILED.
+   * Called when recoverJobs is false to allow users to manually retry via UI.
+   */
+  async markInterruptedJobsAsFailed() {
+    try {
+      const interruptedVersions = await this.store.getVersionsByStatus([
+        VersionStatus.RUNNING,
+        VersionStatus.QUEUED
+      ]);
+      if (interruptedVersions.length === 0) {
+        logger.debug("No interrupted jobs to mark as failed");
+        return;
+      }
+      for (const version of interruptedVersions) {
+        await this.store.updateVersionStatus(
+          version.id,
+          VersionStatus.FAILED,
+          "Job interrupted"
+        );
+        logger.info(
+          `❌ Marked interrupted job as failed: ${version.library_name}@${version.name || "latest"}`
+        );
+      }
+    } catch (error) {
+      logger.error(`❌ Failed to mark interrupted jobs as failed: ${error}`);
+    }
+  }
   /**
    * Stops the pipeline manager and attempts to gracefully shut down workers.
    * Currently, it just stops processing new jobs. Cancellation of active jobs
@@ -16280,7 +16903,6 @@ class PipelineManager {
     }
     this.isRunning = false;
     logger.debug("PipelineManager stopping. No new jobs will be started.");
-    await this.scraperService.cleanup();
   }
   /**
    * Enqueues a new document processing job, aborting any existing QUEUED/RUNNING job for the same library+version (including unversioned).
@@ -16870,6 +17492,7 @@ function createAppServerConfig(options) {
     enableWorker: options.enableWorker ?? true,
     port: options.port,
     externalWorkerUrl: options.externalWorkerUrl,
+    showLogo: options.showLogo ?? true,
     startupContext: options.startupContext
   };
 }
@@ -17064,6 +17687,7 @@ function createDefaultAction(cli) {
           enableApiServer: true,
           enableWorker: true,
           port: appConfig.server.ports.default,
+          showLogo: argv.logo,
           startupContext: {
             cliCommand: "default",
             mcpProtocol: "http"
@@ -17351,6 +17975,7 @@ function createMcpCommand(cli) {
             enableWorker: !serverUrl,
             port: appConfig.server.ports.mcp,
             externalWorkerUrl: serverUrl,
+            showLogo: argv.logo,
             startupContext: {
               cliCommand: "mcp",
               mcpProtocol: "http"
@@ -17877,6 +18502,7 @@ function createWebCommand(cli) {
           enableWorker: !serverUrl,
           port: appConfig.server.ports.web,
           externalWorkerUrl: serverUrl,
+          showLogo: argv.logo,
           startupContext: {
             cliCommand: "web"
           }
@@ -17961,6 +18587,7 @@ function createWorkerCommand(cli) {
           enableApiServer: true,
           enableWorker: true,
           port: appConfig.server.ports.worker,
+          showLogo: argv.logo,
           startupContext: {
             cliCommand: "worker"
           }
@@ -17989,7 +18616,7 @@ function createCli(argv) {
   let globalEventBus = null;
   let globalTelemetryService = null;
   const commandStartTimes = /* @__PURE__ */ new Map();
-  const cli = yargs(hideBin(argv)).scriptName("docs-mcp-server").strict().usage("Usage: $0 <command> [options]").version("1.36.0").option("verbose", {
+  const cli = yargs(hideBin(argv)).scriptName("docs-mcp-server").strict().usage("Usage: $0 <command> [options]").version("2.0.0").option("verbose", {
     type: "boolean",
     description: "Enable verbose (debug) logging",
     default: false
@@ -18013,6 +18640,10 @@ function createCli(argv) {
   }).option("config", {
     type: "string",
     description: "Path to configuration file"
+  }).option("logo", {
+    type: "boolean",
+    description: "Show ASCII art logo on startup",
+    default: true
   }).middleware(async (argv2) => {
     if (argv2.verbose && argv2.silent) {
       throw new Error("Arguments verbose and silent are mutually exclusive");
@@ -18045,7 +18676,7 @@ function createCli(argv) {
     if (shouldEnableTelemetry() && telemetry.isEnabled()) {
       const commandName = argv2._[0]?.toString() || "default";
       telemetry.setGlobalContext({
-        appVersion: "1.36.0",
+        appVersion: "2.0.0",
         appPlatform: process.platform,
         appNodeVersion: process.version,
         appInterface: "cli",