apcore-mcp 0.9.0 → 0.10.1

package/README.md

@@ -186,6 +186,29 @@ function serve(
 ): Promise<void>;
 ```
 
+### `asyncServe(registryOrExecutor, options?)`
+
+Embed the MCP server into a larger Node.js HTTP application. Returns an HTTP request handler and a close function for lifecycle management.
+
+```typescript
+import { asyncServe } from "apcore-mcp";
+
+const { handler, close } = await asyncServe(executor, {
+  name: "apcore-mcp",
+  explorer: true,
+  allowExecute: true,
+});
+
+// Mount in a custom HTTP server
+const server = http.createServer(handler);
+server.listen(8000);
+
+// Clean up when done
+await close();
+```
+
+Accepts the same options as `serve()` except `transport`, `host`, `port`, `onStartup`, and `onShutdown`.
+
 ### Tool Explorer
 
 When `explorer: true` is passed to `serve()`, a browser-based Tool Explorer UI is mounted on HTTP transports. It provides an interactive page for browsing tool schemas and testing tool execution.
@@ -295,37 +318,6 @@ function toOpenaiTools(
 - `tags` — Filter modules by tags
 - `prefix` — Filter modules by ID prefix
 
-## Architecture
-
-```
-src/
-├── index.ts              # Public API: serve(), toOpenaiTools()
-├── cli.ts                # CLI entry point
-├── types.ts              # TypeScript interfaces
-├── helpers.ts            # reportProgress() / elicit() helpers
-├── adapters/
-│   ├── schema.ts         # JSON Schema $ref inlining
-│   ├── annotations.ts    # Module annotations -> MCP hints
-│   ├── errors.ts         # Error sanitization
-│   ├── idNormalizer.ts   # Dot-notation <-> dash-notation
-│   └── approval.ts       # Elicitation-based approval handler
-├── auth/
-│   ├── jwt.ts            # JWT Bearer token authenticator
-│   ├── storage.ts        # AsyncLocalStorage identity propagation
-│   └── types.ts          # Authenticator / Identity interfaces
-├── converters/
-│   └── openai.ts         # OpenAI tool definition converter
-├── explorer/
-│   ├── handler.ts        # Explorer HTTP route handler
-│   └── html.ts           # Self-contained HTML/CSS/JS page
-└── server/
-    ├── factory.ts        # MCP Server creation & handler registration
-    ├── router.ts         # Tool call execution routing
-    ├── context.ts        # BridgeContext for executor call chains
-    ├── transport.ts      # Transport lifecycle (stdio/HTTP/SSE)
-    └── listener.ts       # Dynamic registry event listener
-```
-
 ## Examples
 
 See [examples/README.md](examples/README.md) for runnable demos covering both class-based modules and zero-code-intrusion wrapping via the `module()` factory.
@@ -358,10 +350,6 @@ npm run build
 npm run dev
 ```
 
-## Testing
-
-313 tests across 23 test suites.
-
 ## License
 
 Apache-2.0

package/dist/adapters/annotations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/adapters/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEzE,qBAAa,gBAAgB;IAC3B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,kBAAkB;IAoB3E;;;;;;OAMG;IACH,mBAAmB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,MAAM;IAwDlE;;;;OAIG;IACH,mBAAmB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO;CAOpE"}
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/adapters/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAczE,qBAAa,gBAAgB;IAC3B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,kBAAkB;IAoB3E;;;;;;OAMG;IACH,mBAAmB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,MAAM;IAmDlE;;;;OAIG;IACH,mBAAmB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO;CAOpE"}

package/dist/adapters/annotations.js

@@ -5,6 +5,17 @@
  * hint-based annotation system. Also provides description suffix generation
  * and approval requirement checking.
  */
