toolception 0.6.0 → 0.6.2

package/dist/meta/registerMetaTools.d.ts

@@ -1,6 +1,13 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Mode } from '../types/index.js';
 import { DynamicToolManager } from '../core/DynamicToolManager.js';
+import { ToolRegistry } from '../core/ToolRegistry.js';
+/**
+ * Reserved toolset key for meta-tools.
+ * Meta-tools are registered under this key to enable collision detection
+ * and tracking via the ToolRegistry.
+ */
+export declare const META_TOOLSET_KEY = "_meta";
 /**
  * Registers meta-tools on the MCP server for toolset management.
  *
@@ -11,11 +18,15 @@ import { DynamicToolManager } from '../core/DynamicToolManager.js';
  *
  * In STATIC mode, only list_tools is registered since toolsets are fixed at startup.
  *
+ * Meta-tools are registered with the ToolRegistry under the reserved "_meta" toolset key
+ * to enable collision detection with user-defined tools.
+ *
  * @param server - The MCP server to register tools on
  * @param manager - The DynamicToolManager instance
+ * @param toolRegistry - The ToolRegistry for collision detection
  * @param options - Configuration options including the mode
  */
-export declare function registerMetaTools(server: McpServer, manager: DynamicToolManager, options?: {
+export declare function registerMetaTools(server: McpServer, manager: DynamicToolManager, toolRegistry: ToolRegistry, options?: {
     mode?: Exclude<Mode, "ALL">;
 }): void;
 //# sourceMappingURL=registerMetaTools.d.ts.map

package/dist/meta/registerMetaTools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registerMetaTools.d.ts","sourceRoot":"","sources":["../../src/meta/registerMetaTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAEnE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;CAAE,GACxC,IAAI,CAoHN"}
+{"version":3,"file":"registerMetaTools.d.ts","sourceRoot":"","sources":["../../src/meta/registerMetaTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,kBAAkB,EAC3B,YAAY,EAAE,YAAY,EAC1B,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;CAAE,GACxC,IAAI,CA0HN"}

package/dist/mode/ModeResolver.d.ts

@@ -1,14 +1,12 @@
 import { Mode, ToolSetCatalog } from '../types/index.js';
-interface ModeResolverKeys {
-    dynamic?: string[];
-    toolsets?: string[];
-}
-interface ModeResolverOptions {
-    keys?: ModeResolverKeys;
-}
+import { ModeResolverKeys, ModeResolverOptions } from './mode.types.js';
 export declare class ToolsetValidator {
     private readonly keys;
     constructor(options?: ModeResolverOptions);
+    static builder(): {
+        keys(value: ModeResolverKeys): /*elided*/ any;
+        build(): ToolsetValidator;
+    };
     resolveMode(env?: Record<string, string | undefined>, args?: Record<string, unknown>): Mode | null;
     parseCommaSeparatedToolSets(input: string, catalog: ToolSetCatalog): string[];
     getModulesForToolSets(toolsets: string[], catalog: ToolSetCatalog): string[];
@@ -18,8 +16,12 @@ export declare class ToolsetValidator {
         error?: string;
     };
     /**
-     * Validates and retrieves modules for a set of toolsets.
-     * Note: A toolset with only direct tools (no modules) is valid and returns an empty modules array.
+     * @param name - The invalid name value
+     * @param catalog - The toolset catalog for listing available options
+     * @returns Validation result with descriptive error message
+     */
+    private createInvalidNameError;
+    /**
      * @param toolsetNames - Array of toolset names to validate
      * @param catalog - The toolset catalog to validate against
      * @returns Validation result with modules array if valid
@@ -32,5 +34,4 @@ export declare class ToolsetValidator {
     private isDynamicEnabled;
     private getToolsetsString;
 }
-export {};
 //# sourceMappingURL=ModeResolver.d.ts.map

package/dist/mode/ModeResolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ModeResolver.d.ts","sourceRoot":"","sources":["../../src/mode/ModeResolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE9D,UAAU,gBAAgB;IACxB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,UAAU,mBAAmB;IAC3B,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAWD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;gBAEtC,OAAO,GAAE,mBAAwB;IAOtC,WAAW,CAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACxC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,GAAG,IAAI;IAgBP,2BAA2B,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,cAAc,GACtB,MAAM,EAAE;IAqBJ,qBAAqB,CAC1B,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,EAAE,cAAc,GACtB,MAAM,EAAE;IAUJ,mBAAmB,CACxB,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,cAAc,GACtB;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IA6B3D;;;;;;OAMG;IACI,sBAAsB,CAC3B,YAAY,EAAE,MAAM,EAAE,EACtB,OAAO,EAAE,cAAc,GACtB;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAyB3D,OAAO,CAAC,gBAAgB;IAexB,OAAO,CAAC,iBAAiB;CAW1B"}
+{"version":3,"file":"ModeResolver.d.ts","sourceRoot":"","sources":["../../src/mode/ModeResolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAG7E,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;gBAEtC,OAAO,GAAE,mBAAwB;IAO7C,MAAM,CAAC,OAAO;oBAGE,gBAAgB;;;IAMzB,WAAW,CAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACxC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,GAAG,IAAI;IAgBP,2BAA2B,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,cAAc,GACtB,MAAM,EAAE;IAqBJ,qBAAqB,CAC1B,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,EAAE,cAAc,GACtB,MAAM,EAAE;IAUJ,mBAAmB,CACxB,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,cAAc,GACtB;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAmB3D;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAiB9B;;;;OAIG;IACI,sBAAsB,CAC3B,YAAY,EAAE,MAAM,EAAE,EACtB,OAAO,EAAE,cAAc,GACtB;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAyB3D,OAAO,CAAC,gBAAgB;IAexB,OAAO,CAAC,iBAAiB;CAW1B"}

package/dist/mode/ModuleResolver.d.ts

@@ -1,12 +1,14 @@
 import { ToolSetCatalog, ToolSetDefinition, McpToolDefinition, ModuleLoader } from '../types/index.js';
-export interface ModuleResolverOptions {
-    catalog: ToolSetCatalog;
-    moduleLoaders?: Record<string, ModuleLoader>;
-}
+import { ModuleResolverOptions } from './mode.types.js';
 export declare class ModuleResolver {
     private readonly catalog;
     private readonly moduleLoaders;
     constructor(options: ModuleResolverOptions);
+    static builder(): {
+        catalog(value: ToolSetCatalog): /*elided*/ any;
+        moduleLoaders(value: Record<string, ModuleLoader>): /*elided*/ any;
+        build(): ModuleResolver;
+    };
     getAvailableToolsets(): string[];
     getToolsetDefinition(name: string): ToolSetDefinition | undefined;
     validateToolsetName(name: unknown): {
@@ -15,5 +17,17 @@ export declare class ModuleResolver {
         error?: string;
     };
     resolveToolsForToolsets(toolsets: string[], context?: unknown): Promise<McpToolDefinition[]>;
+    /**
+     * @param def - The toolset definition
+     * @param collected - Mutable array to append direct tools to
+     */
+    private collectDirectTools;
+    /**
+     * @param def - The toolset definition containing module keys
+     * @param toolsetName - The toolset name for error messages
+     * @param context - Optional context passed to module loaders
+     * @param collected - Mutable array to append loaded tools to
+     */
+    private loadModuleTools;
 }
 //# sourceMappingURL=ModuleResolver.d.ts.map

package/dist/mode/ModuleResolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ModuleResolver.d.ts","sourceRoot":"","sources":["../../src/mode/ModuleResolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACb,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,cAAc,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAC9C;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+B;gBAEjD,OAAO,EAAE,qBAAqB;IAKnC,oBAAoB,IAAI,MAAM,EAAE;IAIhC,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIjE,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG;QACzC,OAAO,EAAE,OAAO,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB;IA6BY,uBAAuB,CAClC,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,iBAAiB,EAAE,CAAC;CA4BhC"}
+{"version":3,"file":"ModuleResolver.d.ts","sourceRoot":"","sources":["../../src/mode/ModuleResolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAG7D,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+B;gBAEjD,OAAO,EAAE,qBAAqB;IAa1C,MAAM,CAAC,OAAO;uBAGK,cAAc;6BACR,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;;;IAM9C,oBAAoB,IAAI,MAAM,EAAE;IAIhC,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIjE,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG;QACzC,OAAO,EAAE,OAAO,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB;IAoCY,uBAAuB,CAClC,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAW/B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;;;OAKG;YACW,eAAe;CAuB9B"}

package/dist/mode/mode.types.d.ts

@@ -0,0 +1,15 @@
+import { ToolSetCatalog, ModuleLoader } from '../types/index.js';
+export interface ModeResolverKeys {
+    dynamic?: string[];
+    toolsets?: string[];
+}
+export interface ModeResolverOptions {
+    keys?: ModeResolverKeys;
+}
+export declare const DEFAULT_KEYS: Required<ModeResolverKeys>;
+export declare const RESERVED_TOOLSET_KEYS: string[];
+export interface ModuleResolverOptions {
+    catalog: ToolSetCatalog;
+    moduleLoaders?: Record<string, ModuleLoader>;
+}
+//# sourceMappingURL=mode.types.d.ts.map

package/dist/mode/mode.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.types.d.ts","sourceRoot":"","sources":["../../src/mode/mode.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,gBAAgB,CAOnD,CAAC;AAEF,eAAO,MAAM,qBAAqB,UAAY,CAAC;AAE/C,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,cAAc,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAC9C"}

package/dist/permissions/PermissionAwareFastifyTransport.d.ts

@@ -1,29 +1,7 @@
 import { FastifyInstance } from 'fastify';
 import { DynamicToolManager } from '../core/DynamicToolManager.js';
-import { ClientRequestContext, PermissionAwareBundle } from './createPermissionAwareBundle.js';
-import { CustomEndpointDefinition } from '../http/customEndpoints.js';
-export interface PermissionAwareFastifyTransportOptions {
-    host?: string;
-    port?: number;
-    basePath?: string;
-    cors?: boolean;
-    logger?: boolean;
-    app?: FastifyInstance;
-    /**
-     * Optional custom HTTP endpoints to register alongside MCP protocol endpoints.
-     * Allows adding REST-like endpoints with Zod validation and type inference.
-     * Handlers receive permission context (allowedToolsets, failedToolsets).
-     */
-    customEndpoints?: CustomEndpointDefinition[];
-}
-/**
- * Enhanced Fastify transport that supports permission-based toolset access.
- * Integrates with PermissionResolver to enforce per-client toolset permissions.
- *
- * This transport extracts client context from requests and passes it to the
- * permission-aware bundle creator, ensuring each client receives only their
- * authorized toolsets while maintaining session management and caching.
- */
+import { ClientRequestContext, PermissionAwareBundle, PermissionAwareFastifyTransportOptions } from './permissions.types.js';
+import { CustomEndpointDefinition } from '../http/http.types.js';
 export declare class PermissionAwareFastifyTransport {
     #private;
     private readonly options;
@@ -32,23 +10,21 @@ export declare class PermissionAwareFastifyTransport {
     private app;
     private readonly configSchema?;
     private readonly clientCache;
-    /**
-     * Creates a new PermissionAwareFastifyTransport instance.
-     * @param defaultManager - Default tool manager for status endpoints
-     * @param createPermissionAwareBundle - Function to create permission-aware bundles
-     * @param options - Transport configuration options
-     * @param configSchema - Optional JSON schema for configuration discovery
-     */
     constructor(defaultManager: DynamicToolManager, createPermissionAwareBundle: (context: ClientRequestContext) => Promise<PermissionAwareBundle>, options?: PermissionAwareFastifyTransportOptions, configSchema?: object);
-    /**
-     * Starts the Fastify server and registers all MCP endpoints.
-     * Sets up routes for health checks, tool status, and MCP protocol handling.
-     */
+    static builder(): {
+        defaultManager(value: DynamicToolManager): /*elided*/ any;
+        createPermissionAwareBundle(value: (context: ClientRequestContext) => Promise<PermissionAwareBundle>): /*elided*/ any;
+        host(value: string): /*elided*/ any;
+        port(value: number): /*elided*/ any;
+        basePath(value: string): /*elided*/ any;
+        cors(value: boolean): /*elided*/ any;
+        logger(value: boolean): /*elided*/ any;
+        app(value: FastifyInstance): /*elided*/ any;
+        customEndpoints(value: CustomEndpointDefinition[]): /*elided*/ any;
+        configSchema(value: object): /*elided*/ any;
+        build(): PermissionAwareFastifyTransport;
+    };
     start(): Promise<void>;
-    /**
-     * Stops the Fastify server and cleans up all resources.
-     * Closes all client sessions and clears the cache.
-     */
     stop(): Promise<void>;
 }
 //# sourceMappingURL=PermissionAwareFastifyTransport.d.ts.map

package/dist/permissions/PermissionAwareFastifyTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PermissionAwareFastifyTransport.d.ts","sourceRoot":"","sources":["../../src/permissions/PermissionAwareFastifyTransport.ts"],"names":[],"mappings":"AAAA,OAAgB,EACd,KAAK,eAAe,EAGrB,MAAM,SAAS,CAAC;AAGjB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAMxE,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAG3E,MAAM,WAAW,sCAAsC;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,eAAe,CAAC;IACtB;;;;OAIG;IACH,eAAe,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC9C;AAED;;;;;;;GAOG;AACH,qBAAa,+BAA+B;;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAQtB;IACF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAER;IACpC,OAAO,CAAC,GAAG,CAAgC;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAS;IAGvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAWzB;IAEH;;;;;;OAMG;gBAED,cAAc,EAAE,kBAAkB,EAClC,2BAA2B,EAAE,CAC3B,OAAO,EAAE,oBAAoB,KAC1B,OAAO,CAAC,qBAAqB,CAAC,EACnC,OAAO,GAAE,sCAA2C,EACpD,YAAY,CAAC,EAAE,MAAM;IAgBvB;;;OAGG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoDnC;;;OAGG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAwUnC"}
+{"version":3,"file":"PermissionAwareFastifyTransport.d.ts","sourceRoot":"","sources":["../../src/permissions/PermissionAwareFastifyTransport.ts"],"names":[],"mappings":"AAAA,OAAgB,EACd,KAAK,eAAe,EAGrB,MAAM,SAAS,CAAC;AAIjB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAMxE,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACrB,sCAAsC,EACvC,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAQtE,qBAAa,+BAA+B;;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAQtB;IACF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAER;IACpC,OAAO,CAAC,GAAG,CAAgC;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAS;IAGvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAWzB;gBAGD,cAAc,EAAE,kBAAkB,EAClC,2BAA2B,EAAE,CAC3B,OAAO,EAAE,oBAAoB,KAC1B,OAAO,CAAC,qBAAqB,CAAC,EACnC,OAAO,GAAE,sCAA2C,EACpD,YAAY,CAAC,EAAE,MAAM;IAgBvB,MAAM,CAAC,OAAO;8BAMY,kBAAkB;2CACL,CAAC,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,qBAAqB,CAAC;oBACxF,MAAM;oBACN,MAAM;wBACF,MAAM;oBACV,OAAO;sBACL,OAAO;mBACV,eAAe;+BACH,wBAAwB,EAAE;4BAC7B,MAAM;;;IAMjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoDtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CA0TnC"}

package/dist/permissions/PermissionResolver.d.ts

@@ -1,43 +1,28 @@
 import { PermissionConfig } from '../types/index.js';
-/**
- * Resolves and caches client permissions based on configured permission sources.
- * Supports both header-based and config-based permission resolution with caching
- * for performance optimization.
- */
 export declare class PermissionResolver {
     #private;
     private config;
     private cache;
     private readonly normalizedHeaderName;
-    /**
-     * Creates a new PermissionResolver instance.
-     * @param config - The permission configuration defining how permissions are resolved
-     */
     constructor(config: PermissionConfig);
+    static builder(): {
+        source(value: "headers" | "config"): /*elided*/ any;
+        headerName(value: string): /*elided*/ any;
+        staticMap(value: Record<string, string[]>): /*elided*/ any;
+        resolver(value: (clientId: string) => string[]): /*elided*/ any;
+        defaultPermissions(value: string[]): /*elided*/ any;
+        build(): PermissionResolver;
+    };
     /**
-     * Resolves permissions for a client based on the configured source.
-     * Results are cached to improve performance for subsequent requests from the same client.
-     * Handles all errors gracefully by returning empty permissions on failure.
-     *
-     * Note on caching: For header-based permissions, permissions are cached by clientId.
-     * This means subsequent requests from the same client will use cached permissions,
-     * even if headers change. Use invalidateCache(clientId) to force re-resolution.
-     *
      * @param clientId - The unique identifier for the client
-     * @param headers - Optional request headers (required for header-based permissions)
+     * @param headers - Optional request headers
      * @returns Array of toolset names the client is allowed to access
      */
     resolvePermissions(clientId: string, headers?: Record<string, string>): string[];
     /**
-     * Invalidates cached permissions for a specific client.
-     * Call this when you know a client's permissions have changed.
      * @param clientId - The client ID to invalidate
      */
     invalidateCache(clientId: string): void;
-    /**
-     * Clears the permission cache.
-     * Useful for cleanup during server shutdown or when permissions need to be refreshed.
-     */
     clearCache(): void;
 }
 //# sourceMappingURL=PermissionResolver.d.ts.map

package/dist/permissions/PermissionResolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PermissionResolver.d.ts","sourceRoot":"","sources":["../../src/permissions/PermissionResolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;GAIG;AACH,qBAAa,kBAAkB;;IAQjB,OAAO,CAAC,MAAM;IAP1B,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAE9C;;;OAGG;gBACiB,MAAM,EAAE,gBAAgB;IAO5C;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,MAAM,EAAE;IAyCX;;;;OAIG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IA6IvC;;;OAGG;IACH,UAAU,IAAI,IAAI;CAGnB"}
+{"version":3,"file":"PermissionResolver.d.ts","sourceRoot":"","sources":["../../src/permissions/PermissionResolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,qBAAa,kBAAkB;;IAIjB,OAAO,CAAC,MAAM;IAH1B,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;gBAE1B,MAAM,EAAE,gBAAgB;IAO5C,MAAM,CAAC,OAAO;sBAGI,SAAS,GAAG,QAAQ;0BAChB,MAAM;yBACP,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;wBACzB,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,EAAE;kCACpB,MAAM,EAAE;;;IAMtC;;;;OAIG;IACH,kBAAkB,CAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,MAAM,EAAE;IAyCX;;OAEG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IA2HvC,UAAU,IAAI,IAAI;CAGnB"}

package/dist/permissions/{createPermissionAwareBundle.d.ts → permissions.types.d.ts}

@@ -1,6 +1,20 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ServerOrchestrator } from '../core/ServerOrchestrator.js';
-import { PermissionResolver } from './PermissionResolver.js';
+import { CustomEndpointDefinition } from '../http/http.types.js';
+export interface PermissionAwareFastifyTransportOptions {
+    host?: string;
+    port?: number;
+    basePath?: string;
+    cors?: boolean;
+    logger?: boolean;
+    app?: import('fastify').FastifyInstance;
+    /**
+     * Optional custom HTTP endpoints to register alongside MCP protocol endpoints.
+     * Allows adding REST-like endpoints with Zod validation and type inference.
+     * Handlers receive permission context (allowedToolsets, failedToolsets).
+     */
+    customEndpoints?: CustomEndpointDefinition[];
+}
 /**
  * Context information extracted from a client request.
  * Used to identify the client and resolve their permissions.
@@ -8,7 +22,7 @@ import { PermissionResolver } from './PermissionResolver.js';
 export interface ClientRequestContext {
     /**
      * Unique identifier for the client making the request.
-     * May be provided via mcp-client-id header or generated as anonymous ID.
+     * Must be provided via the mcp-client-id header for MCP protocol traffic.
      */
     clientId: string;
     /**
@@ -40,19 +54,4 @@ export interface PermissionAwareBundle {
      */
     failedToolsets: string[];
 }
-/**
- * Creates a permission-aware bundle creation function that wraps the original
- * createBundle function with permission resolution and enforcement.
- *
- * This function resolves client permissions and passes them to the bundle creator,
- * which creates a server with STATIC mode configured to only those toolsets.
- *
- * @param originalCreateBundle - Bundle creation function that accepts allowed toolsets
- * @param permissionResolver - Resolver instance for determining client permissions
- * @returns Enhanced bundle creation function that accepts client context
- */
-export declare function createPermissionAwareBundle(originalCreateBundle: (allowedToolsets: string[]) => {
-    server: McpServer;
-    orchestrator: ServerOrchestrator;
-}, permissionResolver: PermissionResolver): (context: ClientRequestContext) => Promise<PermissionAwareBundle>;
-//# sourceMappingURL=createPermissionAwareBundle.d.ts.map
+//# sourceMappingURL=permissions.types.d.ts.map

package/dist/permissions/permissions.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.types.d.ts","sourceRoot":"","sources":["../../src/permissions/permissions.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAEtE,MAAM,WAAW,sCAAsC;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,SAAS,EAAE,eAAe,CAAC;IACxC;;;;OAIG;IACH,eAAe,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,MAAM,EAAE,SAAS,CAAC;IAElB;;OAEG;IACH,YAAY,EAAE,kBAAkB,CAAC;IAEjC;;;OAGG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;IAE1B;;;OAGG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B"}

package/dist/permissions/permissions.utils.d.ts

@@ -0,0 +1,31 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ExposurePolicy, PermissionConfig } from '../types/index.js';
+import { ServerOrchestrator } from '../core/ServerOrchestrator.js';
+import { PermissionResolver } from './PermissionResolver.js';
+import { ClientRequestContext, PermissionAwareBundle } from './permissions.types.js';
+/**
+ * Validates a permission configuration object to ensure it meets all requirements.
+ * Throws descriptive errors for any validation failures.
+ * @param config - The permission configuration to validate
+ */
+export declare function validatePermissionConfig(config: PermissionConfig): void;
+/**
+ * Creates a permission-aware bundle creation function that wraps the original
+ * createBundle function with permission resolution and enforcement.
+ *
+ * @param originalCreateBundle - Bundle creation function that accepts allowed toolsets
+ * @param permissionResolver - Resolver instance for determining client permissions
+ * @returns Enhanced bundle creation function that accepts client context
+ */
+export declare function createPermissionAwareBundle(originalCreateBundle: (allowedToolsets: string[]) => {
+    server: McpServer;
+    orchestrator: ServerOrchestrator;
+}, permissionResolver: PermissionResolver): (context: ClientRequestContext) => Promise<PermissionAwareBundle>;
+/**
+ * Validates and sanitizes exposure policy for permission-based servers.
+ * Certain policy options are not applicable or could conflict with permission-based access control.
+ * @param policy - The original exposure policy
+ * @returns Sanitized policy safe for permission-based servers
+ */
+export declare function sanitizeExposurePolicyForPermissions(policy?: ExposurePolicy): ExposurePolicy | undefined;
+//# sourceMappingURL=permissions.utils.d.ts.map

package/dist/permissions/permissions.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.utils.d.ts","sourceRoot":"","sources":["../../src/permissions/permissions.utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,wBAAwB,CAAC;AAIhC;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAKvE;AA4FD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,oBAAoB,EAAE,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK;IACnD,MAAM,EAAE,SAAS,CAAC;IAClB,YAAY,EAAE,kBAAkB,CAAC;CAClC,EACD,kBAAkB,EAAE,kBAAkB,IAGpC,SAAS,oBAAoB,KAC5B,OAAO,CAAC,qBAAqB,CAAC,CAkDlC;AAID;;;;;GAKG;AACH,wBAAgB,oCAAoC,CAClD,MAAM,CAAC,EAAE,cAAc,GACtB,cAAc,GAAG,SAAS,CAkC5B"}

package/dist/server/createMcpServer.d.ts

@@ -1,47 +1,4 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { ExposurePolicy, Mode, ModuleLoader, SessionContextConfig, ToolSetCatalog } from '../types/index.js';
-import { FastifyTransportOptions } from '../http/FastifyTransport.js';
-export interface CreateMcpServerOptions {
-    catalog: ToolSetCatalog;
-    moduleLoaders?: Record<string, ModuleLoader>;
-    exposurePolicy?: ExposurePolicy;
-    context?: unknown;
-    startup?: {
-        mode?: Exclude<Mode, "ALL">;
-        toolsets?: string[] | "ALL";
-    };
-    registerMetaTools?: boolean;
-    http?: FastifyTransportOptions;
-    /**
-     * Factory to create an MCP server instance. Required.
-     * In DYNAMIC mode, a new instance is created per client bundle.
-     * In STATIC mode, a single instance is created and reused across bundles.
-     */
-    createServer: () => McpServer;
-    configSchema?: object;
-    /**
-     * Optional per-session context configuration.
-     * Enables extracting context from query parameters and merging with base context
-     * on a per-request basis. Useful for multi-tenant scenarios.
-     *
-     * @example
-     * ```typescript
-     * sessionContext: {
-     *   enabled: true,
-     *   queryParam: {
-     *     name: 'config',
-     *     encoding: 'base64',
-     *     allowedKeys: ['API_TOKEN', 'USER_ID'],
-     *   },
-     *   merge: 'shallow',
-     * }
-     * ```
-     */
-    sessionContext?: SessionContextConfig;
-}
-export declare function createMcpServer(options: CreateMcpServerOptions): Promise<{
-    server: McpServer;
-    start: () => Promise<void>;
-    close: () => Promise<void>;
-}>;
+import { CreateMcpServerOptions, McpServerHandle } from './server.types.js';
+export type { CreateMcpServerOptions } from './server.types.js';
+export declare function createMcpServer(options: CreateMcpServerOptions): Promise<McpServerHandle>;
 //# sourceMappingURL=createMcpServer.d.ts.map

package/dist/server/createMcpServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createMcpServer.d.ts","sourceRoot":"","sources":["../../src/server/createMcpServer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EACV,cAAc,EACd,IAAI,EACJ,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,6BAA6B,CAAC;AAKrC,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,cAAc,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC7C,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,KAAK,CAAA;KAAE,CAAC;IACvE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,IAAI,CAAC,EAAE,uBAAuB,CAAC;IAC/B;;;;OAIG;IACH,YAAY,EAAE,MAAM,SAAS,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;;;;OAiBG;IACH,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACvC;AAaD,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB;;;;GA2IpE"}
+{"version":3,"file":"createMcpServer.d.ts","sourceRoot":"","sources":["../../src/server/createMcpServer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAWjF,YAAY,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAEhE,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,CAgC1B"}

package/dist/server/createPermissionBasedMcpServer.d.ts

@@ -1,65 +1,3 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { CreatePermissionBasedMcpServerOptions } from '../types/index.js';
-/**
- * Creates an MCP server with permission-based toolset access control.
- *
- * This function provides a separate API for creating servers where each client receives
- * only the toolsets they're authorized to access. Each client gets a fresh server instance
- * with STATIC mode configured to their allowed toolsets, ensuring per-client isolation
- * without meta-tools or dynamic loading.
- *
- * The server supports two permission sources:
- * - **Header-based**: Permissions are read from request headers (e.g., `mcp-toolset-permissions`)
- * - **Config-based**: Permissions are resolved server-side using static maps or resolver functions
- *
- * @param options - Configuration options including permission settings, catalog, and HTTP transport options
- * @returns Server instance with `server`, `start()`, and `close()` methods matching the createMcpServer interface
- * @throws {Error} If permission configuration is invalid, missing, or if startup.mode is provided
- *
- * @example
- * // Header-based permissions
- * const server = await createPermissionBasedMcpServer({
- *   createServer: () => new McpServer({ name: "my-server", version: "1.0.0" }),
- *   catalog: { toolsetA: { name: "Toolset A", tools: [...] } },
- *   permissions: {
- *     source: 'headers',
- *     headerName: 'mcp-toolset-permissions' // optional, this is the default
- *   }
- * });
- *
- * @example
- * // Config-based permissions with static map
- * const server = await createPermissionBasedMcpServer({
- *   createServer: () => new McpServer({ name: "my-server", version: "1.0.0" }),
- *   catalog: { toolsetA: { name: "Toolset A", tools: [...] } },
- *   permissions: {
- *     source: 'config',
- *     staticMap: {
- *       'client-1': ['toolsetA', 'toolsetB'],
- *       'client-2': ['toolsetC']
- *     },
- *     defaultPermissions: [] // optional, defaults to empty array
- *   }
- * });
- *
- * @example
- * // Config-based permissions with resolver function
- * const server = await createPermissionBasedMcpServer({
- *   createServer: () => new McpServer({ name: "my-server", version: "1.0.0" }),
- *   catalog: { toolsetA: { name: "Toolset A", tools: [...] } },
- *   permissions: {
- *     source: 'config',
- *     resolver: (clientId) => {
- *       // Your custom logic to determine permissions
- *       return clientId.startsWith('admin-') ? ['toolsetA', 'toolsetB'] : ['toolsetA'];
- *     },
- *     defaultPermissions: ['toolsetA'] // fallback if resolver fails
- *   }
- * });
- */
-export declare function createPermissionBasedMcpServer(options: CreatePermissionBasedMcpServerOptions): Promise<{
-    server: McpServer;
-    start: () => Promise<void>;
-    close: () => Promise<void>;
-}>;
+import { CreatePermissionBasedMcpServerOptions, McpServerHandle } from './server.types.js';
+export declare function createPermissionBasedMcpServer(options: CreatePermissionBasedMcpServerOptions): Promise<McpServerHandle>;
 //# sourceMappingURL=createPermissionBasedMcpServer.d.ts.map

package/dist/server/createPermissionBasedMcpServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createPermissionBasedMcpServer.d.ts","sourceRoot":"","sources":["../../src/server/createPermissionBasedMcpServer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EACV,qCAAqC,EAEtC,MAAM,mBAAmB,CAAC;AAqD3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAsB,8BAA8B,CAClD,OAAO,EAAE,qCAAqC;;;;GA6G/C"}
+{"version":3,"file":"createPermissionBasedMcpServer.d.ts","sourceRoot":"","sources":["../../src/server/createPermissionBasedMcpServer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,qCAAqC,EACrC,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAW3B,wBAAsB,8BAA8B,CAClD,OAAO,EAAE,qCAAqC,GAC7C,OAAO,CAAC,eAAe,CAAC,CA+B1B"}

package/dist/server/server.types.d.ts

@@ -0,0 +1,71 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ExposurePolicy, Mode, ModuleLoader, PermissionConfig, SessionContextConfig, ToolSetCatalog } from '../types/index.js';
+import { FastifyTransportOptions } from '../http/http.types.js';
+/** Handle returned by both `createMcpServer` and `createPermissionBasedMcpServer`. */
+export interface McpServerHandle {
+    server: McpServer;
+    start: () => Promise<void>;
+    close: () => Promise<void>;
+}
+export interface CreateMcpServerOptions {
+    catalog: ToolSetCatalog;
+    moduleLoaders?: Record<string, ModuleLoader>;
+    exposurePolicy?: ExposurePolicy;
+    context?: unknown;
+    startup?: {
+        mode?: Exclude<Mode, "ALL">;
+        toolsets?: string[] | "ALL";
+    };
+    registerMetaTools?: boolean;
+    http?: FastifyTransportOptions;
+    /**
+     * Factory to create an MCP server instance. Required.
+     * In DYNAMIC mode, a new instance is created per client bundle.
+     * In STATIC mode, a single instance is created and reused across bundles.
+     */
+    createServer: () => McpServer;
+    configSchema?: object;
+    /**
+     * Optional per-session context configuration.
+     * Enables extracting context from query parameters and merging with base context
+     * on a per-request basis. Useful for multi-tenant scenarios.
+     *
+     * @example
+     * ```typescript
+     * sessionContext: {
+     *   enabled: true,
+     *   queryParam: {
+     *     name: 'config',
+     *     encoding: 'base64',
+     *     allowedKeys: ['API_TOKEN', 'USER_ID'],
+     *   },
+     *   merge: 'shallow',
+     * }
+     * ```
+     */
+    sessionContext?: SessionContextConfig;
+}
+export type CreatePermissionBasedMcpServerOptions = Omit<CreateMcpServerOptions, "startup"> & {
+    /**
+     * Permission configuration defining how client access control is enforced.
+     *
+     * This field is required for permission-based servers. It determines whether
+     * permissions are read from request headers or resolved server-side using
+     * static maps or resolver functions.
+     *
+     * @see {@link PermissionConfig} for detailed configuration options and examples
+     */
+    permissions: PermissionConfig;
+    /**
+     * Startup configuration is not allowed for permission-based servers.
+     *
+     * Permission-based servers automatically determine which toolsets to load for
+     * each client based on the `permissions` configuration. The server internally
+     * uses STATIC mode per client to ensure isolation and prevent dynamic toolset
+     * changes during a session.
+     *
+     * @deprecated Do not use - permission-based servers determine toolsets from client permissions
+     */
+    startup?: never;
+};
+//# sourceMappingURL=server.types.d.ts.map

package/dist/server/server.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.types.d.ts","sourceRoot":"","sources":["../../src/server/server.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EACV,cAAc,EACd,IAAI,EACJ,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAErE,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,cAAc,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC7C,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,KAAK,CAAA;KAAE,CAAC;IACvE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,IAAI,CAAC,EAAE,uBAAuB,CAAC;IAC/B;;;;OAIG;IACH,YAAY,EAAE,MAAM,SAAS,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;;;;OAiBG;IACH,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACvC;AAED,MAAM,MAAM,qCAAqC,GAAG,IAAI,CACtD,sBAAsB,EACtB,SAAS,CACV,GAAG;IACF;;;;;;;;OAQG;IACH,WAAW,EAAE,gBAAgB,CAAC;IAE9B;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC;CACjB,CAAC"}

package/dist/server/server.utils.d.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { Mode } from '../types/index.js';
+/**
+ * Zod schema for validating startup configuration.
+ * Uses strict mode to reject unknown properties like 'initialToolsets'.
+ */
+export declare const startupConfigSchema: z.ZodObject<{
+    mode: z.ZodOptional<z.ZodEnum<["DYNAMIC", "STATIC"]>>;
+    toolsets: z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodLiteral<"ALL">]>>;
+}, "strict", z.ZodTypeAny, {
+    toolsets?: string[] | "ALL" | undefined;
+    mode?: "DYNAMIC" | "STATIC" | undefined;
+}, {
+    toolsets?: string[] | "ALL" | undefined;
+    mode?: "DYNAMIC" | "STATIC" | undefined;
+}>;
+/**
+ * Validates a startup configuration object against `startupConfigSchema`.
+ * Throws a descriptive error when the config is invalid.
+ *
+ * @param startup - The startup configuration to validate
+ */
+export declare function validateStartupConfig(startup: {
+    mode?: Exclude<Mode, "ALL">;
+    toolsets?: string[] | "ALL";
+}): void;
+/**
+ * Creates a notifier function that sends `tools/list_changed` notifications
+ * to an MCP server. Handles two different notification APIs and suppresses
+ * "Not connected" errors that occur when no clients are connected.
+ *
+ * @returns A function that sends tools/list_changed notifications to an MCP server
+ */
+export declare function createToolsChangedNotifier(): (target: unknown) => Promise<void>;
+/**
+ * Resolves whether meta-tools should be registered.
+ * When `explicit` is provided it takes precedence; otherwise meta-tools are
+ * enabled in DYNAMIC mode and disabled in STATIC mode.
+ *
+ * @param explicit - The user-provided registerMetaTools value (undefined = auto)
+ * @param mode - The resolved server mode
+ * @returns Whether meta-tools should be registered
+ */
+export declare function resolveMetaToolsFlag(explicit: boolean | undefined, mode: Exclude<Mode, "ALL">): boolean;
+//# sourceMappingURL=server.utils.d.ts.map