@arabold/docs-mcp-server 1.15.1 → 1.16.0

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { execSync } from "node:child_process";
-import fs$1, { existsSync } from "node:fs";
+import fs$1, { readFileSync, existsSync } from "node:fs";
 import "dotenv/config";
 import { Command } from "commander";
 import * as http from "node:http";
@@ -16,12 +16,13 @@ import { VirtualConsole, JSDOM } from "jsdom";
 import { chromium } from "playwright";
 import { gfm } from "@joplin/turndown-plugin-gfm";
 import TurndownService from "turndown";
-import { TextDecoder } from "node:util";
+import iconv from "iconv-lite";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import axios from "axios";
 import { HeaderGenerator } from "header-generator";
 import fs from "node:fs/promises";
 import path from "node:path";
+import * as mime from "mime-types";
 import { v4 } from "uuid";
 import psl from "psl";
 import { URL as URL$1, fileURLToPath } from "node:url";
@@ -41,7 +42,7 @@ import Fastify from "fastify";
 import { jsxs, jsx, Fragment } from "@kitajs/html/jsx-runtime";
 import DOMPurify from "dompurify";
 const name = "@arabold/docs-mcp-server";
-const version = "1.15.0";
+const version = "1.15.1";
 const description = "MCP server for fetching and searching documentation";
 const type = "module";
 const bin = { "docs-mcp-server": "dist/index.js" };
@@ -49,8 +50,8 @@ const license = "MIT";
 const repository = { "type": "git", "url": "git+https://github.com/arabold/docs-mcp-server.git" };
 const files = ["dist", "public", "db", "README.md", "LICENSE", "package.json"];
 const scripts = { "prepare": "husky || true", "build": "vite build --config vite.config.web.ts && vite build", "start": "node --enable-source-maps dist/index.js", "cli": "node --enable-source-maps dist/index.js", "server": "node --enable-source-maps dist/index.ts", "web": "node --enable-source-maps dist/index.ts web", "dev:cli": "vite-node src/index.ts", "dev:server": "vite-node --watch src/index.ts", "dev:server:stdio": "vite-node --watch src/index.ts -- --protocol stdio", "dev:server:http": "vite-node --watch src/index.ts -- --protocol http", "dev:web": "npm-run-all --parallel dev:web:assets dev:web:bin", "dev:web:bin": "vite-node --watch src/index.ts web", "dev:web:assets": "vite build --config vite.config.web.ts --watch", "test": "vitest run", "test:watch": "vitest", "test:coverage": "vitest run --coverage", "lint": "biome check .", "format": "biome format . --write", "postinstall": "echo 'Skipping Playwright browser install. See README.md for details.'" };
