toolception 0.4.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)
@@ -589,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)
@@ -736,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)
 

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;

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,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;IAeV,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA8LnC;;;OAGG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAYlC;;;;;OAKG;IACH,OAAO,CAAC,aAAa;CAkBtB"}
+{"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"}

package/dist/http/customEndpoints.d.ts

@@ -0,0 +1,247 @@
+import { z } from 'zod';
+/**
+ * Supported HTTP methods for custom endpoints
+ */
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+/**
+ * Request context passed to custom endpoint handlers.
+ * Contains validated and typed request data without exposing Fastify types.
+ */
+export interface CustomEndpointRequest<TBody = unknown, TQuery = unknown, TParams = unknown> {
+    /**
+     * Validated request body (typed from bodySchema)
+     */
+    body: TBody;
+    /**
+     * Validated query parameters (typed from querySchema)
+     */
+    query: TQuery;
+    /**
+     * Validated path parameters (typed from paramsSchema)
+     */
+    params: TParams;
+    /**
+     * Raw request headers
+     */
+    headers: Record<string, string | string[] | undefined>;
+    /**
+     * Client ID (from mcp-client-id header or auto-generated for anonymous clients)
+     */
+    clientId: string;
+}
+/**
+ * Permission-aware request context for custom endpoints in permission-based servers.
+ * Extends CustomEndpointRequest with permission information.
+ */
+export interface PermissionAwareEndpointRequest<TBody = unknown, TQuery = unknown, TParams = unknown> extends CustomEndpointRequest<TBody, TQuery, TParams> {
+    /**
+     * Toolsets this client is allowed to access (resolved from permissions)
+     */
+    allowedToolsets: string[];
+    /**
+     * Toolsets that failed to enable for this client
+     */
+    failedToolsets: string[];
+}
+/**
+ * Handler function type with automatic type inference from Zod schemas.
+ * Receives validated and typed request data, returns typed response.
+ */
+export type CustomEndpointHandler<TBody extends z.ZodTypeAny, TQuery extends z.ZodTypeAny, TParams extends z.ZodTypeAny, TResponse extends z.ZodTypeAny> = (request: CustomEndpointRequest<TBody extends z.ZodTypeAny ? z.infer<TBody> : never, TQuery extends z.ZodTypeAny ? z.infer<TQuery> : never, TParams extends z.ZodTypeAny ? z.infer<TParams> : never>) => Promise<z.infer<TResponse>> | z.infer<TResponse>;
+/**
+ * Permission-aware handler function type for permission-based servers.
+ * Receives permission context in addition to validated request data.
+ */
+export type PermissionAwareEndpointHandler<TBody extends z.ZodTypeAny, TQuery extends z.ZodTypeAny, TParams extends z.ZodTypeAny, TResponse extends z.ZodTypeAny> = (request: PermissionAwareEndpointRequest<TBody extends z.ZodTypeAny ? z.infer<TBody> : never, TQuery extends z.ZodTypeAny ? z.infer<TQuery> : never, TParams extends z.ZodTypeAny ? z.infer<TParams> : never>) => Promise<z.infer<TResponse>> | z.infer<TResponse>;
+/**
+ * Custom HTTP endpoint definition with Zod schema-based validation and type inference.
+ * Allows defining REST-like endpoints alongside MCP protocol endpoints.
+ *
+ * @template TBody - Zod schema for request body validation
+ * @template TQuery - Zod schema for query parameter validation
+ * @template TParams - Zod schema for path parameter validation
+ * @template TResponse - Zod schema for response validation
+ *
+ * @example
+ * ```typescript
+ * const getUserEndpoint = defineEndpoint({
+ *   method: "GET",
+ *   path: "/users/:userId",
+ *   paramsSchema: z.object({
+ *     userId: z.string().uuid(),
+ *   }),
+ *   responseSchema: z.object({
+ *     id: z.string(),
+ *     name: z.string(),
+ *   }),
+ *   handler: async (req) => {
+ *     // req.params is typed: { userId: string }
+ *     const { userId } = req.params;
+ *     return { id: userId, name: "Alice" };
+ *   },
+ * });
+ * ```
+ */
+export interface CustomEndpointDefinition<TBody extends z.ZodTypeAny = z.ZodTypeAny, TQuery extends z.ZodTypeAny = z.ZodTypeAny, TParams extends z.ZodTypeAny = z.ZodTypeAny, TResponse extends z.ZodTypeAny = z.ZodTypeAny> {
+    /**
+     * HTTP method for this endpoint
+     */
+    method: HttpMethod;
+    /**
+     * URL path (relative to basePath). Supports path parameters using :param syntax.
+     *
+     * @example
+     * - "/users" - Simple path
+     * - "/users/:id" - Path with single parameter
+     * - "/items/:category/:id" - Path with multiple parameters
+     */
+    path: string;
+    /**
+     * Optional Zod schema for request body validation (typically used with POST, PUT, PATCH).
+     * Enables automatic type inference for handler body parameter.
+     */
+    bodySchema?: TBody;
+    /**
+     * Optional Zod schema for query parameter validation.
+     * Enables automatic type inference for handler query parameter.
+     *
+     * @example
+     * ```typescript
+     * querySchema: z.object({
+     *   limit: z.coerce.number().int().positive().default(10),
+     *   offset: z.coerce.number().int().nonnegative().default(0),
+     * })
+     * ```
+     */
+    querySchema?: TQuery;
+    /**
+     * Optional Zod schema for path parameter validation.
+     * Enables automatic type inference for handler params parameter.
+     */
+    paramsSchema?: TParams;
+    /**
+     * Optional Zod schema for response validation.
+     * Enables automatic type inference for handler return type.
+     * If validation fails, returns 500 error to prevent information leakage.
+     */
+    responseSchema?: TResponse;
+    /**
+     * Request handler function with inferred types from schemas.
+     * Receives validated and typed request data, returns typed response.
+     */
+    handler: CustomEndpointHandler<TBody, TQuery, TParams, TResponse>;
+    /**
+     * Optional description for documentation purposes
+     */
+    description?: string;
+}
+/**
+ * Standard error response structure for custom endpoints
+ */
+export interface EndpointErrorResponse {
+    error: {
+        /**
+         * Error code indicating the type of error
+         * - VALIDATION_ERROR: Request validation failed (400)
+         * - INTERNAL_ERROR: Handler threw an error (500)
+         * - RESPONSE_VALIDATION_ERROR: Response validation failed (500)
+         */
+        code: "VALIDATION_ERROR" | "INTERNAL_ERROR" | "RESPONSE_VALIDATION_ERROR";
+        /**
+         * Human-readable error message
+         */
+        message: string;
+        /**
+         * Optional additional error details (e.g., Zod validation errors)
+         */
+        details?: unknown;
+    };
+}
+/**
+ * Helper function to create type-safe custom endpoints with automatic type inference.
+ * Provides better IntelliSense and type checking for endpoint definitions.
+ *
+ * @template TBody - Zod schema for request body
+ * @template TQuery - Zod schema for query parameters
+ * @template TParams - Zod schema for path parameters
+ * @template TResponse - Zod schema for response
+ *
+ * @param definition - Endpoint definition with schemas and handler
+ * @returns The same endpoint definition with full type inference
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ * import { defineEndpoint } from "toolception";
+ *
+ * const getUsersEndpoint = defineEndpoint({
+ *   method: "GET",
+ *   path: "/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(),
+ *     })),
+ *     total: z.number(),
+ *   }),
+ *   handler: async (req) => {
+ *     // req.query is fully typed: { limit: number, role?: "admin" | "user" }
+ *     const { limit, role } = req.query;
+ *
+ *     return {
+ *       users: [{ id: "1", name: "Alice" }],
+ *       total: 1,
+ *     };
+ *   },
+ * });
+ * ```
+ */
+export declare function defineEndpoint<TBody extends z.ZodTypeAny = z.ZodNever, TQuery extends z.ZodTypeAny = z.ZodNever, TParams extends z.ZodTypeAny = z.ZodNever, TResponse extends z.ZodTypeAny = z.ZodAny>(definition: CustomEndpointDefinition<TBody, TQuery, TParams, TResponse>): CustomEndpointDefinition<TBody, TQuery, TParams, TResponse>;
+/**
+ * Helper function to create permission-aware custom endpoints for permission-based servers.
+ * Similar to defineEndpoint but with access to permission context in the handler.
+ *
+ * @template TBody - Zod schema for request body
+ * @template TQuery - Zod schema for query parameters
+ * @template TParams - Zod schema for path parameters
+ * @template TResponse - Zod schema for response
+ *
+ * @param definition - Endpoint definition with permission-aware handler
+ * @returns Endpoint definition compatible with permission-based servers
+ *
+ * @example
+ * ```typescript
+ * import { definePermissionAwareEndpoint } from "toolception";
+ *
+ * const statsEndpoint = definePermissionAwareEndpoint({
+ *   method: "GET",
+ *   path: "/my-permissions",
+ *   responseSchema: z.object({
+ *     toolsets: z.array(z.string()),
+ *     count: z.number(),
+ *   }),
+ *   handler: async (req) => {
+ *     // req.allowedToolsets and req.failedToolsets are available
+ *     return {
+ *       toolsets: req.allowedToolsets,
+ *       count: req.allowedToolsets.length,
+ *     };
+ *   },
+ * });
+ * ```
+ */
+export declare function definePermissionAwareEndpoint<TBody extends z.ZodTypeAny = z.ZodNever, TQuery extends z.ZodTypeAny = z.ZodNever, TParams extends z.ZodTypeAny = z.ZodNever, TResponse extends z.ZodTypeAny = z.ZodAny>(definition: {
+    method: HttpMethod;
+    path: string;
+    bodySchema?: TBody;
+    querySchema?: TQuery;
+    paramsSchema?: TParams;
+    responseSchema?: TResponse;
+    handler: PermissionAwareEndpointHandler<TBody, TQuery, TParams, TResponse>;
+    description?: string;
+}): CustomEndpointDefinition<TBody, TQuery, TParams, TResponse>;
+//# sourceMappingURL=customEndpoints.d.ts.map

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

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

