docusaurus-plugin-mcp-server 0.7.0 → 0.9.0

package/dist/index.mjs

@@ -5,6 +5,7 @@ import { unified } from 'unified';
 import rehypeParse from 'rehype-parse';
 import { select } from 'hast-util-select';
 import { toString } from 'hast-util-to-string';
+import { toHtml } from 'hast-util-to-html';
 import rehypeRemark from 'rehype-remark';
 import remarkStringify from 'remark-stringify';
 import remarkGfm from 'remark-gfm';
@@ -182,7 +183,7 @@ async function extractContent(filePath, options) {
   let contentHtml = "";
   if (contentElement) {
     const cleanedElement = cleanContentElement(contentElement, options.excludeSelectors);
-    contentHtml = serializeElement(cleanedElement);
+    contentHtml = toHtml(cleanedElement);
   }
   return {
     title,
@@ -190,57 +191,6 @@ async function extractContent(filePath, options) {
     contentHtml
   };
 }
-function serializeElement(element) {
-  const voidElements = /* @__PURE__ */ new Set([
-    "area",
-    "base",
-    "br",
-    "col",
-    "embed",
-    "hr",
-    "img",
-    "input",
-    "link",
-    "meta",
-    "param",
-    "source",
-    "track",
-    "wbr"
-  ]);
-  function serialize(node) {
-    if (!node || typeof node !== "object") return "";
-    const n = node;
-    if (n.type === "text") {
-      return n.value ?? "";
-    }
-    if (n.type === "element" && n.tagName) {
-      const tagName = n.tagName;
-      const props = n.properties ?? {};
-      const attrs = [];
-      for (const [key, value] of Object.entries(props)) {
-        if (key === "className" && Array.isArray(value)) {
-          attrs.push(`class="${value.join(" ")}"`);
-        } else if (typeof value === "boolean") {
-          if (value) attrs.push(key);
-        } else if (value !== void 0 && value !== null) {
-          attrs.push(`${key}="${String(value)}"`);
-        }
-      }
-      const attrStr = attrs.length > 0 ? " " + attrs.join(" ") : "";
-      if (voidElements.has(tagName)) {
-        return `<${tagName}${attrStr} />`;
-      }
-      const children = n.children ?? [];
-      const childrenHtml = children.map(serialize).join("");
-      return `<${tagName}${attrStr}>${childrenHtml}</${tagName}>`;
-    }
-    if (n.type === "root" && n.children) {
-      return n.children.map(serialize).join("");
-    }
-    return "";
-  }
-  return serialize(element);
-}
 async function htmlToMarkdown(html) {
   if (!html || html.trim().length === 0) {
     return "";
@@ -377,9 +327,10 @@ function createSearchIndex() {
     }
   });
 }
