docusaurus-plugin-mcp-server 0.9.0 → 0.10.1

package/dist/index.d.mts

@@ -1,479 +0,0 @@
-import { LoadContext, Plugin } from '@docusaurus/types';
-import { b as McpServerPluginOptions, M as McpServerConfig, P as ProcessedDoc, S as SearchResult, E as ExtractedContent, D as DocHeading, F as FlattenedRoute } from './index-j-CdaS6k.mjs';
-export { c as DEFAULT_OPTIONS, d as DocsFetchParams, e as DocsIndex, f as DocsSearchParams, g as McpManifest, h as McpServerDataConfig, a as McpServerFileConfig, R as ResolvedPluginOptions } from './index-j-CdaS6k.mjs';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { IncomingMessage, ServerResponse } from 'node:http';
-import FlexSearch from 'flexsearch';
-import { z } from 'zod';
-import { Root } from 'hast';
-
-/**
- * Docusaurus plugin that generates MCP server artifacts during build
- */
-declare function mcpServerPlugin(context: LoadContext, options: McpServerPluginOptions): Plugin;
-
-/**
- * MCP Server for documentation
- *
- * This class provides the MCP server implementation that can be used
- * with any HTTP framework (Express, Vercel, Cloudflare Workers, etc.)
- *
- * Supports two modes:
- * - File-based: Load docs and search index from filesystem (Node.js)
- * - Pre-loaded: Accept docs and search index data directly (Workers)
- *
- * Uses the official MCP SDK for proper protocol handling.
- */
-declare class McpDocsServer {
-    private config;
-    private searchProvider;
-    private mcpServer;
-    private initialized;
-    constructor(config: McpServerConfig);
-    /**
-     * Register all MCP tools using definitions from tool files
-     */
-    private registerTools;
-    /**
-     * Get a document by URL using the search provider
-     */
-    private getDocument;
-    /**
-     * 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
-     */
-    initialize(): Promise<void>;
-    /**
-     * 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
-     */
-    handleHttpRequest(req: IncomingMessage, res: ServerResponse, parsedBody?: unknown): Promise<void>;
-    /**
-     * 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
-     */
-    handleWebRequest(request: Request): Promise<Response>;
-    /**
-     * Get server status information
-     *
-     * Useful for health checks and debugging
-     */
-    getStatus(): Promise<{
-        name: string;
-        version: string;
-        initialized: boolean;
-        docCount: number;
-        baseUrl?: string;
-        searchProvider?: string;
-    }>;
-    /**
-     * Get the underlying McpServer instance
-     *
-     * Useful for advanced use cases like custom transports
-     */
-    getMcpServer(): McpServer;
-}
-
-/**
- * Context passed to providers during initialization
- */
-interface ProviderContext {
-    /** Site base URL (e.g., https://docs.example.com) */
-    baseUrl: string;
-    /** MCP server name */
-    serverName: string;
-    /** MCP server version */
-    serverVersion: string;
-    /** Output directory for artifacts */
-    outputDir: string;
-}
-/**
- * Build-time provider that indexes extracted documents.
- *
- * Consumers implement this to push docs to external systems (Glean, Algolia, etc.)
- * or to transform the extraction output for their own pipelines.
- *
- * @example
- * ```typescript
- * import type { ContentIndexer, ProviderContext } from 'docusaurus-plugin-mcp-server';
- * import type { ProcessedDoc } from 'docusaurus-plugin-mcp-server';
- *
- * export default class AlgoliaIndexer implements ContentIndexer {
- *   readonly name = 'algolia';
- *
- *   shouldRun(): boolean {
- *     // Only run when ALGOLIA_SYNC=true is set
- *     return process.env.ALGOLIA_SYNC === 'true';
- *   }
- *
- *   async initialize(context: ProviderContext): Promise<void> {
- *     console.log(`[Algolia] Initializing for ${context.baseUrl}`);
- *   }
- *
- *   async indexDocuments(docs: ProcessedDoc[]): Promise<void> {
- *     // Push docs to Algolia
- *   }
- *
- *   async finalize(): Promise<Map<string, unknown>> {
- *     // No local artifacts needed
- *     return new Map();
- *   }
- * }
- * ```
- */
-interface ContentIndexer {
-    /** Unique name for this indexer */
-    readonly name: string;
-    /**
-     * Check if this indexer should run.
-     * Use this to gate execution on environment variables.
-     * Default: true if not implemented.
-     *
-     * @example
-     * shouldRun() {
-     *   if (process.env.GLEAN_SYNC !== 'true') {
-     *     console.log('[Glean] Skipping sync (set GLEAN_SYNC=true to enable)');
-     *     return false;
-     *   }
-     *   return true;
-     * }
-     */
-    shouldRun?(): boolean;
-    /**
-     * Initialize the indexer with context about the build.
-     * Called once before indexDocuments.
-     */
-    initialize(context: ProviderContext): Promise<void>;
-    /**
-     * Index the extracted documents.
-     * Called once with all processed documents.
-     */
-    indexDocuments(docs: ProcessedDoc[]): Promise<void>;
-    /**
-     * Return artifacts to write to outputDir.
-     * Map of filename -> JSON-serializable content.
-     * Return empty map to skip local artifact generation.
-     */
-    finalize(): Promise<Map<string, unknown>>;
-    /**
-     * Optional metadata to include in manifest.json
-     */
-    getManifestData?(): Promise<Record<string, unknown>>;
-}
-/**
- * Data passed to search provider during initialization.
- * Supports both file-based and pre-loaded data modes.
- */
-interface SearchProviderInitData {
-    /** Path to docs.json (file mode) */
-    docsPath?: string;
-    /** Path to search-index.json (file mode) */
-    indexPath?: string;
-    /** Pre-loaded docs (data mode) */
-    docs?: Record<string, ProcessedDoc>;
-    /** Pre-loaded index data (data mode) */
-    indexData?: Record<string, unknown>;
-}
-/**
- * Options for search queries
- */
-interface SearchOptions {
-    /** Maximum number of results to return */
-    limit?: number;
-}
-/**
- * Runtime provider that handles search queries from MCP tools.
- *
- * Consumers implement this to delegate search to external systems (Glean, Algolia, etc.).
- *
- * @example
- * ```typescript
- * import type { SearchProvider, ProviderContext, SearchOptions } from 'docusaurus-plugin-mcp-server';
- * import type { SearchResult, ProcessedDoc } from 'docusaurus-plugin-mcp-server';
- *
- * export default class GleanSearchProvider implements SearchProvider {
- *   readonly name = 'glean';
- *
- *   private apiEndpoint = process.env.GLEAN_API_ENDPOINT!;
- *   private apiToken = process.env.GLEAN_API_TOKEN!;
- *
- *   async initialize(context: ProviderContext): Promise<void> {
- *     if (!this.apiEndpoint || !this.apiToken) {
- *       throw new Error('GLEAN_API_ENDPOINT and GLEAN_API_TOKEN required');
- *     }
- *   }
- *
- *   isReady(): boolean {
- *     return !!this.apiEndpoint && !!this.apiToken;
- *   }
- *
- *   async search(query: string, options?: SearchOptions): Promise<SearchResult[]> {
- *     // Call Glean Search API and transform results
- *     return [];
- *   }
- * }
- * ```
- */
-interface SearchProvider {
-    /** Unique name for this provider */
-    readonly name: string;
-    /**
-     * Initialize the search provider.
-     * Called once before any search queries.
-     */
-    initialize(context: ProviderContext, initData?: SearchProviderInitData): Promise<void>;
-    /**
-     * Check if the provider is ready to handle search queries.
-     */
-    isReady(): boolean;
-    /**
-     * Search for documents matching the query.
-     */
-    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
-    /**
-     * Get a document by its route.
-     * Used by docs_get_page and docs_get_section tools.
-     */
-    getDocument?(route: string): Promise<ProcessedDoc | null>;
-    /**
-     * Check if the provider is healthy.
-     * Used for health checks and debugging.
-     */
-    healthCheck?(): Promise<{
-        healthy: boolean;
-        message?: string;
-    }>;
-}
-/**
- * Type for module that exports a ContentIndexer
- */
-type ContentIndexerModule = {
-    default: new () => ContentIndexer;
-};
-/**
- * Type for module that exports a SearchProvider
- */
-type SearchProviderModule = {
-    default: new () => SearchProvider;
-};
-
-/**
- * Load an indexer by name or module path.
- *
- * @param specifier - Either 'flexsearch' for the built-in indexer, or a module path
- *                    (relative path like './my-indexer.js' or npm package like '@myorg/indexer')
- * @returns Instantiated ContentIndexer
- *
- * @example
- * ```typescript
- * // Built-in
- * const indexer = await loadIndexer('flexsearch');
- *
- * // Custom relative path
- * const indexer = await loadIndexer('./src/providers/algolia-indexer.js');
- *
- * // Custom npm package
- * const indexer = await loadIndexer('@myorg/custom-indexer');
- * ```
- */
-declare function loadIndexer(specifier: string): Promise<ContentIndexer>;
-/**
- * Load a search provider by name or module path.
- *
- * @param specifier - Either 'flexsearch' for the built-in provider, or a module path
- *                    (relative path like './my-search.js' or npm package like '@myorg/search')
- * @returns Instantiated SearchProvider
- *
- * @example
- * ```typescript
- * // Built-in
- * const provider = await loadSearchProvider('flexsearch');
- *
- * // Custom relative path
- * const provider = await loadSearchProvider('./src/providers/glean-search.js');
- *
- * // Custom npm package
- * const provider = await loadSearchProvider('@myorg/glean-search');
- * ```
- */
-declare function loadSearchProvider(specifier: string): Promise<SearchProvider>;
-
-/**
- * Built-in FlexSearch content indexer.
- *
- * This indexer builds a local FlexSearch index and produces:
- * - docs.json: All processed documents keyed by full URL
- * - search-index.json: Exported FlexSearch index for runtime search
- */
-declare class FlexSearchIndexer implements ContentIndexer {
-    readonly name = "flexsearch";
-    private baseUrl;
-    private docsIndex;
-    private exportedIndex;
-    private docCount;
-    /**
-     * FlexSearch indexer always runs by default.
-     * It respects the indexers configuration - if not included, it won't run.
-     */
-    shouldRun(): boolean;
-    initialize(context: ProviderContext): Promise<void>;
-    indexDocuments(docs: ProcessedDoc[]): Promise<void>;
-    finalize(): Promise<Map<string, unknown>>;
-    getManifestData(): Promise<Record<string, unknown>>;
-}
-
-/**
- * Document structure for FlexSearch indexing
- */
-interface IndexableDocument {
-    /** Unique identifier (route path) */
-    id: string;
-    /** Document title */
-    title: string;
-    /** Full content for search */
-    content: string;
-    /** Concatenated heading text for search */
-    headings: string;
-    /** Meta description */
-    description: string;
-}
-
-type FlexSearchDocument = FlexSearch.Document<IndexableDocument, string[]>;
-/**
- * Build the search index from processed documents
- *
- * @param docs - Documents to index
- * @param baseUrl - Optional base URL to construct full URLs as document IDs
- */
-declare function buildSearchIndex(docs: ProcessedDoc[], baseUrl?: string): FlexSearchDocument;
-/**
- * Search the index and return results with weighted ranking
- *
- * Ranking combines:
- * - Field importance (title > headings > description > content)
- * - Position in results (earlier = more relevant)
- */
-declare function searchIndex(index: FlexSearchDocument, docs: Record<string, ProcessedDoc>, query: string, options?: {
-    limit?: number;
-}): SearchResult[];
-/**
- * Export the search index to a serializable format
- */
-declare function exportSearchIndex(index: FlexSearchDocument): Promise<unknown>;
-/**
- * Import a search index from serialized data
- */
-declare function importSearchIndex(data: Record<string, unknown>): Promise<FlexSearchDocument>;
-
-/**
- * Built-in FlexSearch search provider.
- *
- * This provider uses the local FlexSearch index for search queries.
- * Supports both file-based loading (Node.js) and pre-loaded data (Workers).
- */
-declare class FlexSearchProvider implements SearchProvider {
-    readonly name = "flexsearch";
-    private docs;
-    private searchIndex;
-    private ready;
-    initialize(_context: ProviderContext, initData?: SearchProviderInitData): Promise<void>;
-    isReady(): boolean;
-    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
-    getDocument(url: string): Promise<ProcessedDoc | null>;
-    healthCheck(): Promise<{
-        healthy: boolean;
-        message?: string;
-    }>;
-    /**
-     * Get all loaded documents (for compatibility with existing server code)
-     */
-    getDocs(): Record<string, ProcessedDoc> | null;
-    /**
-     * Get the FlexSearch index (for compatibility with existing server code)
-     */
-    getSearchIndex(): FlexSearchDocument | null;
-}
-
-/**
- * Tool definition for docs_search
- */
-declare const docsSearchTool: {
-    name: string;
-    description: string;
-    inputSchema: {
-        query: z.ZodString;
-        limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-    };
-};
-
-/**
- * Tool definition for docs_fetch
- */
-declare const docsFetchTool: {
-    name: string;
-    description: string;
-    inputSchema: {
-        url: z.ZodString;
-    };
-};
-
-/**
- * Convert HTML string to Markdown
- */
-declare function htmlToMarkdown(html: string): Promise<string>;
-
-/**
- * Parse HTML string into HAST (HTML AST)
- */
-declare function parseHtml(html: string): Root;
-/**
- * Parse HTML file into HAST
- */
-declare function parseHtmlFile(filePath: string): Promise<Root>;
-/**
- * Options for content extraction
- */
-interface ExtractContentOptions {
-    /** CSS selectors for content containers, in priority order */
-    contentSelectors: string[];
-    /** CSS selectors for elements to exclude from content */
-    excludeSelectors: string[];
-}
-/**
- * Extract content from HTML file
- */
-declare function extractContent(filePath: string, options: ExtractContentOptions): Promise<ExtractedContent>;
-
-/**
- * Extract headings from markdown content with their positions
- */
-declare function extractHeadingsFromMarkdown(markdown: string): DocHeading[];
-/**
- * Extract a specific section from markdown by heading ID
- */
-declare function extractSection(markdown: string, headingId: string, headings: DocHeading[]): string | null;
-
-/**
- * Discover all HTML files in the build directory and create routes for them.
- * This is more reliable than using Docusaurus routes as it captures all built pages.
- */
-declare function discoverHtmlFiles(outDir: string): Promise<FlattenedRoute[]>;
-/**
- * Get all processable routes from the build directory
- */
-declare function collectRoutes(outDir: string, excludePatterns: string[]): Promise<FlattenedRoute[]>;
-
-export { type ContentIndexer, type ContentIndexerModule, DocHeading, ExtractedContent, FlattenedRoute, type FlexSearchDocument, FlexSearchIndexer, FlexSearchProvider, McpDocsServer, McpServerConfig, McpServerPluginOptions, ProcessedDoc, type ProviderContext, type SearchOptions, type SearchProvider, type SearchProviderInitData, type SearchProviderModule, SearchResult, buildSearchIndex, collectRoutes, discoverHtmlFiles, docsFetchTool, docsSearchTool, exportSearchIndex, extractContent, extractHeadingsFromMarkdown, extractSection, htmlToMarkdown, importSearchIndex, loadIndexer, loadSearchProvider, mcpServerPlugin, parseHtml, parseHtmlFile, searchIndex };