docusaurus-plugin-mcp-server 0.6.0 → 0.8.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/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;
+// 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 formatSearchResults(results, baseUrl) {
   if (results.length === 0) {
     return "No matching documents found.";
@@ -173,29 +281,7 @@ function formatSearchResults(results, baseUrl) {
   return lines.join("\n");
 }
 
-// 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;
-}
+// src/mcp/tools/docs-fetch.ts
 function formatPageContent(doc, baseUrl) {
   if (!doc) {
     return "Page not found. Please check the route path and try again.";
@@ -230,89 +316,6 @@ function formatPageContent(doc, baseUrl) {
   return lines.join("\n");
 }
 
-// src/processing/heading-extractor.ts
-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();
-}
-
-// 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.";
-  }
-  if (!result.content) {
-    const lines2 = [`Section "${headingId}" not found in this document.`, "", "Available sections:"];
-    for (const heading of result.availableHeadings) {
-      const indent = "  ".repeat(heading.level - 1);
-      lines2.push(`${indent}- ${heading.text} (id: ${heading.id})`);
-    }
-    return lines2.join("\n");
-  }
-  const lines = [];
-  const fullUrl = baseUrl ? `${baseUrl.replace(/\/$/, "")}${result.doc.route}#${headingId}` : null;
-  lines.push(`# ${result.headingText}`);
-  if (fullUrl) {
-    lines.push(`> From: ${result.doc.title} - ${fullUrl}`);
-  } else {
-    lines.push(`> From: ${result.doc.title} (${result.doc.route})`);
-  }
-  lines.push("");
-  lines.push("---");
-  lines.push("");
-  lines.push(result.content);
-  return lines.join("\n");
-}
-
 // src/mcp/server.ts
 function isFileConfig(config) {
   return "docsPath" in config && "indexPath" in config;
@@ -322,8 +325,7 @@ function isDataConfig(config) {
 }
 var McpDocsServer = class {
   config;
-  docs = null;
-  searchIndex = null;
+  searchProvider = null;
   mcpServer;
   initialized = false;
   constructor(config) {
@@ -356,75 +358,83 @@ 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(
-      "docs_get_page",
+      "docs_fetch",
       {
-        description: "Retrieve the complete content of a documentation page as markdown. Use this when you need the full content of a specific page.",
+        description: "Fetch the complete content of a documentation page. Use this when you need the full content of a specific page.",
         inputSchema: {
           route: z.string().min(1).describe('The page route path (e.g., "/docs/getting-started" or "/api/reference")')
         }
       },
       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) }]
-        };
-      }
-    );
-    this.mcpServer.registerTool(
-      "docs_get_section",
-      {
-        description: "Retrieve a specific section from a documentation page by its heading ID. Use this when you need only a portion of a page rather than the entire content.",
-        inputSchema: {
-          route: z.string().min(1).describe("The page route path"),
-          headingId: z.string().min(1).describe(
-            'The heading ID of the section to extract (e.g., "installation", "api-reference")'
-          )
-        }
-      },
-      async ({ route, headingId }) => {
-        await this.initialize();
-        if (!this.docs) {
+        try {
+          const doc = await this.getDocument(route);
           return {
-            content: [{ type: "text", text: "Server not initialized. Please try again." }],
+            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
           };
         }
-        const result = executeDocsGetSection({ route, headingId }, this.docs);
-        return {
-          content: [
-            {
-              type: "text",
-              text: formatSectionContent(result, headingId, this.config.baseUrl)
-            }
-          ]
-        };
       }
     );
   }
   /**
-   * 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 +444,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 +524,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
     };
   }
   /**