-const dependencies = { "@fastify/formbody": "^8.0.2", "@fastify/static": "^8.1.1", "@joplin/turndown-plugin-gfm": "^1.0.62", "@kitajs/html": "^4.2.9", "@kitajs/ts-html-plugin": "^4.1.1", "@langchain/aws": "^0.1.10", "@langchain/community": "^0.3.43", "@langchain/google-genai": "^0.2.9", "@langchain/google-vertexai": "^0.2.9", "@langchain/openai": "^0.5.10", "@modelcontextprotocol/sdk": "^1.11.4", "alpinejs": "^3.14.9", "axios": "^1.9.0", "axios-retry": "^4.5.0", "better-sqlite3": "^11.10.0", "cheerio": "^1.0.0", "commander": "^13.1.0", "dompurify": "^3.2.5", "dotenv": "^16.5.0", "env-paths": "^3.0.0", "fastify": "^5.3.3", "flowbite": "^3.1.2", "fuse.js": "^7.1.0", "header-generator": "^2.1.66", "htmx.org": "^1.9.12", "jsdom": "^26.1.0", "langchain": "0.3.19", "minimatch": "^10.0.1", "playwright": "^1.52.0", "psl": "^1.15.0", "remark": "^15.0.1", "remark-gfm": "^4.0.1", "remark-html": "^16.0.1", "semver": "^7.7.2", "sqlite-vec": "^0.1.7-alpha.2", "turndown": "^7.2.0", "zod": "^3.24.4" };
-const devDependencies = { "@biomejs/biome": "1.9.4", "@commitlint/cli": "^19.8.1", "@commitlint/config-conventional": "^19.8.1", "@semantic-release/changelog": "^6.0.3", "@semantic-release/git": "^10.0.1", "@semantic-release/github": "^11.0.2", "@semantic-release/npm": "^12.0.1", "@tailwindcss/postcss": "^4.1.7", "@tailwindcss/vite": "^4.1.7", "@types/alpinejs": "^3.13.11", "@types/better-sqlite3": "^7.6.13", "@types/jsdom": "~21.1.7", "@types/lint-staged": "~13.3.0", "@types/node": "^20.17.47", "@types/node-fetch": "^2.6.12", "@types/psl": "^1.1.3", "@types/semver": "^7.7.0", "@types/turndown": "^5.0.5", "autoprefixer": "^10.4.21", "flowbite-typography": "^1.0.5", "husky": "^9.1.7", "lint-staged": "^15.5.2", "memfs": "^4.17.2", "npm-run-all": "^4.1.5", "postcss": "^8.5.3", "semantic-release": "^24.2.4", "tailwindcss": "^4.1.4", "typescript": "^5.8.3", "vite": "^6.3.5", "vite-node": "^3.1.2", "vite-plugin-dts": "^4.5.4", "vitest": "^3.1.3" };
+const dependencies = { "@fastify/formbody": "^8.0.2", "@fastify/static": "^8.1.1", "@joplin/turndown-plugin-gfm": "^1.0.62", "@kitajs/html": "^4.2.9", "@kitajs/ts-html-plugin": "^4.1.1", "@langchain/aws": "^0.1.10", "@langchain/community": "^0.3.43", "@langchain/google-genai": "^0.2.9", "@langchain/google-vertexai": "^0.2.9", "@langchain/openai": "^0.5.10", "@modelcontextprotocol/sdk": "^1.11.4", "alpinejs": "^3.14.9", "axios": "^1.9.0", "axios-retry": "^4.5.0", "better-sqlite3": "^11.10.0", "cheerio": "^1.0.0", "commander": "^13.1.0", "dompurify": "^3.2.5", "dotenv": "^16.5.0", "env-paths": "^3.0.0", "fastify": "^5.3.3", "flowbite": "^3.1.2", "fuse.js": "^7.1.0", "header-generator": "^2.1.66", "htmx.org": "^1.9.12", "iconv-lite": "^0.6.3", "jsdom": "^26.1.0", "langchain": "0.3.19", "mime-types": "^3.0.1", "minimatch": "^10.0.1", "playwright": "^1.52.0", "psl": "^1.15.0", "remark": "^15.0.1", "remark-gfm": "^4.0.1", "remark-html": "^16.0.1", "semver": "^7.7.2", "sqlite-vec": "^0.1.7-alpha.2", "turndown": "^7.2.0", "zod": "^3.24.4" };
+const devDependencies = { "@biomejs/biome": "1.9.4", "@commitlint/cli": "^19.8.1", "@commitlint/config-conventional": "^19.8.1", "@semantic-release/changelog": "^6.0.3", "@semantic-release/git": "^10.0.1", "@semantic-release/github": "^11.0.2", "@semantic-release/npm": "^12.0.1", "@tailwindcss/postcss": "^4.1.7", "@tailwindcss/vite": "^4.1.7", "@types/alpinejs": "^3.13.11", "@types/better-sqlite3": "^7.6.13", "@types/jsdom": "~21.1.7", "@types/lint-staged": "~13.3.0", "@types/mime-types": "^2.1.4", "@types/node": "^20.17.47", "@types/node-fetch": "^2.6.12", "@types/psl": "^1.1.3", "@types/semver": "^7.7.0", "@types/turndown": "^5.0.5", "autoprefixer": "^10.4.21", "flowbite-typography": "^1.0.5", "husky": "^9.1.7", "lint-staged": "^15.5.2", "memfs": "^4.17.2", "npm-run-all": "^4.1.5", "postcss": "^8.5.3", "semantic-release": "^24.2.4", "tailwindcss": "^4.1.4", "typescript": "^5.8.3", "vite": "^6.3.5", "vite-node": "^3.1.2", "vite-plugin-dts": "^4.5.4", "vitest": "^3.1.3" };
 const engines = { "node": ">=20.0.0" };
 const packageJson = {
   name,
@@ -372,6 +373,21 @@ class HtmlMetadataExtractorMiddleware {
     await next();
   }
 }
