docusaurus-plugin-mcp-server 0.10.2 → 0.12.0

package/README.md

@@ -206,7 +206,7 @@ Search across documentation with relevance ranking. Returns matching documents w
   "name": "docs_search",
   "arguments": {
     "query": "authentication",
-    "limit": 5
+    "limit": 16
   }
 }
 ```
@@ -214,7 +214,7 @@ Search across documentation with relevance ranking. Returns matching documents w
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `query` | `string` | required | Search query |
-| `limit` | `number` | `5` | Max results (1-20) |
+| `limit` | `number` | `16` | Max results (1-20) |
 
 **Response includes:**
 - Full URL for each result (use with `docs_fetch`)
@@ -255,6 +255,8 @@ Retrieve full page content as markdown. Use this after searching to get the comp
 | `server.name` | `string` | `'docs-mcp-server'` | Name of the MCP server |
 | `server.version` | `string` | `'1.0.0'` | Version of the MCP server |
 | `excludeRoutes` | `string[]` | `['/404*', '/search*']` | Routes to exclude (glob patterns) |
+| `indexers` | `string[] \| false` | `['flexsearch']` | Indexers to run during build. Use `false` to disable. Supports built-in (`'flexsearch'`), relative paths, or npm packages. |
+| `search` | `string` | `'flexsearch'` | Search provider module for runtime queries. Supports built-in (`'flexsearch'`), relative paths, or npm packages. |
 
 ### Default Selectors
 
@@ -268,6 +270,90 @@ Retrieve full page content as markdown. Use this after searching to get the comp
 ['nav', 'header', 'footer', 'aside', '[role="navigation"]', '[role="banner"]', '[role="contentinfo"]']
 ```
 
+## Custom Providers
+
+The plugin uses a two-phase provider model: **indexers** run at build time to process documents, and **search providers** handle queries at runtime. Both are pluggable.
+
+### ContentIndexer
+
+Implement `ContentIndexer` to push documents to an external system during build:
+
+```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 {
+    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();
+  }
+}
+```
+
+### SearchProvider
+
+Implement `SearchProvider` to delegate runtime search to an external service:
+
+```typescript
+import type { SearchProvider, ProviderContext, SearchOptions } from 'docusaurus-plugin-mcp-server';
+import type { SearchResult } 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 [];
+  }
+}
+```
+
+### Configuring Custom Providers
+
+```javascript
+// docusaurus.config.js
+module.exports = {
+  plugins: [
+    [
+      'docusaurus-plugin-mcp-server',
+      {
+        // Run both the built-in FlexSearch indexer and a custom one
+        indexers: ['flexsearch', './my-algolia-indexer.js'],
+        // Use a custom search provider at runtime
+        search: '@myorg/glean-search',
+      },
+    ],
+  ],
+};
+```
+
 ## Server Configuration
 
 For the runtime adapters:
@@ -408,47 +494,24 @@ The plugin operates in two phases:
 
 ## Local Development
 
-Run a local HTTP server for testing:
+Run a local MCP server for testing using the built-in Node adapter:
 
 ```javascript
 // mcp-server.mjs
-import http from 'http';
-import { McpDocsServer } from 'docusaurus-plugin-mcp-server';
-import path from 'path';
-import { fileURLToPath } from 'url';
+import { createNodeServer } from 'docusaurus-plugin-mcp-server/adapters';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-const server = new McpDocsServer({
-  docsPath: path.join(__dirname, 'build/mcp/docs.json'),
-  indexPath: path.join(__dirname, 'build/mcp/search-index.json'),
+createNodeServer({
+  docsPath: './build/mcp/docs.json',
+  indexPath: './build/mcp/search-index.json',
   name: 'my-docs',
   baseUrl: 'http://localhost:3000',
-});
-
-http.createServer(async (req, res) => {
-  if (req.method === 'OPTIONS') {
-    res.writeHead(204, {
-      'Access-Control-Allow-Origin': '*',
-      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-      'Access-Control-Allow-Headers': 'Content-Type',
-    });
-    res.end();
-    return;
-  }
-
-  if (req.method !== 'POST') {
-    res.writeHead(405);
-    res.end();
-    return;
-  }
-
-  await server.handleHttpRequest(req, res);
 }).listen(3456, () => {
   console.log('MCP server at http://localhost:3456');
 });
 ```
 
