docusaurus-plugin-mcp-server 0.5.0

package/dist/cli/verify.mjs

@@ -0,0 +1,702 @@
+#!/usr/bin/env node
+import fs2 from 'fs-extra';
+import path from 'path';
+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';
+
+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 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 importSearchIndex(data) {
+  const index = createSearchIndex();
+  for (const [key, value] of Object.entries(data)) {
+    await index.import(
+      key,
+      value
+    );
+  }
+  return index;
+}
+
+// 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;
+}
+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
+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/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;
+}
+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 fs2.pathExists(this.config.docsPath)) {
+          this.docs = await fs2.readJson(this.config.docsPath);
+        } else {
+          throw new Error(`Docs file not found: ${this.config.docsPath}`);
+        }
+        if (await fs2.pathExists(this.config.indexPath)) {
+          const indexData = await fs2.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;
+  }
+};
+
+// src/cli/verify.ts
+async function verifyBuild(buildDir) {
+  const result = {
+    success: true,
+    docsFound: 0,
+    errors: [],
+    warnings: []
+  };
+  const mcpDir = path.join(buildDir, "mcp");
+  if (!await fs2.pathExists(mcpDir)) {
+    result.errors.push(`MCP directory not found: ${mcpDir}`);
+    result.errors.push('Did you run "npm run build" with the MCP plugin configured?');
+    result.success = false;
+    return result;
+  }
+  const requiredFiles = ["docs.json", "search-index.json", "manifest.json"];
+  for (const file of requiredFiles) {
+    const filePath = path.join(mcpDir, file);
+    if (!await fs2.pathExists(filePath)) {
+      result.errors.push(`Required file missing: ${filePath}`);
+      result.success = false;
+    }
+  }
+  if (!result.success) {
+    return result;
+  }
+  try {
+    const docsPath = path.join(mcpDir, "docs.json");
+    const docs = await fs2.readJson(docsPath);
+    if (typeof docs !== "object" || docs === null) {
+      result.errors.push("docs.json is not a valid object");
+      result.success = false;
+    } else {
+      result.docsFound = Object.keys(docs).length;
+      if (result.docsFound === 0) {
+        result.warnings.push("docs.json contains no documents");
+      }
+      for (const [route, doc] of Object.entries(docs)) {
+        const d = doc;
+        if (!d.title || typeof d.title !== "string") {
+          result.warnings.push(`Document ${route} is missing a title`);
+        }
+        if (!d.markdown || typeof d.markdown !== "string") {
+          result.warnings.push(`Document ${route} is missing markdown content`);
+        }
+      }
+    }
+  } catch (error) {
+    result.errors.push(`Failed to parse docs.json: ${error.message}`);
+    result.success = false;
+  }
+  try {
+    const indexPath = path.join(mcpDir, "search-index.json");
+    const indexData = await fs2.readJson(indexPath);
+    if (typeof indexData !== "object" || indexData === null) {
+      result.errors.push("search-index.json is not a valid object");
+      result.success = false;
+    }
+  } catch (error) {
+    result.errors.push(`Failed to parse search-index.json: ${error.message}`);
+    result.success = false;
+  }
+  try {
+    const manifestPath = path.join(mcpDir, "manifest.json");
+    const manifest = await fs2.readJson(manifestPath);
+    if (!manifest.name || typeof manifest.name !== "string") {
+      result.warnings.push("manifest.json is missing server name");
+    }
+    if (!manifest.version || typeof manifest.version !== "string") {
+      result.warnings.push("manifest.json is missing server version");
+    }
+  } catch (error) {
+    result.errors.push(`Failed to parse manifest.json: ${error.message}`);
+    result.success = false;
+  }
+  return result;
+}
+async function testServer(buildDir) {
+  const mcpDir = path.join(buildDir, "mcp");
+  const docsPath = path.join(mcpDir, "docs.json");
+  const indexPath = path.join(mcpDir, "search-index.json");
+  const manifestPath = path.join(mcpDir, "manifest.json");
+  try {
+    const manifest = await fs2.readJson(manifestPath);
+    const docs = await fs2.readJson(docsPath);
+    const searchIndexData = await fs2.readJson(indexPath);
+    const server = new McpDocsServer({
+      name: manifest.name || "test-docs",
+      version: manifest.version || "1.0.0",
+      docs,
+      searchIndexData
+    });
+    await server.initialize();
+    const status = await server.getStatus();
+    if (!status.initialized) {
+      return { success: false, message: "Server failed to initialize" };
+    }
+    if (status.docCount === 0) {
+      return { success: false, message: "Server has no documents loaded" };
+    }
+    return {
+      success: true,
+      message: `Server initialized with ${status.docCount} documents`
+    };
+  } catch (error) {
+    return {
+      success: false,
+      message: `Server test failed: ${error.message}`
+    };
+  }
+}
+async function main() {
+  const args = process.argv.slice(2);
+  const buildDir = args[0] || "./build";
+  console.log("");
+  console.log("\u{1F50D} MCP Build Verification");
+  console.log("=".repeat(50));
+  console.log(`Build directory: ${path.resolve(buildDir)}`);
+  console.log("");
+  console.log("\u{1F4C1} Checking build output...");
+  const verifyResult = await verifyBuild(buildDir);
+  if (verifyResult.errors.length > 0) {
+    console.log("");
+    console.log("\u274C Errors:");
+    for (const error of verifyResult.errors) {
+      console.log(`   \u2022 ${error}`);
+    }
+  }
+  if (verifyResult.warnings.length > 0) {
+    console.log("");
+    console.log("\u26A0\uFE0F  Warnings:");
+    for (const warning of verifyResult.warnings) {
+      console.log(`   \u2022 ${warning}`);
+    }
+  }
+  if (!verifyResult.success) {
+    console.log("");
+    console.log("\u274C Build verification failed");
+    process.exit(1);
+  }
+  console.log(`   \u2713 Found ${verifyResult.docsFound} documents`);
+  console.log("   \u2713 All required files present");
+  console.log("   \u2713 File structure valid");
+  console.log("");
+  console.log("\u{1F680} Testing MCP server...");
+  const serverResult = await testServer(buildDir);
+  if (!serverResult.success) {
+    console.log(`   \u274C ${serverResult.message}`);
+    console.log("");
+    console.log("\u274C Server test failed");
+    process.exit(1);
+  }
+  console.log(`   \u2713 ${serverResult.message}`);
+  console.log("");
+  console.log("\u2705 All checks passed!");
+  console.log("");
+  console.log("Next steps:");
+  console.log("  1. Deploy your site to a hosting provider");
+  console.log("  2. Configure MCP endpoint (see README for platform guides)");
+  console.log("  3. Connect your AI tools to the MCP server");
+  console.log("");
+  process.exit(0);
+}
+main().catch((error) => {
+  console.error("Unexpected error:", error);
+  process.exit(1);
+});
+//# sourceMappingURL=verify.mjs.map
+//# sourceMappingURL=verify.mjs.map