+/** Default annotation values matching apcore's ModuleAnnotations defaults. */
+const DEFAULT_ANNOTATIONS = {
+    readonly: false,
+    destructive: false,
+    idempotent: false,
+    requiresApproval: false,
+    openWorld: true,
+    streaming: false,
+    cacheable: false,
+    paginated: false,
+};
 export class AnnotationMapper {
     /**
      * Convert apcore module annotations to MCP annotations dict.
@@ -45,14 +56,6 @@ export class AnnotationMapper {
         if (annotations === null) {
             return "";
         }
-        const DEFAULTS = {
-            readonly: false,
-            destructive: false,
-            idempotent: false,
-            requires_approval: false,
-            open_world: true,
-            streaming: false,
-        };
         const warnings = [];
         if (annotations.destructive) {
             warnings.push("WARNING: DESTRUCTIVE - This operation may irreversibly modify or " +
@@ -62,18 +65,22 @@ export class AnnotationMapper {
             warnings.push("REQUIRES APPROVAL: Human confirmation is required before execution.");
         }
         const parts = [];
-        if (annotations.readonly !== DEFAULTS.readonly)
+        if (annotations.readonly !== DEFAULT_ANNOTATIONS.readonly)
             parts.push(`readonly=${annotations.readonly}`);
-        if (annotations.destructive !== DEFAULTS.destructive)
+        if (annotations.destructive !== DEFAULT_ANNOTATIONS.destructive)
             parts.push(`destructive=${annotations.destructive}`);
-        if (annotations.idempotent !== DEFAULTS.idempotent)
+        if (annotations.idempotent !== DEFAULT_ANNOTATIONS.idempotent)
             parts.push(`idempotent=${annotations.idempotent}`);
-        if (annotations.requiresApproval !== DEFAULTS.requires_approval)
+        if (annotations.requiresApproval !== DEFAULT_ANNOTATIONS.requiresApproval)
             parts.push(`requires_approval=${annotations.requiresApproval}`);
-        if (annotations.openWorld !== DEFAULTS.open_world)
+        if (annotations.openWorld !== DEFAULT_ANNOTATIONS.openWorld)
             parts.push(`open_world=${annotations.openWorld}`);
-        if (annotations.streaming !== DEFAULTS.streaming)
+        if (annotations.streaming !== DEFAULT_ANNOTATIONS.streaming)
             parts.push(`streaming=${annotations.streaming}`);
+        if ((annotations.cacheable ?? false) !== DEFAULT_ANNOTATIONS.cacheable)
+            parts.push(`cacheable=${annotations.cacheable}`);
+        if ((annotations.paginated ?? false) !== DEFAULT_ANNOTATIONS.paginated)
+            parts.push(`paginated=${annotations.paginated}`);
         if (warnings.length === 0 && parts.length === 0) {
             return "";
         }

package/dist/adapters/annotations.js.map

@@ -1 +1 @@
-{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../src/adapters/annotations.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../src/adapters/annotations.ts"],"names":[],"mappings":"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"}

package/dist/apcore-mcp.d.ts

@@ -0,0 +1,150 @@
+/**
+ * APCoreMCP: Unified entry point for apcore-mcp.
+ *
+ * Wraps Registry discovery, MCP server creation, and OpenAI tool export
+ * into a single object with a simple API.
+ *
+ * @example
+ * ```ts
+ * // Minimal — just point to extensions
+ * const mcp = new APCoreMCP("./extensions");
+ * await mcp.serve();
+ *
+ * // With options
+ * const mcp = new APCoreMCP("./extensions", { name: "my-server", tags: ["public"] });
+ * await mcp.serve({ transport: "streamable-http", port: 9000, explorer: true });
+ *
+ * // Export OpenAI tools
+ * const tools = mcp.toOpenaiTools();
+ *
+ * // Embed into existing HTTP server
+ * const app = await mcp.asyncServe({ explorer: true });
+ * // app.handler is a Node.js request handler; call app.close() on shutdown
+ *
+ * // Use existing Registry or Executor
+ * const mcp = new APCoreMCP(registry);
+ * ```
+ */
+import type { RegistryOrExecutor, Registry, Executor, OpenAIToolDef } from "./types.js";
+import type { Authenticator } from "./auth/types.js";
+import type { MetricsExporter } from "./server/transport.js";
+import type { AsyncServeApp, ToOpenaiToolsOptions } from "./index.js";
+/** Options for the APCoreMCP constructor. */
+export interface APCoreMCPOptions {
+    /** MCP server name. Default: "apcore-mcp" */
+    name?: string;
+    /** MCP server version. Default: package version */
+    version?: string;
+    /** Filter modules by tags. */
+    tags?: string[] | null;
+    /** Filter modules by prefix. */
+    prefix?: string | null;
+    /** Minimum log level. */
+    logLevel?: "DEBUG" | "INFO" | "WARNING" | "ERROR" | "CRITICAL";
+    /** Enable input validation against schemas. Default: false */
+    validateInputs?: boolean;
+    /** Optional MetricsCollector for Prometheus /metrics endpoint. */
+    metricsCollector?: MetricsExporter;
+    /** Optional authenticator for request authentication (HTTP transports only). */
+    authenticator?: Authenticator;
+    /** If true (default), unauthenticated requests are rejected with 401. */
+    requireAuth?: boolean;
+    /** Custom paths exempt from authentication. */
+    exemptPaths?: string[];
+    /** Optional approval handler passed to the Executor. */
+    approvalHandler?: unknown;
+    /**
+     * Optional function that formats execution results into text for LLM consumption.
+     * When undefined, results are serialised with `JSON.stringify(result)`.
+     */
+    outputFormatter?: (result: Record<string, unknown>) => string;
+}
+/** Options for APCoreMCP.serve() (transport + lifecycle subset). */
+export interface APCoreMCPServeOptions {
+    /** Transport type. Default: "stdio" */
+    transport?: "stdio" | "streamable-http" | "sse";
+    /** Host address for HTTP-based transports. Default: "127.0.0.1" */
+    host?: string;
+    /** Port number for HTTP-based transports. Default: 8000 */
+    port?: number;
+    /** Callback invoked before the server starts. */
+    onStartup?: () => void | Promise<void>;
+    /** Callback invoked after the server stops. */
+    onShutdown?: () => void | Promise<void>;
+    /** Enable the browser-based Tool Explorer UI (HTTP only). Default: false */
+    explorer?: boolean;
+    /** URL prefix for the explorer. Default: "/explorer" */
+    explorerPrefix?: string;
+    /** Allow tool execution from the explorer UI. Default: false */
+    allowExecute?: boolean;
+    /** Title for the explorer UI page. */
+    explorerTitle?: string;
+    /** Project name shown in the explorer UI footer. */
+    explorerProjectName?: string;
+    /** Project URL shown in the explorer UI footer. */
+    explorerProjectUrl?: string;
+}
+/** Options for APCoreMCP.asyncServe() (embed subset). */
+export interface APCoreMCPAsyncServeOptions {
+    /** Enable the browser-based Tool Explorer UI. Default: false */
+    explorer?: boolean;
+    /** URL prefix for the explorer. Default: "/explorer" */
+    explorerPrefix?: string;
+    /** Allow tool execution from the explorer UI. Default: false */
+    allowExecute?: boolean;
+    /** MCP endpoint path. Default: "/mcp" */
+    endpoint?: string;
+}
+export declare class APCoreMCP {
+    private _backend;
+    private readonly _options;
+    private _registry;
+    private _executor;
+    private readonly _extensionsDir;
+    /**
+     * Create an APCoreMCP instance.
+     *
+     * @param extensionsDirOrBackend - Path to an apcore extensions directory,
+     *   or an existing Registry or Executor instance.
+     * @param options - Configuration options.
+     */
+    constructor(extensionsDirOrBackend: string | RegistryOrExecutor, options?: APCoreMCPOptions);
+    /** The underlying apcore Registry. */
+    get registry(): Registry;
+    /** The underlying apcore Executor (resolved lazily). */
+    get executor(): Executor | undefined;
+    /** List all discovered module IDs that will be exposed as tools. */
+    get tools(): string[];
+    /**
+     * Build the full ServeOptions by merging constructor options with per-call overrides.
+     */
+    private _buildServeOptions;
+    /**
+     * Resolve the backend (handles extensions dir lazy init).
+     */
+    private _resolveBackend;
+    /**
+     * Launch the MCP server (blocks until shutdown).
+     *
+     * @param options - Transport and lifecycle options.
+     */
+    serve(options?: APCoreMCPServeOptions): Promise<void>;
+    /**
+     * Build an embeddable MCP HTTP request handler.
+     *
+     * Unlike `serve()`, this does NOT create its own HTTP server. Returns a
+     * Node.js HTTP request handler and a close function.
+     *
+     * @param options - Embed options.
+     * @returns Object with `handler` and `close()`.
+     */
+    asyncServe(options?: APCoreMCPAsyncServeOptions): Promise<AsyncServeApp>;
+    /**
+     * Export modules as OpenAI-compatible tool definitions.
+     *
+     * @param options - Conversion options (embedAnnotations, strict).
+     * @returns List of OpenAI tool definition dicts.
+     */
+    toOpenaiTools(options?: ToOpenaiToolsOptions): OpenAIToolDef[];
+}
+//# sourceMappingURL=apcore-mcp.d.ts.map

package/dist/apcore-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apcore-mcp.d.ts","sourceRoot":"","sources":["../src/apcore-mcp.ts"],"names":[],"mappings":"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"}

package/dist/apcore-mcp.js

@@ -0,0 +1,217 @@
+/**
+ * APCoreMCP: Unified entry point for apcore-mcp.
+ *
+ * Wraps Registry discovery, MCP server creation, and OpenAI tool export
+ * into a single object with a simple API.
+ *
+ * @example
+ * ```ts
+ * // Minimal — just point to extensions
+ * const mcp = new APCoreMCP("./extensions");
+ * await mcp.serve();
+ *
+ * // With options
+ * const mcp = new APCoreMCP("./extensions", { name: "my-server", tags: ["public"] });
+ * await mcp.serve({ transport: "streamable-http", port: 9000, explorer: true });
+ *
+ * // Export OpenAI tools
+ * const tools = mcp.toOpenaiTools();
+ *
+ * // Embed into existing HTTP server
+ * const app = await mcp.asyncServe({ explorer: true });
+ * // app.handler is a Node.js request handler; call app.close() on shutdown
+ *
+ * // Use existing Registry or Executor
+ * const mcp = new APCoreMCP(registry);
+ * ```
+ */
+import { serve, asyncServe, toOpenaiTools, resolveRegistry, } from "./index.js";
+export class APCoreMCP {
+    _backend;
+    _options;
+    _registry;
+    _executor;
+    _extensionsDir;
+    /**
+     * Create an APCoreMCP instance.
+     *
+     * @param extensionsDirOrBackend - Path to an apcore extensions directory,
+     *   or an existing Registry or Executor instance.
+     * @param options - Configuration options.
+     */
+    constructor(extensionsDirOrBackend, options = {}) {
+        // Validate upfront
+        const name = options.name ?? "apcore-mcp";
+        if (!name || name.length === 0) {
+            throw new Error("name must not be empty");
+        }
+        if (name.length > 255) {
+            throw new Error("name must not exceed 255 characters");
+        }
+        if (options.tags) {
+            for (const tag of options.tags) {
+                if (!tag || tag.length === 0) {
+                    throw new Error("tags must not contain empty strings");
+                }
+            }
+        }
+        if (options.prefix !== undefined && options.prefix !== null && options.prefix.length === 0) {
+            throw new Error("prefix must not be empty if provided");
+        }
+        this._options = { name, ...options };
+        if (typeof extensionsDirOrBackend === "string") {
+            // Defer discovery to first use — will be resolved lazily
+            this._backend = null;
+            this._extensionsDir = extensionsDirOrBackend;
+        }
+        else {
+            this._backend = extensionsDirOrBackend;
+            this._extensionsDir = undefined;
+        }
+    }
+    /** The underlying apcore Registry. */
+    get registry() {
+        if (!this._registry) {
+            if (this._backend !== null) {
+                this._registry = resolveRegistry(this._backend);
+            }
+            else {
+                throw new Error("Registry not yet resolved. Call serve() or asyncServe() first, " +
+                    "or pass a Registry/Executor to the constructor.");
+            }
+        }
+        return this._registry;
+    }
+    /** The underlying apcore Executor (resolved lazily). */
+    get executor() {
+        return this._executor;
+    }
+    /** List all discovered module IDs that will be exposed as tools. */
+    get tools() {
+        const reg = this.registry;
+        const result = reg.list({
+            tags: this._options.tags ?? undefined,
+            prefix: this._options.prefix ?? undefined,
+        });
+        // registry.list() may return ModuleDescriptor[] or string[] depending on apcore-js version
+        if (result.length === 0)
+            return [];
+        if (typeof result[0] === "string")
+            return result;
+        return result.map((d) => d.moduleId);
+    }
+    /**
+     * Build the full ServeOptions by merging constructor options with per-call overrides.
+     */
+    _buildServeOptions(overrides = {}) {
+        return {
+            transport: overrides.transport,
+            host: overrides.host,
+            port: overrides.port,
+            name: this._options.name,
+            version: this._options.version,
+            validateInputs: this._options.validateInputs,
+            tags: this._options.tags,
+            prefix: this._options.prefix,
+            logLevel: this._options.logLevel,
+            onStartup: overrides.onStartup,
+            onShutdown: overrides.onShutdown,
+            metricsCollector: this._options.metricsCollector,
+            explorer: overrides.explorer,
+            explorerPrefix: overrides.explorerPrefix,
+            allowExecute: overrides.allowExecute,
+            explorerTitle: overrides.explorerTitle,
+            explorerProjectName: overrides.explorerProjectName,
+            explorerProjectUrl: overrides.explorerProjectUrl,
+            authenticator: this._options.authenticator,
+            requireAuth: this._options.requireAuth,
+            exemptPaths: this._options.exemptPaths,
+            approvalHandler: this._options.approvalHandler,
+            outputFormatter: this._options.outputFormatter,
+        };
+    }
+    /**
+     * Resolve the backend (handles extensions dir lazy init).
+     */
+    async _resolveBackend() {
+        if (this._backend !== null)
+            return this._backend;
+        if (!this._extensionsDir) {
+            throw new Error("No backend configured");
+        }
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const apcore = await import("apcore-js");
+            const RegistryClass = apcore.Registry ?? apcore.default?.Registry;
+            if (!RegistryClass) {
+                throw new Error("Cannot find Registry class in apcore-js");
+            }
+            const registry = new RegistryClass({ extensionsDir: this._extensionsDir });
+            if (typeof registry.discover === "function") {
+                await registry.discover();
+            }
+            this._registry = registry;
+            this._backend = registry;
+            return registry;
+        }
+        catch (err) {
+            throw new Error(`Failed to create Registry from extensions dir "${this._extensionsDir}". ` +
+                `Ensure apcore-js is installed. Original error: ${err}`);
+        }
+    }
+    /**
+     * Launch the MCP server (blocks until shutdown).
+     *
+     * @param options - Transport and lifecycle options.
+     */
+    async serve(options = {}) {
+        const backend = await this._resolveBackend();
+        await serve(backend, this._buildServeOptions(options));
+    }
+    /**
+     * Build an embeddable MCP HTTP request handler.
+     *
+     * Unlike `serve()`, this does NOT create its own HTTP server. Returns a
+     * Node.js HTTP request handler and a close function.
+     *
+     * @param options - Embed options.
+     * @returns Object with `handler` and `close()`.
+     */
+    async asyncServe(options = {}) {
+        const backend = await this._resolveBackend();
+        const asyncOpts = {
+            name: this._options.name,
+            version: this._options.version,
+            validateInputs: this._options.validateInputs,
+            tags: this._options.tags,
+            prefix: this._options.prefix,
+            logLevel: this._options.logLevel,
+            metricsCollector: this._options.metricsCollector,
+            explorer: options.explorer,
+            explorerPrefix: options.explorerPrefix,
+            allowExecute: options.allowExecute,
+            authenticator: this._options.authenticator,
+            requireAuth: this._options.requireAuth,
+            exemptPaths: this._options.exemptPaths,
+            approvalHandler: this._options.approvalHandler,
+            endpoint: options.endpoint,
+            outputFormatter: this._options.outputFormatter,
+        };
+        return asyncServe(backend, asyncOpts);
+    }
+    /**
+     * Export modules as OpenAI-compatible tool definitions.
+     *
+     * @param options - Conversion options (embedAnnotations, strict).
+     * @returns List of OpenAI tool definition dicts.
+     */
+    toOpenaiTools(options = {}) {
+        const reg = this.registry;
+        return toOpenaiTools(reg, {
+            ...options,
+            tags: this._options.tags ?? undefined,
+            prefix: this._options.prefix ?? undefined,
+        });
+    }
+}
+//# sourceMappingURL=apcore-mcp.js.map

