/**
 * 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>;
    /**
     * Get the number of indexed documents.
     * Used for status reporting and health checks.
     */
    getDocCount?(): number;
    /**
     * Check if the provider is healthy.
     * Used for health checks and debugging.
     */
    healthCheck?(): Promise<{
        healthy: boolean;
        message?: string;
    }>;
}

/**
 * Field name in the search index. Higher weight = ranked higher when matched.
 */
type FlexSearchField = 'title' | 'headings' | 'description' | 'content';
/**
 * Overrides for the built-in FlexSearch index configuration.
 *
 * The defaults are tuned for English content. Sites with long compound
 * words (e.g. German, Finnish) or large doc sets may want to relax
 * `tokenize`, drop `context`, or lower `resolution` to reduce
 * index size.
 *
 * The same config must be supplied at build time (via plugin options)
 * AND at runtime (via `McpServerBaseConfig.flexsearch`). Otherwise the
 * runtime provider deserializes the index with the wrong shape and
 * returns no results.
 */
interface FlexSearchConfig {
    /** Tokenization mode. Default: 'forward'. Use 'strict' for whole-word-only. */
    tokenize?: 'strict' | 'forward' | 'reverse' | 'full';
    /** Ranking resolution 1-9. Default: 9. Lower = smaller index. */
    resolution?: number;
    /** Phrase/proximity context. Default: { resolution: 2, depth: 2, bidirectional: true }. Set to false to disable (much smaller index). */
    context?: false | {
        resolution?: number;
        depth?: number;
        bidirectional?: boolean;
    };
    /** Query result cache. Default: 100. */
    cache?: number | boolean;
    /** Custom tokenizer. Default: lowercase split + English stemmer. */
    encode?: (str: string) => string[];
    /** Weights applied per field during ranking. Defaults: title 3, headings 2, description 1.5, content 1. */
    fieldWeights?: Partial<Record<FlexSearchField, number>>;
}
/**
 * Configuration options for the MCP server plugin
 */
interface McpServerPluginOptions {
    /** Output directory for MCP artifacts (relative to build dir). Default: 'mcp' */
    outputDir?: string;
    /** CSS selectors for content extraction, in order of priority */
    contentSelectors?: string[];
    /** CSS selectors for elements to remove from content before processing */
    excludeSelectors?: string[];
    /** Minimum content length (in characters) to consider a page valid. Default: 50 */
    minContentLength?: number;
    /** Server configuration */
    server?: {
        /** Name of the MCP server */
        name?: string;
        /** Version of the MCP server */
        version?: string;
        /**
         * Explicit MCP HTTP endpoint URL for the install button.
         * When set, `urlBase` and auto-derived paths are ignored.
         */
        url?: string;
        /**
         * How to derive the MCP URL from site config when `url` is not set.
         * - `'origin'` (default): `{siteUrl}/{outputDir}` — MCP at the site origin.
         * - `'site'`: under the Docusaurus `baseUrl`, e.g. `{siteUrl}{baseUrl}{outputDir}`.
         */
        urlBase?: 'origin' | 'site';
    };
    /** Routes to exclude from processing (glob patterns) */
    excludeRoutes?: string[];
    /**
     * Indexers to run during build.
     *
     * - undefined (default): runs 'flexsearch' for backward compatibility
     * - ['flexsearch']: same as default, produces docs.json + search-index.json
     * - ['./my-indexer.js']: runs only custom indexer(s)
     * - false: disables all indexing, no artifacts produced
     *
     * Each string can be:
     * - 'flexsearch' (built-in)
     * - './path/to/indexer.js' (relative path)
     * - '@myorg/custom-indexer' (npm package)
     */
    indexers?: string[] | false;
    /**
     * Search provider module. Default: 'flexsearch'
     *
     * Can be:
     * - 'flexsearch' (built-in, requires FlexSearch indexer to have run)
     * - './path/to/search.js' (relative path)
     * - '@myorg/glean-search' (npm package)
     */
    search?: string;
    /**
     * Overrides for the built-in FlexSearch indexer/provider. See {@link FlexSearchConfig}.
     * Ignored when a custom indexer/provider is used.
     */
    flexsearch?: FlexSearchConfig;
}
/**
 * Resolved plugin options with defaults applied
 */
interface ResolvedPluginOptions {
    outputDir: string;
    contentSelectors: string[];
    excludeSelectors: string[];
    minContentLength: number;
    server: {
        name: string;
        version: string;
        url?: string;
        urlBase?: 'origin' | 'site';
    };
    excludeRoutes: string[];
    /** Indexers to run. undefined means ['flexsearch'], false disables indexing */
    indexers: string[] | false | undefined;
    /** Search provider module */
    search: string;
    /** FlexSearch overrides for the built-in indexer/provider. */
    flexsearch?: FlexSearchConfig;
}
/**
 * A processed documentation page
 */