-function addDocumentToIndex(index, doc) {
+function addDocumentToIndex(index, doc, baseUrl) {
+  const id = baseUrl ? `${baseUrl.replace(/\/$/, "")}${doc.route}` : doc.route;
   const indexable = {
-    id: doc.route,
+    id,
     title: doc.title,
     content: doc.markdown,
     headings: doc.headings.map((h) => h.text).join(" "),
@@ -387,10 +338,10 @@ function addDocumentToIndex(index, doc) {
   };
   index.add(indexable);
 }
-function buildSearchIndex(docs) {
+function buildSearchIndex(docs, baseUrl) {
   const index = createSearchIndex();
   for (const doc of docs) {
-    addDocumentToIndex(index, doc);
+    addDocumentToIndex(index, doc, baseUrl);
   }
   return index;
 }
@@ -421,6 +372,8 @@ function searchIndex(index, docs, query, options = {}) {
     const doc = docs[docId];
     if (!doc) continue;
     results.push({
+      url: docId,
+      // docId is the full URL when indexed with baseUrl
       route: doc.route,
       title: doc.title,
       score,
@@ -495,6 +448,7 @@ async function importSearchIndex(data) {
 // src/providers/indexers/flexsearch-indexer.ts
 var FlexSearchIndexer = class {
   name = "flexsearch";
+  baseUrl = "";
   docsIndex = {};
   exportedIndex = null;
   docCount = 0;
@@ -505,7 +459,8 @@ var FlexSearchIndexer = class {
   shouldRun() {
     return true;
   }
-  async initialize(_context) {
+  async initialize(context) {
+    this.baseUrl = context.baseUrl.replace(/\/$/, "");
     this.docsIndex = {};
     this.exportedIndex = null;
     this.docCount = 0;
@@ -513,10 +468,11 @@ var FlexSearchIndexer = class {
   async indexDocuments(docs) {
     this.docCount = docs.length;
     for (const doc of docs) {
-      this.docsIndex[doc.route] = doc;
+      const fullUrl = `${this.baseUrl}${doc.route}`;
+      this.docsIndex[fullUrl] = doc;
     }
     console.log("[FlexSearch] Building search index...");
-    const searchIndex2 = buildSearchIndex(docs);
+    const searchIndex2 = buildSearchIndex(docs, this.baseUrl);
     this.exportedIndex = await exportSearchIndex(searchIndex2);
     console.log(`[FlexSearch] Indexed ${this.docCount} documents`);
   }
@@ -576,16 +532,11 @@ var FlexSearchProvider = class {
     const limit = options?.limit ?? 5;
     return searchIndex(this.searchIndex, this.docs, query, { limit });
   }
-  async getDocument(route) {
+  async getDocument(url) {
     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;
+    return this.docs[url] ?? null;
   }
   async healthCheck() {
     if (!this.isReady()) {
@@ -818,28 +769,16 @@ function mcpServerPlugin(context, options) {
     }
   };
 }
-
-// src/mcp/tools/docs-search.ts
+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)")
+};
 var docsSearchTool = {
   name: "docs_search",
-  description: "Search across developer documentation. Returns ranked results with snippets and matching headings.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      query: {
-        type: "string",
-        description: "Search query string"
-      },
-      limit: {
-        type: "number",
-        description: "Maximum number of results to return (default: 5, max: 20)",
-        default: 5
-      }
-    },
-    required: ["query"]
-  }
+  description: "Search the documentation for relevant pages. Returns matching documents with URLs, snippets, and relevance scores. Use this to find information across all documentation.",
+  inputSchema: docsSearchInputSchema
 };
-function formatSearchResults(results, baseUrl) {
+function formatSearchResults(results) {
   if (results.length === 0) {
     return "No matching documents found.";
   }
@@ -849,38 +788,29 @@ function formatSearchResults(results, baseUrl) {
     const result = results[i];
     if (!result) continue;
     lines.push(`${i + 1}. **${result.title}**`);
-    if (baseUrl) {
-      const fullUrl = `${baseUrl.replace(/\/$/, "")}${result.route}`;
-      lines.push(`   URL: ${fullUrl}`);
-    }
-    lines.push(`   Route: ${result.route}`);
+    lines.push(`   URL: ${result.url}`);
     if (result.matchingHeadings && result.matchingHeadings.length > 0) {
       lines.push(`   Matching sections: ${result.matchingHeadings.join(", ")}`);
     }
     lines.push(`   ${result.snippet}`);
     lines.push("");
   }
+  lines.push("Use docs_fetch with the URL to retrieve the full page content.");
   return lines.join("\n");
 }
-
-// src/mcp/tools/docs-get-page.ts
-var docsGetPageTool = {
-  name: "docs_get_page",
-  description: "Retrieve the full content of a documentation page as markdown. Use this after searching to get complete page content.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      route: {
-        type: "string",
-        description: "The route path of the page (e.g., /docs/getting-started)"
-      }
-    },
-    required: ["route"]
-  }
+var docsFetchInputSchema = {
+  url: z.string().url().describe(
+    'The full URL of the page to fetch (e.g., "https://docs.example.com/docs/getting-started")'
+  )
+};
+var docsFetchTool = {
+  name: "docs_fetch",
+  description: "Fetch the complete content of a documentation page. Use this after searching to get the full markdown content of a specific page.",
+  inputSchema: docsFetchInputSchema
 };
-function formatPageContent(doc, baseUrl) {
+function formatPageContent(doc) {
   if (!doc) {
-    return "Page not found. Please check the route path and try again.";
+    return "Page not found. Please check the URL and try again.";
   }
   const lines = [];
   lines.push(`# ${doc.title}`);
@@ -889,12 +819,6 @@ function formatPageContent(doc, baseUrl) {
     lines.push(`> ${doc.description}`);
     lines.push("");
   }
-  if (baseUrl) {
-    const fullUrl = `${baseUrl.replace(/\/$/, "")}${doc.route}`;
-    lines.push(`**URL:** ${fullUrl}`);
-  }
-  lines.push(`**Route:** ${doc.route}`);
-  lines.push("");
   if (doc.headings.length > 0) {
     lines.push("## Contents");
     lines.push("");
@@ -912,52 +836,6 @@ function formatPageContent(doc, baseUrl) {
   return lines.join("\n");
 }
 
-// src/mcp/tools/docs-get-section.ts
-var docsGetSectionTool = {
-  name: "docs_get_section",
-  description: "Retrieve a specific section of a documentation page by heading ID. Use this to get focused content from a larger page.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      route: {
-        type: "string",
-        description: "The route path of the page (e.g., /docs/getting-started)"
-      },
-      headingId: {
-        type: "string",
-        description: "The ID of the heading to retrieve (e.g., authentication)"
-      }
-    },
-    required: ["route", "headingId"]
-  }
-};
-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;
@@ -986,17 +864,14 @@ var McpDocsServer = class {
     this.registerTools();
   }
   /**
-   * Register all MCP tools using the SDK's registerTool API
+   * Register all MCP tools using definitions from tool files
    */
   registerTools() {
     this.mcpServer.registerTool(
-      "docs_search",
+      docsSearchTool.name,
       {
-        description: "Search the documentation for relevant pages. Returns matching documents with snippets and relevance scores. Use this to find information across all documentation.",
-        inputSchema: {
-          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)")
-        }
+        description: docsSearchTool.description,
+        inputSchema: docsSearchTool.inputSchema
       },
       async ({ query, limit }) => {
         await this.initialize();
@@ -1009,9 +884,7 @@ var McpDocsServer = class {
         try {
           const results = await this.searchProvider.search(query, { limit });
           return {
-            content: [
-              { type: "text", text: formatSearchResults(results, this.config.baseUrl) }
-            ]
+            content: [{ type: "text", text: formatSearchResults(results) }]
           };
         } catch (error) {
           console.error("[MCP] Search error:", error);
@@ -1023,47 +896,12 @@ var McpDocsServer = class {
       }
     );
     this.mcpServer.registerTool(
-      "docs_get_page",
-      {
-        description: "Retrieve the complete content of a documentation page as markdown. 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.searchProvider || !this.searchProvider.isReady()) {
-          return {
-            content: [{ type: "text", text: "Server not initialized. Please try again." }],
-            isError: true
-          };
-        }
-        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(
-      "docs_get_section",
+      docsFetchTool.name,
       {
-        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")'
-          )
-        }
+        description: docsFetchTool.description,
+        inputSchema: docsFetchTool.inputSchema
       },
-      async ({ route, headingId }) => {
+      async ({ url }) => {
         await this.initialize();
         if (!this.searchProvider || !this.searchProvider.isReady()) {
           return {
@@ -1072,58 +910,14 @@ var McpDocsServer = class {
           };
         }
         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);
+          const doc = await this.getDocument(url);
           return {
-            content: [
-              {
-                type: "text",
-                text: formatSectionContent(
-                  { content: sectionContent, doc, headingText: heading.text, availableHeadings },
-                  headingId,
-                  this.config.baseUrl
-                )
-              }
-            ]
+            content: [{ type: "text", text: formatPageContent(doc) }]
           };
         } catch (error) {
-          console.error("[MCP] Get section error:", error);
+          console.error("[MCP] Fetch error:", error);
           return {
-            content: [{ type: "text", text: `Error getting section: ${String(error)}` }],
+            content: [{ type: "text", text: `Error fetching page: ${String(error)}` }],
             isError: true
           };
         }
@@ -1131,24 +925,14 @@ var McpDocsServer = class {
     );
   }
   /**
-   * Get a document by route using the search provider
+   * Get a document by URL using the search provider
    */
-  async getDocument(route) {
+  async getDocument(url) {
     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 this.searchProvider.getDocument(url);
     }
     return null;
   }
@@ -1267,6 +1051,6 @@ var McpDocsServer = class {
   }
 };
 
-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 };
+export { DEFAULT_OPTIONS, FlexSearchIndexer, FlexSearchProvider, McpDocsServer, buildSearchIndex, collectRoutes, discoverHtmlFiles, docsFetchTool, docsSearchTool, exportSearchIndex, extractContent, extractHeadingsFromMarkdown, extractSection, htmlToMarkdown, importSearchIndex, loadIndexer, loadSearchProvider, mcpServerPlugin, parseHtml, parseHtmlFile, searchIndex };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map