package/dist/apcore-mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apcore-mcp.js","sourceRoot":"","sources":["../src/apcore-mcp.ts"],"names":[],"mappings":"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"}

package/dist/auth/hooks.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Auth hook builder for mcp-embedded-ui explorer integration.
+ *
+ * Mirrors the Python `_build_auth_hook` pattern from apcore-mcp-python.
+ * Bridges the Authenticator interface to mcp-embedded-ui's AuthHook,
+ * propagating identity through AsyncLocalStorage for the call chain.
+ */
+import type { Authenticator } from "./types.js";
+/**
+ * Minimal incoming request shape accepted by the auth hook.
+ * Compatible with mcp-embedded-ui's IncomingRequest.
+ */
+interface IncomingRequest {
+    headers: Record<string, string | string[] | undefined>;
+}
+/**
+ * Build an auth hook for mcp-embedded-ui that bridges to an Authenticator.
+ *
+ * The hook:
+ * 1. Extracts headers from the incoming request
+ * 2. Delegates to `authenticator.authenticate()` for token validation
+ * 3. Throws on auth failure (mcp-embedded-ui catches this and returns 401)
+ * 4. Wraps `next()` in `identityStorage.run()` so `getCurrentIdentity()` works
+ *
+ * @param authenticator - An Authenticator instance (e.g. JWTAuthenticator)
+ * @returns An auth hook function compatible with mcp-embedded-ui's AuthHook type
+ */
+export declare function buildExplorerAuthHook(authenticator: Authenticator): (req: IncomingRequest, next: () => Promise<Response>) => Promise<Response>;
+export {};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/auth/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/auth/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhD;;;GAGG;AACH,UAAU,eAAe;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;CACxD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,aAAa,GAC3B,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAS5E"}