package/dist/http/endpointRegistration.d.ts

@@ -0,0 +1,35 @@
+import { FastifyInstance, FastifyRequest } from 'fastify';
+import { CustomEndpointDefinition } from './customEndpoints.js';
+/**
+ * Options for registering custom endpoints
+ */
+export interface RegisterCustomEndpointsOptions {
+    /**
+     * Optional function to extract additional context for each request.
+     * Used by permission-aware transport to inject permission data.
+     */
+    contextExtractor?: (req: FastifyRequest) => Promise<Record<string, any>> | Record<string, any>;
+}
+/**
+ * Registers custom endpoints on a Fastify instance.
+ * Handles Zod validation, error responses, and type-safe request mapping.
+ *
+ * @param app - Fastify instance to register endpoints on
+ * @param basePath - Base path for all endpoints (e.g., "/" or "/api")
+ * @param endpoints - Array of custom endpoint definitions
+ * @param options - Optional configuration for endpoint registration
+ *
+ * @example
+ * ```typescript
+ * registerCustomEndpoints(app, "/api", [
+ *   defineEndpoint({
+ *     method: "GET",
+ *     path: "/users",
+ *     querySchema: z.object({ limit: z.coerce.number() }),
+ *     handler: async (req) => ({ users: [] }),
+ *   }),
+ * ]);
+ * ```
+ */
+export declare function registerCustomEndpoints(app: FastifyInstance, basePath: string, endpoints: CustomEndpointDefinition[], options?: RegisterCustomEndpointsOptions): void;
+//# sourceMappingURL=endpointRegistration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"endpointRegistration.d.ts","sourceRoot":"","sources":["../../src/http/endpointRegistration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAgB,MAAM,SAAS,CAAC;AAG7E,OAAO,KAAK,EACV,wBAAwB,EAGzB,MAAM,sBAAsB,CAAC;AAE9B;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CACjB,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,wBAAwB,EAAE,EACrC,OAAO,CAAC,EAAE,8BAA8B,GACvC,IAAI,CAgIN"}