interface ProcessedDoc {
    /** URL route path (e.g., /docs/getting-started) */
    route: string;
    /** Page title extracted from HTML */
    title: string;
    /** Meta description if available */
    description: string;
    /** Full page content as markdown */
    markdown: string;
    /** Headings with IDs for section navigation */
    headings: DocHeading[];
}
/**
 * A heading within a document
 */
interface DocHeading {
    /** Heading level (1-6) */
    level: number;
    /** Heading text content */
    text: string;
    /** Anchor ID for linking */
    id: string;
    /** Character offset where this section starts in the markdown */
    startOffset: number;
    /** Character offset where this section ends in the markdown */
    endOffset: number;
}
/**
 * Search result from FlexSearch
 */
interface SearchResult {
    /** Full URL of the matching document (use this with docs_fetch) */
    url: string;
    /** Route path of the matching document */
    route: string;
    /** Title of the document */
    title: string;
    /** Relevance score */
    score: number;
    /** Snippet of matching content */
    snippet: string;
    /** Matching headings if any */
    matchingHeadings?: string[];
}
/**
 * Manifest metadata for the MCP artifacts
 */
interface McpManifest {
    /** Plugin version */
    version: string;
    /** Build timestamp */
    buildTime: string;
    /** Number of documents indexed */
    docCount: number;
    /** Server name */
    serverName: string;
    /** Base URL of the documentation site */
    baseUrl?: string;
    /** Names of indexers that ran during build */
    indexers?: string[];
}
/**
 * Per-tool configuration overrides
 */
interface McpToolConfig {
    /** Override the default tool description shown to MCP clients */
    description?: string;
}
/**
 * Overrides for the built-in MCP tools, keyed by tool name
 */
interface McpServerToolsConfig {
    /** Overrides for the docs_search tool */
    docs_search?: McpToolConfig;
    /** Overrides for the docs_fetch tool */
    docs_fetch?: McpToolConfig;
}
/**
 * Common MCP server configuration shared by all loading modes
 */
interface McpServerBaseConfig {
    /** Server name */
    name: string;
    /** Server version */
    version?: string;
    /** Base URL for constructing full page URLs (e.g., https://docs.example.com) */
    baseUrl?: string;
    /**
     * Search provider. Default: 'flexsearch'.
     *
     * Accepts either a module specifier (string) loaded via dynamic `import()`,
     * or a {@link SearchProvider} instance. Pass an instance when running in a
     * bundled environment (Cloudflare Workers, etc.) where dynamic import of
     * arbitrary specifiers is not available.
     */
    search?: string | SearchProvider;
    /**
     * Overrides for the built-in FlexSearch provider. See {@link FlexSearchConfig}.
     * Must match the config used at index build time. Ignored when `search` is
     * a custom provider.
     */
    flexsearch?: FlexSearchConfig;
    /**
     * Instructions describing how to use the server and its tools.
     * Surfaced to MCP clients in the initialize response.
     */
    instructions?: string;
    /** Per-tool overrides, such as custom descriptions */
    tools?: McpServerToolsConfig;
}
/**
 * MCP Server configuration for file-based loading
 */
interface McpServerFileConfig extends McpServerBaseConfig {
    /** Path to docs.json file */
    docsPath: string;
    /** Path to search-index.json file */
    indexPath: string;
}
/**
 * MCP Server configuration for pre-loaded data (e.g., Cloudflare Workers)
 */
interface McpServerDataConfig extends McpServerBaseConfig {
    /** Pre-loaded docs data */
    docs: Record<string, ProcessedDoc>;
    /** Pre-loaded search index data (exported from FlexSearch via exportSearchIndex) */
    searchIndexData: Record<string, unknown>;
}
/**
 * MCP Server configuration - supports both file-based and pre-loaded data modes
 */
type McpServerConfig = McpServerFileConfig | McpServerDataConfig;
/**
 * Input parameters for docs_search tool
 */
interface DocsSearchParams {
    /** Search query string */
    query: string;
    /** Maximum number of results (default: 16, max: 20) */
    limit?: number;
}
/**
 * Input parameters for docs_fetch tool
 */
interface DocsFetchParams {
    /** Full URL of the page to fetch */
    url: string;
}
/**
 * Default plugin options
 */
declare const DEFAULT_PLUGIN_OPTIONS: ResolvedPluginOptions;

export { type ContentIndexer as C, DEFAULT_PLUGIN_OPTIONS as D, type FlexSearchConfig as F, type McpServerDataConfig as M, type ProcessedDoc as P, type SearchProvider as S, type McpServerConfig as a, type McpServerPluginOptions as b, type DocHeading as c, type DocsFetchParams as d, type DocsSearchParams as e, type McpManifest as f, type McpServerFileConfig as g, type ProviderContext as h, type SearchOptions as i, type SearchProviderInitData as j, type SearchResult as k };