+const DEFAULT_MAX_PAGES$1 = 1e3;
+const DEFAULT_MAX_DEPTH$1 = 3;
+const DEFAULT_MAX_CONCURRENCY = 3;
+const DEFAULT_PROTOCOL = "stdio";
+const DEFAULT_HTTP_PORT = 6280;
+const DEFAULT_WEB_PORT = 6281;
+const DEFAULT_PAGE_TIMEOUT = 5e3;
+const FETCHER_MAX_RETRIES = 6;
+const FETCHER_BASE_DELAY = 1e3;
+const SPLITTER_MIN_CHUNK_SIZE = 500;
+const SPLITTER_PREFERRED_CHUNK_SIZE = 1500;
+const SPLITTER_MAX_CHUNK_SIZE = 5e3;
+const EMBEDDING_BATCH_SIZE = 100;
+const MIGRATION_MAX_RETRIES = 5;
+const MIGRATION_RETRY_DELAY_MS = 300;
 var ScrapeMode = /* @__PURE__ */ ((ScrapeMode2) => {
   ScrapeMode2["Fetch"] = "fetch";
   ScrapeMode2["Playwright"] = "playwright";
@@ -387,10 +403,15 @@ class HtmlPlaywrightMiddleware {
   async ensureBrowser() {
     if (!this.browser || !this.browser.isConnected()) {
       const launchArgs = process.env.PLAYWRIGHT_LAUNCH_ARGS?.split(" ") ?? [];
+      const executablePath = process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH || void 0;
       logger.debug(
         `Launching new Playwright browser instance (Chromium) with args: ${launchArgs.join(" ") || "none"}...`
       );
-      this.browser = await chromium.launch({ channel: "chromium", args: launchArgs });
+      this.browser = await chromium.launch({
+        channel: "chromium",
+        args: launchArgs,
+        executablePath
+      });
       this.browser.on("disconnected", () => {
         logger.debug("Playwright browser instance disconnected.");
         this.browser = null;
@@ -409,12 +430,50 @@ class HtmlPlaywrightMiddleware {
       this.browser = null;
     }
   }
+  /**
+   * Waits for common loading indicators (spinners, loaders) that are currently visible to disappear from the page.
+   * Only waits for selectors that are present and visible at the time of check.
+   *
+   * @param page The Playwright page instance to operate on.
+   */
+  async waitForLoadingToComplete(page) {
+    const commonLoadingSelectors = [
+      '[class*="loading"]',
+      '[class*="spinner"]',
+      '[class*="loader"]',
+      '[id*="loading"]',
+      '[class*="preload"]',
+      "#loading",
+      '[aria-label*="loading" i]',
+      '[aria-label*="spinner" i]'
+    ];
+    const waitPromises = [];
+    for (const selector of commonLoadingSelectors) {
+      try {
+        const isVisible = await page.isVisible(selector).catch(() => false);
+        if (isVisible) {
+          waitPromises.push(
+            page.waitForSelector(selector, {
+              state: "hidden",
+              timeout: DEFAULT_PAGE_TIMEOUT
+            }).catch(() => {
+            })
+          );
+        }
+      } catch {
+      }
+    }
+    if (waitPromises.length > 0) {
+      await Promise.all(waitPromises);
+    }
+  }
   /**
    * Processes the context using Playwright, rendering dynamic content and propagating credentials for all same-origin requests.
    *
    * - Parses credentials from the URL (if present).
    * - Uses browser.newContext({ httpCredentials }) for HTTP Basic Auth on the main page and subresources.
    * - Injects Authorization header for all same-origin requests if credentials are present and not already set.
+   * - Waits for common loading indicators to disappear before extracting HTML.
    *
    * @param context The middleware context containing the HTML and source URL.
    * @param next The next middleware function in the pipeline.
@@ -447,7 +506,7 @@ class HtmlPlaywrightMiddleware {
         );
       }
     } catch (e) {
-      logger.warn(`⚠️ Could not parse URL for credential extraction: ${context.source}`);
+      logger.warn(`⚠️  Could not parse URL for credential extraction: ${context.source}`);
     }
     try {
       const browser = await this.ensureBrowser();
@@ -492,6 +551,7 @@ class HtmlPlaywrightMiddleware {
       });
       await page.goto(context.source, { waitUntil: "load" });
       await page.waitForSelector("body");
+      await this.waitForLoadingToComplete(page);
       renderedHtml = await page.content();
       logger.debug(`Playwright: Successfully rendered content for ${context.source}`);
     } catch (error) {
@@ -515,7 +575,7 @@ class HtmlPlaywrightMiddleware {
       );
     } else {
       logger.warn(
-        `⚠️ Playwright rendering resulted in null content for ${context.source}. Proceeding without content update.`
+        `⚠️  Playwright rendering resulted in null content for ${context.source}. Proceeding without content update.`
       );
     }
     await next();
@@ -611,7 +671,7 @@ class HtmlSanitizerMiddleware {
           }
         } catch (selectorError) {
           logger.warn(
-            `⚠️ Potentially invalid selector "${selector}" during element removal: ${selectorError}`
+            `⚠️  Potentially invalid selector "${selector}" during element removal: ${selectorError}`
           );
           context.errors.push(
             new Error(`Invalid selector "${selector}": ${selectorError}`)
@@ -711,7 +771,7 @@ ${text.replace(/^\n+|\n+$/g, "")}
       const markdown = this.turndownService.turndown(htmlToConvert).trim();
       if (!markdown) {
         const warnMsg = `HTML to Markdown conversion resulted in empty content for ${context.source}.`;
-        logger.warn(`⚠️ ${warnMsg}`);
+        logger.warn(`⚠️  ${warnMsg}`);
         context.content = "";
       } else {
         context.content = markdown;
@@ -768,11 +828,12 @@ class MarkdownMetadataExtractorMiddleware {
   }
 }
 function convertToString(content, charset) {
-  if (Buffer.isBuffer(content)) {
-    const decoder = new TextDecoder(charset || "utf-8");
-    return decoder.decode(content);
+  if (typeof content === "string") return content;
+  try {
+    return iconv.decode(content, charset || "utf-8");
+  } catch {
+    return iconv.decode(content, "utf-8");
   }
-  return content;
 }
 class BasePipeline {
   /**
@@ -985,13 +1046,13 @@ class FetchUrlTool {
       }
       if (!processed) {
         logger.warn(
-          `⚠️ Unsupported content type "${rawContent.mimeType}" for ${url}. Returning raw content.`
+          `⚠️  Unsupported content type "${rawContent.mimeType}" for ${url}. Returning raw content.`
         );
         const contentString = typeof rawContent.content === "string" ? rawContent.content : Buffer.from(rawContent.content).toString("utf-8");
         return contentString;
       }
       for (const err of processed.errors) {
-        logger.warn(`⚠️ Processing error for ${url}: ${err.message}`);
+        logger.warn(`⚠️  Processing error for ${url}: ${err.message}`);
       }
       if (typeof processed.textContent !== "string" || !processed.textContent.trim()) {
         throw new ToolError(
@@ -1179,20 +1240,6 @@ class RemoveTool {
     }
   }
 }
-const DEFAULT_MAX_PAGES$1 = 1e3;
-const DEFAULT_MAX_DEPTH$1 = 3;
-const DEFAULT_MAX_CONCURRENCY = 3;
-const DEFAULT_PROTOCOL = "stdio";
-const DEFAULT_HTTP_PORT = 6280;
-const DEFAULT_WEB_PORT = 6281;
-const FETCHER_MAX_RETRIES = 6;
-const FETCHER_BASE_DELAY = 1e3;
-const SPLITTER_MIN_CHUNK_SIZE = 500;
-const SPLITTER_PREFERRED_CHUNK_SIZE = 1500;
-const SPLITTER_MAX_CHUNK_SIZE = 5e3;
-const EMBEDDING_BATCH_SIZE = 100;
-const MIGRATION_MAX_RETRIES = 5;
-const MIGRATION_RETRY_DELAY_MS = 300;
 class ScrapeTool {
   docService;
   manager;
@@ -1717,7 +1764,7 @@ ${formattedJob}`);
         if (validation.success) {
           statusFilter = validation.data;
         } else {
-          logger.warn(`⚠️ Invalid status parameter received: ${statusParam}`);
+          logger.warn(`⚠️  Invalid status parameter received: ${statusParam}`);
         }
       }
       const result = await tools.listJobs.execute({ status: statusFilter });
@@ -1746,7 +1793,7 @@ ${formattedJob}`);
     },
     async (uri, { jobId }) => {
       if (typeof jobId !== "string" || jobId.length === 0) {
-        logger.warn(`⚠️ Invalid jobId received in URI: ${jobId}`);
+        logger.warn(`⚠️  Invalid jobId received in URI: ${jobId}`);
         return { contents: [] };
       }
       const result = await tools.getJobInfo.execute({ jobId });
@@ -1959,7 +2006,7 @@ class HttpFetcher {
         if (attempt < maxRetries && (status === void 0 || this.retryableStatusCodes.includes(status))) {
           const delay = baseDelay * 2 ** attempt;
           logger.warn(
-            `⚠️ Attempt ${attempt + 1}/${maxRetries + 1} failed for ${source} (Status: ${status}, Code: ${code}). Retrying in ${delay}ms...`
+            `⚠️  Attempt ${attempt + 1}/${maxRetries + 1} failed for ${source} (Status: ${status}, Code: ${code}). Retrying in ${delay}ms...`
           );
           await this.delay(delay);
           continue;
@@ -1981,13 +2028,17 @@ class FileFetcher {
   canFetch(source) {
     return source.startsWith("file://");
   }
+  /**
+   * Fetches the content of a file given a file:// URL, decoding percent-encoded paths as needed.
+   * Only HTML and Markdown files are processed.
+   */
   async fetch(source, options) {
-    const filePath = source.replace(/^file:\/\//, "");
-    logger.info(`📄 Fetching file: ${filePath}`);
+    const rawPath = source.replace("file://", "");
+    const filePath = decodeURIComponent(rawPath);
     try {
       const content = await fs.readFile(filePath);
       const ext = path.extname(filePath).toLowerCase();
-      const mimeType = this.getMimeType(ext);
+      const mimeType = mime.lookup(ext) || "application/octet-stream";
       return {
         content,
         mimeType,
@@ -2003,19 +2054,6 @@ class FileFetcher {
       );
     }
   }
-  getMimeType(ext) {
-    switch (ext) {
-      case ".html":
-      case ".htm":
-        return "text/html";
-      case ".md":
-        return "text/markdown";
-      case ".txt":
-        return "text/plain";
-      default:
-        return "application/octet-stream";
-    }
-  }
 }
 async function initializeTools(docService, pipelineManager) {
   const tools = {
@@ -2072,7 +2110,7 @@ async function stopServer() {
   }
   runningServer = null;
   if (hadError) {
-    logger.warn("⚠️ MCP Server instance stopped with errors.");
+    logger.warn("⚠️  MCP Server instance stopped with errors.");
   } else {
     logger.info("✅ MCP Server instance stopped.");
   }
@@ -2184,9 +2222,19 @@ function extractPathAndQuery(url) {
 function shouldIncludeUrl(url, includePatterns, excludePatterns) {
   const path2 = extractPathAndQuery(url);
   const normalizedPath = path2.startsWith("/") ? path2 : `/${path2}`;
-  if (matchesAnyPattern(normalizedPath, excludePatterns)) return false;
+  let basename;
+  if (url.startsWith("file://")) {
+    try {
+      const u = new URL(url);
+      basename = u.pathname ? u.pathname.split("/").pop() : void 0;
+    } catch {
+    }
+  }
+  const stripSlash = (patterns) => patterns?.map((p) => p.startsWith("/") ? p.slice(1) : p);
+  if (matchesAnyPattern(normalizedPath, excludePatterns) || basename && matchesAnyPattern(basename, stripSlash(excludePatterns)))
+    return false;
   if (!includePatterns || includePatterns.length === 0) return true;
-  return matchesAnyPattern(normalizedPath, includePatterns);
+  return matchesAnyPattern(normalizedPath, includePatterns) || (basename ? matchesAnyPattern(basename, stripSlash(includePatterns)) : false);
 }
 function isInScope(baseUrl, targetUrl, scope) {
   if (baseUrl.protocol !== targetUrl.protocol) return false;
@@ -2385,16 +2433,16 @@ class WebScraperStrategy extends BaseScraperStrategy {
       }
       if (!processed) {
         logger.warn(
-          `⚠️ Unsupported content type "${rawContent.mimeType}" for URL ${url}. Skipping processing.`
+          `⚠️  Unsupported content type "${rawContent.mimeType}" for URL ${url}. Skipping processing.`
         );
         return { document: void 0, links: [] };
       }
       for (const err of processed.errors) {
-        logger.warn(`⚠️ Processing error for ${url}: ${err.message}`);
+        logger.warn(`⚠️  Processing error for ${url}: ${err.message}`);
       }
       if (!processed.textContent || !processed.textContent.trim()) {
         logger.warn(
-          `⚠️ No processable content found for ${url} after pipeline execution.`
+          `⚠️  No processable content found for ${url} after pipeline execution.`
         );
         return { document: void 0, links: processed.links };
       }
@@ -2500,15 +2548,14 @@ class LocalFileStrategy extends BaseScraperStrategy {
     return url.startsWith("file://");
   }
   async processItem(item, options, _progressCallback, _signal) {
-    const filePath = item.url.replace(/^file:\/\//, "");
+    const filePath = decodeURIComponent(item.url.replace(/^file:\/\//, ""));
     const stats = await fs.stat(filePath);
     if (stats.isDirectory()) {
       const contents = await fs.readdir(filePath);
-      return {
-        links: contents.map((name2) => `file://${path.join(filePath, name2)}`)
-      };
+      const links = contents.map((name2) => `file://${path.join(filePath, name2)}`).filter((url) => this.shouldProcessUrl(url, options));
+      return { links };
     }
-    logger.info(`📄 Processing file ${this.pageCount}/${options.maxPages}: ${filePath}`);
+    logger.info(`🗂️  Processing file ${this.pageCount}/${options.maxPages}: ${filePath}`);
     const rawContent = await this.fileFetcher.fetch(item.url);
     let processed;
     for (const pipeline of this.pipelines) {
@@ -2519,12 +2566,12 @@ class LocalFileStrategy extends BaseScraperStrategy {
     }
     if (!processed) {
       logger.warn(
-        `⚠️ Unsupported content type "${rawContent.mimeType}" for file ${filePath}. Skipping processing.`
+        `⚠️  Unsupported content type "${rawContent.mimeType}" for file ${filePath}. Skipping processing.`
       );
       return { document: void 0, links: [] };
     }
     for (const err of processed.errors) {
-      logger.warn(`⚠️ Processing error for ${filePath}: ${err.message}`);
+      logger.warn(`⚠️  Processing error for ${filePath}: ${err.message}`);
     }
     return {
       document: {
@@ -2682,7 +2729,7 @@ class PipelineWorker {
       }
       logger.debug(`[${jobId}] Worker finished job successfully.`);
     } catch (error) {
-      logger.warn(`⚠️ [${jobId}] Worker encountered error: ${error}`);
+      logger.warn(`⚠️  [${jobId}] Worker encountered error: ${error}`);
       throw error;
     }
   }
@@ -2719,7 +2766,7 @@ class PipelineManager {
    */
   async start() {
     if (this.isRunning) {
-      logger.warn("⚠️ PipelineManager is already running.");
+      logger.warn("⚠️  PipelineManager is already running.");
       return;
     }
     this.isRunning = true;
@@ -2733,7 +2780,7 @@ class PipelineManager {
    */
   async stop() {
     if (!this.isRunning) {
-      logger.warn("⚠️ PipelineManager is not running.");
+      logger.warn("⚠️  PipelineManager is not running.");
       return;
     }
     this.isRunning = false;
@@ -2852,7 +2899,7 @@ class PipelineManager {
       case PipelineJobStatus.CANCELLED:
       case PipelineJobStatus.CANCELLING:
         logger.warn(
-          `⚠️ Job ${jobId} cannot be cancelled in its current state: ${job.status}`
+          `⚠️  Job ${jobId} cannot be cancelled in its current state: ${job.status}`
         );
         break;
       default:
@@ -3764,7 +3811,7 @@ async function applyMigrations(db) {
       if (error?.code === "SQLITE_BUSY" && retries < MIGRATION_MAX_RETRIES) {
         retries++;
         logger.warn(
-          `⚠️ Migrations busy (SQLITE_BUSY), retrying attempt ${retries}/${MIGRATION_MAX_RETRIES} in ${MIGRATION_RETRY_DELAY_MS}ms...`
+          `⚠️  Migrations busy (SQLITE_BUSY), retrying attempt ${retries}/${MIGRATION_MAX_RETRIES} in ${MIGRATION_RETRY_DELAY_MS}ms...`
         );
         await new Promise((resolve) => setTimeout(resolve, MIGRATION_RETRY_DELAY_MS));
       } else {
@@ -3943,7 +3990,7 @@ class DocumentStore {
    */
   async initializeEmbeddings() {
     const modelSpec = process.env.DOCS_MCP_EMBEDDING_MODEL || "text-embedding-3-small";
-    const { createEmbeddingModel } = await import("./EmbeddingFactory-C6_OpOiy.js");
+    const { createEmbeddingModel } = await import("./EmbeddingFactory-CElwVk3X.js");
     this.embeddings = createEmbeddingModel(modelSpec);
     const testVector = await this.embeddings.embedQuery("test");
     this.modelDimension = testVector.length;
@@ -4367,7 +4414,7 @@ class DocumentManagementService {
     try {
       fs$1.mkdirSync(dbDir, { recursive: true });
     } catch (error) {
-      logger.error(`⚠️ Failed to create database directory ${dbDir}: ${error}`);
+      logger.error(`⚠️  Failed to create database directory ${dbDir}: ${error}`);
     }
     this.store = new DocumentStore(dbPath);
     this.documentRetriever = new DocumentRetrieverService(this.store);
@@ -4407,7 +4454,7 @@ class DocumentManagementService {
     const versions = await this.listVersions(normalizedLibrary);
     const hasUnversioned = await this.exists(normalizedLibrary, "");
     if (versions.length === 0 && !hasUnversioned) {
-      logger.warn(`⚠️ Library '${library}' not found.`);
+      logger.warn(`⚠️  Library '${library}' not found.`);
       const allLibraries = await this.listLibraries();
       const libraryNames = allLibraries.map((lib) => lib.library);
       let suggestions = [];
@@ -4466,7 +4513,7 @@ class DocumentManagementService {
         logger.info(`ℹ️ Unversioned documents exist for ${library}`);
         return { bestMatch: null, hasUnversioned: true };
       }
-      logger.warn(`⚠️ No valid versions found for ${library}`);
+      logger.warn(`⚠️  No valid versions found for ${library}`);
       const allLibraryDetails = await this.store.queryLibraryVersions();
       const libraryDetails = allLibraryDetails.get(library) ?? [];
       throw new VersionNotFoundError(library, targetVersion ?? "", libraryDetails);
@@ -4478,7 +4525,7 @@ class DocumentManagementService {
     } else {
       const versionRegex = /^(\d+)(?:\.(?:x(?:\.x)?|\d+(?:\.(?:x|\d+))?))?$|^$/;
       if (!versionRegex.test(targetVersion)) {
-        logger.warn(`⚠️ Invalid target version format: ${targetVersion}`);
+        logger.warn(`⚠️  Invalid target version format: ${targetVersion}`);
       } else {
         let range = targetVersion;
         if (!semver__default.validRange(targetVersion)) {
@@ -4494,7 +4541,7 @@ class DocumentManagementService {
         `✅ Found best match version ${bestMatch} for ${library}@${targetVersion}`
       );
     } else {
-      logger.warn(`⚠️ No matching semver version found for ${library}@${targetVersion}`);
+      logger.warn(`⚠️  No matching semver version found for ${library}@${targetVersion}`);
     }
     if (!bestMatch && !hasUnversioned) {
       const allLibraryDetails = await this.store.queryLibraryVersions();
@@ -4540,7 +4587,7 @@ class DocumentManagementService {
         path: chunk.section.path
       }
     }));
-    logger.info(`📄 Split document into ${splitDocs.length} chunks`);
+    logger.info(`✂️  Split document into ${splitDocs.length} chunks`);
     await this.store.addDocuments(library, normalizedVersion, splitDocs);
   }
   /**
@@ -4561,17 +4608,23 @@ class DocumentManagementService {
     }));
   }
 }
-const Layout = ({
-  title,
-  version: version2 = "1.15.0",
-  children
-}) => /* @__PURE__ */ jsxs("html", { lang: "en", children: [
-  /* @__PURE__ */ jsxs("head", { children: [
-    /* @__PURE__ */ jsx("meta", { charset: "UTF-8" }),
-    /* @__PURE__ */ jsx("meta", { name: "viewport", content: "width=device-width, initial-scale=1.0" }),
-    /* @__PURE__ */ jsx("title", { safe: true, children: title }),
-    /* @__PURE__ */ jsx("link", { rel: "stylesheet", href: "/assets/main.css" }),
-    /* @__PURE__ */ jsx("style", { children: `
+const Layout = ({ title, version: version2, children }) => {
+  let versionString = version2;
+  if (!versionString) {
+    try {
+      const packageJson2 = JSON.parse(readFileSync("package.json", "utf-8"));
+      versionString = packageJson2.version;
+    } catch (error) {
+      console.error("Error reading package.json:", error);
+    }
+  }
+  return /* @__PURE__ */ jsxs("html", { lang: "en", children: [
+    /* @__PURE__ */ jsxs("head", { children: [
+      /* @__PURE__ */ jsx("meta", { charset: "UTF-8" }),
+      /* @__PURE__ */ jsx("meta", { name: "viewport", content: "width=device-width, initial-scale=1.0" }),
+      /* @__PURE__ */ jsx("title", { safe: true, children: title }),
+      /* @__PURE__ */ jsx("link", { rel: "stylesheet", href: "/assets/main.css" }),
+      /* @__PURE__ */ jsx("style", { children: `
           .htmx-indicator {
             display: none;
           }
@@ -4594,29 +4647,30 @@ const Layout = ({
           form .htmx-indicator .search-text { display: none; }
           form .spinner { display: none; }
         ` })
-  ] }),
-  /* @__PURE__ */ jsxs("body", { class: "bg-gray-50 dark:bg-gray-900", children: [
-    /* @__PURE__ */ jsxs("div", { class: "container max-w-2xl mx-auto px-4 py-4", children: [
-      /* @__PURE__ */ jsx("header", { class: "mb-4", children: /* @__PURE__ */ jsxs("h1", { class: "text-3xl font-bold text-gray-900 dark:text-white", children: [
-        /* @__PURE__ */ jsx("a", { href: "/", children: "MCP Docs" }),
-        version2 ? /* @__PURE__ */ jsxs(
-          "span",
-          {
-            safe: true,
-            class: "ml-2 text-base font-normal text-gray-500 dark:text-gray-400 align-baseline",
-            title: `Version ${version2}`,
-            children: [
-              "v",
-              version2
-            ]
-          }
-        ) : null
-      ] }) }),
-      /* @__PURE__ */ jsx("main", { children })
     ] }),
-    /* @__PURE__ */ jsx("script", { type: "module", src: "/assets/main.js" })
-  ] })
-] });
+    /* @__PURE__ */ jsxs("body", { class: "bg-gray-50 dark:bg-gray-900", children: [
+      /* @__PURE__ */ jsxs("div", { class: "container max-w-2xl mx-auto px-4 py-4", children: [
+        /* @__PURE__ */ jsx("header", { class: "mb-4", children: /* @__PURE__ */ jsxs("h1", { class: "text-3xl font-bold text-gray-900 dark:text-white", children: [
+          /* @__PURE__ */ jsx("a", { href: "/", children: "MCP Docs" }),
+          versionString ? /* @__PURE__ */ jsxs(
+            "span",
+            {
+              safe: true,
+              class: "ml-2 text-base font-normal text-gray-500 dark:text-gray-400 align-baseline",
+              title: `Version ${versionString}`,
+              children: [
+                "v",
+                versionString
+              ]
+            }
+          ) : null
+        ] }) }),
+        /* @__PURE__ */ jsx("main", { children })
+      ] }),
+      /* @__PURE__ */ jsx("script", { type: "module", src: "/assets/main.js" })
+    ] })
+  ] });
+};
 function registerIndexRoute(server) {
   server.get("/", async (_, reply) => {
     reply.type("text/html");
@@ -4857,7 +4911,25 @@ const ScrapeFormContent = () => /* @__PURE__ */ jsxs("div", { class: "mt-4 p-4 b
                 children: "URL"
               }
             ),
-            /* @__PURE__ */ jsx(Tooltip, { text: "Enter the URL of the documentation you want to scrape. This will be the starting point for the scraper." })
+            /* @__PURE__ */ jsx(
+              Tooltip,
+              {
+                text: /* @__PURE__ */ jsxs("div", { children: [
+                  /* @__PURE__ */ jsx("p", { children: "Enter the URL of the documentation you want to scrape." }),
+                  /* @__PURE__ */ jsxs("p", { class: "mt-2", children: [
+                    "For local files/folders, you must use the ",
+                    /* @__PURE__ */ jsx("code", { children: "file://" }),
+                    " ",
+                    "prefix and ensure the path is accessible to the server."
+                  ] }),
+                  /* @__PURE__ */ jsxs("p", { class: "mt-2", children: [
+                    "If running in Docker, ",
+                    /* @__PURE__ */ jsx("b", { children: "mount the folder" }),
+                    " (see README for details)."
+                  ] })
+                ] })
+              }
+            )
           ] }),
           /* @__PURE__ */ jsx(
             "input",
@@ -4875,7 +4947,7 @@ const ScrapeFormContent = () => /* @__PURE__ */ jsxs("div", { class: "mt-4 p-4 b
           /* @__PURE__ */ jsx(
             "div",
             {
-              "x-show": "hasPath",
+              "x-show": "hasPath && !(url.startsWith('file://'))",
               "x-cloak": true,
               "x-transition:enter": "transition ease-out duration-300",
               "x-transition:enter-start": "opacity-0 transform -translate-y-2",
@@ -5652,6 +5724,13 @@ async function stopWebServer(server) {
   }
 }
 function ensurePlaywrightBrowsersInstalled() {
+  const chromiumEnvPath = process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH;
+  if (chromiumEnvPath && existsSync(chromiumEnvPath)) {
+    logger.debug(
+      `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH is set to '${chromiumEnvPath}', skipping Playwright browser install.`
+    );
+    return;
+  }
   try {
     const playwright = require("playwright");
     const chromiumPath = playwright.chromium.executablePath();
@@ -5659,11 +5738,11 @@ function ensurePlaywrightBrowsersInstalled() {
       throw new Error("Playwright Chromium browser not found");
     }
   } catch (err) {
-    console.warn(
+    logger.debug(
       "Playwright browsers not found. Installing Chromium browser for dynamic scraping (this may take a minute)..."
     );
     try {
-      execSync("npx -y playwright install --no-shell --with-deps chromium", {
+      execSync("npm exec -y playwright install --no-shell --with-deps chromium", {
         stdio: "inherit",
         cwd: getProjectRoot()
       });
@@ -5777,7 +5856,9 @@ async function main() {
       await new Promise(() => {
       });
     });
-    program.command("scrape <library> <url>").description("Scrape and index documentation from a URL").option("-v, --version <string>", "Version of the library (optional)").option(
+    program.command("scrape <library> <url>").description(
+      "Scrape and index documentation from a URL or local folder.\n\nTo scrape local files or folders, use a file:// URL.\nExamples:\n  scrape mylib https://react.dev/reference/react\n  scrape mylib file:///Users/me/docs/index.html\n  scrape mylib file:///Users/me/docs/my-library\n\nNote: For local files/folders, you must use the file:// prefix. If running in Docker, mount the folder and use the container path. See README for details."
+    ).option("-v, --version <string>", "Version of the library (optional)").option(
       "-p, --max-pages <number>",
       "Maximum pages to scrape",
       DEFAULT_MAX_PAGES$1.toString()