+The Node adapter handles CORS, preflight requests, and health checks (GET) automatically.
+
 Connect Claude Code:
 ```bash
 claude mcp add --transport http my-docs http://localhost:3456
@@ -494,19 +557,34 @@ import {
   createVercelHandler,
   createNetlifyHandler,
   createCloudflareHandler,
+  createNodeServer,
+  createNodeHandler,
   generateAdapterFiles,
 } from 'docusaurus-plugin-mcp-server/adapters';
 ```
 
+- `createNodeServer(options)` — Creates a complete Node.js HTTP server for local development. Returns an `http.Server` ready to `.listen()`.
+- `createNodeHandler(options)` — Creates a request handler function compatible with `http.createServer()`. Use this when you need to integrate with an existing server.
+
 ### Theme Exports
 
 ```tsx
 import {
   McpInstallButton,
   type McpInstallButtonProps,
+  useMcpRegistry,
+  createDocsRegistry,
+  createDocsRegistryOptions,
+  type McpConfig,
 } from 'docusaurus-plugin-mcp-server/theme';
 ```
 
+- `McpInstallButton` — Dropdown button for users to install the MCP server in their AI tool.
+- `useMcpRegistry()` — React hook that returns the MCP config registry from plugin global data. Returns `undefined` if the plugin is not installed.
+- `createDocsRegistry(config)` — Creates a pre-configured `MCPConfigRegistry` for documentation servers.
+- `createDocsRegistryOptions(config)` — Returns registry options without creating the registry.
+- `McpConfig` — Type for `{ serverUrl: string; serverName: string }`.
+
 ## Requirements
 
 - Node.js >= 20

package/dist/adapters-entry.d.ts

@@ -1,5 +1,5 @@
 import { IncomingMessage, ServerResponse, Server } from 'node:http';
-import { M as McpServerConfig, P as ProcessedDoc, a as McpServerFileConfig } from './index-j-CdaS6k.js';
+import { M as McpServerFileConfig, P as ProcessedDoc } from './index-BhwLRGxJ.js';
 
 /**
  * Vercel adapter for MCP server
@@ -40,7 +40,9 @@ interface VercelResponse extends ServerResponse {
  *
  * Uses the MCP SDK's StreamableHTTPServerTransport for proper protocol handling.
  */
-declare function createVercelHandler(config: McpServerConfig): (req: VercelRequest, res: VercelResponse) => Promise<void>;
+declare function createVercelHandler(config: McpServerFileConfig & {
+    corsOrigin?: string;
+}): (req: VercelRequest, res: VercelResponse) => Promise<void>;
 
 /**
  * Netlify adapter for MCP server
@@ -103,7 +105,9 @@ interface NetlifyResponse {
  * Uses the MCP SDK's WebStandardStreamableHTTPServerTransport for
  * proper protocol handling.
  */
-declare function createNetlifyHandler(config: McpServerConfig): (event: NetlifyEvent, _context: NetlifyContext) => Promise<NetlifyResponse>;
+declare function createNetlifyHandler(config: McpServerFileConfig & {
+    corsOrigin?: string;
+}): (event: NetlifyEvent, _context: NetlifyContext) => Promise<NetlifyResponse>;
 
 /**
  * Cloudflare Workers adapter for MCP server
@@ -145,6 +149,8 @@ interface CloudflareAdapterConfig {
     version?: string;
     /** Base URL for constructing full page URLs */
     baseUrl?: string;
+    /** CORS origin to allow. Defaults to '*' (all origins). */
+    corsOrigin?: string;
 }
 /**
  * Create a Cloudflare Workers fetch handler for the MCP server