docusaurus-plugin-mcp-server 0.6.0 → 0.7.0

package/dist/adapters-entry.mjs

@@ -1,9 +1,10 @@
-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 { z } from 'zod';
 import FlexSearch from 'flexsearch';
+import fs from 'fs-extra';
+import 'http';
 
 // src/mcp/server.ts
 var FIELD_WEIGHTS = {
@@ -136,19 +137,126 @@ 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}`);
+      }
+      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)"
+    );
+  }
+  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(route) {
+    if (!this.docs) {
+      throw new Error("[FlexSearch] Provider not initialized");
+    }
+    if (this.docs[route]) {
+      return this.docs[route];
+    }
+    const normalizedRoute = route.startsWith("/") ? route : `/${route}`;
+    const withoutSlash = route.startsWith("/") ? route.slice(1) : route;
+    return this.docs[normalizedRoute] ?? this.docs[withoutSlash] ?? 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();
+  }
+  try {
+    const module = await import(specifier);
+    const ProviderClass = module.default;
+    if (typeof ProviderClass === "function") {
+      const instance = new ProviderClass();
+      if (!isSearchProvider(instance)) {
+        throw new Error(
+          `Invalid search provider module "${specifier}": does not implement SearchProvider interface`
+        );
+      }
+      return instance;
+    }
+    if (isSearchProvider(ProviderClass)) {
+      return ProviderClass;
+    }
+    throw new Error(
+      `Invalid search provider module "${specifier}": must export a default class or SearchProvider instance`
+    );
+  } 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.`
+      );
+    }
+    throw error;
+  }
+}
+function isSearchProvider(obj) {
+  if (!obj || typeof obj !== "object") {
+    return false;
+  }
+  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
-function executeDocsSearch(params, index, docs) {
-  const { query, limit = 5 } = params;
-  if (!query || typeof query !== "string" || query.trim().length === 0) {
-    throw new Error("Query parameter is required and must be a non-empty string");
-  }
-  const effectiveLimit = Math.min(Math.max(1, limit), 20);
-  const results = searchIndex(index, docs, query.trim(), {
-    limit: effectiveLimit
-  });
-  return results;
-}
 function formatSearchResults(results, baseUrl) {
   if (results.length === 0) {
     return "No matching documents found.";
@@ -174,28 +282,6 @@ function formatSearchResults(results, baseUrl) {
 }
 
 // src/mcp/tools/docs-get-page.ts
-function executeDocsGetPage(params, docs) {
-  const { route } = params;
-  if (!route || typeof route !== "string") {
-    throw new Error("Route parameter is required and must be a string");
-  }
-  let normalizedRoute = route.trim();
-  if (!normalizedRoute.startsWith("/")) {
-    normalizedRoute = "/" + normalizedRoute;
-  }
-  if (normalizedRoute.length > 1 && normalizedRoute.endsWith("/")) {
-    normalizedRoute = normalizedRoute.slice(0, -1);
-  }
-  const doc = docs[normalizedRoute];
-  if (!doc) {
-    const altRoute = normalizedRoute.slice(1);
-    if (docs[altRoute]) {
-      return docs[altRoute] ?? null;
-    }
-    return null;
-  }
-  return doc;
-}
 function formatPageContent(doc, baseUrl) {
   if (!doc) {
     return "Page not found. Please check the route path and try again.";
@@ -240,52 +326,6 @@ function extractSection(markdown, headingId, headings) {
 }
 
 // src/mcp/tools/docs-get-section.ts
-function executeDocsGetSection(params, docs) {
-  const { route, headingId } = params;
-  if (!route || typeof route !== "string") {
-    throw new Error("Route parameter is required and must be a string");
-  }
-  if (!headingId || typeof headingId !== "string") {
-    throw new Error("HeadingId parameter is required and must be a string");
-  }
-  let normalizedRoute = route.trim();
-  if (!normalizedRoute.startsWith("/")) {
-    normalizedRoute = "/" + normalizedRoute;
-  }
-  if (normalizedRoute.length > 1 && normalizedRoute.endsWith("/")) {
-    normalizedRoute = normalizedRoute.slice(0, -1);
-  }
-  const doc = docs[normalizedRoute];
-  if (!doc) {
-    return {
-      content: null,
-      doc: null,
-      headingText: null,
-      availableHeadings: []
-    };
-  }
-  const availableHeadings = doc.headings.map((h) => ({
-    id: h.id,
-    text: h.text,
-    level: h.level
-  }));
-  const heading = doc.headings.find((h) => h.id === headingId.trim());
-  if (!heading) {
-    return {
-      content: null,
-      doc,
-      headingText: null,
-      availableHeadings
-    };
-  }
-  const content = extractSection(doc.markdown, headingId.trim(), doc.headings);
-  return {
-    content,
-    doc,
-    headingText: heading.text,
-    availableHeadings
-  };
-}
 function formatSectionContent(result, headingId, baseUrl) {
   if (!result.doc) {
     return "Page not found. Please check the route path and try again.";
@@ -322,8 +362,7 @@ function isDataConfig(config) {
 }
 var McpDocsServer = class {
   config;
-  docs = null;
-  searchIndex = null;
+  searchProvider = null;
   mcpServer;
   initialized = false;
   constructor(config) {
@@ -356,18 +395,26 @@ var McpDocsServer = class {
       },
       async ({ query, limit }) => {
         await this.initialize();
-        if (!this.docs || !this.searchIndex) {
+        if (!this.searchProvider || !this.searchProvider.isReady()) {
           return {
             content: [{ type: "text", text: "Server not initialized. Please try again." }],
             isError: true
           };
         }
-        const results = executeDocsSearch({ query, limit }, this.searchIndex, this.docs);
-        return {
-          content: [
-            { type: "text", text: formatSearchResults(results, this.config.baseUrl) }
-          ]
-        };
+        try {
+          const results = await this.searchProvider.search(query, { limit });
+          return {
+            content: [
+              { type: "text", text: formatSearchResults(results, this.config.baseUrl) }
+            ]
+          };
+        } catch (error) {
+          console.error("[MCP] Search error:", error);
+          return {
+            content: [{ type: "text", text: `Search error: ${String(error)}` }],
+            isError: true
+          };
+        }
       }
     );
     this.mcpServer.registerTool(
@@ -380,16 +427,24 @@ var McpDocsServer = class {
       },
       async ({ route }) => {
         await this.initialize();
-        if (!this.docs) {
+        if (!this.searchProvider || !this.searchProvider.isReady()) {
           return {
             content: [{ type: "text", text: "Server not initialized. Please try again." }],
             isError: true
           };
         }
-        const doc = executeDocsGetPage({ route }, this.docs);
-        return {
-          content: [{ type: "text", text: formatPageContent(doc, this.config.baseUrl) }]
-        };
+        try {
+          const doc = await this.getDocument(route);
+          return {
+            content: [{ type: "text", text: formatPageContent(doc, this.config.baseUrl) }]
+          };
+        } catch (error) {
+          console.error("[MCP] Get page error:", error);
+          return {
+            content: [{ type: "text", text: `Error getting page: ${String(error)}` }],
+            isError: true
+          };
+        }
       }
     );
     this.mcpServer.registerTool(
@@ -405,26 +460,95 @@ var McpDocsServer = class {
       },
       async ({ route, headingId }) => {
         await this.initialize();
-        if (!this.docs) {
+        if (!this.searchProvider || !this.searchProvider.isReady()) {
           return {
             content: [{ type: "text", text: "Server not initialized. Please try again." }],
             isError: true
           };
         }
-        const result = executeDocsGetSection({ route, headingId }, this.docs);
-        return {
-          content: [
-            {
-              type: "text",
-              text: formatSectionContent(result, headingId, this.config.baseUrl)
-            }
-          ]
-        };
+        try {
+          const doc = await this.getDocument(route);
+          if (!doc) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: formatSectionContent(
+                    { content: null, doc: null, headingText: null, availableHeadings: [] },
+                    headingId,
+                    this.config.baseUrl
+                  )
+                }
+              ]
+            };
+          }
+          const availableHeadings = doc.headings.map((h) => ({
+            id: h.id,
+            text: h.text,
+            level: h.level
+          }));
+          const heading = doc.headings.find((h) => h.id === headingId.trim());
+          if (!heading) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: formatSectionContent(
+                    { content: null, doc, headingText: null, availableHeadings },
+                    headingId,
+                    this.config.baseUrl
+                  )
+                }
+              ]
+            };
+          }
+          const sectionContent = extractSection(doc.markdown, headingId.trim(), doc.headings);
+          return {
+            content: [
+              {
+                type: "text",
+                text: formatSectionContent(
+                  { content: sectionContent, doc, headingText: heading.text, availableHeadings },
+                  headingId,
+                  this.config.baseUrl
+                )
+              }
+            ]
+          };
+        } catch (error) {
+          console.error("[MCP] Get section error:", error);
+          return {
+            content: [{ type: "text", text: `Error getting section: ${String(error)}` }],
+            isError: true
+          };
+        }
       }
     );
   }
   /**
-   * Load docs and search index
+   * Get a document by route using the search provider
+   */
+  async getDocument(route) {
+    if (!this.searchProvider) {
+      return null;
+    }
+    if (this.searchProvider.getDocument) {
+      return this.searchProvider.getDocument(route);
+    }
+    if (this.searchProvider instanceof FlexSearchProvider) {
+      const docs = this.searchProvider.getDocs();
+      if (!docs) return null;
+      if (docs[route]) {
+        return docs[route];
+      }
+      const normalizedRoute = route.startsWith("/") ? route : `/${route}`;
+      const withoutSlash = route.startsWith("/") ? route.slice(1) : route;
+      return docs[normalizedRoute] ?? docs[withoutSlash] ?? null;
+    }
+    return null;
+  }
+  /**
+   * Load docs and search index using the configured search provider
    *
    * For file-based config: reads from disk
    * For data config: uses pre-loaded data directly
@@ -434,24 +558,26 @@ var McpDocsServer = class {
       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)) {
-        this.docs = this.config.docs;
-        this.searchIndex = await importSearchIndex(this.config.searchIndexData);
+        initData.docs = this.config.docs;
+        initData.indexData = this.config.searchIndexData;
       } else if (isFileConfig(this.config)) {
-        if (await fs.pathExists(this.config.docsPath)) {
-          this.docs = await fs.readJson(this.config.docsPath);
-        } else {
-          throw new Error(`Docs file not found: ${this.config.docsPath}`);
-        }
-        if (await fs.pathExists(this.config.indexPath)) {
-          const indexData = await fs.readJson(this.config.indexPath);
-          this.searchIndex = await importSearchIndex(indexData);
-        } else {
-          throw new Error(`Search index not found: ${this.config.indexPath}`);
-        }
+        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);
@@ -512,12 +638,18 @@ var McpDocsServer = class {
    * Useful for health checks and debugging
    */
   async getStatus() {
+    let docCount = 0;
+    if (this.searchProvider instanceof FlexSearchProvider) {
+      const docs = this.searchProvider.getDocs();
+      docCount = docs ? Object.keys(docs).length : 0;
+    }
     return {
       name: this.config.name,
       version: this.config.version ?? "1.0.0",
       initialized: this.initialized,
-      docCount: this.docs ? Object.keys(this.docs).length : 0,
-      baseUrl: this.config.baseUrl
+      docCount,
+      baseUrl: this.config.baseUrl,
+      searchProvider: this.searchProvider?.name
     };
   }
   /**