docusaurus-plugin-mcp-server 0.6.0 → 0.7.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import path2 from 'path';
+import path from 'path';
 import fs3 from 'fs-extra';
 import pMap from 'p-map';
 import { unified } from 'unified';
@@ -34,7 +34,10 @@ var DEFAULT_OPTIONS = {
     name: "docs-mcp-server",
     version: "1.0.0"
   },
-  excludeRoutes: ["/404*", "/search*"]
+  excludeRoutes: ["/404*", "/search*"],
+  indexers: void 0,
+  // Default: ['flexsearch'] applied at runtime
+  search: "flexsearch"
 };
 function filterRoutes(routes, excludePatterns) {
   return routes.filter((route) => {
@@ -50,15 +53,15 @@ async function discoverHtmlFiles(outDir) {
   async function scanDirectory(dir) {
     const entries = await fs3.readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const fullPath = path2.join(dir, entry.name);
+      const fullPath = path.join(dir, entry.name);
       if (entry.isDirectory()) {
         if (["assets", "img", "static"].includes(entry.name)) {
           continue;
         }
         await scanDirectory(fullPath);
       } else if (entry.name === "index.html") {
-        const relativePath = path2.relative(outDir, fullPath);
-        let routePath = "/" + path2.dirname(relativePath).replace(/\\/g, "/");
+        const relativePath = path.relative(outDir, fullPath);
+        let routePath = "/" + path.dirname(relativePath).replace(/\\/g, "/");
         if (routePath === "/.") {
           routePath = "/";
         }
@@ -489,6 +492,201 @@ async function importSearchIndex(data) {
   return index;
 }
 
+// src/providers/indexers/flexsearch-indexer.ts
+var FlexSearchIndexer = class {
+  name = "flexsearch";
+  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.docsIndex = {};
+    this.exportedIndex = null;
+    this.docCount = 0;
+  }
+  async indexDocuments(docs) {
+    this.docCount = docs.length;
+    for (const doc of docs) {
+      this.docsIndex[doc.route] = doc;
+    }
+    console.log("[FlexSearch] Building search index...");
+    const searchIndex2 = buildSearchIndex(docs);
+    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(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 loadIndexer(specifier) {
+  if (specifier === "flexsearch") {
+    return new FlexSearchIndexer();
+  }
+  try {
+    const module = await import(specifier);
+    const IndexerClass = module.default;
+    if (typeof IndexerClass === "function") {
+      const instance = new IndexerClass();
+      if (!isContentIndexer(instance)) {
+        throw new Error(
+          `Invalid indexer module "${specifier}": does not implement ContentIndexer interface`
+        );
+      }
+      return instance;
+    }
+    if (isContentIndexer(IndexerClass)) {
+      return IndexerClass;
+    }
+    throw new Error(
+      `Invalid indexer module "${specifier}": must export a default class or ContentIndexer instance`
+    );
+  } 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 error;
+  }
+}
+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 isContentIndexer(obj) {
+  if (!obj || typeof obj !== "object") {
+    return false;
+  }
+  const indexer = obj;
+  return typeof indexer.name === "string" && typeof indexer.initialize === "function" && typeof indexer.indexDocuments === "function" && typeof indexer.finalize === "function";
+}
+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/plugin/docusaurus-plugin.ts
 function resolveOptions(options) {
   return {
@@ -545,6 +743,10 @@ function mcpServerPlugin(context, options) {
     async postBuild({ outDir }) {
       console.log("[MCP] Starting MCP artifact generation...");
       const startTime = Date.now();
+      if (resolvedOptions.indexers === false) {
+        console.log("[MCP] Indexing disabled, skipping artifact generation");
+        return;
+      }
       const routes = await collectRoutes(outDir, resolvedOptions.excludeRoutes);
       console.log(`[MCP] Found ${routes.length} routes to process`);
       if (routes.length === 0) {
@@ -569,27 +771,47 @@ function mcpServerPlugin(context, options) {
         console.warn("[MCP] No valid documents to index");
         return;
       }
-      const docsIndex = {};
-      for (const doc of validDocs) {
-        docsIndex[doc.route] = doc;
-      }
-      console.log("[MCP] Building search index...");
-      const searchIndex2 = buildSearchIndex(validDocs);
-      const exportedIndex = await exportSearchIndex(searchIndex2);
-      const manifest = {
-        version: resolvedOptions.server.version,
-        buildTime: (/* @__PURE__ */ new Date()).toISOString(),
-        docCount: validDocs.length,
+      const mcpOutputDir = path.join(outDir, resolvedOptions.outputDir);
+      const providerContext = {
+        baseUrl: context.siteConfig.url,
         serverName: resolvedOptions.server.name,
-        baseUrl: context.siteConfig.url
+        serverVersion: resolvedOptions.server.version,
+        outputDir: mcpOutputDir
       };
-      const mcpOutputDir = path2.join(outDir, resolvedOptions.outputDir);
+      const indexerSpecs = resolvedOptions.indexers ?? ["flexsearch"];
       await fs3.ensureDir(mcpOutputDir);
-      await Promise.all([
-        fs3.writeJson(path2.join(mcpOutputDir, "docs.json"), docsIndex, { spaces: 0 }),
-        fs3.writeJson(path2.join(mcpOutputDir, "search-index.json"), exportedIndex, { spaces: 0 }),
-        fs3.writeJson(path2.join(mcpOutputDir, "manifest.json"), manifest, { spaces: 2 })
-      ]);
+      const indexerNames = [];
+      for (const indexerSpec of indexerSpecs) {
+        try {
+          const indexer = await loadIndexer(indexerSpec);
+          if (indexer.shouldRun && !indexer.shouldRun()) {
+            console.log(`[MCP] Skipping indexer: ${indexer.name}`);
+            continue;
+          }
+          console.log(`[MCP] Running indexer: ${indexer.name}`);
+          await indexer.initialize(providerContext);
+          await indexer.indexDocuments(validDocs);
+          const artifacts = await indexer.finalize();
+          for (const [filename, content] of artifacts) {
+            await fs3.writeJson(path.join(mcpOutputDir, filename), content, { spaces: 0 });
+          }
+          indexerNames.push(indexer.name);
+        } catch (error) {
+          console.error(`[MCP] Error running indexer "${indexerSpec}":`, error);
+          throw error;
+        }
+      }
+      if (indexerNames.length > 0) {
+        const manifest = {
+          version: resolvedOptions.server.version,
+          buildTime: (/* @__PURE__ */ new Date()).toISOString(),
+          docCount: validDocs.length,
+          serverName: resolvedOptions.server.name,
+          baseUrl: context.siteConfig.url,
+          indexers: indexerNames
+        };
+        await fs3.writeJson(path.join(mcpOutputDir, "manifest.json"), manifest, { spaces: 2 });
+      }
       const elapsed = Date.now() - startTime;
       console.log(`[MCP] Artifacts written to ${mcpOutputDir}`);
       console.log(`[MCP] Generation complete in ${elapsed}ms`);
@@ -617,17 +839,6 @@ var docsSearchTool = {
     required: ["query"]
   }
 };
-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.";
@@ -667,28 +878,6 @@ var docsGetPageTool = {
     required: ["route"]
   }
 };
-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.";
@@ -742,52 +931,6 @@ var docsGetSectionTool = {
     required: ["route", "headingId"]
   }
 };
-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.";
@@ -824,8 +967,7 @@ function isDataConfig(config) {
 }
 var McpDocsServer = class {
   config;
-  docs = null;
-  searchIndex = null;
+  searchProvider = null;
   mcpServer;
   initialized = false;
   constructor(config) {
@@ -858,18 +1000,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(
@@ -882,16 +1032,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(
@@ -907,26 +1065,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
@@ -936,24 +1163,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 fs3.pathExists(this.config.docsPath)) {
-          this.docs = await fs3.readJson(this.config.docsPath);
-        } else {
-          throw new Error(`Docs file not found: ${this.config.docsPath}`);
-        }
-        if (await fs3.pathExists(this.config.indexPath)) {
-          const indexData = await fs3.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);
@@ -1014,12 +1243,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
     };
   }
   /**
@@ -1032,6 +1267,6 @@ var McpDocsServer = class {
   }
 };
 
-export { DEFAULT_OPTIONS, McpDocsServer, buildSearchIndex, collectRoutes, mcpServerPlugin as default, discoverHtmlFiles, docsGetPageTool, docsGetSectionTool, docsSearchTool, exportSearchIndex, extractContent, extractHeadingsFromMarkdown, extractSection, htmlToMarkdown, importSearchIndex, mcpServerPlugin, parseHtml, parseHtmlFile, searchIndex };
+export { DEFAULT_OPTIONS, FlexSearchIndexer, FlexSearchProvider, McpDocsServer, buildSearchIndex, collectRoutes, mcpServerPlugin as default, discoverHtmlFiles, docsGetPageTool, docsGetSectionTool, docsSearchTool, exportSearchIndex, extractContent, extractHeadingsFromMarkdown, extractSection, htmlToMarkdown, importSearchIndex, loadIndexer, loadSearchProvider, mcpServerPlugin, parseHtml, parseHtmlFile, searchIndex };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map