toolception 0.5.5 → 0.6.1

package/README.md

@@ -11,6 +11,7 @@
 - [Permission-based starter guide](#permission-based-starter-guide)
 - [Permission configuration approaches](#permission-configuration-approaches)
 - [Custom HTTP endpoints](#custom-http-endpoints)
+- [Per-session context](#per-session-context)
 - [API](#api)
   - [createMcpServer](#createmcpserveroptions)
   - [createPermissionBasedMcpServer](#createpermissionbasedmcpserveroptions)
@@ -39,6 +40,7 @@ Toolception addresses this by grouping tools into toolsets and letting you expos
 - **Large or multi-domain catalogs**: You have >20–50 tools or multiple domains (e.g., search, data, billing) and don’t want to expose them all at once.
 - **Task-specific workflows**: You want the client/agent to enable only the tools relevant to the current task.
 - **Multi-tenant or policy needs**: Different users/tenants require different tool access or limits.
+- **Per-session context**: You need different context values (API tokens, user IDs) for each client session passed to module loaders.
 - **Permission-based access control**: You need to enforce client-specific toolset permissions for security, compliance, or multi-tenant isolation. Each client should only see and access the toolsets they're authorized to use, with server-side or header-based permission enforcement.
 - **Collision-safe naming**: You need predictable, namespaced tool names to avoid conflicts.
 - **Lazy loading**: Some tools are heavy and should be loaded on demand.
@@ -719,6 +721,88 @@ Custom endpoints cannot override built-in MCP paths:
 
 See `examples/custom-endpoints-demo.ts` for a full working example with GET, POST, PUT, DELETE endpoints, pagination, and permission-aware handlers.
 
+## Per-session context
+
+Use the `sessionContext` option to enable per-client context values extracted from query parameters. This is useful for multi-tenant scenarios where each client needs different configuration (API tokens, user IDs, etc.) passed to module loaders.
+
+### Basic usage
+
+```ts
+import { createMcpServer } from "toolception";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+const { start } = await createMcpServer({
+  catalog: { /* ... */ },
+  moduleLoaders: { /* ... */ },
+  context: { baseValue: 'shared' },  // Base context for all sessions
+  sessionContext: {
+    enabled: true,
+    queryParam: {
+      name: 'config',
+      encoding: 'base64',
+      allowedKeys: ['API_TOKEN', 'USER_ID'],  // Security: always specify
+    },
+    merge: 'shallow',
+  },
+  createServer: () => new McpServer({
+    name: "my-server",
+    version: "1.0.0",
+    capabilities: { tools: { listChanged: true } },
+  }),
+  http: { port: 3000 },
+});
+
+await start();
+```
+
+### Client connection
+
+```bash
+# Encode session config as base64
+CONFIG=$(echo -n '{"API_TOKEN":"user-secret-token","USER_ID":"123"}' | base64)
+
+# Connect with session config
+curl -X POST "http://localhost:3000/mcp?config=$CONFIG" \
+  -H "mcp-client-id: my-client" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"initialize",...}'
+```
+
+### Module loader receives merged context
+
+```ts
+const moduleLoaders = {
+  tenant: async (ctx: any) => {
+    // ctx = { baseValue: 'shared', API_TOKEN: 'user-secret-token', USER_ID: '123' }
+    return [/* tools using ctx.API_TOKEN */];
+  },
+};
+```
+
+### Custom context resolver
+
+For advanced use cases, provide a custom resolver function:
+
+```ts
+sessionContext: {
+  enabled: true,
+  queryParam: { allowedKeys: ['tenant_id'] },
+  contextResolver: (request, baseContext, parsedConfig) => ({
+    ...baseContext,
+    ...parsedConfig,
+    clientId: request.clientId,
+    timestamp: Date.now(),
+  }),
+}
+```
+
+### Security considerations
+
+- **Always specify `allowedKeys`**: Without a whitelist, any key in the query config is accepted
+- **Fail-secure**: Invalid encoding silently falls back to base context
+- **No logging of values**: Session config values are never logged
+- **Filtered silently**: Disallowed keys are filtered without error messages
+
 ## API
 
 ### createMcpServer(options)
@@ -864,6 +948,28 @@ const moduleLoaders = {
 };
 ```
 
+#### options.sessionContext (optional)
+
+`SessionContextConfig`
+
+Configuration for per-session context extraction from query parameters. Enables multi-tenant use cases where each client session can have its own context values passed to module loaders. See [Per-session context](#per-session-context) for detailed usage examples.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Whether session context extraction is enabled |
+| `queryParam.name` | `string` | `'config'` | Query parameter name |
+| `queryParam.encoding` | `'base64' \| 'json'` | `'base64'` | Encoding format |
+| `queryParam.allowedKeys` | `string[]` | - | Whitelist of allowed keys (recommended for security) |
+| `contextResolver` | `function` | - | Custom context resolver function |
+| `merge` | `'shallow' \| 'deep'` | `'shallow'` | How to merge with base context |
+
+Notes
+
+- Session context is extracted per-request and merged with the base `context` option
+- Each unique session config generates a different cache key, enabling per-tenant module caching
+- Invalid encoding or parsing errors silently fall back to base context (fail-secure)
+- Only applies to DYNAMIC mode servers; STATIC mode uses a single shared server instance
+
 #### options.http (optional)
 
 `{ host?: string; port?: number; basePath?: string; cors?: boolean; logger?: boolean; customEndpoints?: CustomEndpointDefinition[] }`
@@ -970,6 +1076,14 @@ Same as `createMcpServer` - see [options.configSchema](#optionsconfigschema-opti
 
 Same as `createMcpServer` - see [options.context](#optionscontext-optional).
 
+#### options.sessionContext (optional)
+
+`SessionContextConfig`
+
+Session context is available in permission-based servers but has limited support. Because permission-based servers determine toolsets at connection time based on permissions, the session context cannot affect which toolsets are loaded. However, the merged context is still passed to module loaders.
+
+**Note:** A warning is issued if `sessionContext` is used with `createPermissionBasedMcpServer`. For full session context support with per-session toolset caching, use `createMcpServer` with DYNAMIC mode.
+
 ### Meta-tools
 
 Meta-tools are registered based on mode:

package/dist/http/FastifyTransport.d.ts

@@ -1,6 +1,7 @@
 import { FastifyInstance } from 'fastify';
 import { DynamicToolManager } from '../core/DynamicToolManager.js';
 import { ServerOrchestrator } from '../core/ServerOrchestrator.js';
+import { SessionContextResolver } from '../session/SessionContextResolver.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { CustomEndpointDefinition } from './customEndpoints.js';
 export interface FastifyTransportOptions {
@@ -16,17 +17,24 @@ export interface FastifyTransportOptions {
      */
     customEndpoints?: CustomEndpointDefinition[];
 }
+/**
+ * Callback type for creating a server bundle.
+ * Accepts an optional merged context for per-session context support.
+ */
+export type CreateBundleCallback = (mergedContext?: unknown) => {
+    server: McpServer;
+    orchestrator: ServerOrchestrator;
+};
 export declare class FastifyTransport {
     private readonly options;
     private readonly defaultManager;
     private readonly createBundle;
+    private readonly sessionContextResolver?;
+    private readonly baseContext?;
     private app;
     private readonly configSchema?;
     private readonly clientCache;
-    constructor(defaultManager: DynamicToolManager, createBundle: () => {
-        server: McpServer;
-        orchestrator: ServerOrchestrator;
-    }, options?: FastifyTransportOptions, configSchema?: object);
+    constructor(defaultManager: DynamicToolManager, createBundle: CreateBundleCallback, options?: FastifyTransportOptions, configSchema?: object, sessionContextResolver?: SessionContextResolver, baseContext?: unknown);
     start(): Promise<void>;
     /**
      * Stops the Fastify server and cleans up all resources.
@@ -40,5 +48,33 @@ export declare class FastifyTransport {
      * @private
      */
     private cleanupBundle;
+    /**
+     * Resolves the session context and generates a cache key for the request.
+     * If a session context resolver is configured, it extracts query parameters
+     * and merges session-specific context with the base context.
+     *
+     * @param req - The Fastify request
+     * @param clientId - The client identifier
+     * @returns Object with cache key and merged context
+     * @private
+     */
+    private resolveSessionContext;
+    /**
+     * Extracts headers from a Fastify request as a Record.
+     * Normalizes header names to lowercase.
+     *
+     * @param req - The Fastify request
+     * @returns Headers as a string record
+     * @private
+     */
+    private extractHeaders;
+    /**
+     * Extracts query parameters from a Fastify request as a Record.
+     *
+     * @param req - The Fastify request
+     * @returns Query parameters as a string record
+     * @private
+     */
+    private extractQuery;
 }
 //# 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;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"}
+{"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;AAExE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAInF,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;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,aAAa,CAAC,EAAE,OAAO,KAAK;IAC9D,MAAM,EAAE,SAAS,CAAC;IAClB,YAAY,EAAE,kBAAkB,CAAC;CAClC,CAAC;AAEF,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAQtB;IACF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuB;IACpD,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC,CAAyB;IACjE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAU;IACvC,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,oBAAoB,EAClC,OAAO,GAAE,uBAA4B,EACrC,YAAY,CAAC,EAAE,MAAM,EACrB,sBAAsB,CAAC,EAAE,sBAAsB,EAC/C,WAAW,CAAC,EAAE,OAAO;IAkBV,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwMnC;;;OAGG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAYlC;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAmBrB;;;;;;;;;OASG;IACH,OAAO,CAAC,qBAAqB;IAqC7B;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAYtB;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;CAYrB"}

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 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 { ToolSetCatalog, ToolSetDefinition, McpToolDefinition, ExposurePolicy, Mode, ModuleLoader, PermissionConfig, CreatePermissionBasedMcpServerOptions, SessionContextConfig, SessionRequestContext, } from './types/index.js';
+export { SessionContextResolver } from './session/SessionContextResolver.js';
+export type { SessionContextResult } from './session/SessionContextResolver.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;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"}
+{"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,EACrC,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,YAAY,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAGhF,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"}