package/dist/index.d.ts

@@ -2,4 +2,6 @@ export { createMcpServer } from './server/createMcpServer.js';
 export type { CreateMcpServerOptions } from './server/createMcpServer.js';
 export { createPermissionBasedMcpServer } from './server/createPermissionBasedMcpServer.js';
 export type { ToolSetCatalog, ToolSetDefinition, McpToolDefinition, ExposurePolicy, Mode, ModuleLoader, PermissionConfig, CreatePermissionBasedMcpServerOptions, } from './types/index.js';
+export type { CustomEndpointDefinition, CustomEndpointRequest, PermissionAwareEndpointRequest, CustomEndpointHandler, PermissionAwareEndpointHandler, HttpMethod, EndpointErrorResponse, } from './http/customEndpoints.js';
+export { defineEndpoint, definePermissionAwareEndpoint, } from './http/customEndpoints.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,YAAY,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAG1E,OAAO,EAAE,8BAA8B,EAAE,MAAM,4CAA4C,CAAC;AAG5F,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,IAAI,EACJ,YAAY,EACZ,gBAAgB,EAChB,qCAAqC,GACtC,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,YAAY,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAG1E,OAAO,EAAE,8BAA8B,EAAE,MAAM,4CAA4C,CAAC;AAG5F,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,IAAI,EACJ,YAAY,EACZ,gBAAgB,EAChB,qCAAqC,GACtC,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EACV,wBAAwB,EACxB,qBAAqB,EACrB,8BAA8B,EAC9B,qBAAqB,EACrB,8BAA8B,EAC9B,UAAU,EACV,qBAAqB,GACtB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,cAAc,EACd,6BAA6B,GAC9B,MAAM,2BAA2B,CAAC"}