docusaurus-plugin-mcp-server 0.5.0

package/dist/index.mjs

@@ -0,0 +1,1037 @@
+import path2 from 'path';
+import fs3 from 'fs-extra';
+import pMap from 'p-map';
+import { unified } from 'unified';
+import rehypeParse from 'rehype-parse';
+import { select } from 'hast-util-select';
+import { toString } from 'hast-util-to-string';
+import rehypeRemark from 'rehype-remark';
+import remarkStringify from 'remark-stringify';
+import remarkGfm from 'remark-gfm';
+import FlexSearch from 'flexsearch';
+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';
+
+// src/plugin/docusaurus-plugin.ts
+
+// src/types/index.ts
+var DEFAULT_OPTIONS = {
+  outputDir: "mcp",
+  contentSelectors: ["article", "main", ".main-wrapper", '[role="main"]'],
+  excludeSelectors: [
+    "nav",
+    "header",
+    "footer",
+    "aside",
+    '[role="navigation"]',
+    '[role="banner"]',
+    '[role="contentinfo"]'
+  ],
+  minContentLength: 50,
+  server: {
+    name: "docs-mcp-server",
+    version: "1.0.0"
+  },
+  excludeRoutes: ["/404*", "/search*"]
+};
+function filterRoutes(routes, excludePatterns) {
+  return routes.filter((route) => {
+    return !excludePatterns.some((pattern) => {
+      const regexPattern = pattern.replace(/\*/g, ".*").replace(/\?/g, ".");
+      const regex = new RegExp(`^${regexPattern}$`);
+      return regex.test(route.path);
+    });
+  });
+}
+async function discoverHtmlFiles(outDir) {
+  const routes = [];
+  async function scanDirectory(dir) {
+    const entries = await fs3.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path2.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, "/");
+        if (routePath === "/.") {
+          routePath = "/";
+        }
+        routes.push({
+          path: routePath,
+          htmlPath: fullPath
+        });
+      }
+    }
+  }
+  await scanDirectory(outDir);
+  return routes;
+}
+async function collectRoutes(outDir, excludePatterns) {
+  const allRoutes = await discoverHtmlFiles(outDir);
+  const filteredRoutes = filterRoutes(allRoutes, excludePatterns);
+  const uniqueRoutes = /* @__PURE__ */ new Map();
+  for (const route of filteredRoutes) {
+    if (!uniqueRoutes.has(route.path)) {
+      uniqueRoutes.set(route.path, route);
+    }
+  }
+  return Array.from(uniqueRoutes.values());
+}
+function parseHtml(html) {
+  const processor = unified().use(rehypeParse);
+  return processor.parse(html);
+}
+async function parseHtmlFile(filePath) {
+  const html = await fs3.readFile(filePath, "utf-8");
+  return parseHtml(html);
+}
+function extractTitle(tree) {
+  const h1Element = select("h1", tree);
+  if (h1Element) {
+    return toString(h1Element).trim();
+  }
+  const titleElement = select("title", tree);
+  if (titleElement) {
+    return toString(titleElement).trim();
+  }
+  return "Untitled";
+}
+function extractDescription(tree) {
+  const metaDescription = select('meta[name="description"]', tree);
+  if (metaDescription && metaDescription.properties?.content) {
+    return String(metaDescription.properties.content);
+  }
+  const ogDescription = select('meta[property="og:description"]', tree);
+  if (ogDescription && ogDescription.properties?.content) {
+    return String(ogDescription.properties.content);
+  }
+  return "";
+}
+function findContentElement(tree, selectors) {
+  for (const selector of selectors) {
+    const element = select(selector, tree);
+    if (element) {
+      const text = toString(element).trim();
+      if (text.length > 50) {
+        return element;
+      }
+    }
+  }
+  return null;
+}
+var ALWAYS_EXCLUDED = ["script", "style", "noscript"];
+function cleanContentElement(element, excludeSelectors) {
+  const allSelectors = [...ALWAYS_EXCLUDED, ...excludeSelectors];
+  const cloned = JSON.parse(JSON.stringify(element));
+  function removeUnwanted(node) {
+    if (!node.children) return;
+    node.children = node.children.filter((child) => {
+      if (child.type !== "element") return true;
+      const childElement = child;
+      for (const selector of allSelectors) {
+        if (selector.startsWith(".")) {
+          const className = selector.slice(1);
+          const classes = childElement.properties?.className;
+          if (Array.isArray(classes) && classes.includes(className)) {
+            return false;
+          }
+          if (typeof classes === "string" && classes.includes(className)) {
+            return false;
+          }
+        } else if (selector.startsWith("[")) {
+          const match = selector.match(/\[([^=]+)="([^"]+)"\]/);
+          if (match) {
+            const [, attr, value] = match;
+            if (attr && childElement.properties?.[attr] === value) {
+              return false;
+            }
+          }
+        } else {
+          if (childElement.tagName === selector) {
+            return false;
+          }
+        }
+      }
+      removeUnwanted(childElement);
+      return true;
+    });
+  }
+  removeUnwanted(cloned);
+  return cloned;
+}
+async function extractContent(filePath, options) {
+  const tree = await parseHtmlFile(filePath);
+  const title = extractTitle(tree);
+  const description = extractDescription(tree);
+  let contentElement = findContentElement(tree, options.contentSelectors);
+  if (!contentElement) {
+    const body = select("body", tree);
+    if (body) {
+      contentElement = body;
+    }
+  }
+  let contentHtml = "";
+  if (contentElement) {
+    const cleanedElement = cleanContentElement(contentElement, options.excludeSelectors);
+    contentHtml = serializeElement(cleanedElement);
+  }
+  return {
+    title,
+    description,
+    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 "";
+  }
+  try {
+    const processor = unified().use(rehypeParse, { fragment: true }).use(rehypeRemark).use(remarkGfm).use(remarkStringify, {
+      bullet: "-",
+      fences: true
+    });
+    const result = await processor.process(html);
+    let markdown = String(result);
+    markdown = cleanMarkdown(markdown);
+    return markdown;
+  } catch (error) {
+    console.error("Error converting HTML to Markdown:", error);
+    return extractTextFallback(html);
+  }
+}
+function cleanMarkdown(markdown) {
+  return markdown.replace(/\n{3,}/g, "\n\n").split("\n").map((line) => line.trimEnd()).join("\n").trim() + "\n";
+}
+function extractTextFallback(html) {
+  let text = html.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "");
+  text = text.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "");
+  text = text.replace(/<br\s*\/?>/gi, "\n");
+  text = text.replace(/<\/p>/gi, "\n\n");
+  text = text.replace(/<\/h[1-6]>/gi, "\n\n");
+  text = text.replace(/<\/li>/gi, "\n");
+  text = text.replace(/<\/div>/gi, "\n");
+  text = text.replace(/<[^>]+>/g, "");
+  text = text.replace(/&nbsp;/g, " ");
+  text = text.replace(/&amp;/g, "&");
+  text = text.replace(/&lt;/g, "<");
+  text = text.replace(/&gt;/g, ">");
+  text = text.replace(/&quot;/g, '"');
+  text = text.replace(/&#39;/g, "'");
+  text = text.replace(/[ \t]+/g, " ");
+  text = text.replace(/\n{3,}/g, "\n\n");
+  return text.trim();
+}
+
+// src/processing/heading-extractor.ts
+function extractHeadingsFromMarkdown(markdown) {
+  const headings = [];
+  const lines = markdown.split("\n");
+  let currentOffset = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const headingMatch = line.match(/^(#{1,6})\s+(.+?)(?:\s+\{#([^}]+)\})?$/);
+    if (headingMatch) {
+      const hashes = headingMatch[1] ?? "";
+      const level = hashes.length;
+      let text = headingMatch[2] ?? "";
+      let id = headingMatch[3] ?? "";
+      if (!id) {
+        id = generateHeadingId(text);
+      }
+      text = text.replace(/\*\*([^*]+)\*\*/g, "$1");
+      text = text.replace(/_([^_]+)_/g, "$1");
+      text = text.replace(/`([^`]+)`/g, "$1");
+      headings.push({
+        level,
+        text: text.trim(),
+        id,
+        startOffset: currentOffset,
+        endOffset: -1
+        // Will be calculated below
+      });
+    }
+    currentOffset += line.length + 1;
+  }
+  for (let i = 0; i < headings.length; i++) {
+    const current = headings[i];
+    if (!current) continue;
+    let endOffset = markdown.length;
+    for (let j = i + 1; j < headings.length; j++) {
+      const next = headings[j];
+      if (next && next.level <= current.level) {
+        endOffset = next.startOffset;
+        break;
+      }
+    }
+    current.endOffset = endOffset;
+  }
+  return headings;
+}
+function generateHeadingId(text) {
+  return text.toLowerCase().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+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();
+}
+var FIELD_WEIGHTS = {
+  title: 3,
+  headings: 2,
+  description: 1.5,
+  content: 1
+};
+function englishStemmer(word) {
+  if (word.length <= 3) return word;
+  return word.replace(/ing$/, "").replace(/tion$/, "t").replace(/sion$/, "s").replace(/([^aeiou])ed$/, "$1").replace(/([^aeiou])es$/, "$1").replace(/ly$/, "").replace(/ment$/, "").replace(/ness$/, "").replace(/ies$/, "y").replace(/([^s])s$/, "$1");
+}
+function createSearchIndex() {
+  return new FlexSearch.Document({
+    // Use 'full' tokenization for substring matching
+    // This allows "auth" to match "authentication"
+    tokenize: "full",
+    // Enable caching for faster repeated queries
+    cache: 100,
+    // Higher resolution = more granular ranking (1-9)
+    resolution: 9,
+    // Enable context for phrase/proximity matching
+    context: {
+      resolution: 2,
+      depth: 2,
+      bidirectional: true
+    },
+    // Apply stemming to normalize word forms
+    encode: (str) => {
+      const words = str.toLowerCase().split(/[\s\-_.,;:!?'"()[\]{}]+/);
+      return words.filter(Boolean).map(englishStemmer);
+    },
+    // Document schema
+    document: {
+      id: "id",
+      // Index these fields for searching
+      index: ["title", "content", "headings", "description"],
+      // Store these fields in results (for enriched queries)
+      store: ["title", "description"]
+    }
+  });
+}
+function addDocumentToIndex(index, doc) {
+  const indexable = {
+    id: doc.route,
+    title: doc.title,
+    content: doc.markdown,
+    headings: doc.headings.map((h) => h.text).join(" "),
+    description: doc.description
+  };
+  index.add(indexable);
+}
+function buildSearchIndex(docs) {
+  const index = createSearchIndex();
+  for (const doc of docs) {
+    addDocumentToIndex(index, doc);
+  }
+  return index;
+}
+function searchIndex(index, docs, query, options = {}) {
+  const { limit = 5 } = options;
+  const rawResults = index.search(query, {
+    limit: limit * 3,
+    // Get extra results for better ranking after weighting
+    enrich: true
+  });
+  const docScores = /* @__PURE__ */ new Map();
+  for (const fieldResult of rawResults) {
+    const field = fieldResult.field;
+    const fieldWeight = FIELD_WEIGHTS[field] ?? 1;
+    const results2 = fieldResult.result;
+    for (let i = 0; i < results2.length; i++) {
+      const item = results2[i];
+      if (!item) continue;
+      const docId = typeof item === "string" ? item : item.id;
+      const positionScore = (results2.length - i) / results2.length;
+      const weightedScore = positionScore * fieldWeight;
+      const existingScore = docScores.get(docId) ?? 0;
+      docScores.set(docId, existingScore + weightedScore);
+    }
+  }
+  const results = [];
+  for (const [docId, score] of docScores) {
+    const doc = docs[docId];
+    if (!doc) continue;
+    results.push({
+      route: doc.route,
+      title: doc.title,
+      score,
+      snippet: generateSnippet(doc.markdown, query),
+      matchingHeadings: findMatchingHeadings(doc, query)
+    });
+  }
+  results.sort((a, b) => b.score - a.score);
+  return results.slice(0, limit);
+}
+function generateSnippet(markdown, query) {
+  const maxLength = 200;
+  const queryTerms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (queryTerms.length === 0) {
+    return markdown.slice(0, maxLength) + (markdown.length > maxLength ? "..." : "");
+  }
+  const lowerMarkdown = markdown.toLowerCase();
+  let bestIndex = -1;
+  let bestTerm = "";
+  const allTerms = [...queryTerms, ...queryTerms.map(englishStemmer)];
+  for (const term of allTerms) {
+    const index = lowerMarkdown.indexOf(term);
+    if (index !== -1 && (bestIndex === -1 || index < bestIndex)) {
+      bestIndex = index;
+      bestTerm = term;
+    }
+  }
+  if (bestIndex === -1) {
+    return markdown.slice(0, maxLength) + (markdown.length > maxLength ? "..." : "");
+  }
+  const snippetStart = Math.max(0, bestIndex - 50);
+  const snippetEnd = Math.min(markdown.length, bestIndex + bestTerm.length + 150);
+  let snippet = markdown.slice(snippetStart, snippetEnd);
+  snippet = snippet.replace(/^#{1,6}\s+/gm, "").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/!\[([^\]]*)\]\([^)]+\)/g, "").replace(/```[a-z]*\n?/g, "").replace(/`([^`]+)`/g, "$1").replace(/\s+/g, " ").trim();
+  const prefix = snippetStart > 0 ? "..." : "";
+  const suffix = snippetEnd < markdown.length ? "..." : "";
+  return prefix + snippet + suffix;
+}
+function findMatchingHeadings(doc, query) {
+  const queryTerms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const allTerms = [...queryTerms, ...queryTerms.map(englishStemmer)];
+  const matching = [];
+  for (const heading of doc.headings) {
+    const headingLower = heading.text.toLowerCase();
+    const headingStemmed = headingLower.split(/\s+/).map(englishStemmer).join(" ");
+    if (allTerms.some(
+      (term) => headingLower.includes(term) || headingStemmed.includes(englishStemmer(term))
+    )) {
+      matching.push(heading.text);
+    }
+  }
+  return matching.slice(0, 3);
+}
+async function exportSearchIndex(index) {
+  const exportData = {};
+  await index.export((key, data) => {
+    exportData[key] = data;
+  });
+  return exportData;
+}
+async function importSearchIndex(data) {
+  const index = createSearchIndex();
+  for (const [key, value] of Object.entries(data)) {
+    await index.import(
+      key,
+      value
+    );
+  }
+  return index;
+}
+
+// src/plugin/docusaurus-plugin.ts
+function resolveOptions(options) {
+  return {
+    ...DEFAULT_OPTIONS,
+    ...options,
+    server: {
+      ...DEFAULT_OPTIONS.server,
+      ...options.server
+    }
+  };
+}
+async function processHtmlFile(htmlPath, route, options) {
+  try {
+    const extractOptions = {
+      contentSelectors: options.contentSelectors,
+      excludeSelectors: options.excludeSelectors
+    };
+    const extracted = await extractContent(htmlPath, extractOptions);
+    if (!extracted.contentHtml) {
+      console.warn(`[MCP] No content found in ${htmlPath}`);
+      return null;
+    }
+    const markdown = await htmlToMarkdown(extracted.contentHtml);
+    if (!markdown || markdown.trim().length < options.minContentLength) {
+      console.warn(`[MCP] Insufficient content in ${htmlPath}`);
+      return null;
+    }
+    const headings = extractHeadingsFromMarkdown(markdown);
+    return {
+      route,
+      title: extracted.title,
+      description: extracted.description,
+      markdown,
+      headings
+    };
+  } catch (error) {
+    console.error(`[MCP] Error processing ${htmlPath}:`, error);
+    return null;
+  }
+}
+function mcpServerPlugin(context, options) {
+  const resolvedOptions = resolveOptions(options);
+  return {
+    name: "docusaurus-plugin-mcp-server",
+    // Expose configuration to theme components via globalData
+    async contentLoaded({ actions }) {
+      const { setGlobalData } = actions;
+      const serverUrl = `${context.siteConfig.url}/${resolvedOptions.outputDir}`;
+      setGlobalData({
+        serverUrl,
+        serverName: resolvedOptions.server.name
+      });
+    },
+    async postBuild({ outDir }) {
+      console.log("[MCP] Starting MCP artifact generation...");
+      const startTime = Date.now();
+      const routes = await collectRoutes(outDir, resolvedOptions.excludeRoutes);
+      console.log(`[MCP] Found ${routes.length} routes to process`);
+      if (routes.length === 0) {
+        console.warn("[MCP] No routes found to process");
+        return;
+      }
+      const processOptions = {
+        contentSelectors: resolvedOptions.contentSelectors,
+        excludeSelectors: resolvedOptions.excludeSelectors,
+        minContentLength: resolvedOptions.minContentLength
+      };
+      const processedDocs = await pMap(
+        routes,
+        async (route) => {
+          return processHtmlFile(route.htmlPath, route.path, processOptions);
+        },
+        { concurrency: 10 }
+      );
+      const validDocs = processedDocs.filter((doc) => doc !== null);
+      console.log(`[MCP] Successfully processed ${validDocs.length} documents`);
+      if (validDocs.length === 0) {
+        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,
+        serverName: resolvedOptions.server.name,
+        baseUrl: context.siteConfig.url
+      };
+      const mcpOutputDir = path2.join(outDir, resolvedOptions.outputDir);
+      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 elapsed = Date.now() - startTime;
+      console.log(`[MCP] Artifacts written to ${mcpOutputDir}`);
+      console.log(`[MCP] Generation complete in ${elapsed}ms`);
+    }
+  };
+}
+
+// src/mcp/tools/docs-search.ts
+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"]
+  }
+};
+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.";
+  }
+  const lines = [`Found ${results.length} result(s):
+`];
+  for (let i = 0; i < results.length; i++) {
+    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}`);
+    if (result.matchingHeadings && result.matchingHeadings.length > 0) {
+      lines.push(`   Matching sections: ${result.matchingHeadings.join(", ")}`);
+    }
+    lines.push(`   ${result.snippet}`);
+    lines.push("");
+  }
+  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"]
+  }
+};
+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.";
+  }
+  const lines = [];
+  lines.push(`# ${doc.title}`);
+  lines.push("");
+  if (doc.description) {
+    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("");
+    for (const heading of doc.headings) {
+      if (heading.level <= 3) {
+        const indent = "  ".repeat(heading.level - 1);
+        lines.push(`${indent}- [${heading.text}](#${heading.id})`);
+      }
+    }
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+  }
+  lines.push(doc.markdown);
+  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 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;
+}
+function isDataConfig(config) {
+  return "docs" in config && "searchIndexData" in config;
+}
+var McpDocsServer = class {
+  config;
+  docs = null;
+  searchIndex = null;
+  mcpServer;
+  initialized = false;
+  constructor(config) {
+    this.config = config;
+    this.mcpServer = new McpServer(
+      {
+        name: config.name,
+        version: config.version ?? "1.0.0"
+      },
+      {
+        capabilities: {
+          tools: {}
+        }
+      }
+    );
+    this.registerTools();
+  }
+  /**
+   * Register all MCP tools using the SDK's registerTool API
+   */
+  registerTools() {
+    this.mcpServer.registerTool(
+      "docs_search",
+      {
+        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)")
+        }
+      },
+      async ({ query, limit }) => {
+        await this.initialize();
+        if (!this.docs || !this.searchIndex) {
+          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) }
+          ]
+        };
+      }
+    );
+    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.docs) {
+          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) {
+          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)
+            }
+          ]
+        };
+      }
+    );
+  }
+  /**
+   * Load docs and search index
+   *
+   * For file-based config: reads from disk
+   * For data config: uses pre-loaded data directly
+   */
+  async initialize() {
+    if (this.initialized) {
+      return;
+    }
+    try {
+      if (isDataConfig(this.config)) {
+        this.docs = this.config.docs;
+        this.searchIndex = await importSearchIndex(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}`);
+        }
+      } else {
+        throw new Error("Invalid server config: must provide either file paths or pre-loaded data");
+      }
+      this.initialized = true;
+    } catch (error) {
+      console.error("[MCP] Failed to initialize:", error);
+      throw error;
+    }
+  }
+  /**
+   * Handle an HTTP request using the MCP SDK's transport
+   *
+   * This method is designed for serverless environments (Vercel, Netlify).
+   * It creates a stateless transport instance and processes the request.
+   *
+   * @param req - Node.js IncomingMessage or compatible request object
+   * @param res - Node.js ServerResponse or compatible response object
+   * @param parsedBody - Optional pre-parsed request body
+   */
+  async handleHttpRequest(req, res, parsedBody) {
+    await this.initialize();
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: void 0,
+      // Stateless mode - no session tracking
+      enableJsonResponse: true
+      // Return JSON instead of SSE streams
+    });
+    await this.mcpServer.connect(transport);
+    try {
+      await transport.handleRequest(req, res, parsedBody);
+    } finally {
+      await transport.close();
+    }
+  }
+  /**
+   * Handle a Web Standard Request (Cloudflare Workers, Deno, Bun)
+   *
+   * This method is designed for Web Standard environments that use
+   * the Fetch API Request/Response pattern.
+   *
+   * @param request - Web Standard Request object
+   * @returns Web Standard Response object
+   */
+  async handleWebRequest(request) {
+    await this.initialize();
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      sessionIdGenerator: void 0,
+      // Stateless mode
+      enableJsonResponse: true
+    });
+    await this.mcpServer.connect(transport);
+    try {
+      return await transport.handleRequest(request);
+    } finally {
+      await transport.close();
+    }
+  }
+  /**
+   * Get server status information
+   *
+   * Useful for health checks and debugging
+   */
+  async getStatus() {
+    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
+    };
+  }
+  /**
+   * Get the underlying McpServer instance
+   *
+   * Useful for advanced use cases like custom transports
+   */
+  getMcpServer() {
+    return this.mcpServer;
+  }
+};
+
+export { DEFAULT_OPTIONS, McpDocsServer, buildSearchIndex, collectRoutes, mcpServerPlugin as default, discoverHtmlFiles, docsGetPageTool, docsGetSectionTool, docsSearchTool, exportSearchIndex, extractContent, extractHeadingsFromMarkdown, extractSection, htmlToMarkdown, importSearchIndex, mcpServerPlugin, parseHtml, parseHtmlFile, searchIndex };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map