docusaurus-plugin-mcp-server 0.8.0 → 0.10.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-fetch.ts
+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 full page content.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      route: {
-        type: "string",
-        description: "The route path of the page (e.g., /docs/getting-started)"
-      }
-    },
-    required: ["route"]
-  }
+  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("");
@@ -940,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();
@@ -963,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);
@@ -977,14 +896,12 @@ var McpDocsServer = class {
       }
     );
     this.mcpServer.registerTool(
-      "docs_fetch",
+      docsFetchTool.name,
       {
-        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")')
-        }
+        description: docsFetchTool.description,
+        inputSchema: docsFetchTool.inputSchema
       },
-      async ({ route }) => {
+      async ({ url }) => {
         await this.initialize();
         if (!this.searchProvider || !this.searchProvider.isReady()) {
           return {
@@ -993,14 +910,14 @@ var McpDocsServer = class {
           };
         }
         try {
-          const doc = await this.getDocument(route);
+          const doc = await this.getDocument(url);
           return {
-            content: [{ type: "text", text: formatPageContent(doc, this.config.baseUrl) }]
+            content: [{ type: "text", text: formatPageContent(doc) }]
           };
         } catch (error) {
-          console.error("[MCP] Get page error:", error);
+          console.error("[MCP] Fetch error:", error);
           return {
-            content: [{ type: "text", text: `Error getting page: ${String(error)}` }],
+            content: [{ type: "text", text: `Error fetching page: ${String(error)}` }],
             isError: true
           };
         }
@@ -1008,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;
   }