docusaurus-plugin-mcp-server 0.11.0 → 0.12.0

package/dist/cli/verify.js

@@ -1,17 +1,20 @@
 #!/usr/bin/env node
+import FlexSearch from 'flexsearch';
 import fs2 from 'fs-extra';
 import path from 'path';
 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 FlexSearch from 'flexsearch';
 import { z } from 'zod';
 
-var FIELD_WEIGHTS = {
-  title: 3,
-  headings: 2,
-  description: 1.5,
-  content: 1
+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;
@@ -47,7 +50,7 @@ function createSearchIndex() {
     }
   });
 }
-function searchIndex(index, docs, query, options = {}) {
+function querySearchIndex(index, docs, query, options = {}) {
   const { limit = 16 } = options;
   const rawResults = index.search(query, {
     limit: limit * 3,
@@ -139,84 +142,111 @@ async function importSearchIndex(data) {
   }
   return index;
 }
-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 fs2.pathExists(initData.docsPath)) {
-        this.docs = await fs2.readJson(initData.docsPath);
-      } else {
-        throw new Error(`[FlexSearch] Docs file not found: ${initData.docsPath}`);
+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/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 fs2.pathExists(initData.docsPath)) {
+            this.docs = await fs2.readJson(initData.docsPath);
+          } else {
+            throw new Error(`[FlexSearch] Docs file not found: ${initData.docsPath}`);
+          }
+          if (await fs2.pathExists(initData.indexPath)) {
+            const indexData = await fs2.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)"
+        );
       }
-      if (await fs2.pathExists(initData.indexPath)) {
-        const indexData = await fs2.readJson(initData.indexPath);
-        this.searchIndex = await importSearchIndex(indexData);
-      } else {
-        throw new Error(`[FlexSearch] Search index not found: ${initData.indexPath}`);
+      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;
       }
-      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 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 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);
@@ -239,7 +269,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;
@@ -252,6 +283,9 @@ function isSearchProvider(obj) {
   const provider = obj;
   return typeof provider.name === "string" && typeof provider.initialize === "function" && typeof provider.isReady === "function" && typeof provider.search === "function";
 }
+
+// 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(16).describe("Maximum number of results to return (1-20, default: 16)")
@@ -329,14 +363,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: {
@@ -344,20 +386,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." }],
@@ -372,20 +414,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." }],
@@ -400,7 +446,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
           };
         }
@@ -424,43 +475,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
@@ -468,13 +530,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 {
@@ -486,18 +549,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 {
@@ -511,9 +576,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,
@@ -524,14 +588,6 @@ var McpDocsServer = class {
       searchProvider: this.searchProvider?.name
     };
   }
-  /**
-   * Get the underlying McpServer instance
-   *
-   * Useful for advanced use cases like custom transports
-   */
-  getMcpServer() {
-    return this.mcpServer;
-  }
 };
 
 // src/cli/verify.ts