@prmichaelsen/mcp-auth 7.0.4 → 7.2.0

package/README.md

@@ -326,6 +326,155 @@ transport: {
 }
 ```
 
+## Progress Streaming
+
+mcp-auth supports MCP progress notifications, allowing wrapped servers to stream progress updates to clients during long-running operations.
+
+### How It Works
+
+When a client provides a `progressToken` in the request, mcp-auth automatically:
+1. Extracts the progress token from the request
+2. Passes it through to the wrapped MCP server
+3. The wrapped server can send progress notifications back to the client
+4. Progress is isolated per user (multi-tenant safe)
+
+### Client-Side Usage
+
+```typescript
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+
+const client = new Client({
+  name: 'my-client',
+  version: '1.0.0'
+});
+
+// Call tool with progress support
+const result = await client.request({
+  method: 'tools/call',
+  params: {
+    name: 'long_running_operation',
+    arguments: { /* ... */ }
+  }
+}, {
+  progressToken: 'operation-123',
+  onprogress: (progress) => {
+    console.log(`Progress: ${progress.progress}/${progress.total}`);
+    console.log(`Message: ${progress.message}`);
+  }
+});
+```
+
+### Server-Side Implementation
+
+Wrapped MCP servers can send progress notifications:
+
+```typescript
+// In your MCP server tool handler
+export async function handleLongOperation(
+  args: any,
+  extra?: { progressToken?: string | number }
+): Promise<any> {
+  const progressToken = extra?.progressToken;
+  
+  if (progressToken) {
+    // Send progress notifications
+    server.notification({
+      method: 'notifications/progress',
+      params: {
+        progressToken,
+        progress: 50,
+        total: 100,
+        message: 'Processing...'
+      }
+    });
+  }
+  
+  // ... perform operation
+}
+```
+
+### Features
+
+- ✅ **Automatic Pass-Through**: Progress tokens automatically forwarded to wrapped servers
+- ✅ **Multi-Tenant Safe**: Progress notifications isolated per user
+- ✅ **Backward Compatible**: Works with or without progress token (graceful degradation)
+- ✅ **Zero Configuration**: No additional setup required
+
+### Monitoring
+
+Monitor active progress streams via authenticated endpoints:
+
+**User Stats** (shows your own progress streams):
+```bash
+GET /mcp/progress/stats
+Authorization: Bearer <jwt>
+```
+
+**Response**:
+```json
+{
+  "user": {
+    "userId": "user123",
+    "activeStreams": 2,
+    "totalMessages": 1543,
+    "totalBytes": 45231,
+    "oldestStreamAge": 120000
+  },
+  "global": {
+    "activeStreams": 15,
+    "totalMessages": 8234,
+    "userCount": 8
+  },
+  "timestamp": "2026-02-23T21:00:00.000Z"
+}
+```
+
+**All Metrics** (detailed stream information):
+```bash
+GET /mcp/progress/metrics
+Authorization: Bearer <jwt>
+```
+
+**Response**:
+```json
+{
+  "metrics": [
+    {
+      "userId": "user123",
+      "progressToken": "op-456",
+      "startTime": 1708725600000,
+      "lastUpdate": 1708725650000,
+      "duration": 50000,
+      "messageCount": 125,
+      "bytesTransferred": 45231,
+      "averageMessageSize": 361.8,
+      "messagesPerSecond": 2.5
+    }
+  ],
+  "health": {
+    "healthy": true,
+    "issues": [],
+    "warnings": []
+  },
+  "timestamp": "2026-02-23T21:00:00.000Z"
+}
+```
+
+### Performance
+
+- **Memory**: ~1KB per active stream
+- **Network**: ~100-500 bytes per progress notification
+- **CPU**: <1% overhead for typical workloads
+- **Cleanup**: Stale streams (>5 minutes idle) automatically removed every minute
+
+### Notes
+
+- Progress streaming requires SSE or HTTP transport (not available with stdio)
+- Progress tokens are automatically cleaned up after request completion
+- Wrapped servers must implement progress notification support to send updates
+- Health checks detect stale streams and high message rates
+- Monitoring endpoints require authentication
+
 ## MCP Server Contract
 
 To make your MCP server compatible with `wrapServer()`, export a factory function:
@@ -417,6 +566,24 @@ Working examples coming soon in [`examples/`](./examples/):
 - `withTimeout()` - Request timeout
 - `withRetry()` - Automatic retry on failure
 
+## Example Projects
+
+Real-world projects using `@prmichaelsen/mcp-auth`:
+
+### [@prmichaelsen/agentbase-mcp-server](https://github.com/prmichaelsen/agentbase-mcp-server)
+Multi-tenant Instagram MCP server with JWT authentication
+- **Pattern**: Server Wrapping (Dynamic Mode)
+- **Auth**: JWT + API-based token resolution
+- **Use Case**: External API credentials (Instagram)
+- **Transport**: SSE over HTTP
+
+### [@prmichaelsen/remember-mcp-server](https://github.com/prmichaelsen/remember-mcp-server)
+Multi-tenant MCP server for remember-mcp with Platform JWT authentication
+- **Pattern**: Server Wrapping (Static Mode)
+- **Auth**: JWT only (no tokenResolver)
+- **Use Case**: User-scoped data in own database
+- **Transport**: SSE over HTTP
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -9,9 +9,9 @@
  *
  * @packageDocumentation
  */
-export { wrapServer, AuthenticatedServerWrapper, type ServerWrapperConfig, type MCPServerFactory, type NormalizedServerWrapperConfig } from './wrapper/index.js';
+export { wrapServer, AuthenticatedServerWrapper, type ServerWrapperConfig, type MCPServerFactory, type NormalizedServerWrapperConfig, InstancePoolManager, ProgressManager, type ProgressCallback, type ProgressStreamMetrics } from './wrapper/index.js';
 export { AuthenticatedMCPServer, type ServerConfig, type NormalizedServerConfig, withAuth, compose, withLogging, withRateLimit, withTimeout, withRetry, type Tool, AuthenticatedTool, createAuthenticatedTool, type AuthenticatedToolHandler } from './server/index.js';
-export type { TransportType, RequestContext, AuthResult, TransportConfig, RateLimitConfig, LoggingConfig, MiddlewareConfig, PoolingConfig, Result, AsyncFunction, ToolHandler, Middleware } from './types.js';
+export type { TransportType, RequestContext, AuthResult, TransportConfig, RateLimitConfig, LoggingConfig, MiddlewareConfig, InstancePoolConfig, PoolingConfig, Result, AsyncFunction, ToolHandler, Middleware, ProgressNotification, RequestExtra } from './types.js';
 export type { AuthProvider, ResourceTokenResolver, AuthenticatedContext, AuthProviderConfig, TokenResolverConfig } from './auth/types.js';
 export { BaseAuthProvider } from './auth/base-provider.js';
 export { EnvAuthProvider, type EnvAuthProviderConfig, SimpleTokenResolver, type SimpleTokenResolverConfig, JWTAuthProvider, type JWTAuthProviderConfig, type JWTPayload, JWTTokenResolver, type JWTTokenResolverConfig, APITokenResolver, type APITokenResolverConfig } from './auth/providers/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,EACL,UAAU,EACV,0BAA0B,EAC1B,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,6BAA6B,EACnC,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,EACL,sBAAsB,EACtB,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,QAAQ,EACR,OAAO,EACP,WAAW,EACX,aAAa,EACb,WAAW,EACX,SAAS,EACT,KAAK,IAAI,EACT,iBAAiB,EACjB,uBAAuB,EACvB,KAAK,wBAAwB,EAC9B,MAAM,mBAAmB,CAAC;AAM3B,YAAY,EACV,aAAa,EACb,cAAc,EACd,UAAU,EACV,eAAe,EACf,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,MAAM,EACN,aAAa,EACb,WAAW,EACX,UAAU,EACX,MAAM,YAAY,CAAC;AAMpB,YAAY,EACV,YAAY,EACZ,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAG3D,OAAO,EACL,eAAe,EACf,KAAK,qBAAqB,EAC1B,mBAAmB,EACnB,KAAK,yBAAyB,EAC9B,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,gBAAgB,EAChB,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,KAAK,sBAAsB,EAC5B,MAAM,2BAA2B,CAAC;AAQnC,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAEL,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,cAAc,EACd,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,oBAAoB,EAGpB,MAAM,EACN,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,kBAAkB,EAGlB,sBAAsB,EACtB,WAAW,EACX,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAMlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,EACL,UAAU,EACV,0BAA0B,EAC1B,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,6BAA6B,EAClC,mBAAmB,EACnB,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC3B,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,EACL,sBAAsB,EACtB,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,QAAQ,EACR,OAAO,EACP,WAAW,EACX,aAAa,EACb,WAAW,EACX,SAAS,EACT,KAAK,IAAI,EACT,iBAAiB,EACjB,uBAAuB,EACvB,KAAK,wBAAwB,EAC9B,MAAM,mBAAmB,CAAC;AAM3B,YAAY,EACV,aAAa,EACb,cAAc,EACd,UAAU,EACV,eAAe,EACf,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,MAAM,EACN,aAAa,EACb,WAAW,EACX,UAAU,EACV,oBAAoB,EACpB,YAAY,EACb,MAAM,YAAY,CAAC;AAMpB,YAAY,EACV,YAAY,EACZ,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAG3D,OAAO,EACL,eAAe,EACf,KAAK,qBAAqB,EAC1B,mBAAmB,EACnB,KAAK,yBAAyB,EAC9B,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,gBAAgB,EAChB,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,KAAK,sBAAsB,EAC5B,MAAM,2BAA2B,CAAC;AAQnC,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAEL,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,cAAc,EACd,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,oBAAoB,EAGpB,MAAM,EACN,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,kBAAkB,EAGlB,sBAAsB,EACtB,WAAW,EACX,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAMlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG"}

package/dist/index.js

@@ -1,6 +1,8 @@
 import {
   wrapServer,
-  AuthenticatedServerWrapper
+  AuthenticatedServerWrapper,
+  InstancePoolManager,
+  ProgressManager
 } from "./wrapper/index.js";
 import {
   AuthenticatedMCPServer,
@@ -74,6 +76,7 @@ export {
   BaseAuthProvider,
   ConfigurationError,
   EnvAuthProvider,
+  InstancePoolManager,
   InvalidTokenError,
   JWTAuthProvider,
   JWTTokenResolver,
@@ -81,6 +84,7 @@ export {
   Logger,
   MCPAuthError,
   MissingCredentialsError,
+  ProgressManager,
   RateLimitError,
   ServerPoolError,
   SimpleTokenResolver,

package/dist/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "sourcesContent": ["/**\n * @prmichaelsen/mcp-auth\n *\n * Authentication and multi-tenancy framework for MCP (Model Context Protocol) servers.\n *\n * Supports two complementary patterns:\n * 1. **Server Wrapping** - Wrap existing MCP servers without modification (MCP-level auth)\n * 2. **Tool-Level Auth** - Build new MCP servers with integrated auth\n *\n * @packageDocumentation\n */\n\n// ============================================================================\n// PATTERN 1: SERVER WRAPPING (MCP-Level Auth)\n// ============================================================================\n// Use this to wrap existing MCP servers without modifying them\n// Ideal for multi-tenant services that host multiple MCP servers\n\nexport {\n  wrapServer,\n  AuthenticatedServerWrapper,\n  type ServerWrapperConfig,\n  type MCPServerFactory,\n  type NormalizedServerWrapperConfig\n} from './wrapper/index.js';\n\n// ============================================================================\n// PATTERN 2: TOOL-LEVEL AUTH\n// ============================================================================\n// Use this to build new MCP servers with integrated authentication\n// Provides fine-grained control over auth per tool\n\nexport {\n  AuthenticatedMCPServer,\n  type ServerConfig,\n  type NormalizedServerConfig,\n  withAuth,\n  compose,\n  withLogging,\n  withRateLimit,\n  withTimeout,\n  withRetry,\n  type Tool,\n  AuthenticatedTool,\n  createAuthenticatedTool,\n  type AuthenticatedToolHandler\n} from './server/index.js';\n\n// ============================================================================\n// SHARED: CORE TYPES\n// ============================================================================\n\nexport type {\n  TransportType,\n  RequestContext,\n  AuthResult,\n  TransportConfig,\n  RateLimitConfig,\n  LoggingConfig,\n  MiddlewareConfig,\n  PoolingConfig,\n  Result,\n  AsyncFunction,\n  ToolHandler,\n  Middleware\n} from './types.js';\n\n// ============================================================================\n// SHARED: AUTHENTICATION\n// ============================================================================\n\nexport type {\n  AuthProvider,\n  ResourceTokenResolver,\n  AuthenticatedContext,\n  AuthProviderConfig,\n  TokenResolverConfig\n} from './auth/types.js';\n\nexport { BaseAuthProvider } from './auth/base-provider.js';\n\n// Providers\nexport {\n  EnvAuthProvider,\n  type EnvAuthProviderConfig,\n  SimpleTokenResolver,\n  type SimpleTokenResolverConfig,\n  JWTAuthProvider,\n  type JWTAuthProviderConfig,\n  type JWTPayload,\n  JWTTokenResolver,\n  type JWTTokenResolverConfig,\n  APITokenResolver,\n  type APITokenResolverConfig\n} from './auth/providers/index.js';\n\n// ============================================================================\n// TENANT MANAGER INTEGRATION\n// ============================================================================\n// Standard interfaces for tenant manager APIs\n// Helps tenant platforms provide consistent APIs for MCP servers\n\nexport {\n  type TenantAPIErrorResponse,\n  type CredentialsAPIResponse,\n  type CredentialsAPIHeaders,\n  type TenantManagerAPI,\n  TenantAPIStatusCode,\n  TenantAPIErrorCode,\n  createTenantAPIError,\n  TenantAPIErrors\n} from './tenant/index.js';\n\n// ============================================================================\n// SHARED: UTILITIES\n// ============================================================================\n\nexport {\n  // Errors\n  MCPAuthError,\n  AuthenticationError,\n  TokenResolutionError,\n  InvalidTokenError,\n  MissingCredentialsError,\n  ConfigurationError,\n  RateLimitError,\n  ServerPoolError,\n  TransportError,\n  ValidationError,\n  isMCPAuthError,\n  isAuthenticationError,\n  isTokenResolutionError,\n  isRateLimitError,\n  formatErrorForClient,\n  \n  // Logger\n  Logger,\n  LogLevel,\n  defaultLogger,\n  createLogger,\n  sanitizeForLogging,\n  \n  // Validation\n  validateNonEmptyString,\n  validateUrl,\n  validatePositiveNumber,\n  validatePort,\n  validateEnum,\n  validateObject,\n  validateFunction,\n  validateRequiredFields,\n  validateTransportConfig,\n  validateRateLimitConfig,\n  validateLoggingConfig,\n  validatePoolingConfig,\n  sanitizeString,\n  validateUserId,\n  validateResourceType,\n  validateAccessToken\n} from './utils/index.js';\n\n// Re-export types for convenience\nexport type { LogEntry } from './utils/logger.js';\n\n// ============================================================================\n// USAGE EXAMPLES\n// ============================================================================\n\n/**\n * @example Server Wrapping Pattern (MCP-Level Auth)\n * ```typescript\n * import { wrapServer, JWTAuthProvider, DatabaseTokenResolver } from '@prmichaelsen/mcp-auth';\n * import { createServer as createInstagramServer } from '@prmichaelsen/instagram-mcp';\n *\n * const wrapped = wrapServer({\n *   serverFactory: (accessToken, userId) => createInstagramServer(accessToken, userId),\n *   authProvider: new JWTAuthProvider({ jwtSecret: process.env.JWT_SECRET }),\n *   tokenResolver: new DatabaseTokenResolver({ database: {...} }),\n *   resourceType: 'instagram',\n *   transport: { type: 'sse', port: 3000 }\n * });\n *\n * await wrapped.start();\n * ```\n *\n * @example Tool-Level Auth Pattern\n * ```typescript\n * import { AuthenticatedMCPServer, withAuth, EnvAuthProvider } from '@prmichaelsen/mcp-auth';\n *\n * const server = new AuthenticatedMCPServer({\n *   name: 'my-server',\n *   authProvider: new EnvAuthProvider(),\n *   tokenResolver: new SimpleTokenResolver({ tokenEnvVar: 'API_TOKEN' }),\n *   resourceType: 'myapi',\n *   transport: { type: 'stdio' }\n * });\n *\n * server.registerTool('get_data', withAuth(async (args, accessToken, userId) => {\n *   const client = new MyAPIClient(accessToken);\n *   return client.getData(args);\n * }));\n *\n * await server.start();\n * ```\n */\n"],
-  "mappings": "AAkBA;AAAA,EACE;AAAA,EACA;AAAA,OAIK;AAQP;AAAA,EACE;AAAA,EAGA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEA;AAAA,EACA;AAAA,OAEK;AAiCP,SAAS,wBAAwB;AAGjC;AAAA,EACE;AAAA,EAEA;AAAA,EAEA;AAAA,EAGA;AAAA,EAEA;AAAA,OAEK;AAQP;AAAA,EAKE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAMP;AAAA,EAEE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAGA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAGA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;",
+  "sourcesContent": ["/**\n * @prmichaelsen/mcp-auth\n *\n * Authentication and multi-tenancy framework for MCP (Model Context Protocol) servers.\n *\n * Supports two complementary patterns:\n * 1. **Server Wrapping** - Wrap existing MCP servers without modification (MCP-level auth)\n * 2. **Tool-Level Auth** - Build new MCP servers with integrated auth\n *\n * @packageDocumentation\n */\n\n// ============================================================================\n// PATTERN 1: SERVER WRAPPING (MCP-Level Auth)\n// ============================================================================\n// Use this to wrap existing MCP servers without modifying them\n// Ideal for multi-tenant services that host multiple MCP servers\n\nexport {\n  wrapServer,\n  AuthenticatedServerWrapper,\n  type ServerWrapperConfig,\n  type MCPServerFactory,\n  type NormalizedServerWrapperConfig,\n  InstancePoolManager,\n  ProgressManager,\n  type ProgressCallback,\n  type ProgressStreamMetrics\n} from './wrapper/index.js';\n\n// ============================================================================\n// PATTERN 2: TOOL-LEVEL AUTH\n// ============================================================================\n// Use this to build new MCP servers with integrated authentication\n// Provides fine-grained control over auth per tool\n\nexport {\n  AuthenticatedMCPServer,\n  type ServerConfig,\n  type NormalizedServerConfig,\n  withAuth,\n  compose,\n  withLogging,\n  withRateLimit,\n  withTimeout,\n  withRetry,\n  type Tool,\n  AuthenticatedTool,\n  createAuthenticatedTool,\n  type AuthenticatedToolHandler\n} from './server/index.js';\n\n// ============================================================================\n// SHARED: CORE TYPES\n// ============================================================================\n\nexport type {\n  TransportType,\n  RequestContext,\n  AuthResult,\n  TransportConfig,\n  RateLimitConfig,\n  LoggingConfig,\n  MiddlewareConfig,\n  InstancePoolConfig,\n  PoolingConfig,\n  Result,\n  AsyncFunction,\n  ToolHandler,\n  Middleware,\n  ProgressNotification,\n  RequestExtra\n} from './types.js';\n\n// ============================================================================\n// SHARED: AUTHENTICATION\n// ============================================================================\n\nexport type {\n  AuthProvider,\n  ResourceTokenResolver,\n  AuthenticatedContext,\n  AuthProviderConfig,\n  TokenResolverConfig\n} from './auth/types.js';\n\nexport { BaseAuthProvider } from './auth/base-provider.js';\n\n// Providers\nexport {\n  EnvAuthProvider,\n  type EnvAuthProviderConfig,\n  SimpleTokenResolver,\n  type SimpleTokenResolverConfig,\n  JWTAuthProvider,\n  type JWTAuthProviderConfig,\n  type JWTPayload,\n  JWTTokenResolver,\n  type JWTTokenResolverConfig,\n  APITokenResolver,\n  type APITokenResolverConfig\n} from './auth/providers/index.js';\n\n// ============================================================================\n// TENANT MANAGER INTEGRATION\n// ============================================================================\n// Standard interfaces for tenant manager APIs\n// Helps tenant platforms provide consistent APIs for MCP servers\n\nexport {\n  type TenantAPIErrorResponse,\n  type CredentialsAPIResponse,\n  type CredentialsAPIHeaders,\n  type TenantManagerAPI,\n  TenantAPIStatusCode,\n  TenantAPIErrorCode,\n  createTenantAPIError,\n  TenantAPIErrors\n} from './tenant/index.js';\n\n// ============================================================================\n// SHARED: UTILITIES\n// ============================================================================\n\nexport {\n  // Errors\n  MCPAuthError,\n  AuthenticationError,\n  TokenResolutionError,\n  InvalidTokenError,\n  MissingCredentialsError,\n  ConfigurationError,\n  RateLimitError,\n  ServerPoolError,\n  TransportError,\n  ValidationError,\n  isMCPAuthError,\n  isAuthenticationError,\n  isTokenResolutionError,\n  isRateLimitError,\n  formatErrorForClient,\n  \n  // Logger\n  Logger,\n  LogLevel,\n  defaultLogger,\n  createLogger,\n  sanitizeForLogging,\n  \n  // Validation\n  validateNonEmptyString,\n  validateUrl,\n  validatePositiveNumber,\n  validatePort,\n  validateEnum,\n  validateObject,\n  validateFunction,\n  validateRequiredFields,\n  validateTransportConfig,\n  validateRateLimitConfig,\n  validateLoggingConfig,\n  validatePoolingConfig,\n  sanitizeString,\n  validateUserId,\n  validateResourceType,\n  validateAccessToken\n} from './utils/index.js';\n\n// Re-export types for convenience\nexport type { LogEntry } from './utils/logger.js';\n\n// ============================================================================\n// USAGE EXAMPLES\n// ============================================================================\n\n/**\n * @example Server Wrapping Pattern (MCP-Level Auth)\n * ```typescript\n * import { wrapServer, JWTAuthProvider, DatabaseTokenResolver } from '@prmichaelsen/mcp-auth';\n * import { createServer as createInstagramServer } from '@prmichaelsen/instagram-mcp';\n *\n * const wrapped = wrapServer({\n *   serverFactory: (accessToken, userId) => createInstagramServer(accessToken, userId),\n *   authProvider: new JWTAuthProvider({ jwtSecret: process.env.JWT_SECRET }),\n *   tokenResolver: new DatabaseTokenResolver({ database: {...} }),\n *   resourceType: 'instagram',\n *   transport: { type: 'sse', port: 3000 }\n * });\n *\n * await wrapped.start();\n * ```\n *\n * @example Tool-Level Auth Pattern\n * ```typescript\n * import { AuthenticatedMCPServer, withAuth, EnvAuthProvider } from '@prmichaelsen/mcp-auth';\n *\n * const server = new AuthenticatedMCPServer({\n *   name: 'my-server',\n *   authProvider: new EnvAuthProvider(),\n *   tokenResolver: new SimpleTokenResolver({ tokenEnvVar: 'API_TOKEN' }),\n *   resourceType: 'myapi',\n *   transport: { type: 'stdio' }\n * });\n *\n * server.registerTool('get_data', withAuth(async (args, accessToken, userId) => {\n *   const client = new MyAPIClient(accessToken);\n *   return client.getData(args);\n * }));\n *\n * await server.start();\n * ```\n */\n"],
+  "mappings": "AAkBA;AAAA,EACE;AAAA,EACA;AAAA,EAIA;AAAA,EACA;AAAA,OAGK;AAQP;AAAA,EACE;AAAA,EAGA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEA;AAAA,EACA;AAAA,OAEK;AAoCP,SAAS,wBAAwB;AAGjC;AAAA,EACE;AAAA,EAEA;AAAA,EAEA;AAAA,EAGA;AAAA,EAEA;AAAA,OAEK;AAQP;AAAA,EAKE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAMP;AAAA,EAEE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAGA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAGA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;",
   "names": []
 }

package/dist/types.d.ts

@@ -8,6 +8,42 @@
  * Transport types supported by the framework
  */
 export type TransportType = 'stdio' | 'sse' | 'http';
+/**
+ * Progress notification parameters
+ * Used for streaming progress updates during long-running operations
+ */
+export interface ProgressNotification {
+    /**
+     * Unique token identifying this progress stream
+     */
+    progressToken: string | number;
+    /**
+     * Current progress value (optional)
+     */
+    progress?: number;
+    /**
+     * Total expected value (optional)
+     */
+    total?: number;
+    /**
+     * Progress message/description (optional)
+     */
+    message?: string;
+}
+/**
+ * Request extra parameters (from MCP SDK)
+ * Contains optional metadata passed with requests
+ */
+export interface RequestExtra {
+    /**
+     * Progress token for streaming progress notifications
+     */
+    progressToken?: string | number;
+    /**
+     * Additional custom parameters
+     */
+    [key: string]: any;
+}
 /**
  * Request context passed to authentication providers
  * Contains information about the incoming request
@@ -178,8 +214,45 @@ export interface MiddlewareConfig {
      */
     logging?: LoggingConfig;
 }
+/**
+ * Instance pool configuration for pooled mode
+ *
+ * Configures lifecycle management for pooled server instances.
+ * Used when instanceMode is 'pooled' to enable instance reuse.
+ */
+export interface InstancePoolConfig {
+    /**
+     * Maximum number of concurrent instances in the pool
+     *
+     * When this limit is reached, the least recently used instance
+     * will be evicted to make room for new instances.
+     *
+     * @minimum 1
+     */
+    maxSize: number;
+    /**
+     * Milliseconds before closing an idle instance
+     *
+     * Instances that haven't been used for this duration will be
+     * automatically closed and removed from the pool.
+     *
+     * @minimum 1000 (1 second)
+     */
+    idleTimeout: number;
+    /**
+     * Milliseconds before forcing an instance refresh
+     *
+     * Instances older than this duration will be closed and recreated,
+     * even if they're still being used. This prevents stale connections
+     * and ensures instances don't run indefinitely.
+     *
+     * @minimum idleTimeout
+     */
+    maxLifetime: number;
+}
 /**
  * Server pooling configuration
+ * @deprecated Use InstancePoolConfig instead
  */
 export interface PoolingConfig {
     /**

package/dist/types.d.ts.map

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

package/dist/wrapper/config.d.ts

@@ -5,7 +5,7 @@
  */
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { AuthProvider, ResourceTokenResolver } from '../auth/types.js';
-import type { TransportConfig, MiddlewareConfig } from '../types.js';
+import type { TransportConfig, MiddlewareConfig, InstancePoolConfig } from '../types.js';
 /**
  * MCP Server Factory Function
  *
@@ -124,6 +124,23 @@ export interface ServerWrapperConfig {
      */
     instanceMode?: 'ephemeral' | 'pooled';
     /**
+     * Instance pool configuration (required when instanceMode is 'pooled')
+     *
+     * Configures lifecycle management for pooled server instances.
+     * Enables efficient instance reuse for performance-critical applications.
+     *
+     * @example
+     * ```typescript
+     * instancePool: {
+     *   maxSize: 10,              // Max 10 concurrent instances
+     *   idleTimeout: 300000,      // Close after 5 min idle
+     *   maxLifetime: 3600000      // Force refresh after 1 hour
+     * }
+     * ```
+     */
+    instancePool?: InstancePoolConfig;
+    /**
+     * @deprecated Use instancePool instead
      * Optional: Pooling configuration (only used if instanceMode is 'pooled')
      *
      * Note: Pooling is optional and adds complexity. Ephemeral mode is recommended.
@@ -160,9 +177,10 @@ export interface ServerWrapperConfig {
  * Validated and normalized server wrapper configuration
  * Used internally after validation
  */
-export interface NormalizedServerWrapperConfig extends Required<Omit<ServerWrapperConfig, 'middleware' | 'pooling' | 'tokenResolver'>> {
+export interface NormalizedServerWrapperConfig extends Required<Omit<ServerWrapperConfig, 'middleware' | 'pooling' | 'tokenResolver' | 'instancePool'>> {
     tokenResolver: ResourceTokenResolver | null;
     middleware: MiddlewareConfig;
+    instancePool: InstancePoolConfig | null;
     pooling: {
         maxServersPerUser: number;
         idleTimeoutMs: number;

package/dist/wrapper/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/wrapper/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,KACX,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9B;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;OAUG;IACH,aAAa,EAAE,gBAAgB,CAAC;IAEhC;;;;;;;;;OASG;IACH,YAAY,EAAE,YAAY,CAAC;IAE3B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,aAAa,CAAC,EAAE,qBAAqB,CAAC;IAEtC;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,SAAS,EAAE,eAAe,CAAC;IAE3B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAE9B;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;IAEtC;;;;OAIG;IACH,OAAO,CAAC,EAAE;QACR;;;WAGG;QACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAE3B;;;WAGG;QACH,aAAa,CAAC,EAAE,MAAM,CAAC;QAEvB;;;WAGG;QACH,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;IAEF;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,6BAA8B,SAAQ,QAAQ,CAAC,IAAI,CAAC,mBAAmB,EAAE,YAAY,GAAG,SAAS,GAAG,eAAe,CAAC,CAAC;IACpI,aAAa,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC5C,UAAU,EAAE,gBAAgB,CAAC;IAC7B,OAAO,EAAE;QACP,iBAAiB,EAAE,MAAM,CAAC;QAC1B,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/wrapper/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEzF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,KACX,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9B;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;OAUG;IACH,aAAa,EAAE,gBAAgB,CAAC;IAEhC;;;;;;;;;OASG;IACH,YAAY,EAAE,YAAY,CAAC;IAE3B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,aAAa,CAAC,EAAE,qBAAqB,CAAC;IAEtC;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,SAAS,EAAE,eAAe,CAAC;IAE3B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAE9B;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;IAEtC;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAElC;;;;;OAKG;IACH,OAAO,CAAC,EAAE;QACR;;;WAGG;QACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAE3B;;;WAGG;QACH,aAAa,CAAC,EAAE,MAAM,CAAC;QAEvB;;;WAGG;QACH,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;IAEF;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,6BAA8B,SAAQ,QAAQ,CAAC,IAAI,CAAC,mBAAmB,EAAE,YAAY,GAAG,SAAS,GAAG,eAAe,GAAG,cAAc,CAAC,CAAC;IACrJ,aAAa,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC5C,UAAU,EAAE,gBAAgB,CAAC;IAC7B,YAAY,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACxC,OAAO,EAAE;QACP,iBAAiB,EAAE,MAAM,CAAC;QAC1B,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH"}

package/dist/wrapper/index.d.ts

@@ -1,36 +1,16 @@
 /**
- * Server wrapper module exports
- *
- * Provides the main wrapServer() function for wrapping MCP servers with authentication.
+ * Server wrapper exports
  */
-import { AuthenticatedServerWrapper } from './server-wrapper.js';
-import type { ServerWrapperConfig } from './config.js';
-export type { ServerWrapperConfig, MCPServerFactory, NormalizedServerWrapperConfig } from './config.js';
+export { wrapServer } from './server-wrapper.js';
 export { AuthenticatedServerWrapper } from './server-wrapper.js';
+export type { ServerWrapperConfig, NormalizedServerWrapperConfig, MCPServerFactory } from './config.js';
 /**
- * Wrap an MCP server with authentication and multi-tenancy support
- *
- * This is the main entry point for the server wrapping pattern.
- * It creates an authenticated wrapper around your MCP server factory function.
- *
- * @param config - Server wrapper configuration
- * @returns Authenticated server wrapper instance
- *
- * @example
- * ```typescript
- * import { wrapServer } from '@prmichaelsen/mcp-auth';
- * import { createServer } from '@myorg/my-mcp-server';
- *
- * const wrapped = wrapServer({
- *   serverFactory: (accessToken, userId) => createServer(accessToken, userId),
- *   authProvider: new JWTAuthProvider({ ... }),
- *   tokenResolver: new DatabaseTokenResolver({ ... }),
- *   resourceType: 'myapi',
- *   transport: { type: 'sse', port: 3000 }
- * });
- *
- * await wrapped.start();
- * ```
+ * Instance pool manager exports
  */
-export declare function wrapServer(config: ServerWrapperConfig): AuthenticatedServerWrapper;
+export { InstancePoolManager } from './instance-pool-manager.js';
+/**
+ * Progress manager exports
+ */
+export { ProgressManager, type ProgressStreamMetrics } from './progress-manager.js';
+export type { ProgressCallback } from './progress-manager.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/wrapper/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,mBAAmB,EAAoB,MAAM,aAAa,CAAC;AAGzE,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AAGxG,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,mBAAmB,GAAG,0BAA0B,CAElF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/wrapper/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AACjE,YAAY,EAAE,mBAAmB,EAAE,6BAA6B,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAExG;;GAEG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE;;GAEG;AACH,OAAO,EAAE,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACpF,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/wrapper/index.js

@@ -1,10 +1,11 @@
+import { wrapServer } from "./server-wrapper.js";
 import { AuthenticatedServerWrapper } from "./server-wrapper.js";
-import { AuthenticatedServerWrapper as AuthenticatedServerWrapper2 } from "./server-wrapper.js";
-function wrapServer(config) {
-  return new AuthenticatedServerWrapper(config);
-}
+import { InstancePoolManager } from "./instance-pool-manager.js";
+import { ProgressManager } from "./progress-manager.js";
 export {
-  AuthenticatedServerWrapper2 as AuthenticatedServerWrapper,
+  AuthenticatedServerWrapper,
+  InstancePoolManager,
+  ProgressManager,
   wrapServer
 };
 //# sourceMappingURL=index.js.map

package/dist/wrapper/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/wrapper/index.ts"],
-  "sourcesContent": ["/**\n * Server wrapper module exports\n * \n * Provides the main wrapServer() function for wrapping MCP servers with authentication.\n */\n\nimport { AuthenticatedServerWrapper } from './server-wrapper.js';\nimport type { ServerWrapperConfig, MCPServerFactory } from './config.js';\n\n// Export types\nexport type { ServerWrapperConfig, MCPServerFactory, NormalizedServerWrapperConfig } from './config.js';\n\n// Export wrapper class\nexport { AuthenticatedServerWrapper } from './server-wrapper.js';\n\n/**\n * Wrap an MCP server with authentication and multi-tenancy support\n * \n * This is the main entry point for the server wrapping pattern.\n * It creates an authenticated wrapper around your MCP server factory function.\n * \n * @param config - Server wrapper configuration\n * @returns Authenticated server wrapper instance\n * \n * @example\n * ```typescript\n * import { wrapServer } from '@prmichaelsen/mcp-auth';\n * import { createServer } from '@myorg/my-mcp-server';\n * \n * const wrapped = wrapServer({\n *   serverFactory: (accessToken, userId) => createServer(accessToken, userId),\n *   authProvider: new JWTAuthProvider({ ... }),\n *   tokenResolver: new DatabaseTokenResolver({ ... }),\n *   resourceType: 'myapi',\n *   transport: { type: 'sse', port: 3000 }\n * });\n * \n * await wrapped.start();\n * ```\n */\nexport function wrapServer(config: ServerWrapperConfig): AuthenticatedServerWrapper {\n  return new AuthenticatedServerWrapper(config);\n}\n"],
-  "mappings": "AAMA,SAAS,kCAAkC;AAO3C,SAAS,8BAAAA,mCAAkC;AA2BpC,SAAS,WAAW,QAAyD;AAClF,SAAO,IAAI,2BAA2B,MAAM;AAC9C;",
-  "names": ["AuthenticatedServerWrapper"]
+  "sourcesContent": ["/**\n * Server wrapper exports\n */\n\nexport { wrapServer } from './server-wrapper.js';\nexport { AuthenticatedServerWrapper } from './server-wrapper.js';\nexport type { ServerWrapperConfig, NormalizedServerWrapperConfig, MCPServerFactory } from './config.js';\n\n/**\n * Instance pool manager exports\n */\nexport { InstancePoolManager } from './instance-pool-manager.js';\n\n/**\n * Progress manager exports\n */\nexport { ProgressManager, type ProgressStreamMetrics } from './progress-manager.js';\nexport type { ProgressCallback } from './progress-manager.js';\n"],
+  "mappings": "AAIA,SAAS,kBAAkB;AAC3B,SAAS,kCAAkC;AAM3C,SAAS,2BAA2B;AAKpC,SAAS,uBAAmD;",
+  "names": []
 }

package/dist/wrapper/instance-pool-manager.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Instance Pool Manager
+ *
+ * Manages lifecycle of pooled server instances with configurable
+ * size limits, idle timeouts, and maximum lifetimes.
+ */
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { InstancePoolConfig } from '../types.js';
+import type { Logger } from '../utils/logger.js';
+/**
+ * Instance Pool Manager
+ *
+ * Manages a pool of server instances with automatic lifecycle management:
+ * - Reuses instances for the same user
+ * - Enforces maximum pool size with LRU eviction
+ * - Automatically closes idle instances
+ * - Forces refresh of old instances
+ * - Periodic cleanup of expired instances
+ *
+ * @example
+ * ```typescript
+ * const poolManager = new InstancePoolManager({
+ *   maxSize: 10,
+ *   idleTimeout: 300000,
+ *   maxLifetime: 3600000
+ * }, logger);
+ *
+ * const server = await poolManager.getInstance(
+ *   'user123',
+ *   'token456',
+ *   (token, userId) => createMyServer(token, userId)
+ * );
+ * ```
+ */
+export declare class InstancePoolManager {
+    private instances;
+    private config;
+    private logger;
+    private cleanupTimer?;
+    constructor(config: InstancePoolConfig, logger: Logger);
+    /**
+     * Get or create a server instance for a user
+     *
+     * If a valid instance exists for the user, it will be reused.
+     * Otherwise, a new instance will be created using the factory function.
+     *
+     * @param userId - User identifier
+     * @param accessToken - Access token for the user
+     * @param factory - Factory function to create new server instances
+     * @returns Server instance (existing or newly created)
+     */
+    getInstance(userId: string, accessToken: string, factory: (accessToken: string, userId: string) => Server | Promise<Server>): Promise<Server>;
+    /**
+     * Check if an instance is still valid
+     *
+     * An instance is valid if:
+     * - It hasn't exceeded its maximum lifetime
+     * - It hasn't been idle for too long
+     *
+     * @param instance - Instance metadata to check
+     * @returns true if instance is valid, false otherwise
+     */
+    private isValid;
+    /**
+     * Evict the least recently used instance
+     *
+     * Finds the instance with the oldest lastUsed timestamp
+     * and removes it from the pool.
+     */
+    private evictLeastRecentlyUsed;
+    /**
+     * Remove an instance from the pool
+     *
+     * Closes the server instance (if it has a close method)
+     * and removes it from the pool.
+     *
+     * @param userId - User ID of the instance to remove
+     */
+    private removeInstance;
+    /**
+     * Start periodic cleanup timer
+     *
+     * Runs cleanup every minute to remove expired instances.
+     */
+    private startCleanupTimer;
+    /**
+     * Clean up expired instances
+     *
+     * Removes all instances that are no longer valid
+     * (exceeded max lifetime or idle timeout).
+     */
+    private cleanupExpiredInstances;
+    /**
+     * Close all pooled instances
+     *
+     * Closes all server instances and clears the pool.
+     * Should be called when shutting down the server.
+     */
+    closeAll(): Promise<void>;
+    /**
+     * Get pool statistics
+     *
+     * Returns current state of the pool for monitoring and debugging.
+     *
+     * @returns Pool statistics including size and instance details
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        instances: {
+            userId: string;
+            age: number;
+            idle: number;
+            createdAt: string;
+            lastUsed: string;
+        }[];
+    };
+}
+//# sourceMappingURL=instance-pool-manager.d.ts.map

package/dist/wrapper/instance-pool-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-pool-manager.d.ts","sourceRoot":"","sources":["../../src/wrapper/instance-pool-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAsBjD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,SAAS,CAAgC;IACjD,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAAC,CAAiB;gBAE1B,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM;IAatD;;;;;;;;;;OAUG;IACG,WAAW,CACf,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GACzE,OAAO,CAAC,MAAM,CAAC;IAgDlB;;;;;;;;;OASG;IACH,OAAO,CAAC,OAAO;IAsBf;;;;;OAKG;YACW,sBAAsB;IAqBpC;;;;;;;OAOG;YACW,cAAc;IAqB5B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAYzB;;;;;OAKG;YACW,uBAAuB;IAsBrC;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB/B;;;;;;OAMG;IACH,QAAQ;;;;;;;;;;;CAcT"}