docusaurus-plugin-mcp-server 0.5.0

package/dist/index.d.mts

@@ -0,0 +1,234 @@
+import { LoadContext, Plugin } from '@docusaurus/types';
+import { a as McpServerPluginOptions, M as McpServerConfig, P as ProcessedDoc, S as SearchResult, E as ExtractedContent, D as DocHeading, F as FlattenedRoute } from './index-CzA4FjeE.mjs';
+export { b as DEFAULT_OPTIONS, c as DocsGetPageParams, d as DocsGetSectionParams, e as DocsIndex, f as DocsSearchParams, g as McpManifest, h as McpServerDataConfig, i as McpServerFileConfig, R as ResolvedPluginOptions } from './index-CzA4FjeE.mjs';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { Root } from 'hast';
+import FlexSearch from 'flexsearch';
+
+/**
+ * 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 docs;
+    private searchIndex;
+    private mcpServer;
+    private initialized;
+    constructor(config: McpServerConfig);
+    /**
+     * Register all MCP tools using the SDK's registerTool API
+     */
+    private registerTools;
+    /**
+     * Load docs and search index
+     *
+     * 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;
+    }>;
+    /**
+     * Get the underlying McpServer instance
+     *
+     * Useful for advanced use cases like custom transports
+     */
+    getMcpServer(): McpServer;
+}
+
+/**
+ * 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
+ */
+declare function buildSearchIndex(docs: ProcessedDoc[]): 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>;
+
+/**
+ * Tool definition for docs_search
+ */
+declare const docsSearchTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+                default: number;
+            };
+        };
+        required: string[];
+    };
+};
+
+/**
+ * Tool definition for docs_get_page
+ */
+declare const docsGetPageTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            route: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+
+/**
+ * Tool definition for docs_get_section
+ */
+declare const docsGetSectionTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            route: {
+                type: string;
+                description: string;
+            };
+            headingId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+
+/**
+ * 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 { DocHeading, ExtractedContent, FlattenedRoute, type FlexSearchDocument, McpDocsServer, McpServerConfig, McpServerPluginOptions, ProcessedDoc, SearchResult, buildSearchIndex, collectRoutes, mcpServerPlugin as default, discoverHtmlFiles, docsGetPageTool, docsGetSectionTool, docsSearchTool, exportSearchIndex, extractContent, extractHeadingsFromMarkdown, extractSection, htmlToMarkdown, importSearchIndex, mcpServerPlugin, parseHtml, parseHtmlFile, searchIndex };

package/dist/index.d.ts

@@ -0,0 +1,234 @@
+import { LoadContext, Plugin } from '@docusaurus/types';
+import { a as McpServerPluginOptions, M as McpServerConfig, P as ProcessedDoc, S as SearchResult, E as ExtractedContent, D as DocHeading, F as FlattenedRoute } from './index-CzA4FjeE.js';
+export { b as DEFAULT_OPTIONS, c as DocsGetPageParams, d as DocsGetSectionParams, e as DocsIndex, f as DocsSearchParams, g as McpManifest, h as McpServerDataConfig, i as McpServerFileConfig, R as ResolvedPluginOptions } from './index-CzA4FjeE.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { Root } from 'hast';
+import FlexSearch from 'flexsearch';
+
+/**
+ * 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 docs;
+    private searchIndex;
+    private mcpServer;
+    private initialized;
+    constructor(config: McpServerConfig);
+    /**
+     * Register all MCP tools using the SDK's registerTool API
+     */
+    private registerTools;
+    /**
+     * Load docs and search index
+     *
+     * 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;
+    }>;
+    /**
+     * Get the underlying McpServer instance
+     *
+     * Useful for advanced use cases like custom transports
+     */
+    getMcpServer(): McpServer;
+}
+
+/**
+ * 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
+ */
+declare function buildSearchIndex(docs: ProcessedDoc[]): 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>;
+
+/**
+ * Tool definition for docs_search
+ */
+declare const docsSearchTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+                default: number;
+            };
+        };
+        required: string[];
+    };
+};
+
+/**
+ * Tool definition for docs_get_page
+ */
+declare const docsGetPageTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            route: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+
+/**
+ * Tool definition for docs_get_section
+ */
+declare const docsGetSectionTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            route: {
+                type: string;
+                description: string;
+            };
+            headingId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+
+/**
+ * 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 { DocHeading, ExtractedContent, FlattenedRoute, type FlexSearchDocument, McpDocsServer, McpServerConfig, McpServerPluginOptions, ProcessedDoc, SearchResult, buildSearchIndex, collectRoutes, mcpServerPlugin as default, discoverHtmlFiles, docsGetPageTool, docsGetSectionTool, docsSearchTool, exportSearchIndex, extractContent, extractHeadingsFromMarkdown, extractSection, htmlToMarkdown, importSearchIndex, mcpServerPlugin, parseHtml, parseHtmlFile, searchIndex };