toolception 0.2.5 → 0.3.0

package/dist/server/createPermissionBasedMcpServer.d.ts

@@ -0,0 +1,65 @@
+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>;
+}>;
+//# sourceMappingURL=createPermissionBasedMcpServer.d.ts.map

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

@@ -0,0 +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,EAAE,qCAAqC,EAAE,MAAM,mBAAmB,CAAC;AAO/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAsB,8BAA8B,CAClD,OAAO,EAAE,qCAAqC;;;;GA6F/C"}

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
+import { CreateMcpServerOptions } from '../server/createMcpServer.js';
 export type McpToolDefinition = {
     name: string;
     description: string;
@@ -22,4 +23,232 @@ export type ExposurePolicy = {
 };
 export type ToolingErrorCode = "E_VALIDATION" | "E_POLICY_MAX_ACTIVE" | "E_TOOL_NAME_CONFLICT" | "E_NOTIFY_FAILED" | "E_INTERNAL";
 export type ModuleLoader = (context?: unknown) => Promise<McpToolDefinition[]> | McpToolDefinition[];
+/**
+ * Configuration for permission-based toolset access control.
+ *
+ * Defines how client permissions are resolved and applied when using
+ * `createPermissionBasedMcpServer`. Supports two permission sources:
+ *
+ * **Header-based permissions**: Permissions are extracted from request headers.
+ * This approach is simpler but requires proper authentication/authorization in your
+ * application layer to prevent header tampering.
+ *
+ * **Config-based permissions**: Permissions are resolved server-side using either
+ * a static map or a resolver function. This provides stronger security by not
+ * trusting client-provided permission data.
+ *
+ * @example Header-based configuration
+ * ```typescript
+ * const config: PermissionConfig = {
+ *   source: 'headers',
+ *   headerName: 'mcp-toolset-permissions' // optional, this is the default
+ * };
+ * // Client sends: mcp-toolset-permissions: toolset-a,toolset-b
+ * ```
+ *
+ * @example Config-based with static map
+ * ```typescript
+ * const config: PermissionConfig = {
+ *   source: 'config',
+ *   staticMap: {
+ *     'client-1': ['toolset-a', 'toolset-b'],
+ *     'client-2': ['toolset-c']
+ *   },
+ *   defaultPermissions: [] // optional, for unknown clients
+ * };
+ * ```
+ *
+ * @example Config-based with resolver function
+ * ```typescript
+ * const config: PermissionConfig = {
+ *   source: 'config',
+ *   resolver: (clientId: string) => {
+ *     // Custom logic to determine permissions
+ *     if (clientId.startsWith('admin-')) {
+ *       return ['toolset-a', 'toolset-b', 'toolset-c'];
+ *     }
+ *     return ['toolset-a'];
+ *   },
+ *   defaultPermissions: ['toolset-a'] // fallback if resolver fails
+ * };
+ * ```
+ */
+export type PermissionConfig = {
+    /**
+     * The source of permission data.
+     *
+     * - `'headers'`: Read permissions from request headers. Requires proper authentication
+     *   in your application layer to prevent tampering.
+     * - `'config'`: Use server-side permission configuration via staticMap or resolver.
+     *   Provides stronger security by not trusting client-provided data.
+     */
+    source: "headers" | "config";
+    /**
+     * Name of the header containing permission data (for header-based permissions).
+     *
+     * The header value should be a comma-separated list of toolset names.
+     * Only used when `source` is `'headers'`.
+     *
+     * @default 'mcp-toolset-permissions'
+     * @example
+     * ```typescript
+     * // With default header name
+     * { source: 'headers' }
+     * // Client sends: mcp-toolset-permissions: toolset-a,toolset-b
+     *
+     * // With custom header name
+     * { source: 'headers', headerName: 'x-allowed-toolsets' }
+     * // Client sends: x-allowed-toolsets: toolset-a,toolset-b
+     * ```
+     */
+    headerName?: string;
+    /**
+     * Static mapping of client IDs to their allowed toolsets (for config-based permissions).
+     *
+     * Each key is a client ID, and the value is an array of toolset names the client can access.
+     * Only used when `source` is `'config'`. At least one of `staticMap` or `resolver` must
+     * be provided for config-based permissions.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   source: 'config',
+     *   staticMap: {
+     *     'client-1': ['toolset-a', 'toolset-b'],
+     *     'client-2': ['toolset-c'],
+     *     'admin-user': ['toolset-a', 'toolset-b', 'toolset-c']
+     *   }
+     * }
+     * ```
+     */
+    staticMap?: Record<string, string[]>;
+    /**
+     * Synchronous function to resolve permissions for a client (for config-based permissions).
+     *
+     * Called with the client ID and should return an array of allowed toolset names.
+     * Only used when `source` is `'config'`. If both `staticMap` and `resolver` are provided,
+     * the resolver takes precedence with staticMap as fallback.
+     *
+     * The function should be synchronous and deterministic. If it throws an error or returns
+     * a non-array value, the system falls back to `staticMap` or `defaultPermissions`.
+     *
+     * @param clientId - The unique identifier for the client requesting access
+     * @returns Array of toolset names the client is allowed to access
+     *
+     * @example
+     * ```typescript
+     * {
+     *   source: 'config',
+     *   resolver: (clientId: string) => {
+     *     // Integrate with your auth system
+     *     const user = getUserFromCache(clientId);
+     *     if (user.role === 'admin') {
+     *       return ['toolset-a', 'toolset-b', 'toolset-c'];
+     *     } else if (user.role === 'user') {
+     *       return ['toolset-a'];
+     *     }
+     *     return [];
+     *   }
+     * }
+     * ```
+     */
+    resolver?: (clientId: string) => string[];
+    /**
+     * Default permissions to apply when a client is not found in staticMap or resolver fails.
+     *
+     * Used as a fallback when:
+     * - Client ID is not found in `staticMap`
+     * - `resolver` function throws an error or returns invalid data
+     * - No other permission source provides valid permissions
+     *
+     * If not specified, defaults to an empty array (no toolsets allowed).
+     *
+     * @default []
+     * @example
+     * ```typescript
+     * {
+     *   source: 'config',
+     *   staticMap: { 'known-client': ['toolset-a'] },
+     *   defaultPermissions: ['public-toolset'] // Unknown clients get this
+     * }
+     * ```
+     */
+    defaultPermissions?: string[];
+};
+/**
+ * Options for creating a permission-based MCP server.
+ *
+ * Extends `CreateMcpServerOptions` but removes the `startup` field and requires
+ * a `permissions` configuration. Permission-based servers automatically use DYNAMIC
+ * mode internally to ensure per-client isolation, with each client receiving only
+ * their authorized toolsets.
+ *
+ * All standard options from `CreateMcpServerOptions` are supported, including:
+ * - `createServer`: Factory function to create MCP server instances
+ * - `catalog`: Toolset catalog defining available toolsets
+ * - `moduleLoaders`: Optional lazy-loading modules for toolsets
+ * - `exposurePolicy`: Optional policy for toolset exposure control
+ * - `http`: HTTP transport configuration (host, port, CORS, etc.)
+ * - `context`: Optional context passed to module loaders
+ *
+ * @example Basic header-based server
+ * ```typescript
+ * const options: CreatePermissionBasedMcpServerOptions = {
+ *   createServer: () => new McpServer({ name: "my-server", version: "1.0.0" }),
+ *   catalog: {
+ *     'toolset-a': { name: 'Toolset A', tools: [...] },
+ *     'toolset-b': { name: 'Toolset B', tools: [...] }
+ *   },
+ *   permissions: {
+ *     source: 'headers'
+ *   },
+ *   http: {
+ *     port: 3000,
+ *     cors: true
+ *   }
+ * };
+ * ```
+ *
+ * @example Config-based server with static map
+ * ```typescript
+ * const options: CreatePermissionBasedMcpServerOptions = {
+ *   createServer: () => new McpServer({ name: "my-server", version: "1.0.0" }),
+ *   catalog: {
+ *     'toolset-a': { name: 'Toolset A', tools: [...] },
+ *     'toolset-b': { name: 'Toolset B', tools: [...] }
+ *   },
+ *   permissions: {
+ *     source: 'config',
+ *     staticMap: {
+ *       'client-1': ['toolset-a'],
+ *       'client-2': ['toolset-a', 'toolset-b']
+ *     },
+ *     defaultPermissions: []
+ *   }
+ * };
+ * ```
+ */
+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=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAE5B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAE/D,MAAM,MAAM,IAAI,GAAG,SAAS,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEhD,MAAM,MAAM,cAAc,GAAG;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,eAAe,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CACnE,CAAC;AAEF,MAAM,MAAM,gBAAgB,GACxB,cAAc,GACd,qBAAqB,GACrB,sBAAsB,GACtB,iBAAiB,GACjB,YAAY,CAAC;AAKjB,MAAM,MAAM,YAAY,GAAG,CACzB,OAAO,CAAC,EAAE,OAAO,KACd,OAAO,CAAC,iBAAiB,EAAE,CAAC,GAAG,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAI3E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAE5B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAE/D,MAAM,MAAM,IAAI,GAAG,SAAS,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEhD,MAAM,MAAM,cAAc,GAAG;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,eAAe,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CACnE,CAAC;AAEF,MAAM,MAAM,gBAAgB,GACxB,cAAc,GACd,qBAAqB,GACrB,sBAAsB,GACtB,iBAAiB,GACjB,YAAY,CAAC;AAKjB,MAAM,MAAM,YAAY,GAAG,CACzB,OAAO,CAAC,EAAE,OAAO,KACd,OAAO,CAAC,iBAAiB,EAAE,CAAC,GAAG,iBAAiB,EAAE,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;;;;OAOG;IACH,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;IAE7B;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;IAE1C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolception",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "main": "dist/index.js",
@@ -58,6 +58,11 @@
     "dynamic-tools",
     "toolset",
     "tool-management",
+    "permissions",
+    "authentication",
+    "access-control",
+    "security",
+    "authorization",
     "json-rpc",
     "fastify",
     "zod",