package/dist/auth/hooks.js

@@ -0,0 +1,31 @@
+/**
+ * Auth hook builder for mcp-embedded-ui explorer integration.
+ *
+ * Mirrors the Python `_build_auth_hook` pattern from apcore-mcp-python.
+ * Bridges the Authenticator interface to mcp-embedded-ui's AuthHook,
+ * propagating identity through AsyncLocalStorage for the call chain.
+ */
+import { identityStorage } from "./storage.js";
+/**
+ * Build an auth hook for mcp-embedded-ui that bridges to an Authenticator.
+ *
+ * The hook:
+ * 1. Extracts headers from the incoming request
+ * 2. Delegates to `authenticator.authenticate()` for token validation
+ * 3. Throws on auth failure (mcp-embedded-ui catches this and returns 401)
+ * 4. Wraps `next()` in `identityStorage.run()` so `getCurrentIdentity()` works
+ *
+ * @param authenticator - An Authenticator instance (e.g. JWTAuthenticator)
+ * @returns An auth hook function compatible with mcp-embedded-ui's AuthHook type
+ */
+export function buildExplorerAuthHook(authenticator) {
+    return async (req, next) => {
+        const shimReq = { headers: req.headers };
+        const identity = await authenticator.authenticate(shimReq);
+        if (!identity) {
+            throw new Error("Unauthorized");
+        }
+        return identityStorage.run(identity, next);
+    };
+}
+//# sourceMappingURL=hooks.js.map

package/dist/auth/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/auth/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAU/C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CACnC,aAA4B;IAE5B,OAAO,KAAK,EAAE,GAAoB,EAAE,IAA6B,EAAE,EAAE;QACnE,MAAM,OAAO,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAgC,CAAC;QACvE,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QAC3D,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,eAAe,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC7C,CAAC,CAAC;AACJ,CAAC"}