docusaurus-plugin-mcp-server 0.9.0 → 0.10.1

package/dist/cli/verify.mjs

@@ -1,705 +0,0 @@
-#!/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 FlexSearch from 'flexsearch';
-import { z } from 'zod';
-
-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({
-      url: docId,
-      // docId is the full URL when indexed with baseUrl
-      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;
-}
-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 fs2.pathExists(initData.docsPath)) {
-        this.docs = await fs2.readJson(initData.docsPath);
-      } else {
-        throw new Error(`[FlexSearch] Docs file not found: ${initData.docsPath}`);
-      }
-      if (await fs2.pathExists(initData.indexPath)) {
-        const indexData = await fs2.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(url) {
-    if (!this.docs) {
-      throw new Error("[FlexSearch] Provider not initialized");
-    }
-    return this.docs[url] ?? 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 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 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";
-}
-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 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) {
-  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}**`);
-    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");
-}
-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) {
-  if (!doc) {
-    return "Page not found. Please check the URL and try again.";
-  }
-  const lines = [];
-  lines.push(`# ${doc.title}`);
-  lines.push("");
-  if (doc.description) {
-    lines.push(`> ${doc.description}`);
-    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/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;
-  searchProvider = 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 definitions from tool files
-   */
-  registerTools() {
-    this.mcpServer.registerTool(
-      docsSearchTool.name,
-      {
-        description: docsSearchTool.description,
-        inputSchema: docsSearchTool.inputSchema
-      },
-      async ({ query, limit }) => {
-        await this.initialize();
-        if (!this.searchProvider || !this.searchProvider.isReady()) {
-          return {
-            content: [{ type: "text", text: "Server not initialized. Please try again." }],
-            isError: true
-          };
-        }
-        try {
-          const results = await this.searchProvider.search(query, { limit });
-          return {
-            content: [{ type: "text", text: formatSearchResults(results) }]
-          };
-        } catch (error) {
-          console.error("[MCP] Search error:", error);
-          return {
-            content: [{ type: "text", text: `Search error: ${String(error)}` }],
-            isError: true
-          };
-        }
-      }
-    );
-    this.mcpServer.registerTool(
-      docsFetchTool.name,
-      {
-        description: docsFetchTool.description,
-        inputSchema: docsFetchTool.inputSchema
-      },
-      async ({ url }) => {
-        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(url);
-          return {
-            content: [{ type: "text", text: formatPageContent(doc) }]
-          };
-        } catch (error) {
-          console.error("[MCP] Fetch error:", error);
-          return {
-            content: [{ type: "text", text: `Error fetching page: ${String(error)}` }],
-            isError: true
-          };
-        }
-      }
-    );
-  }
-  /**
-   * Get a document by URL using the search provider
-   */
-  async getDocument(url) {
-    if (!this.searchProvider) {
-      return null;
-    }
-    if (this.searchProvider.getDocument) {
-      return this.searchProvider.getDocument(url);
-    }
-    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
-   */
-  async initialize() {
-    if (this.initialized) {
-      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)) {
-        initData.docs = this.config.docs;
-        initData.indexData = this.config.searchIndexData;
-      } else if (isFileConfig(this.config)) {
-        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);
-      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() {
-    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,
-      baseUrl: this.config.baseUrl,
-      searchProvider: this.searchProvider?.name
-    };
-  }
-  /**
-   * 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