mcp4openapi 0.1.0 → 0.2.1

package/dist/src/mcp-server.d.ts

@@ -20,6 +20,14 @@ export declare class MCPServer {
      * Supports nested objects but keeps first level of arrays
      */
     private filterFields;
+    /**
+     * Format error message for client with correlation ID
+     *
+     * Why: Categorize errors as "safe" (4xx client errors) vs "unsafe" (5xx server errors)
+     * Safe errors show API message to help user fix the issue
+     * Unsafe errors show generic message to avoid leaking sensitive info
+     */
+    private formatErrorForClient;
     constructor(logger?: Logger);
     initialize(specPath: string, profilePath?: string): Promise<void>;
     /**
@@ -36,12 +44,30 @@ export declare class MCPServer {
      * Get base URL from profile config or OpenAPI spec
      */
     private getBaseUrl;
+    /**
+     * Get auth configurations as array (supports single or multiple auth methods)
+     * Returns array sorted by priority (lower = higher priority)
+     */
+    private getAuthConfigs;
+    /**
+     * Get primary (highest priority) auth configuration
+     */
+    private getPrimaryAuthConfig;
+    /**
+     * Get highest priority auth configuration that reads token from environment
+     */
+    private getEnvBackedAuthConfig;
+    /**
+     * Get OAuth configuration from auth configs (if any)
+     */
+    private getOAuthConfig;
     /**
      * Get or create HTTP client for session
      */
     private getHttpClientForSession;
     /**
      * Get auth token from HTTP transport session
+     * Ensures token is valid (refreshes if expired) before returning
      */
     private getAuthTokenFromSession;
     /**
@@ -61,6 +87,13 @@ export declare class MCPServer {
      * No result aggregation needed.
      */
     private executeSimpleTool;
+    /**
+     * Encode path segment if it contains special characters (like slashes)
+     *
+     * Why: GitLab and other APIs require path parameters (like project paths)
+     * to be URL-encoded when used in URL path.
+     */
+    private encodePathSegment;
     /**
      * Resolve path parameters using profile aliases
      *

package/dist/src/mcp-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../../src/mcp-server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkBH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAO1C,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,OAAO,CAAC,CAAU;IAC1B,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,iBAAiB,CAA2B;IACpD,OAAO,CAAC,iBAAiB,CAAC,CAAoB;IAC9C,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAa;IAElC;;;OAGG;IACH,OAAO,CAAC,YAAY;gBAkBR,MAAM,CAAC,EAAE,MAAM;IAqBrB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwDvE;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAW5B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA8B5B;;OAEG;IACH,OAAO,CAAC,UAAU;IAYlB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAuC/B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAS/B;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAO5B;;OAEG;IACH,OAAO,CAAC,aAAa;IA6ErB;;;;;OAKG;YACW,iBAAiB;IAgF/B;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAyBnB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAsB1B;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;IA8BnB;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAM/B;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+CxD;;;;OAIG;YACW,oBAAoB;IAiBlC,OAAO,CAAC,gBAAgB;YA0BV,cAAc;IAiE5B,OAAO,CAAC,kBAAkB;IA6B1B;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAK5B"}
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../../src/mcp-server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6BH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAO1C,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,OAAO,CAAC,CAAU;IAC1B,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,iBAAiB,CAA2B;IACpD,OAAO,CAAC,iBAAiB,CAAC,CAAoB;IAC9C,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAa;IAElC;;;OAGG;IACH,OAAO,CAAC,YAAY;IAkBpB;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;gBA8ChB,MAAM,CAAC,EAAE,MAAM;IAqBrB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA4DvE;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAW5B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA8B5B;;OAEG;IACH,OAAO,CAAC,UAAU;IAYlB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAUtB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAK5B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAK9B;;OAEG;IACH,OAAO,CAAC,cAAc;IAMtB;;OAEG;YACW,uBAAuB;IAuCrC;;;OAGG;YACW,uBAAuB;IAsBrC;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAO5B;;OAEG;IACH,OAAO,CAAC,aAAa;IAuFrB;;;;;OAKG;YACW,iBAAiB;IAgF/B;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAKzB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAyBnB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAsB1B;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;IA8BnB;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAM/B;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6ExD;;;;OAIG;YACW,oBAAoB;IAiBlC,OAAO,CAAC,gBAAgB;YA6BV,cAAc;YA8Gd,kBAAkB;IAoDhC;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAK5B"}

package/dist/src/mcp-server.js

@@ -11,7 +11,8 @@ import { OpenAPIParser } from './openapi-parser.js';
 import { ProfileLoader } from './profile-loader.js';
 import { ToolGenerator } from './tool-generator.js';
 import { CompositeExecutor } from './composite-executor.js';
-import { ConfigurationError, OperationNotFoundError, ValidationError } from './errors.js';
+import { ConfigurationError, OperationNotFoundError, ValidationError, AuthenticationError, AuthorizationError, RateLimitError, NetworkError, generateCorrelationId } from './errors.js';
+import { TIMEOUTS, OAUTH_RATE_LIMIT } from './constants.js';
 import { HttpClientFactory } from './http-client-factory.js';
 import { SchemaValidator } from './schema-validator.js';
 import { ConsoleLogger, JsonLogger } from './logger.js';
@@ -47,6 +48,51 @@ export class MCPServer {
         }
         return filtered;
     }
+    /**
+     * Format error message for client with correlation ID
+     *
+     * Why: Categorize errors as "safe" (4xx client errors) vs "unsafe" (5xx server errors)
+     * Safe errors show API message to help user fix the issue
+     * Unsafe errors show generic message to avoid leaking sensitive info
+     */
+    formatErrorForClient(error, correlationId) {
+        // Authentication errors - safe to show (token expired, invalid credentials)
+        if (error instanceof AuthenticationError) {
+            return `Authentication failed: ${error.message} (correlation ID: ${correlationId})`;
+        }
+        // Authorization errors - safe to show (insufficient permissions)
+        if (error instanceof AuthorizationError) {
+            return `Authorization failed: ${error.message} (correlation ID: ${correlationId})`;
+        }
+        // Rate limit errors - safe to show (helps user understand backoff)
+        if (error instanceof RateLimitError) {
+            const retryInfo = error.details?.retryAfter
+                ? ` Retry after ${error.details.retryAfter} seconds.`
+                : '';
+            return `Rate limit exceeded: ${error.message}${retryInfo} (correlation ID: ${correlationId})`;
+        }
+        // Network errors with 4xx status - safe to show (client errors)
+        if (error instanceof NetworkError && error.details?.statusCode) {
+            const statusCode = error.details.statusCode;
+            if (statusCode >= 400 && statusCode < 500) {
+                return `Request failed: ${error.message} (correlation ID: ${correlationId})`;
+            }
+        }
+        // Validation errors - safe to show (helps user fix input)
+        if (error instanceof ValidationError) {
+            return `Validation error: ${error.message} (correlation ID: ${correlationId})`;
+        }
+        // Operation not found - safe to show (configuration issue)
+        if (error instanceof OperationNotFoundError) {
+            return `Operation not found: ${error.message} (correlation ID: ${correlationId})`;
+        }
+        // Configuration errors - safe to show (helps admin fix setup)
+        if (error instanceof ConfigurationError) {
+            return `Configuration error: ${error.message} (correlation ID: ${correlationId})`;
+        }
+        // Generic/unknown errors - hide details, show only correlation ID
+        return `Internal error (correlation ID: ${correlationId})`;
+    }
     constructor(logger) {
         this.logger = logger || new ConsoleLogger();
         this.schemaValidator = new SchemaValidator();
@@ -66,7 +112,7 @@ export class MCPServer {
         // Load OpenAPI spec
         await this.parser.load(specPath);
         this.logger.info('Loaded OpenAPI spec', { specPath });
-        // Load profile
+        // Load or create MCP profile
         if (profilePath) {
             const loader = new ProfileLoader();
             this.profile = await loader.load(profilePath);
@@ -85,28 +131,32 @@ export class MCPServer {
             this.checkToolNameLengths();
         }
         // Re-create logger with auth config for token redaction
-        if (this.profile.interceptors?.auth) {
-            this.logger = this.createLoggerWithAuth(this.profile.interceptors.auth);
-            this.logger.info('Logger re-configured with auth token redaction');
+        const authConfigs = this.getAuthConfigs();
+        if (authConfigs.length > 0) {
+            // Use first auth config for logger (primary)
+            this.logger = this.createLoggerWithAuth(authConfigs[0]);
+            this.logger.info('Logger re-configured with auth token redaction', {
+                authMethods: authConfigs.length,
+            });
         }
         // Setup HTTP client with interceptors
         // For stdio transport, create client with env token
         // For HTTP transport, clients are created per-session with user's token
         const baseUrl = this.getBaseUrl();
-        const authConfig = this.profile.interceptors?.auth;
-        const hasAuth = !!authConfig;
-        const envToken = hasAuth ? process.env[authConfig.value_from_env] : undefined;
-        if (hasAuth && envToken) {
+        const envAuthConfig = this.getEnvBackedAuthConfig();
+        const envVarName = envAuthConfig?.value_from_env;
+        const envToken = envVarName ? process.env[envVarName] : undefined;
+        if (envAuthConfig && envToken) {
             // Token available in env - create global client (stdio transport)
             const httpClient = this.httpClientFactory.createGlobalClient({
                 profile: this.profile,
                 baseUrl,
             });
-            this.compositeExecutor = new CompositeExecutor(this.parser, httpClient);
+            this.compositeExecutor = new CompositeExecutor(this.parser, httpClient, this.profile.parameter_aliases);
         }
         else {
             // No env token or no auth - will use per-session clients (HTTP transport)
-            this.compositeExecutor = new CompositeExecutor(this.parser);
+            this.compositeExecutor = new CompositeExecutor(this.parser, undefined, this.profile.parameter_aliases);
         }
         this.logger.info('MCP server initialized', {
             baseUrl,
@@ -119,7 +169,7 @@ export class MCPServer {
      * Why: Prevents sensitive tokens from appearing in logs
      */
     createLoggerWithAuth(authConfig) {
-        const logFormat = process.env.LOG_FORMAT || 'console';
+        const logFormat = process.env.MCP4_LOG_FORMAT || 'console';
         const logLevel = this.logger instanceof ConsoleLogger || this.logger instanceof JsonLogger
             ? this.logger.level
             : undefined;
@@ -131,9 +181,9 @@ export class MCPServer {
      * Check tool name lengths and warn if needed
      */
     checkToolNameLengths() {
-        const maxLength = parseInt(process.env.MCP_TOOLNAME_MAX || '45', 10);
-        const strategy = (process.env.MCP_TOOLNAME_STRATEGY || 'none').toLowerCase();
-        const warnOnly = (process.env.MCP_TOOLNAME_WARN_ONLY || 'true').toLowerCase() === 'true';
+        const maxLength = parseInt(process.env.MCP4_TOOLNAME_MAX || '45', 10);
+        const strategy = (process.env.MCP4_TOOLNAME_STRATEGY || 'none').toLowerCase();
+        const warnOnly = (process.env.MCP4_TOOLNAME_WARN_ONLY || 'true').toLowerCase() === 'true';
         // Only warn if strategy is 'none' or warn-only mode is enabled
         if (strategy !== NamingStrategy.None && !warnOnly) {
             return; // Names already shortened, no need to warn
@@ -148,10 +198,10 @@ export class MCPServer {
         }));
         const warningOptions = {
             maxLength,
-            similarTopN: parseInt(process.env.MCP_TOOLNAME_SIMILAR_TOP || '3', 10),
-            similarityThreshold: parseFloat(process.env.MCP_TOOLNAME_SIMILARITY_THRESHOLD || '0.75'),
-            minParts: parseInt(process.env.MCP_TOOLNAME_MIN_PARTS || '3', 10),
-            minLength: parseInt(process.env.MCP_TOOLNAME_MIN_LENGTH || '20', 10),
+            similarTopN: parseInt(process.env.MCP4_TOOLNAME_SIMILAR_TOP || '3', 10),
+            similarityThreshold: parseFloat(process.env.MCP4_TOOLNAME_SIMILARITY_THRESHOLD || '0.75'),
+            minParts: parseInt(process.env.MCP4_TOOLNAME_MIN_PARTS || '3', 10),
+            minLength: parseInt(process.env.MCP4_TOOLNAME_MIN_LENGTH || '20', 10),
         };
         generateNameWarnings(opsForNaming, warningOptions, this.logger);
     }
@@ -169,17 +219,51 @@ export class MCPServer {
         }
         return this.parser.getBaseUrl();
     }
+    /**
+     * Get auth configurations as array (supports single or multiple auth methods)
+     * Returns array sorted by priority (lower = higher priority)
+     */
+    getAuthConfigs() {
+        const auth = this.profile?.interceptors?.auth;
+        if (!auth)
+            return [];
+        const configs = Array.isArray(auth) ? auth : [auth];
+        // Sort by priority (lower = higher priority)
+        return configs.sort((a, b) => (a.priority || 0) - (b.priority || 0));
+    }
+    /**
+     * Get primary (highest priority) auth configuration
+     */
+    getPrimaryAuthConfig() {
+        const configs = this.getAuthConfigs();
+        return configs[0];
+    }
+    /**
+     * Get highest priority auth configuration that reads token from environment
+     */
+    getEnvBackedAuthConfig() {
+        const configs = this.getAuthConfigs();
+        return configs.find(config => config.type !== 'oauth' && !!config.value_from_env);
+    }
+    /**
+     * Get OAuth configuration from auth configs (if any)
+     */
+    getOAuthConfig() {
+        const configs = this.getAuthConfigs();
+        const oauthConfig = configs.find(c => c.type === 'oauth');
+        return oauthConfig?.oauth_config;
+    }
     /**
      * Get or create HTTP client for session
      */
-    getHttpClientForSession(sessionId) {
+    async getHttpClientForSession(sessionId) {
         if (!sessionId) {
             // Fallback to global client for stdio transport
             if (!this.httpClientFactory.hasGlobalClient()) {
                 const hasHttpTransport = !!this.httpTransport;
                 const transport = hasHttpTransport ? 'http' : 'stdio';
-                const authConfig = this.profile?.interceptors?.auth;
-                const envVarName = authConfig?.value_from_env || 'API_TOKEN';
+                const envAuthConfig = this.getEnvBackedAuthConfig();
+                const envVarName = envAuthConfig?.value_from_env || 'MCP4_API_TOKEN';
                 const hasEnvToken = !!process.env[envVarName];
                 throw new ConfigurationError(`HTTP client not initialized. ` +
                     `Transport: ${transport}, ` +
@@ -194,8 +278,8 @@ export class MCPServer {
         if (!this.profile) {
             throw new ConfigurationError('Profile not initialized. Call initialize() first.');
         }
-        // Get auth token from session
-        const authToken = this.getAuthTokenFromSession(sessionId);
+        // Get auth token from session (ensures token is valid/refreshed)
+        const authToken = await this.getAuthTokenFromSession(sessionId);
         // Create or get session client using factory
         return this.httpClientFactory.getOrCreateSessionClient(sessionId, {
             profile: this.profile,
@@ -205,11 +289,23 @@ export class MCPServer {
     }
     /**
      * Get auth token from HTTP transport session
+     * Ensures token is valid (refreshes if expired) before returning
      */
-    getAuthTokenFromSession(sessionId) {
+    async getAuthTokenFromSession(sessionId) {
+        // Early return if sessionId is missing/empty
+        // Prevents misleading warn logs with empty sessionId
+        if (!sessionId) {
+            return undefined;
+        }
         if (!this.httpTransport) {
             return undefined;
         }
+        // Ensure token is valid (refresh if expired)
+        const isValid = await this.httpTransport.ensureValidSessionToken(sessionId);
+        if (!isValid) {
+            this.logger.warn('Session token validation/refresh failed', { sessionId });
+            // Still return token if available - let the API call fail with proper error
+        }
         // Use public API instead of type casting
         return this.httpTransport.getSessionToken(sessionId);
     }
@@ -238,9 +334,11 @@ export class MCPServer {
                 return { tools };
             }
             catch (err) {
-                this.logger.error('ListTools handler error', err);
+                // Generate correlation ID only on error (lazy)
+                const correlationId = generateCorrelationId();
+                this.logger.error('ListTools handler error', err, { correlationId });
                 // Always return generic error to clients
-                throw new Error('Internal error');
+                throw new Error(`Internal error (correlation ID: ${correlationId})`);
             }
         });
         // Execute tool
@@ -284,9 +382,16 @@ export class MCPServer {
                 };
             }
             catch (err) {
-                this.logger.error('CallTool handler error', err);
-                // Throw generic error for stdio clients
-                throw new Error('Internal error');
+                // Generate correlation ID only on error (lazy)
+                const correlationId = generateCorrelationId();
+                this.logger.error('CallTool handler error', err, {
+                    correlationId,
+                    toolName: request.params.name,
+                    action: request.params.arguments?.action
+                });
+                // Return user-friendly error message with correlation ID
+                const errorMessage = this.formatErrorForClient(err, correlationId);
+                throw new Error(errorMessage);
             }
         });
     }
@@ -338,7 +443,7 @@ export class MCPServer {
             }
         }
         // Execute with session-specific client
-        const httpClient = this.getHttpClientForSession(sessionId);
+        const httpClient = await this.getHttpClientForSession(sessionId);
         const response = await httpClient.request(operation.method, path, {
             params: queryParams,
             body,
@@ -355,6 +460,16 @@ export class MCPServer {
         }
         return result;
     }
+    /**
+     * Encode path segment if it contains special characters (like slashes)
+     *
+     * Why: GitLab and other APIs require path parameters (like project paths)
+     * to be URL-encoded when used in URL path.
+     */
+    encodePathSegment(value) {
+        const val = String(value);
+        return val.includes('/') ? encodeURIComponent(val) : val;
+    }
     /**
      * Resolve path parameters using profile aliases
      *
@@ -366,13 +481,13 @@ export class MCPServer {
         return template.replace(/\{(\w+)\}/g, (_, key) => {
             // Try direct match first
             if (args[key] !== undefined) {
-                return String(args[key]);
+                return this.encodePathSegment(args[key]);
             }
             // Try aliases from profile
             const possibleAliases = aliases[key] || [];
             for (const alias of possibleAliases) {
                 if (args[alias] !== undefined) {
-                    return String(args[alias]);
+                    return this.encodePathSegment(args[alias]);
                 }
             }
             throw new ValidationError(`Missing path parameter: ${key}` +
@@ -449,30 +564,56 @@ export class MCPServer {
      */
     async runHttp(host, port) {
         const { HttpTransport } = await import('./http-transport.js');
+        // Get OAuth config from profile (supports multi-auth)
+        const oauthConfig = this.getOAuthConfig();
+        if (oauthConfig) {
+            this.logger.info('OAuth authentication enabled for HTTP transport');
+        }
+        // Get auth configs for token validation
+        const authConfigs = this.getAuthConfigs();
+        const baseUrl = this.getBaseUrl();
+        // Extract OAuth rate limit from profile (if configured)
+        const oauthAuthConfig = authConfigs.find(c => c.type === 'oauth');
+        const oauthRateLimit = oauthAuthConfig?.oauth_rate_limit;
+        // Extract resource metadata from OpenAPI spec or profile
+        const resourceMetadata = this.parser.getResourceMetadata();
         const config = {
             host,
             port,
-            sessionTimeoutMs: parseInt(process.env.SESSION_TIMEOUT_MS || '1800000', 10),
-            heartbeatEnabled: process.env.HEARTBEAT_ENABLED === 'true',
-            heartbeatIntervalMs: parseInt(process.env.HEARTBEAT_INTERVAL_MS || '30000', 10),
-            metricsEnabled: process.env.METRICS_ENABLED === 'true',
-            metricsPath: process.env.METRICS_PATH || '/metrics',
-            allowedOrigins: process.env.ALLOWED_ORIGINS
-                ? process.env.ALLOWED_ORIGINS.split(',').map(o => o.trim())
+            sessionTimeoutMs: parseInt(process.env.MCP4_SESSION_TIMEOUT_MS || String(TIMEOUTS.SESSION_TIMEOUT_MS), 10),
+            heartbeatEnabled: process.env.MCP4_HEARTBEAT_ENABLED === 'true',
+            heartbeatIntervalMs: parseInt(process.env.MCP4_HEARTBEAT_INTERVAL_MS || String(TIMEOUTS.HEARTBEAT_INTERVAL_MS), 10),
+            metricsEnabled: process.env.MCP4_METRICS_ENABLED === 'true',
+            metricsPath: process.env.MCP4_METRICS_PATH || '/metrics',
+            allowedOrigins: process.env.MCP4_ALLOWED_ORIGINS
+                ? process.env.MCP4_ALLOWED_ORIGINS.split(',').map(o => o.trim())
                 : undefined,
-            rateLimitEnabled: process.env.HTTP_RATE_LIMIT_ENABLED !== 'false', // default: true
-            rateLimitWindowMs: parseInt(process.env.HTTP_RATE_LIMIT_WINDOW_MS || '60000', 10),
-            rateLimitMaxRequests: parseInt(process.env.HTTP_RATE_LIMIT_MAX_REQUESTS || '100', 10),
-            rateLimitMetricsMax: parseInt(process.env.HTTP_RATE_LIMIT_METRICS_MAX || '10', 10),
-            maxTokenLength: process.env.TOKEN_MAX_LENGTH
-                ? parseInt(process.env.TOKEN_MAX_LENGTH, 10)
+            rateLimitEnabled: process.env.MCP4_HTTP_RATE_LIMIT_ENABLED !== 'false', // default: true
+            rateLimitWindowMs: parseInt(process.env.MCP4_HTTP_RATE_LIMIT_WINDOW_MS || String(TIMEOUTS.RATE_LIMIT_WINDOW_MS), 10),
+            rateLimitMaxRequests: parseInt(process.env.MCP4_HTTP_RATE_LIMIT_MAX_REQUESTS || '100', 10),
+            rateLimitMetricsMax: parseInt(process.env.MCP4_HTTP_RATE_LIMIT_METRICS_MAX || '10', 10),
+            // OAuth rate limiting (priority: profile > env vars > defaults)
+            rateLimitOAuthMax: oauthRateLimit?.max_requests
+                || parseInt(process.env.MCP4_OAUTH_RATE_LIMIT_MAX || String(OAUTH_RATE_LIMIT.MAX_REQUESTS), 10),
+            rateLimitOAuthWindowMs: oauthRateLimit?.window_ms
+                || parseInt(process.env.MCP4_OAUTH_RATE_LIMIT_WINDOW_MS || String(OAUTH_RATE_LIMIT.WINDOW_MS), 10),
+            maxTokenLength: process.env.MCP4_TOKEN_MAX_LENGTH
+                ? parseInt(process.env.MCP4_TOKEN_MAX_LENGTH, 10)
                 : undefined, // Uses default from http-transport.ts if undefined
+            oauthConfig, // Pass OAuth config if available
+            baseUrl, // Pass base URL for token validation
+            authConfigs, // Pass auth configs for token validation
+            // OAuth resource metadata (priority: profile > OpenAPI > fallback)
+            resourceName: this.profile?.resource_name || resourceMetadata.name || 'MCP Server',
+            resourceDocumentation: this.profile?.resource_documentation || resourceMetadata.documentation,
+            sslCertFile: process.env.MCP4_SSL_CERT_FILE,
+            sslKeyFile: process.env.MCP4_SSL_KEY_FILE,
         };
-        // Warn if binding to non-localhost without explicit ALLOWED_ORIGINS
+        // Warn if binding to non-localhost without explicit MCP4_ALLOWED_ORIGINS
         const isLocalhost = host === 'localhost' || host === '127.0.0.1' || host === '::1';
         const hasAllowedOrigins = Array.isArray(config.allowedOrigins) && config.allowedOrigins.length > 0;
         if (!isLocalhost && !hasAllowedOrigins) {
-            this.logger.warn('Binding to non-localhost with empty ALLOWED_ORIGINS. Set ALLOWED_ORIGINS or bind to localhost.');
+            this.logger.warn('Binding to non-localhost with empty MCP4_ALLOWED_ORIGINS. Set MCP4_ALLOWED_ORIGINS or bind to localhost.');
         }
         this.httpTransport = new HttpTransport(config, this.logger);
         // Set message handler to process JSON-RPC messages
@@ -502,7 +643,7 @@ export class MCPServer {
         }
         // Handle other JSON-RPC requests
         // (tools/list, prompts/list, etc.)
-        return this.handleOtherRequest(message);
+        return await this.handleOtherRequest(message, sessionId);
     }
     handleInitialize(message, sessionId) {
         const req = message;
@@ -516,6 +657,8 @@ export class MCPServer {
                 tools: {},
             },
         };
+        // OAuth capability is communicated via 401 responses with WWW-Authenticate header
+        // as per MCP Authorization specification
         // Include sessionId if available (for HTTP transport)
         if (sessionId) {
             result.sessionId = sessionId;
@@ -531,6 +674,28 @@ export class MCPServer {
         const params = req.params;
         const toolName = params.name;
         const args = params.arguments;
+        // Check OAuth authentication for tool operations
+        if (this.httpTransport && this.httpTransport.hasOAuthProvider()) {
+            const authToken = await this.getAuthTokenFromSession(sessionId || '');
+            if (!authToken) {
+                // Return OAuth required error with WWW-Authenticate header
+                // This should trigger the OAuth flow in the client
+                const errorResponse = {
+                    jsonrpc: '2.0',
+                    id: req.id,
+                    error: {
+                        code: -32001, // Application error
+                        message: 'Authentication required. Please authorize via OAuth.',
+                        data: {
+                            oauth_required: true,
+                            resource_metadata: `${this.httpTransport.getServerUrl()}/.well-known/oauth-protected-resource/mcp`,
+                            scope: 'api'
+                        }
+                    }
+                };
+                return errorResponse;
+            }
+        }
         try {
             // Find tool definition
             const toolDef = this.profile?.tools.find(t => t.name === toolName);
@@ -540,7 +705,7 @@ export class MCPServer {
             // Execute tool (reuse existing execution logic)
             let result;
             if (toolDef.composite && toolDef.steps) {
-                const httpClient = this.getHttpClientForSession(sessionId);
+                const httpClient = await this.getHttpClientForSession(sessionId);
                 const compositeResult = await this.compositeExecutor.execute(toolDef.steps, args, toolDef.partial_results || false, httpClient);
                 result = {
                     data: compositeResult.data,
@@ -567,25 +732,69 @@ export class MCPServer {
             };
         }
         catch (error) {
-            // Log internal error details, but return generic message to client
+            // Generate correlation ID only on error (lazy)
+            const correlationId = generateCorrelationId();
+            // Log internal error details with correlation ID
             this.logger.error('Tool call error', error, {
+                correlationId,
                 toolName,
                 action: args?.action,
                 resourceType: args?.resource_type,
                 sessionId
             });
+            // Return user-friendly error message with correlation ID
+            const errorMessage = this.formatErrorForClient(error, correlationId);
+            // Map error type to JSON-RPC error code
+            let errorCode = -32603; // Internal error (default)
+            if (error instanceof AuthenticationError) {
+                errorCode = -32001; // Authentication error
+            }
+            else if (error instanceof AuthorizationError) {
+                errorCode = -32002; // Authorization error
+            }
+            else if (error instanceof ValidationError) {
+                errorCode = -32602; // Invalid params
+            }
+            else if (error instanceof RateLimitError) {
+                errorCode = -32003; // Rate limit error
+            }
+            else if (error instanceof OperationNotFoundError) {
+                errorCode = -32601; // Method not found
+            }
             return {
                 jsonrpc: '2.0',
                 id: req.id,
                 error: {
-                    code: -32603,
-                    message: 'Internal error',
+                    code: errorCode,
+                    message: errorMessage,
                 },
             };
         }
     }
-    handleOtherRequest(message) {
+    async handleOtherRequest(message, sessionId) {
         const req = message;
+        // Check OAuth authentication for other operations (like tools/list)
+        if (this.httpTransport && this.httpTransport.hasOAuthProvider()) {
+            const authToken = await this.getAuthTokenFromSession(sessionId || '');
+            if (!authToken) {
+                // Return OAuth required error with WWW-Authenticate header
+                // This should trigger the OAuth flow in the client
+                const errorResponse = {
+                    jsonrpc: '2.0',
+                    id: req.id,
+                    error: {
+                        code: -32001, // Application error
+                        message: 'Authentication required. Please authorize via OAuth.',
+                        data: {
+                            oauth_required: true,
+                            resource_metadata: `${this.httpTransport.getServerUrl()}/.well-known/oauth-protected-resource/mcp`,
+                            scope: 'api'
+                        }
+                    }
+                };
+                return errorResponse;
+            }
+        }
         // Handle tools/list
         if (req.method === 'tools/list') {
             const tools = this.profile?.tools.map(toolDef => this.toolGenerator.generateTool(toolDef)) || [];