toolception 0.3.0 → 0.5.0

package/README.md

@@ -10,6 +10,7 @@
 - [Static startup](#static-startup)
 - [Permission-based starter guide](#permission-based-starter-guide)
 - [Permission configuration approaches](#permission-configuration-approaches)
+- [Custom HTTP endpoints](#custom-http-endpoints)
 - [API](#api)
   - [createMcpServer](#createmcpserveroptions)
   - [createPermissionBasedMcpServer](#createpermissionbasedmcpserveroptions)
@@ -171,7 +172,7 @@ process.on("SIGTERM", async () => {
 
 ## Static startup
 
-Enable some or ALL toolsets at bootstrap. Note: provide a server or factory:
+Enable some or ALL toolsets at bootstrap. In STATIC mode, a single server instance is created and reused for all clients:
 
 ```ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -181,26 +182,30 @@ const staticCatalog = {
   quotes: { name: "Quotes", description: "Market quotes", modules: ["quotes"] },
 };
 
+// Load specific toolsets
 createMcpServer({
   catalog: staticCatalog,
   startup: { mode: "STATIC", toolsets: ["search", "quotes"] },
   http: { port: 3001 },
-  server: new McpServer({
-    name: "static-1",
-    version: "0.0.0",
-    capabilities: { tools: { listChanged: false } },
-  }),
+  createServer: () =>
+    new McpServer({
+      name: "static-1",
+      version: "0.0.0",
+      capabilities: { tools: { listChanged: false } },
+    }),
 });
 
+// Load ALL toolsets
 createMcpServer({
   catalog: staticCatalog,
   startup: { mode: "STATIC", toolsets: "ALL" },
   http: { port: 3002 },
-  server: new McpServer({
-    name: "static-2",
-    version: "0.0.0",
-    capabilities: { tools: { listChanged: false } },
-  }),
+  createServer: () =>
+    new McpServer({
+      name: "static-2",
+      version: "0.0.0",
+      capabilities: { tools: { listChanged: false } },
+    }),
 });
 ```
 
@@ -585,6 +590,135 @@ await start();
 
 **Note:** Resolver functions must be synchronous. If you need to fetch permissions from external sources, do so before server creation and cache the results.
 
+## Custom HTTP endpoints
+
+Toolception supports custom HTTP endpoints alongside MCP protocol endpoints, enabling REST-like APIs with Zod validation and type inference.
+
+### Basic usage
+
+```ts
+import { createMcpServer, defineEndpoint } from "toolception";
+import { z } from "zod";
+
+const { start } = await createMcpServer({
+  // ... standard options
+  http: {
+    port: 3000,
+    customEndpoints: [
+      defineEndpoint({
+        method: "GET",
+        path: "/api/users",
+        querySchema: z.object({
+          limit: z.coerce.number().int().positive().default(10),
+          role: z.enum(["admin", "user"]).optional(),
+        }),
+        responseSchema: z.object({
+          users: z.array(z.object({ id: z.string(), name: z.string() })),
+        }),
+        handler: async (req) => {
+          // req.query is typed: { limit: number, role?: "admin" | "user" }
+          // req.clientId is available from mcp-client-id header
+          return { users: [{ id: "1", name: "Alice" }] };
+        },
+      }),
+    ],
+  },
+});
+```
+
+### Validation schemas
+
+- **querySchema**: Validates URL query parameters (use `z.coerce` for type conversion)
+- **bodySchema**: Validates request body (POST/PUT/PATCH)
+- **paramsSchema**: Validates path parameters (e.g., `/users/:userId`)
+- **responseSchema**: Validates handler response (prevents invalid data leakage)
+
+### Request context
+
+Handlers receive a typed request object:
+
+```ts
+{
+  body: TBody,        // Validated from bodySchema
+  query: TQuery,      // Validated from querySchema
+  params: TParams,    // Validated from paramsSchema
+  headers: Record<string, string | string[] | undefined>,
+  clientId: string,   // From mcp-client-id header or auto-generated
+}
+```
+
+### Permission-aware endpoints
+
+Use `definePermissionAwareEndpoint` in permission-based servers to access client permissions:
+
+```ts
+import { createPermissionBasedMcpServer, definePermissionAwareEndpoint } from "toolception";
+
+const { start } = await createPermissionBasedMcpServer({
+  // ... permission config
+  http: {
+    customEndpoints: [
+      definePermissionAwareEndpoint({
+        method: "GET",
+        path: "/api/me",
+        responseSchema: z.object({
+          clientId: z.string(),
+          allowedToolsets: z.array(z.string()),
+          isAdmin: z.boolean(),
+        }),
+        handler: async (req) => {
+          // req.allowedToolsets and req.failedToolsets are available
+          return {
+            clientId: req.clientId,
+            allowedToolsets: req.allowedToolsets,
+            isAdmin: req.allowedToolsets.includes("admin-tools"),
+          };
+        },
+      }),
+    ],
+  },
+});
+```
+
+### Error handling
+
+Validation failures return standardized error responses:
+
+- **400 VALIDATION_ERROR**: Request validation failed (body, query, or params)
+- **500 INTERNAL_ERROR**: Handler threw an exception
+- **500 RESPONSE_VALIDATION_ERROR**: Response validation failed
+
+Example error response:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Validation failed for query",
+    "details": [
+      {
+        "code": "invalid_type",
+        "path": ["limit"],
+        "message": "Expected number, received string"
+      }
+    ]
+  }
+}
+```
+
+### Reserved paths
+
+Custom endpoints cannot override built-in MCP paths:
+
+- `/mcp` - MCP JSON-RPC endpoint
+- `/healthz` - Health check
+- `/tools` - Tool listing
+- `/.well-known/mcp-config` - Configuration schema
+
+### Complete example
+
+See `examples/custom-endpoints-demo.ts` for a full working example with GET, POST, PUT, DELETE endpoints, pagination, and permission-aware handlers.
+
 ## API
 
 ### createMcpServer(options)
@@ -664,9 +798,11 @@ Startup precedence and validation
 
 #### options.registerMetaTools (optional)
 
-`boolean` (default: true in DYNAMIC mode; false in STATIC unless explicitly set)
+`boolean` (default: true in DYNAMIC mode; false in STATIC mode)
 
-- Whether to register management tools like `enable_toolset`, `disable_toolset`, `list_tools`.
+- Whether to register meta-tools for toolset management.
+- In DYNAMIC mode: Registers all meta-tools (`enable_toolset`, `disable_toolset`, `list_toolsets`, `describe_toolset`, `list_tools`).
+- In STATIC mode: Only registers `list_tools` (other meta-tools are not applicable since toolsets are fixed at startup).
 
 #### options.exposurePolicy (optional)
 
@@ -730,9 +866,10 @@ const moduleLoaders = {
 
 #### options.http (optional)
 
-`{ host?: string; port?: number; basePath?: string; cors?: boolean; logger?: boolean }`
+`{ host?: string; port?: number; basePath?: string; cors?: boolean; logger?: boolean; customEndpoints?: CustomEndpointDefinition[] }`
 
 - Fastify transport configuration. Defaults: host `0.0.0.0`, port `3000`, basePath `/`, CORS enabled, logger disabled.
+- `customEndpoints`: Optional array of custom HTTP endpoints to register alongside MCP protocol endpoints. See [Custom HTTP endpoints](#custom-http-endpoints) for details.
 
 #### options.createServer (optional)
 
@@ -805,13 +942,17 @@ Same as `createMcpServer` - see [options.moduleLoaders](#optionsmoduleloaders-op
 
 `ExposurePolicy` (partial support)
 
-Permission-based servers override certain policy fields:
+Permission-based servers only support `namespaceToolsWithSetKey`. Other policy fields are ignored because toolset access is controlled by permissions:
 
-- `allowlist`: Set automatically based on resolved permissions (cannot be manually configured)
-- `maxActiveToolsets`: Set automatically to match permission count
-- `namespaceToolsWithSetKey`: Supported (default: true)
-- `denylist`: Not supported (use permissions instead)
-- `onLimitExceeded`: Not applicable
+| Field                      | Support                                           |
+| -------------------------- | ------------------------------------------------- |
+| `namespaceToolsWithSetKey` | ✅ Supported (default: true)                       |
+| `allowlist`                | ⚠️ Ignored (determined by client permissions)     |
+| `denylist`                 | ⚠️ Ignored (use permissions instead)              |
+| `maxActiveToolsets`        | ⚠️ Ignored (determined by permission count)       |
+| `onLimitExceeded`          | ⚠️ Ignored (no toolset limits enforced)           |
+
+**Note:** If you provide ignored options, the server will log warnings at startup to alert you.
 
 #### options.http (optional)
 
@@ -831,11 +972,21 @@ Same as `createMcpServer` - see [options.context](#optionscontext-optional).
 
 ### Meta-tools
 
-Enabled by default when mode is DYNAMIC (or when `registerMetaTools` is true):
+Meta-tools are registered based on mode:
+
+**DYNAMIC mode** (registered by default, or when `registerMetaTools` is true):
+
+- `enable_toolset` - Enable a toolset by name
+- `disable_toolset` - Disable a toolset by name (state only; tools remain registered)
+- `list_toolsets` - List available toolsets with active status
+- `describe_toolset` - Describe a specific toolset with definition and tools
+- `list_tools` - List currently registered tool names
+
+**STATIC mode** (when `registerMetaTools` is true):
+
+- `list_tools` - List currently registered tool names
 
-- `enable_toolset`, `disable_toolset`, `list_tools`
-  Only in DYNAMIC mode:
-- `list_toolsets`, `describe_toolset`
+Note: In STATIC mode, `enable_toolset`, `disable_toolset`, `list_toolsets`, and `describe_toolset` are not available since toolsets are fixed at startup.
 
 ## Permission-based client integration
 
@@ -1344,17 +1495,19 @@ Note on dynamic mode: Both direct and module-produced tools are supported. Modul
 
 ## Startup modes
 
-The server operates in one of two primary modes (legacy load-all is not recommended here):
+The server operates in one of two primary modes:
 
-1. Dynamic mode (startup.mode = "DYNAMIC")
+1. **Dynamic mode** (`startup.mode = "DYNAMIC"`)
 
-   - Starts with meta-tools for runtime management: `enable_toolset`, `disable_toolset`, `list_toolsets`, `describe_toolset`, and `list_tools` (always available)
+   - All meta-tools registered: `enable_toolset`, `disable_toolset`, `list_toolsets`, `describe_toolset`, `list_tools`
    - Tools are loaded on-demand via meta-tool calls
+   - Each client gets an isolated server instance
    - Best for flexible, task-specific workflows where tool needs change
 
-2. Static mode (startup.mode = "STATIC")
+2. **Static mode** (`startup.mode = "STATIC"`)
    - Pre-loads specific toolsets at startup (`toolsets` array or "ALL")
-   - Meta-tools limited to `list_tools` by default
+   - Only `list_tools` meta-tool is available (toolsets cannot be changed at runtime)
+   - A single server instance is reused for all clients
    - Best for known, consistent tool requirements
 
 ## License

package/dist/core/DynamicToolManager.d.ts

@@ -19,14 +19,48 @@ export declare class DynamicToolManager {
     private readonly toolRegistry;
     private readonly activeToolsets;
     constructor(options: DynamicToolManagerOptions);
+    /**
+     * Sends a tool list change notification if configured.
+     * Logs warnings on failure instead of throwing.
+     * @returns Promise that resolves when notification is sent (or skipped)
+     * @private
+     */
+    private notifyToolsChanged;
     getAvailableToolsets(): string[];
     getActiveToolsets(): string[];
     getToolsetDefinition(name: string): ToolSetDefinition | undefined;
     isActive(name: string): boolean;
-    enableToolset(toolsetName: string): Promise<{
+    /**
+     * Enables a single toolset by name.
+     * Validates the toolset, checks exposure policies, resolves tools, and registers them.
+     * @param toolsetName - The name of the toolset to enable
+     * @param skipNotification - If true, skips the tool list change notification (for batch operations)
+     * @returns Result object with success status and message
+     */
+    enableToolset(toolsetName: string, skipNotification?: boolean): Promise<{
         success: boolean;
         message: string;
     }>;
+    /**
+     * Checks if a toolset is allowed by the exposure policy.
+     * @param toolsetName - The sanitized toolset name to check
+     * @returns Object indicating if allowed and reason message if not
+     * @private
+     */
+    private checkExposurePolicy;
+    /**
+     * Registers a single tool with the MCP server.
+     * @param tool - The tool definition to register
+     * @param toolsetKey - The toolset key for tracking
+     * @private
+     */
+    private registerSingleTool;
+    /**
+     * Disables a toolset by name.
+     * Note: Due to MCP limitations, tools remain registered but the toolset is marked inactive.
+     * @param toolsetName - The name of the toolset to disable
+     * @returns Result object with success status and message
+     */
     disableToolset(toolsetName: string): Promise<{
         success: boolean;
         message: string;
@@ -40,6 +74,12 @@ export declare class DynamicToolManager {
         tools: string[];
         toolsetToTools: Record<string, string[]>;
     };
+    /**
+     * Enables multiple toolsets in a batch operation.
+     * Sends a single notification after all toolsets are processed.
+     * @param toolsetNames - Array of toolset names to enable
+     * @returns Result object with overall success status and individual results
+     */
     enableToolsets(toolsetNames: string[]): Promise<{
         success: boolean;
         results: Array<{
@@ -50,7 +90,10 @@ export declare class DynamicToolManager {
         }>;
         message: string;
     }>;
-    private registerDirectTools;
+    /**
+     * Enables all available toolsets in a batch operation.
+     * @returns Result object with overall success status and individual results
+     */
     enableAllToolsets(): Promise<{
         success: boolean;
         results: Array<{

package/dist/core/DynamicToolManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DynamicToolManager.d.ts","sourceRoot":"","sources":["../../src/core/DynamicToolManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EACV,cAAc,EAEd,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAChD,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAA6B;IACjE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAE5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;gBAExC,OAAO,EAAE,yBAAyB;IAUvC,oBAAoB,IAAI,MAAM,EAAE;IAIhC,iBAAiB,IAAI,MAAM,EAAE;IAI7B,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIjE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIzB,aAAa,CACxB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IA2FpC,cAAc,CACzB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAoC1C,SAAS;;;;;;;;;IAYH,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAC3D,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,KAAK,CAAC;YACb,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,EAAE,OAAO,CAAC;YACjB,OAAO,EAAE,MAAM,CAAC;YAChB,IAAI,CAAC,EAAE,gBAAgB,CAAC;SACzB,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IAgCF,OAAO,CAAC,mBAAmB;IAuBd,iBAAiB,IAAI,OAAO,CAAC;QACxC,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,KAAK,CAAC;YACb,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,EAAE,OAAO,CAAC;YACjB,OAAO,EAAE,MAAM,CAAC;YAChB,IAAI,CAAC,EAAE,gBAAgB,CAAC;SACzB,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CAIH"}
+{"version":3,"file":"DynamicToolManager.d.ts","sourceRoot":"","sources":["../../src/core/DynamicToolManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EACV,cAAc,EAEd,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAChD,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAA6B;IACjE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAE5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;gBAExC,OAAO,EAAE,yBAAyB;IAU9C;;;;;OAKG;YACW,kBAAkB;IASzB,oBAAoB,IAAI,MAAM,EAAE;IAIhC,iBAAiB,IAAI,MAAM,EAAE;IAI7B,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIjE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAItC;;;;;;OAMG;IACU,aAAa,CACxB,WAAW,EAAE,MAAM,EACnB,gBAAgB,UAAQ,GACvB,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IA4EjD;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAsC3B;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAY1B;;;;;OAKG;IACU,cAAc,CACzB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAgC1C,SAAS;;;;;;;;;IAYhB;;;;;OAKG;IACU,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAC3D,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,KAAK,CAAC;YACb,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,EAAE,OAAO,CAAC;YACjB,OAAO,EAAE,MAAM,CAAC;YAChB,IAAI,CAAC,EAAE,gBAAgB,CAAC;SACzB,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IAuCF;;;OAGG;IACU,iBAAiB,IAAI,OAAO,CAAC;QACxC,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,KAAK,CAAC;YACb,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,EAAE,OAAO,CAAC;YACjB,OAAO,EAAE,MAAM,CAAC;YAChB,IAAI,CAAC,EAAE,gBAAgB,CAAC;SACzB,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CAIH"}

package/dist/core/ServerOrchestrator.d.ts

@@ -1,10 +1,10 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { DynamicToolManager } from './DynamicToolManager.js';
-import { ExposurePolicy, Mode, ToolSetCatalog } from '../types/index.js';
+import { ExposurePolicy, Mode, ModuleLoader, ToolSetCatalog } from '../types/index.js';
 export interface ServerOrchestratorOptions {
     server: McpServer;
     catalog: ToolSetCatalog;
-    moduleLoaders?: Record<string, any>;
+    moduleLoaders?: Record<string, ModuleLoader>;
     exposurePolicy?: ExposurePolicy;
     context?: unknown;
     notifyToolsListChanged?: () => Promise<void> | void;
@@ -19,7 +19,29 @@ export declare class ServerOrchestrator {
     private readonly resolver;
     private readonly manager;
     private readonly toolsetValidator;
+    private readonly initPromise;
+    private initError;
     constructor(options: ServerOrchestratorOptions);
+    /**
+     * Initializes toolsets asynchronously during construction.
+     * Stores any errors for later retrieval via ensureReady().
+     * @param initial - The toolsets to initialize or "ALL"
+     * @returns Promise that resolves when initialization is complete
+     * @private
+     */
+    private initializeToolsets;
+    /**
+     * Waits for the orchestrator to be fully initialized.
+     * Call this before using the orchestrator to ensure all toolsets are loaded.
+     * @throws {Error} If initialization failed
+     */
+    ensureReady(): Promise<void>;
+    /**
+     * Checks if the orchestrator has finished initialization.
+     * Does not throw on error - use ensureReady() for that.
+     * @returns Promise that resolves to true if ready, false if initialization failed
+     */
+    isReady(): Promise<boolean>;
     private resolveStartupConfig;
     getMode(): Exclude<Mode, "ALL">;
     getManager(): DynamicToolManager;

package/dist/core/ServerOrchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ServerOrchestrator.d.ts","sourceRoot":"","sources":["../../src/core/ServerOrchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAG9E,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,cAAc,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACpC,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sBAAsB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpD,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;CAC7B;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;gBAExC,OAAO,EAAE,yBAAyB;IAoC9C,OAAO,CAAC,oBAAoB;IAqDrB,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;IAI/B,UAAU,IAAI,kBAAkB;CAGxC"}
+{"version":3,"file":"ServerOrchestrator.d.ts","sourceRoot":"","sources":["../../src/core/ServerOrchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,KAAK,EACV,cAAc,EACd,IAAI,EACJ,YAAY,EACZ,cAAc,EACf,MAAM,mBAAmB,CAAC;AAG3B,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,SAAS,CAAC;IAClB,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,sBAAsB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpD,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;CAC7B;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgB;IAC5C,OAAO,CAAC,SAAS,CAAsB;gBAE3B,OAAO,EAAE,yBAAyB;IAgC9C;;;;;;OAMG;YACW,kBAAkB;IAgBhC;;;;OAIG;IACU,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAOzC;;;;OAIG;IACU,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAKxC,OAAO,CAAC,oBAAoB;IAqDrB,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;IAI/B,UAAU,IAAI,kBAAkB;CAGxC"}

package/dist/http/FastifyTransport.d.ts

@@ -2,6 +2,7 @@ import { FastifyInstance } from 'fastify';
 import { DynamicToolManager } from '../core/DynamicToolManager.js';
 import { ServerOrchestrator } from '../core/ServerOrchestrator.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { CustomEndpointDefinition } from './customEndpoints.js';
 export interface FastifyTransportOptions {
     host?: string;
     port?: number;
@@ -9,6 +10,11 @@ export interface FastifyTransportOptions {
     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.
+     */
+    customEndpoints?: CustomEndpointDefinition[];
 }
 export declare class FastifyTransport {
     private readonly options;
@@ -22,6 +28,17 @@ export declare class FastifyTransport {
         orchestrator: ServerOrchestrator;
     }, options?: FastifyTransportOptions, configSchema?: object);
     start(): Promise<void>;
+    /**
+     * Stops the Fastify server and cleans up all resources.
+     * Closes all client sessions and clears the cache.
+     */
     stop(): Promise<void>;
+    /**
+     * Cleans up resources associated with a client bundle.
+     * Closes all sessions within the bundle.
+     * @param bundle - The client bundle to clean up
+     * @private
+     */
+    private cleanupBundle;
 }
 //# sourceMappingURL=FastifyTransport.d.ts.map

package/dist/http/FastifyTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FastifyTransport.d.ts","sourceRoot":"","sources":["../../src/http/FastifyTransport.ts"],"names":[],"mappings":"AAAA,OAAgB,EACd,KAAK,eAAe,EAGrB,MAAM,SAAS,CAAC;AAGjB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAIxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,MAAM,WAAW,uBAAuB;IACtC,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;IAEjB,GAAG,CAAC,EAAE,eAAe,CAAC;CACvB;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAOtB;IACF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAG3B;IACF,OAAO,CAAC,GAAG,CAAgC;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAS;IAGvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAIvB;gBAGH,cAAc,EAAE,kBAAkB,EAClC,YAAY,EAAE,MAAM;QAAE,MAAM,EAAE,SAAS,CAAC;QAAC,YAAY,EAAE,kBAAkB,CAAA;KAAE,EAC3E,OAAO,GAAE,uBAA4B,EACrC,YAAY,CAAC,EAAE,MAAM;IAeV,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA8LtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAOnC"}
+{"version":3,"file":"FastifyTransport.d.ts","sourceRoot":"","sources":["../../src/http/FastifyTransport.ts"],"names":[],"mappings":"AAAA,OAAgB,EACd,KAAK,eAAe,EAGrB,MAAM,SAAS,CAAC;AAGjB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAIxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAGrE,MAAM,WAAW,uBAAuB;IACtC,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;IAEjB,GAAG,CAAC,EAAE,eAAe,CAAC;IACtB;;;OAGG;IACH,eAAe,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC9C;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAQtB;IACF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAG3B;IACF,OAAO,CAAC,GAAG,CAAgC;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAS;IAGvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CASzB;gBAGD,cAAc,EAAE,kBAAkB,EAClC,YAAY,EAAE,MAAM;QAAE,MAAM,EAAE,SAAS,CAAC;QAAC,YAAY,EAAE,kBAAkB,CAAA;KAAE,EAC3E,OAAO,GAAE,uBAA4B,EACrC,YAAY,CAAC,EAAE,MAAM;IAgBV,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoMnC;;;OAGG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAYlC;;;;;OAKG;IACH,OAAO,CAAC,aAAa;CAkBtB"}