docusaurus-plugin-mcp-server 0.10.2 → 0.12.0

package/dist/adapters-entry.js

@@ -1,17 +1,19 @@
+import FlexSearch from 'flexsearch';
+import fs from 'fs-extra';
 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 fs from 'fs-extra';
 import { z } from 'zod';
 import { createServer } from 'http';
 
-// src/mcp/server.ts
-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;
@@ -19,9 +21,9 @@ function englishStemmer(word) {
 }
 function createSearchIndex() {
   return new FlexSearch.Document({
-    // Use 'full' tokenization for substring matching
-    // This allows "auth" to match "authentication"
-    tokenize: "full",
+    // 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)
@@ -47,8 +49,8 @@ function createSearchIndex() {
     }
   });
 }
-function searchIndex(index, docs, query, options = {}) {
-  const { limit = 5 } = options;
+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
@@ -139,84 +141,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 fs.pathExists(initData.docsPath)) {
-        this.docs = await fs.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 fs.pathExists(initData.docsPath)) {
+            this.docs = await fs.readJson(initData.docsPath);
+          } else {
+            throw new Error(`[FlexSearch] Docs file not found: ${initData.docsPath}`);
+          }
+          if (await fs.pathExists(initData.indexPath)) {
+            const indexData = await fs.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 fs.pathExists(initData.indexPath)) {
-        const indexData = await fs.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 ?? 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 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 +268,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,9 +282,12 @@ 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(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",
@@ -329,14 +362,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 +385,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 +413,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 +445,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 +474,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 +529,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 +548,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 +575,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,37 +587,29 @@ 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/adapters/cors.ts
-var CORS_HEADERS = {
-  "Access-Control-Allow-Origin": "*",
-  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-  "Access-Control-Allow-Headers": "Content-Type"
-};
-function getCorsHeaders() {
-  return { ...CORS_HEADERS };
+function getCorsHeaders(origin = "*") {
+  return {
+    "Access-Control-Allow-Origin": origin,
+    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type"
+  };
 }
 
 // src/adapters/vercel.ts
 function createVercelHandler(config) {
   let server = null;
+  const { corsOrigin, ...serverConfig } = config;
   function getServer() {
     if (!server) {
-      server = new McpDocsServer(config);
+      server = new McpDocsServer(serverConfig);
     }
     return server;
   }
   return async function handler(req, res) {
-    const corsHeaders = getCorsHeaders();
+    const corsHeaders = getCorsHeaders(corsOrigin);
     if (req.method === "OPTIONS") {
       res.writeHead(204, corsHeaders);
       res.end();
@@ -588,14 +643,13 @@ function createVercelHandler(config) {
       const mcpServer = getServer();
       await mcpServer.handleHttpRequest(req, res, req.body);
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
       console.error("MCP Server Error:", error);
       return res.status(500).json({
         jsonrpc: "2.0",
         id: null,
         error: {
           code: -32603,
-          message: `Internal server error: ${errorMessage}`
+          message: "Internal server error"
         }
       });
     }
@@ -635,14 +689,15 @@ async function responseToNetlify(response, additionalHeaders) {
 }
 function createNetlifyHandler(config) {
   let server = null;
+  const { corsOrigin, ...serverConfig } = config;
   function getServer() {
     if (!server) {
-      server = new McpDocsServer(config);
+      server = new McpDocsServer(serverConfig);
     }
     return server;
   }
   return async function handler(event, _context) {
-    const corsHeaders = getCorsHeaders();
+    const corsHeaders = getCorsHeaders(corsOrigin);
     const headers = {
       "Content-Type": "application/json",
       ...corsHeaders
@@ -682,7 +737,6 @@ function createNetlifyHandler(config) {
       const response = await mcpServer.handleWebRequest(request);
       return await responseToNetlify(response, corsHeaders);
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
       console.error("MCP Server Error:", error);
       return {
         statusCode: 500,
@@ -692,7 +746,7 @@ function createNetlifyHandler(config) {
           id: null,
           error: {
             code: -32603,
-            message: `Internal server error: ${errorMessage}`
+            message: "Internal server error"
           }
         })
       };
@@ -703,12 +757,13 @@ function createNetlifyHandler(config) {
 // src/adapters/cloudflare.ts
 function createCloudflareHandler(config) {
   let server = null;
+  const { corsOrigin, ...rest } = config;
   const serverConfig = {
-    docs: config.docs,
-    searchIndexData: config.searchIndexData,
-    name: config.name,
-    version: config.version,
-    baseUrl: config.baseUrl
+    docs: rest.docs,
+    searchIndexData: rest.searchIndexData,
+    name: rest.name,
+    version: rest.version,
+    baseUrl: rest.baseUrl
   };
   function getServer() {
     if (!server) {
@@ -717,7 +772,7 @@ function createCloudflareHandler(config) {
     return server;
   }
   return async function fetch(request) {
-    const corsHeaders = getCorsHeaders();
+    const corsHeaders = getCorsHeaders(corsOrigin);
     if (request.method === "OPTIONS") {
       return new Response(null, { status: 204, headers: corsHeaders });
     }
@@ -758,7 +813,6 @@ function createCloudflareHandler(config) {
         headers: newHeaders
       });
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
       console.error("MCP Server Error:", error);
       return new Response(
         JSON.stringify({
@@ -766,7 +820,7 @@ function createCloudflareHandler(config) {
           id: null,
           error: {
             code: -32603,
-            message: `Internal server error: ${errorMessage}`
+            message: "Internal server error"
           }
         }),
         {
@@ -891,31 +945,21 @@ function generateCloudflareFiles(name, baseUrl) {
       content: `/**
  * Cloudflare Worker for MCP server
  *
- * Note: This requires bundling docs.json and search-index.json with the worker,
- * or using Cloudflare KV/R2 for storage.
- *
- * For bundling, use wrangler with custom build configuration.
+ * Workers cannot access the filesystem, so docs and search index
+ * are imported as JSON modules and passed as pre-loaded data.
  */
 
 import { createCloudflareHandler } from 'docusaurus-plugin-mcp-server/adapters';
-
-// Option 1: Import bundled data (requires bundler configuration)
-// import docs from '../build/mcp/docs.json';
-// import searchIndex from '../build/mcp/search-index.json';
-
-// Option 2: Use KV bindings (requires KV namespace configuration)
-// const docs = await env.MCP_KV.get('docs', { type: 'json' });
-// const searchIndex = await env.MCP_KV.get('search-index', { type: 'json' });
+import docs from '../build/mcp/docs.json';
+import searchIndex from '../build/mcp/search-index.json';
 
 export default {
   fetch: createCloudflareHandler({
+    docs,
+    searchIndexData: searchIndex,
     name: '${name}',
     version: '1.0.0',
     baseUrl: '${baseUrl}',
-    // docsPath and indexPath are used for file-based loading
-    // For Workers, you'll need to configure data loading differently
-    docsPath: './mcp/docs.json',
-    indexPath: './mcp/search-index.json',
   }),
 };
 `
@@ -927,14 +971,10 @@ export default {
 main = "workers/mcp.js"
 compatibility_date = "2024-01-01"
 
-# Uncomment to use KV for storing docs
-# [[kv_namespaces]]
-# binding = "MCP_KV"
-# id = "your-kv-namespace-id"
-
-# Static assets (the Docusaurus build)
-# [site]
-# bucket = "./build"
+# Allow importing JSON files as modules
+[[rules]]
+type = "Data"
+globs = ["**/*.json"]
 `
     }
   ];
@@ -994,8 +1034,21 @@ function createNodeHandler(options) {
       const mcpServer = getServer();
       await mcpServer.handleHttpRequest(req, res, body);
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
       console.error("[MCP] Request error:", error);
+      if (error instanceof Error && error.message === "Request body too large") {
+        res.writeHead(413, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            jsonrpc: "2.0",
+            id: null,
+            error: {
+              code: -32600,
+              message: "Request body too large"
+            }
+          })
+        );
+        return;
+      }
       res.writeHead(500, { "Content-Type": "application/json" });
       res.end(
         JSON.stringify({
@@ -1003,7 +1056,7 @@ function createNodeHandler(options) {
           id: null,
           error: {
             code: -32603,
-            message: `Internal server error: ${message}`
+            message: "Internal server error"
           }
         })
       );
@@ -1014,11 +1067,19 @@ function createNodeServer(options) {
   const handler = createNodeHandler(options);
   return createServer(handler);
 }
+var MAX_BODY_SIZE = 1024 * 1024;
 async function parseRequestBody(req) {
   return new Promise((resolve, reject) => {
     let body = "";
+    let size = 0;
     req.on("data", (chunk) => {
-      body += chunk;
+      size += typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.length;
+      if (size > MAX_BODY_SIZE) {
+        req.destroy();
+        reject(new Error("Request body too large"));
+        return;
+      }
+      body += chunk.toString();
     });
     req.on("end", () => {
       try {