docusaurus-plugin-mcp-server 0.10.2 → 0.12.0

package/dist/index.js

@@ -1,5 +1,6 @@
-import path from 'path';
+import FlexSearch from 'flexsearch';
 import fs3 from 'fs-extra';
+import path from 'path';
 import pMap from 'p-map';
 import { unified } from 'unified';
 import rehypeParse from 'rehype-parse';
@@ -9,16 +10,327 @@ import { toHtml } from 'hast-util-to-html';
 import rehypeRemark from 'rehype-remark';
 import remarkStringify from 'remark-stringify';
 import remarkGfm from 'remark-gfm';
-import FlexSearch from 'flexsearch';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
 import { z } from 'zod';
 
-// src/plugin/docusaurus-plugin.ts
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+function englishStemmer(word) {
+  if (word.length <= 3) return word;
+  return word.replace(/ing$/, "").replace(/tion$/, "t").replace(/sion$/, "s").replace(/([^aeiou])ed$/, "$1").replace(/([^aeiou])es$/, "$1").replace(/ly$/, "").replace(/ment$/, "").replace(/ness$/, "").replace(/ies$/, "y").replace(/([^s])s$/, "$1");
+}
+function createSearchIndex() {
+  return new FlexSearch.Document({
+    // Use 'forward' tokenization to avoid OOM with large doc sets
+    // See: https://github.com/scalvert/docusaurus-plugin-mcp-server/issues/11
+    tokenize: "forward",
+    // Enable caching for faster repeated queries
+    cache: 100,
+    // Higher resolution = more granular ranking (1-9)
+    resolution: 9,
+    // Enable context for phrase/proximity matching
+    context: {
+      resolution: 2,
+      depth: 2,
+      bidirectional: true
+    },
+    // Apply stemming to normalize word forms
+    encode: (str) => {
+      const words = str.toLowerCase().split(/[\s\-_.,;:!?'"()[\]{}]+/);
+      return words.filter(Boolean).map(englishStemmer);
+    },
+    // Document schema
+    document: {
+      id: "id",
+      // Index these fields for searching
+      index: ["title", "content", "headings", "description"],
+      // Store these fields in results (for enriched queries)
+      store: ["title", "description"]
+    }
+  });
+}
+function addDocumentToIndex(index, doc, baseUrl) {
+  const id = baseUrl ? `${baseUrl.replace(/\/$/, "")}${doc.route}` : doc.route;
+  const indexable = {
+    id,
+    title: doc.title,
+    content: doc.markdown,
+    headings: doc.headings.map((h) => h.text).join(" "),
+    description: doc.description
+  };
+  index.add(indexable);
+}
+function buildSearchIndex(docs, baseUrl) {
+  const index = createSearchIndex();
+  for (const doc of docs) {
+    addDocumentToIndex(index, doc, baseUrl);
+  }
+  return index;
+}
+function querySearchIndex(index, docs, query, options = {}) {
+  const { limit = 16 } = options;
+  const rawResults = index.search(query, {
+    limit: limit * 3,
+    // Get extra results for better ranking after weighting
+    enrich: true
+  });
+  const docScores = /* @__PURE__ */ new Map();
+  for (const fieldResult of rawResults) {
+    const field = fieldResult.field;
+    const fieldWeight = FIELD_WEIGHTS[field] ?? 1;
+    const results2 = fieldResult.result;
+    for (let i = 0; i < results2.length; i++) {
+      const item = results2[i];
+      if (!item) continue;
+      const docId = typeof item === "string" ? item : item.id;
+      const positionScore = (results2.length - i) / results2.length;
+      const weightedScore = positionScore * fieldWeight;
+      const existingScore = docScores.get(docId) ?? 0;
+      docScores.set(docId, existingScore + weightedScore);
+    }
+  }
+  const results = [];
+  for (const [docId, score] of docScores) {
+    const doc = docs[docId];
+    if (!doc) continue;
+    results.push({
+      url: docId,
+      // docId is the full URL when indexed with baseUrl
+      route: doc.route,
+      title: doc.title,
+      score,
+      snippet: generateSnippet(doc.markdown, query),
+      matchingHeadings: findMatchingHeadings(doc, query)
+    });
+  }
+  results.sort((a, b) => b.score - a.score);
+  return results.slice(0, limit);
+}
+function generateSnippet(markdown, query) {
+  const maxLength = 200;
+  const queryTerms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (queryTerms.length === 0) {
+    return markdown.slice(0, maxLength) + (markdown.length > maxLength ? "..." : "");
+  }
+  const lowerMarkdown = markdown.toLowerCase();
+  let bestIndex = -1;
+  let bestTerm = "";
+  const allTerms = [...queryTerms, ...queryTerms.map(englishStemmer)];
+  for (const term of allTerms) {
+    const index = lowerMarkdown.indexOf(term);
+    if (index !== -1 && (bestIndex === -1 || index < bestIndex)) {
+      bestIndex = index;
+      bestTerm = term;
+    }
+  }
+  if (bestIndex === -1) {
+    return markdown.slice(0, maxLength) + (markdown.length > maxLength ? "..." : "");
+  }
+  const snippetStart = Math.max(0, bestIndex - 50);
+  const snippetEnd = Math.min(markdown.length, bestIndex + bestTerm.length + 150);
+  let snippet = markdown.slice(snippetStart, snippetEnd);
+  snippet = snippet.replace(/^#{1,6}\s+/gm, "").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/!\[([^\]]*)\]\([^)]+\)/g, "").replace(/```[a-z]*\n?/g, "").replace(/`([^`]+)`/g, "$1").replace(/\s+/g, " ").trim();
+  const prefix = snippetStart > 0 ? "..." : "";
+  const suffix = snippetEnd < markdown.length ? "..." : "";
+  return prefix + snippet + suffix;
+}
+function findMatchingHeadings(doc, query) {
+  const queryTerms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const allTerms = [...queryTerms, ...queryTerms.map(englishStemmer)];
+  const matching = [];
+  for (const heading of doc.headings) {
+    const headingLower = heading.text.toLowerCase();
+    const headingStemmed = headingLower.split(/\s+/).map(englishStemmer).join(" ");
+    if (allTerms.some(
+      (term) => headingLower.includes(term) || headingStemmed.includes(englishStemmer(term))
+    )) {
+      matching.push(heading.text);
+    }
+  }
+  return matching.slice(0, 3);
+}
+async function exportSearchIndex(index) {
+  const exportData = {};
+  await index.export((key, data) => {
+    exportData[key] = data;
+  });
+  return exportData;
+}
+async function importSearchIndex(data) {
+  const index = createSearchIndex();
+  for (const [key, value] of Object.entries(data)) {
+    await index.import(
+      key,
+      value
+    );
+  }
+  return index;
+}
+var FIELD_WEIGHTS;
+var init_flexsearch_core = __esm({
+  "src/search/flexsearch-core.ts"() {
+    FIELD_WEIGHTS = {
+      title: 3,
+      headings: 2,
+      description: 1.5,
+      content: 1
+    };
+  }
+});
+
+// src/providers/indexers/flexsearch-indexer.ts
+var flexsearch_indexer_exports = {};
+__export(flexsearch_indexer_exports, {
+  FlexSearchIndexer: () => FlexSearchIndexer
+});
+var FlexSearchIndexer;
+var init_flexsearch_indexer = __esm({
+  "src/providers/indexers/flexsearch-indexer.ts"() {
+    init_flexsearch_core();
+    FlexSearchIndexer = class {
+      name = "flexsearch";
+      baseUrl = "";
+      docsIndex = {};
+      exportedIndex = null;
+      docCount = 0;
+      /**
+       * FlexSearch indexer always runs by default.
+       * It respects the indexers configuration - if not included, it won't run.
+       */
+      shouldRun() {
+        return true;
+      }
+      async initialize(context) {
+        this.baseUrl = context.baseUrl.replace(/\/$/, "");
+        this.docsIndex = {};
+        this.exportedIndex = null;
+        this.docCount = 0;
+      }
+      async indexDocuments(docs) {
+        this.docCount = docs.length;
+        for (const doc of docs) {
+          const fullUrl = `${this.baseUrl}${doc.route}`;
+          this.docsIndex[fullUrl] = doc;
+        }
+        console.log("[FlexSearch] Building search index...");
+        const searchIndex = buildSearchIndex(docs, this.baseUrl);
+        this.exportedIndex = await exportSearchIndex(searchIndex);
+        console.log(`[FlexSearch] Indexed ${this.docCount} documents`);
+      }
+      async finalize() {
+        const artifacts = /* @__PURE__ */ new Map();
+        artifacts.set("docs.json", this.docsIndex);
+        artifacts.set("search-index.json", this.exportedIndex);
+        return artifacts;
+      }
+      async getManifestData() {
+        return {
+          searchEngine: "flexsearch"
+        };
+      }
+    };
+  }
+});
+
+// src/providers/search/flexsearch-provider.ts
+var flexsearch_provider_exports = {};
+__export(flexsearch_provider_exports, {
+  FlexSearchProvider: () => FlexSearchProvider
+});
+var FlexSearchProvider;
+var init_flexsearch_provider = __esm({
+  "src/providers/search/flexsearch-provider.ts"() {
+    init_flexsearch_core();
+    FlexSearchProvider = class {
+      name = "flexsearch";
+      docs = null;
+      searchIndex = null;
+      ready = false;
+      async initialize(_context, initData) {
+        if (!initData) {
+          throw new Error("[FlexSearch] SearchProviderInitData required for FlexSearch provider");
+        }
+        if (initData.docs && initData.indexData) {
+          this.docs = initData.docs;
+          this.searchIndex = await importSearchIndex(initData.indexData);
+          this.ready = true;
+          return;
+        }
+        if (initData.docsPath && initData.indexPath) {
+          if (await fs3.pathExists(initData.docsPath)) {
+            this.docs = await fs3.readJson(initData.docsPath);
+          } else {
+            throw new Error(`[FlexSearch] Docs file not found: ${initData.docsPath}`);
+          }
+          if (await fs3.pathExists(initData.indexPath)) {
+            const indexData = await fs3.readJson(initData.indexPath);
+            this.searchIndex = await importSearchIndex(indexData);
+          } else {
+            throw new Error(`[FlexSearch] Search index not found: ${initData.indexPath}`);
+          }
+          this.ready = true;
+          return;
+        }
+        throw new Error(
+          "[FlexSearch] Invalid init data: must provide either file paths (docsPath, indexPath) or pre-loaded data (docs, indexData)"
+        );
+      }
+      isReady() {
+        return this.ready && this.docs !== null && this.searchIndex !== null;
+      }
+      async search(query, options) {
+        if (!this.isReady() || !this.docs || !this.searchIndex) {
+          throw new Error("[FlexSearch] Provider not initialized");
+        }
+        const limit = options?.limit ?? 16;
+        return querySearchIndex(this.searchIndex, this.docs, query, { limit });
+      }
+      async getDocument(url) {
+        if (!this.docs) {
+          throw new Error("[FlexSearch] Provider not initialized");
+        }
+        return this.docs[url] ?? null;
+      }
+      async healthCheck() {
+        if (!this.isReady()) {
+          return { healthy: false, message: "FlexSearch provider not initialized" };
+        }
+        const docCount = this.docs ? Object.keys(this.docs).length : 0;
+        return {
+          healthy: true,
+          message: `FlexSearch provider ready with ${docCount} documents`
+        };
+      }
+      getDocCount() {
+        return this.docs ? Object.keys(this.docs).length : 0;
+      }
+      /**
+       * Get all loaded documents (for compatibility with existing server code)
+       */
+      getDocs() {
+        return this.docs;
+      }
+      /**
+       * Get the FlexSearch index (for compatibility with existing server code)
+       */
+      getSearchIndex() {
+        return this.searchIndex;
+      }
+    };
+  }
+});
 
 // src/types/index.ts
-var DEFAULT_OPTIONS = {
+var DEFAULT_PLUGIN_OPTIONS = {
   outputDir: "mcp",
   contentSelectors: ["article", "main", ".main-wrapper", '[role="main"]'],
   excludeSelectors: [
@@ -280,292 +592,12 @@ function extractHeadingsFromMarkdown(markdown) {
 function generateHeadingId(text) {
   return text.toLowerCase().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
 }
-function extractSection(markdown, headingId, headings) {
-  const heading = headings.find((h) => h.id === headingId);
-  if (!heading) {
-    return null;
-  }
-  return markdown.slice(heading.startOffset, heading.endOffset).trim();
-}
-var FIELD_WEIGHTS = {
-  title: 3,
-  headings: 2,
-  description: 1.5,
-  content: 1
-};
-function englishStemmer(word) {
-  if (word.length <= 3) return word;
-  return word.replace(/ing$/, "").replace(/tion$/, "t").replace(/sion$/, "s").replace(/([^aeiou])ed$/, "$1").replace(/([^aeiou])es$/, "$1").replace(/ly$/, "").replace(/ment$/, "").replace(/ness$/, "").replace(/ies$/, "y").replace(/([^s])s$/, "$1");
-}
-function createSearchIndex() {
-  return new FlexSearch.Document({
-    // Use 'full' tokenization for substring matching
-    // This allows "auth" to match "authentication"
-    tokenize: "full",
-    // Enable caching for faster repeated queries
-    cache: 100,
-    // Higher resolution = more granular ranking (1-9)
-    resolution: 9,
-    // Enable context for phrase/proximity matching
-    context: {
-      resolution: 2,
-      depth: 2,
-      bidirectional: true
-    },
-    // Apply stemming to normalize word forms
-    encode: (str) => {
-      const words = str.toLowerCase().split(/[\s\-_.,;:!?'"()[\]{}]+/);
-      return words.filter(Boolean).map(englishStemmer);
-    },
-    // Document schema
-    document: {
-      id: "id",
-      // Index these fields for searching
-      index: ["title", "content", "headings", "description"],
-      // Store these fields in results (for enriched queries)
-      store: ["title", "description"]
-    }
-  });
-}
-function addDocumentToIndex(index, doc, baseUrl) {
-  const id = baseUrl ? `${baseUrl.replace(/\/$/, "")}${doc.route}` : doc.route;
-  const indexable = {
-    id,
-    title: doc.title,
-    content: doc.markdown,
-    headings: doc.headings.map((h) => h.text).join(" "),
-    description: doc.description
-  };
-  index.add(indexable);
-}
-function buildSearchIndex(docs, baseUrl) {
-  const index = createSearchIndex();
-  for (const doc of docs) {
-    addDocumentToIndex(index, doc, baseUrl);
-  }
-  return index;
-}
-function searchIndex(index, docs, query, options = {}) {
-  const { limit = 5 } = options;
-  const rawResults = index.search(query, {
-    limit: limit * 3,
-    // Get extra results for better ranking after weighting
-    enrich: true
-  });
-  const docScores = /* @__PURE__ */ new Map();
-  for (const fieldResult of rawResults) {
-    const field = fieldResult.field;
-    const fieldWeight = FIELD_WEIGHTS[field] ?? 1;
-    const results2 = fieldResult.result;
-    for (let i = 0; i < results2.length; i++) {
-      const item = results2[i];
-      if (!item) continue;
-      const docId = typeof item === "string" ? item : item.id;
-      const positionScore = (results2.length - i) / results2.length;
-      const weightedScore = positionScore * fieldWeight;
-      const existingScore = docScores.get(docId) ?? 0;
-      docScores.set(docId, existingScore + weightedScore);
-    }
-  }
-  const results = [];
-  for (const [docId, score] of docScores) {
-    const doc = docs[docId];
-    if (!doc) continue;
-    results.push({
-      url: docId,
-      // docId is the full URL when indexed with baseUrl
-      route: doc.route,
-      title: doc.title,
-      score,
-      snippet: generateSnippet(doc.markdown, query),
-      matchingHeadings: findMatchingHeadings(doc, query)
-    });
-  }
-  results.sort((a, b) => b.score - a.score);
-  return results.slice(0, limit);
-}
-function generateSnippet(markdown, query) {
-  const maxLength = 200;
-  const queryTerms = query.toLowerCase().split(/\s+/).filter(Boolean);
-  if (queryTerms.length === 0) {
-    return markdown.slice(0, maxLength) + (markdown.length > maxLength ? "..." : "");
-  }
-  const lowerMarkdown = markdown.toLowerCase();
-  let bestIndex = -1;
-  let bestTerm = "";
-  const allTerms = [...queryTerms, ...queryTerms.map(englishStemmer)];
-  for (const term of allTerms) {
-    const index = lowerMarkdown.indexOf(term);
-    if (index !== -1 && (bestIndex === -1 || index < bestIndex)) {
-      bestIndex = index;
-      bestTerm = term;
-    }
-  }
-  if (bestIndex === -1) {
-    return markdown.slice(0, maxLength) + (markdown.length > maxLength ? "..." : "");
-  }
-  const snippetStart = Math.max(0, bestIndex - 50);
-  const snippetEnd = Math.min(markdown.length, bestIndex + bestTerm.length + 150);
-  let snippet = markdown.slice(snippetStart, snippetEnd);
-  snippet = snippet.replace(/^#{1,6}\s+/gm, "").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/!\[([^\]]*)\]\([^)]+\)/g, "").replace(/```[a-z]*\n?/g, "").replace(/`([^`]+)`/g, "$1").replace(/\s+/g, " ").trim();
-  const prefix = snippetStart > 0 ? "..." : "";
-  const suffix = snippetEnd < markdown.length ? "..." : "";
-  return prefix + snippet + suffix;
-}
-function findMatchingHeadings(doc, query) {
-  const queryTerms = query.toLowerCase().split(/\s+/).filter(Boolean);
-  const allTerms = [...queryTerms, ...queryTerms.map(englishStemmer)];
-  const matching = [];
-  for (const heading of doc.headings) {
-    const headingLower = heading.text.toLowerCase();
-    const headingStemmed = headingLower.split(/\s+/).map(englishStemmer).join(" ");
-    if (allTerms.some(
-      (term) => headingLower.includes(term) || headingStemmed.includes(englishStemmer(term))
-    )) {
-      matching.push(heading.text);
-    }
-  }
-  return matching.slice(0, 3);
-}
-async function exportSearchIndex(index) {
-  const exportData = {};
-  await index.export((key, data) => {
-    exportData[key] = data;
-  });
-  return exportData;
-}
-async function importSearchIndex(data) {
-  const index = createSearchIndex();
-  for (const [key, value] of Object.entries(data)) {
-    await index.import(
-      key,
-      value
-    );
-  }
-  return index;
-}
-
-// src/providers/indexers/flexsearch-indexer.ts
-var FlexSearchIndexer = class {
-  name = "flexsearch";
-  baseUrl = "";
-  docsIndex = {};
-  exportedIndex = null;
-  docCount = 0;
-  /**
-   * FlexSearch indexer always runs by default.
-   * It respects the indexers configuration - if not included, it won't run.
-   */
-  shouldRun() {
-    return true;
-  }
-  async initialize(context) {
-    this.baseUrl = context.baseUrl.replace(/\/$/, "");
-    this.docsIndex = {};
-    this.exportedIndex = null;
-    this.docCount = 0;
-  }
-  async indexDocuments(docs) {
-    this.docCount = docs.length;
-    for (const doc of docs) {
-      const fullUrl = `${this.baseUrl}${doc.route}`;
-      this.docsIndex[fullUrl] = doc;
-    }
-    console.log("[FlexSearch] Building search index...");
-    const searchIndex2 = buildSearchIndex(docs, this.baseUrl);
-    this.exportedIndex = await exportSearchIndex(searchIndex2);
-    console.log(`[FlexSearch] Indexed ${this.docCount} documents`);
-  }
-  async finalize() {
-    const artifacts = /* @__PURE__ */ new Map();
-    artifacts.set("docs.json", this.docsIndex);
-    artifacts.set("search-index.json", this.exportedIndex);
-    return artifacts;
-  }
-  async getManifestData() {
-    return {
-      searchEngine: "flexsearch"
-    };
-  }
-};
-var FlexSearchProvider = class {
-  name = "flexsearch";
-  docs = null;
-  searchIndex = null;
-  ready = false;
-  async initialize(_context, initData) {
-    if (!initData) {
-      throw new Error("[FlexSearch] SearchProviderInitData required for FlexSearch provider");
-    }
-    if (initData.docs && initData.indexData) {
-      this.docs = initData.docs;
-      this.searchIndex = await importSearchIndex(initData.indexData);
-      this.ready = true;
-      return;
-    }
-    if (initData.docsPath && initData.indexPath) {
-      if (await fs3.pathExists(initData.docsPath)) {
-        this.docs = await fs3.readJson(initData.docsPath);
-      } else {
-        throw new Error(`[FlexSearch] Docs file not found: ${initData.docsPath}`);
-      }
-      if (await fs3.pathExists(initData.indexPath)) {
-        const indexData = await fs3.readJson(initData.indexPath);
-        this.searchIndex = await importSearchIndex(indexData);
-      } else {
-        throw new Error(`[FlexSearch] Search index not found: ${initData.indexPath}`);
-      }
-      this.ready = true;
-      return;
-    }
-    throw new Error(
-      "[FlexSearch] Invalid init data: must provide either file paths (docsPath, indexPath) or pre-loaded data (docs, indexData)"
-    );
-  }
-  isReady() {
-    return this.ready && this.docs !== null && this.searchIndex !== null;
-  }
-  async search(query, options) {
-    if (!this.isReady() || !this.docs || !this.searchIndex) {
-      throw new Error("[FlexSearch] Provider not initialized");
-    }
-    const limit = options?.limit ?? 5;
-    return searchIndex(this.searchIndex, this.docs, query, { limit });
-  }
-  async getDocument(url) {
-    if (!this.docs) {
-      throw new Error("[FlexSearch] Provider not initialized");
-    }
-    return this.docs[url] ?? null;
-  }
-  async healthCheck() {
-    if (!this.isReady()) {
-      return { healthy: false, message: "FlexSearch provider not initialized" };
-    }
-    const docCount = this.docs ? Object.keys(this.docs).length : 0;
-    return {
-      healthy: true,
-      message: `FlexSearch provider ready with ${docCount} documents`
-    };
-  }
-  /**
-   * Get all loaded documents (for compatibility with existing server code)
-   */
-  getDocs() {
-    return this.docs;
-  }
-  /**
-   * Get the FlexSearch index (for compatibility with existing server code)
-   */
-  getSearchIndex() {
-    return this.searchIndex;
-  }
-};
 
 // src/providers/loader.ts
 async function loadIndexer(specifier) {
   if (specifier === "flexsearch") {
-    return new FlexSearchIndexer();
+    const { FlexSearchIndexer: FlexSearchIndexer2 } = await Promise.resolve().then(() => (init_flexsearch_indexer(), flexsearch_indexer_exports));
+    return new FlexSearchIndexer2();
   }
   try {
     const module = await import(specifier);
@@ -587,14 +619,17 @@ async function loadIndexer(specifier) {
     );
   } catch (error) {
     if (error instanceof Error && error.message.includes("Cannot find module")) {
-      throw new Error(`Indexer module not found: "${specifier}". Check the path or package name.`);
+      throw new Error(`Indexer module not found: "${specifier}". Check the path or package name.`, {
+        cause: error
+      });
     }
     throw error;
   }
 }
 async function loadSearchProvider(specifier) {
   if (specifier === "flexsearch") {
-    return new FlexSearchProvider();
+    const { FlexSearchProvider: FlexSearchProvider2 } = await Promise.resolve().then(() => (init_flexsearch_provider(), flexsearch_provider_exports));
+    return new FlexSearchProvider2();
   }
   try {
     const module = await import(specifier);
@@ -617,7 +652,8 @@ async function loadSearchProvider(specifier) {
   } catch (error) {
     if (error instanceof Error && error.message.includes("Cannot find module")) {
       throw new Error(
-        `Search provider module not found: "${specifier}". Check the path or package name.`
+        `Search provider module not found: "${specifier}". Check the path or package name.`,
+        { cause: error }
       );
     }
     throw error;
@@ -641,10 +677,10 @@ function isSearchProvider(obj) {
 // src/plugin/docusaurus-plugin.ts
 function resolveOptions(options) {
   return {
-    ...DEFAULT_OPTIONS,
+    ...DEFAULT_PLUGIN_OPTIONS,
     ...options,
     server: {
-      ...DEFAULT_OPTIONS.server,
+      ...DEFAULT_PLUGIN_OPTIONS.server,
       ...options.server
     }
   };
@@ -769,9 +805,12 @@ function mcpServerPlugin(context, options) {
     }
   };
 }
+
+// src/mcp/tools/docs-search.ts
+init_flexsearch_core();
 var docsSearchInputSchema = {
   query: z.string().min(1).describe("The search query string"),
-  limit: z.number().int().min(1).max(20).optional().default(5).describe("Maximum number of results to return (1-20, default: 5)")
+  limit: z.number().int().min(1).max(20).optional().default(16).describe("Maximum number of results to return (1-20, default: 16)")
 };
 var docsSearchTool = {
   name: "docs_search",
@@ -846,14 +885,22 @@ function isDataConfig(config) {
 var McpDocsServer = class {
   config;
   searchProvider = null;
-  mcpServer;
   initialized = false;
+  initPromise = null;
+  initError = null;
   constructor(config) {
     this.config = config;
-    this.mcpServer = new McpServer(
+  }
+  /**
+   * Create a fresh McpServer instance with tools registered.
+   * Each request gets its own server to avoid concurrency issues
+   * with the SDK's transport reassignment.
+   */
+  createMcpServer() {
+    const server = new McpServer(
       {
-        name: config.name,
-        version: config.version ?? "1.0.0"
+        name: this.config.name,
+        version: this.config.version ?? "1.0.0"
       },
       {
         capabilities: {
@@ -861,20 +908,20 @@ var McpDocsServer = class {
         }
       }
     );
-    this.registerTools();
+    this.registerTools(server);
+    return server;
   }
   /**
    * Register all MCP tools using definitions from tool files
    */
-  registerTools() {
-    this.mcpServer.registerTool(
+  registerTools(server) {
+    server.registerTool(
       docsSearchTool.name,
       {
         description: docsSearchTool.description,
         inputSchema: docsSearchTool.inputSchema
       },
       async ({ query, limit }) => {
-        await this.initialize();
         if (!this.searchProvider || !this.searchProvider.isReady()) {
           return {
             content: [{ type: "text", text: "Server not initialized. Please try again." }],
@@ -889,20 +936,24 @@ var McpDocsServer = class {
         } catch (error) {
           console.error("[MCP] Search error:", error);
           return {
-            content: [{ type: "text", text: `Search error: ${String(error)}` }],
+            content: [
+              {
+                type: "text",
+                text: "An error occurred while searching. Please try again."
+              }
+            ],
             isError: true
           };
         }
       }
     );
-    this.mcpServer.registerTool(
+    server.registerTool(
       docsFetchTool.name,
       {
         description: docsFetchTool.description,
         inputSchema: docsFetchTool.inputSchema
       },
       async ({ url }) => {
-        await this.initialize();
         if (!this.searchProvider || !this.searchProvider.isReady()) {
           return {
             content: [{ type: "text", text: "Server not initialized. Please try again." }],
@@ -917,7 +968,12 @@ var McpDocsServer = class {
         } catch (error) {
           console.error("[MCP] Fetch error:", error);
           return {
-            content: [{ type: "text", text: `Error fetching page: ${String(error)}` }],
+            content: [
+              {
+                type: "text",
+                text: "An error occurred while fetching the page. Please try again."
+              }
+            ],
             isError: true
           };
         }
@@ -941,43 +997,54 @@ var McpDocsServer = class {
    *
    * For file-based config: reads from disk
    * For data config: uses pre-loaded data directly
+   *
+   * Uses promise-based locking to prevent concurrent initialization.
+   * Caches initialization errors so repeated calls fail fast.
    */
   async initialize() {
+    if (this.initError) {
+      throw this.initError;
+    }
     if (this.initialized) {
       return;
     }
-    try {
-      const searchSpecifier = this.config.search ?? "flexsearch";
-      this.searchProvider = await loadSearchProvider(searchSpecifier);
-      const providerContext = {
-        baseUrl: this.config.baseUrl ?? "",
-        serverName: this.config.name,
-        serverVersion: this.config.version ?? "1.0.0",
-        outputDir: ""
-        // Not relevant for runtime
-      };
-      const initData = {};
-      if (isDataConfig(this.config)) {
-        initData.docs = this.config.docs;
-        initData.indexData = this.config.searchIndexData;
-      } else if (isFileConfig(this.config)) {
-        initData.docsPath = this.config.docsPath;
-        initData.indexPath = this.config.indexPath;
-      } else {
-        throw new Error("Invalid server config: must provide either file paths or pre-loaded data");
-      }
-      await this.searchProvider.initialize(providerContext, initData);
-      this.initialized = true;
-    } catch (error) {
-      console.error("[MCP] Failed to initialize:", error);
-      throw error;
+    if (!this.initPromise) {
+      this.initPromise = this._doInitialize().catch((error) => {
+        this.initError = error instanceof Error ? error : new Error(String(error));
+        this.initPromise = null;
+        throw this.initError;
+      });
+    }
+    return this.initPromise;
+  }
+  async _doInitialize() {
+    const searchSpecifier = this.config.search ?? "flexsearch";
+    this.searchProvider = await loadSearchProvider(searchSpecifier);
+    const providerContext = {
+      baseUrl: this.config.baseUrl ?? "",
+      serverName: this.config.name,
+      serverVersion: this.config.version ?? "1.0.0",
+      outputDir: ""
+      // Not relevant for runtime
+    };
+    const initData = {};
+    if (isDataConfig(this.config)) {
+      initData.docs = this.config.docs;
+      initData.indexData = this.config.searchIndexData;
+    } else if (isFileConfig(this.config)) {
+      initData.docsPath = this.config.docsPath;
+      initData.indexPath = this.config.indexPath;
+    } else {
+      throw new Error("Invalid server config: must provide either file paths or pre-loaded data");
     }
+    await this.searchProvider.initialize(providerContext, initData);
+    this.initialized = true;
   }
   /**
    * Handle an HTTP request using the MCP SDK's transport
    *
    * This method is designed for serverless environments (Vercel, Netlify).
-   * It creates a stateless transport instance and processes the request.
+   * Creates a fresh McpServer per request to avoid concurrency issues.
    *
    * @param req - Node.js IncomingMessage or compatible request object
    * @param res - Node.js ServerResponse or compatible response object
@@ -985,13 +1052,14 @@ var McpDocsServer = class {
    */
   async handleHttpRequest(req, res, parsedBody) {
     await this.initialize();
+    const server = this.createMcpServer();
     const transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: void 0,
       // Stateless mode - no session tracking
       enableJsonResponse: true
       // Return JSON instead of SSE streams
     });
-    await this.mcpServer.connect(transport);
+    await server.connect(transport);
     try {
       await transport.handleRequest(req, res, parsedBody);
     } finally {
@@ -1003,18 +1071,20 @@ var McpDocsServer = class {
    *
    * This method is designed for Web Standard environments that use
    * the Fetch API Request/Response pattern.
+   * Creates a fresh McpServer per request to avoid concurrency issues.
    *
    * @param request - Web Standard Request object
    * @returns Web Standard Response object
    */
   async handleWebRequest(request) {
     await this.initialize();
+    const server = this.createMcpServer();
     const transport = new WebStandardStreamableHTTPServerTransport({
       sessionIdGenerator: void 0,
       // Stateless mode
       enableJsonResponse: true
     });
-    await this.mcpServer.connect(transport);
+    await server.connect(transport);
     try {
       return await transport.handleRequest(request);
     } finally {
@@ -1028,9 +1098,8 @@ var McpDocsServer = class {
    */
   async getStatus() {
     let docCount = 0;
-    if (this.searchProvider instanceof FlexSearchProvider) {
-      const docs = this.searchProvider.getDocs();
-      docCount = docs ? Object.keys(docs).length : 0;
+    if (this.searchProvider?.getDocCount) {
+      docCount = this.searchProvider.getDocCount();
     }
     return {
       name: this.config.name,
@@ -1041,16 +1110,8 @@ var McpDocsServer = class {
       searchProvider: this.searchProvider?.name
     };
   }
-  /**
-   * Get the underlying McpServer instance
-   *
-   * Useful for advanced use cases like custom transports
-   */
-  getMcpServer() {
-    return this.mcpServer;
-  }
 };
 
-export { DEFAULT_OPTIONS, FlexSearchIndexer, FlexSearchProvider, McpDocsServer, buildSearchIndex, collectRoutes, mcpServerPlugin as default, discoverHtmlFiles, docsFetchTool, docsSearchTool, exportSearchIndex, extractContent, extractHeadingsFromMarkdown, extractSection, htmlToMarkdown, importSearchIndex, loadIndexer, loadSearchProvider, mcpServerPlugin, parseHtml, parseHtmlFile, searchIndex };
+export { DEFAULT_PLUGIN_OPTIONS, McpDocsServer, mcpServerPlugin as default, docsFetchTool, docsSearchTool, loadIndexer, loadSearchProvider, mcpServerPlugin };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map