mcp-ts-template 2.4.0 → 2.4.2

package/dist/index.js

@@ -29010,7 +29010,7 @@ var require_gaxios = __commonJS((exports) => {
   function hasFetch() {
     return hasWindow() && !!window.fetch;
   }
-  function hasBuffer() {
+  function hasBuffer2() {
     return typeof Buffer !== "undefined";
   }
   function hasHeader(options, header) {
@@ -29236,7 +29236,7 @@ Content-Type: ${partContentType}\r
       const isFormData = typeof FormData === "undefined" ? false : (opts === null || opts === undefined ? undefined : opts.data) instanceof FormData;
       if (is_stream_1.default.readable(opts.data)) {
         opts.body = opts.data;
-      } else if (hasBuffer() && Buffer.isBuffer(opts.data)) {
+      } else if (hasBuffer2() && Buffer.isBuffer(opts.data)) {
         opts.body = opts.data;
         if (!hasHeader(opts, "Content-Type")) {
           opts.headers["Content-Type"] = "application/json";
@@ -117141,7 +117141,7 @@ var z = /* @__PURE__ */ Object.freeze({
 // package.json
 var package_default = {
   name: "mcp-ts-template",
-  version: "2.3.9",
+  version: "2.4.1",
   mcpName: "io.github.cyanheads/mcp-ts-template",
   description: "The definitive, production-grade template for building powerful and scalable Model Context Protocol (MCP) servers with TypeScript, featuring built-in observability (OpenTelemetry), declarative tooling, robust error handling, and a modular, DI-driven architecture.",
   main: "dist/index.js",
@@ -117645,81 +117645,175 @@ var config = parseConfig();
 
 // src/utils/telemetry/instrumentation.ts
 var import_api = __toESM(require_src(), 1);
-var import_auto_instrumentations_node = __toESM(require_src58(), 1);
-var import_exporter_metrics_otlp_http = __toESM(require_src62(), 1);
-var import_exporter_trace_otlp_http = __toESM(require_src63(), 1);
-var import_instrumentation_pino = __toESM(require_src40(), 1);
-var import_resources = __toESM(require_src52(), 1);
-var import_sdk_metrics = __toESM(require_src59(), 1);
-var import_sdk_node = __toESM(require_src83(), 1);
-var import_sdk_trace_node = __toESM(require_src67(), 1);
-var import_incubating = __toESM(require_index_incubating(), 1);
+
+// src/utils/internal/runtime.ts
+var safeHas = (key) => {
+  try {
+    return typeof globalThis[key] !== "undefined";
+  } catch {
+    return false;
+  }
+};
+var isNode = typeof process !== "undefined" && typeof process.versions?.node === "string";
+var hasProcess = typeof process !== "undefined";
+var hasBuffer = typeof Buffer !== "undefined";
+var hasTextEncoder = safeHas("TextEncoder");
+var hasPerformanceNow = typeof globalThis.performance?.now === "function";
+var isWorkerLike = !isNode && typeof globalThis.WorkerGlobalScope !== "undefined";
+var isBrowserLike = !isNode && !isWorkerLike && safeHas("window");
+var runtimeCaps = {
+  isNode,
+  isWorkerLike,
+  isBrowserLike,
+  hasProcess,
+  hasBuffer,
+  hasTextEncoder,
+  hasPerformanceNow
+};
+
+// src/utils/telemetry/instrumentation.ts
 var sdk = null;
 var isOtelInitialized = false;
-if (config.openTelemetry.enabled && !isOtelInitialized) {
-  isOtelInitialized = true;
-  try {
-    const otelLogLevelString = config.openTelemetry.logLevel.toUpperCase();
-    const otelLogLevel = import_api.DiagLogLevel[otelLogLevelString] ?? import_api.DiagLogLevel.INFO;
-    import_api.diag.setLogger(new import_api.DiagConsoleLogger, otelLogLevel);
-    const tracesEndpoint = config.openTelemetry.tracesEndpoint;
-    const metricsEndpoint = config.openTelemetry.metricsEndpoint;
-    if (!tracesEndpoint && !metricsEndpoint) {
-      import_api.diag.warn("OTEL_ENABLED is true, but no OTLP endpoint for traces or metrics is configured. OpenTelemetry will not export any telemetry.");
-    }
-    const resource = import_resources.resourceFromAttributes({
-      [import_incubating.ATTR_SERVICE_NAME]: config.openTelemetry.serviceName,
-      [import_incubating.ATTR_SERVICE_VERSION]: config.openTelemetry.serviceVersion,
-      "deployment.environment.name": config.environment
-    });
-    const spanProcessors = [];
-    if (tracesEndpoint) {
-      import_api.diag.info(`Using OTLP exporter for traces, endpoint: ${tracesEndpoint}`);
-      const traceExporter = new import_exporter_trace_otlp_http.OTLPTraceExporter({ url: tracesEndpoint });
-      spanProcessors.push(new import_sdk_trace_node.BatchSpanProcessor(traceExporter));
-    } else {
-      import_api.diag.info("No OTLP traces endpoint configured. Traces will not be exported.");
-    }
-    const metricReader = metricsEndpoint ? new import_sdk_metrics.PeriodicExportingMetricReader({
-      exporter: new import_exporter_metrics_otlp_http.OTLPMetricExporter({ url: metricsEndpoint }),
-      exportIntervalMillis: 15000
-    }) : undefined;
-    sdk = new import_sdk_node.NodeSDK({
-      resource,
-      spanProcessors,
-      ...metricReader && { metricReader },
-      sampler: new import_sdk_trace_node.TraceIdRatioBasedSampler(config.openTelemetry.samplingRatio),
-      instrumentations: [
-        import_auto_instrumentations_node.getNodeAutoInstrumentations({
-          "@opentelemetry/instrumentation-http": {
-            enabled: true,
-            ignoreIncomingRequestHook: (req) => req.url === "/healthz"
-          },
-          "@opentelemetry/instrumentation-fs": { enabled: false }
-        }),
-        new import_instrumentation_pino.PinoInstrumentation({
-          logHook: (_span, record) => {
-            record["trace_id"] = _span.spanContext().traceId;
-            record["span_id"] = _span.spanContext().spanId;
-          }
-        })
-      ]
-    });
-    sdk.start();
-    import_api.diag.info(`OpenTelemetry initialized for ${config.openTelemetry.serviceName} v${config.openTelemetry.serviceVersion}`);
-  } catch (error) {
-    import_api.diag.error("Error initializing OpenTelemetry", error);
-    sdk = null;
+var initializationPromise = null;
+function canUseNodeSDK() {
+  return runtimeCaps.isNode && typeof process?.versions?.node === "string" && typeof process.env === "object";
+}
+function detectCloudResource() {
+  const attrs = {};
+  if (runtimeCaps.isWorkerLike) {
+    attrs["cloud.provider"] = "cloudflare";
+    attrs["cloud.platform"] = "cloudflare_workers";
+  }
+  if (typeof process !== "undefined" && process.env?.AWS_LAMBDA_FUNCTION_NAME) {
+    attrs["cloud.provider"] = "aws";
+    attrs["cloud.platform"] = "aws_lambda";
+    if (process.env.AWS_REGION) {
+      attrs["cloud.region"] = process.env.AWS_REGION;
+    }
+  }
+  if (typeof process !== "undefined" && (process.env?.FUNCTION_TARGET || process.env?.K_SERVICE)) {
+    attrs["cloud.provider"] = "gcp";
+    attrs["cloud.platform"] = process.env.FUNCTION_TARGET ? "gcp_cloud_functions" : "gcp_cloud_run";
+    if (process.env.GCP_REGION) {
+      attrs["cloud.region"] = process.env.GCP_REGION;
+    }
   }
+  attrs["deployment.environment.name"] = config.environment;
+  return attrs;
 }
-async function shutdownOpenTelemetry() {
-  if (sdk) {
+async function initializeOpenTelemetry() {
+  if (initializationPromise) {
+    return initializationPromise;
+  }
+  if (isOtelInitialized) {
+    return;
+  }
+  initializationPromise = (async () => {
+    if (!config.openTelemetry.enabled) {
+      import_api.diag.info("OpenTelemetry disabled via configuration.");
+      isOtelInitialized = true;
+      return;
+    }
+    if (!canUseNodeSDK()) {
+      import_api.diag.info("NodeSDK unavailable in this runtime. Using lightweight telemetry mode.");
+      isOtelInitialized = true;
+      return;
+    }
+    isOtelInitialized = true;
     try {
-      await sdk.shutdown();
-      import_api.diag.info("OpenTelemetry terminated successfully.");
+      const [
+        { getNodeAutoInstrumentations },
+        { OTLPMetricExporter },
+        { OTLPTraceExporter },
+        { PinoInstrumentation },
+        { resourceFromAttributes },
+        { PeriodicExportingMetricReader },
+        { NodeSDK },
+        { BatchSpanProcessor, TraceIdRatioBasedSampler },
+        { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION }
+      ] = await Promise.all([
+        Promise.resolve().then(() => __toESM(require_src58(), 1)),
+        Promise.resolve().then(() => __toESM(require_src62(), 1)),
+        Promise.resolve().then(() => __toESM(require_src63(), 1)),
+        Promise.resolve().then(() => __toESM(require_src40(), 1)),
+        Promise.resolve().then(() => __toESM(require_src52(), 1)),
+        Promise.resolve().then(() => __toESM(require_src59(), 1)),
+        Promise.resolve().then(() => __toESM(require_src83(), 1)),
+        Promise.resolve().then(() => __toESM(require_src67(), 1)),
+        Promise.resolve().then(() => __toESM(require_index_incubating(), 1))
+      ]);
+      const otelLogLevelString = config.openTelemetry.logLevel.toUpperCase();
+      const otelLogLevel = import_api.DiagLogLevel[otelLogLevelString] ?? import_api.DiagLogLevel.INFO;
+      import_api.diag.setLogger(new import_api.DiagConsoleLogger, otelLogLevel);
+      const tracesEndpoint = config.openTelemetry.tracesEndpoint;
+      const metricsEndpoint = config.openTelemetry.metricsEndpoint;
+      if (!tracesEndpoint && !metricsEndpoint) {
+        import_api.diag.warn("OTEL_ENABLED is true, but no OTLP endpoint for traces or metrics is configured. OpenTelemetry will not export any telemetry.");
+      }
+      const resource = resourceFromAttributes({
+        [ATTR_SERVICE_NAME]: config.openTelemetry.serviceName,
+        [ATTR_SERVICE_VERSION]: config.openTelemetry.serviceVersion,
+        ...detectCloudResource()
+      });
+      const spanProcessors = [];
+      if (tracesEndpoint) {
+        import_api.diag.info(`Using OTLP exporter for traces, endpoint: ${tracesEndpoint}`);
+        const traceExporter = new OTLPTraceExporter({ url: tracesEndpoint });
+        spanProcessors.push(new BatchSpanProcessor(traceExporter));
+      } else {
+        import_api.diag.info("No OTLP traces endpoint configured. Traces will not be exported.");
+      }
+      const metricReader = metricsEndpoint ? new PeriodicExportingMetricReader({
+        exporter: new OTLPMetricExporter({ url: metricsEndpoint }),
+        exportIntervalMillis: 15000
+      }) : undefined;
+      sdk = new NodeSDK({
+        resource,
+        spanProcessors,
+        ...metricReader && { metricReader },
+        sampler: new TraceIdRatioBasedSampler(config.openTelemetry.samplingRatio),
+        instrumentations: [
+          getNodeAutoInstrumentations({
+            "@opentelemetry/instrumentation-http": {
+              enabled: true,
+              ignoreIncomingRequestHook: (req) => req.url === "/healthz"
+            },
+            "@opentelemetry/instrumentation-fs": { enabled: false }
+          }),
+          new PinoInstrumentation({
+            logHook: (_span, record) => {
+              record["trace_id"] = _span.spanContext().traceId;
+              record["span_id"] = _span.spanContext().spanId;
+            }
+          })
+        ]
+      });
+      sdk.start();
+      import_api.diag.info(`OpenTelemetry NodeSDK initialized for ${config.openTelemetry.serviceName} v${config.openTelemetry.serviceVersion}`);
     } catch (error) {
-      import_api.diag.error("Error terminating OpenTelemetry", error);
+      import_api.diag.error("Error initializing OpenTelemetry", error);
+      sdk = null;
+      throw error;
     }
+  })();
+  return initializationPromise;
+}
+async function shutdownOpenTelemetry(timeoutMs = 5000) {
+  if (!sdk) {
+    return;
+  }
+  try {
+    const shutdownPromise = sdk.shutdown();
+    const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("OpenTelemetry SDK shutdown timeout")), timeoutMs));
+    await Promise.race([shutdownPromise, timeoutPromise]);
+    import_api.diag.info("OpenTelemetry SDK terminated successfully.");
+  } catch (error) {
+    import_api.diag.error("Error terminating OpenTelemetry SDK", error);
+    throw error;
+  } finally {
+    sdk = null;
+    isOtelInitialized = false;
+    initializationPromise = null;
   }
 }
 
@@ -117789,6 +117883,26 @@ var requestContextServiceInstance = {
       }
     }
     return context;
+  },
+  withAuthInfo(authInfo, parentContext) {
+    const baseContext = this.createRequestContext({
+      operation: "withAuthInfo",
+      parentContext,
+      additionalContext: {
+        tenantId: authInfo.tenantId
+      }
+    });
+    const authContext2 = {
+      sub: authInfo.subject ?? authInfo.clientId,
+      scopes: authInfo.scopes,
+      clientId: authInfo.clientId,
+      token: authInfo.token,
+      ...authInfo.tenantId ? { tenantId: authInfo.tenantId } : {}
+    };
+    return {
+      ...baseContext,
+      auth: authContext2
+    };
   }
 };
 var requestContextService = requestContextServiceInstance;
@@ -118201,8 +118315,10 @@ class Logger {
   }
   async createPinoLogger(level) {
     const pinoLevel = mcpToPinoLevel[level] || "info";
+    const isTest = config.environment === "testing";
+    const enableTestLogs = process.env.ENABLE_TEST_LOGS === "true";
     const pinoOptions = {
-      level: pinoLevel,
+      level: isTest && !enableTestLogs ? "silent" : pinoLevel,
       base: {
         env: config.environment,
         version: config.mcpServerVersion,
@@ -118220,7 +118336,6 @@ class Logger {
     const { default: path } = await import("path");
     const transports = [];
     const isDevelopment = config.environment === "development";
-    const isTest = config.environment === "testing";
     if (isDevelopment && !isServerless2) {
       try {
         const { createRequire: createRequire2 } = await import("node:module");
@@ -118436,6 +118551,25 @@ class Logger {
 var logger = Logger.getInstance();
 
 // src/utils/internal/error-handler/mappings.ts
+var COMPILED_PATTERN_CACHE = new Map;
+function getCompiledPattern(pattern) {
+  const cacheKey = pattern instanceof RegExp ? pattern.source + pattern.flags : pattern;
+  if (COMPILED_PATTERN_CACHE.has(cacheKey)) {
+    return COMPILED_PATTERN_CACHE.get(cacheKey);
+  }
+  let compiled;
+  if (pattern instanceof RegExp) {
+    let flags = pattern.flags.replace("g", "");
+    if (!flags.includes("i")) {
+      flags += "i";
+    }
+    compiled = new RegExp(pattern.source, flags);
+  } else {
+    compiled = new RegExp(pattern, "i");
+  }
+  COMPILED_PATTERN_CACHE.set(cacheKey, compiled);
+  return compiled;
+}
 var ERROR_TYPE_MAPPINGS = {
   SyntaxError: -32007 /* ValidationError */,
   TypeError: -32007 /* ValidationError */,
@@ -118487,17 +118621,76 @@ var COMMON_ERROR_PATTERNS = [
     errorCode: -32007 /* ValidationError */
   }
 ];
+var COMPILED_ERROR_PATTERNS = COMMON_ERROR_PATTERNS.map((mapping) => ({
+  ...mapping,
+  compiledPattern: getCompiledPattern(mapping.pattern)
+}));
+var PROVIDER_ERROR_PATTERNS = [
+  {
+    pattern: /ThrottlingException|TooManyRequestsException/i,
+    errorCode: -32003 /* RateLimited */
+  },
+  {
+    pattern: /AccessDenied|UnauthorizedOperation/i,
+    errorCode: -32005 /* Forbidden */
+  },
+  {
+    pattern: /ResourceNotFoundException/i,
+    errorCode: -32001 /* NotFound */
+  },
+  { pattern: /status code 401/i, errorCode: -32006 /* Unauthorized */ },
+  { pattern: /status code 403/i, errorCode: -32005 /* Forbidden */ },
+  { pattern: /status code 404/i, errorCode: -32001 /* NotFound */ },
+  { pattern: /status code 409/i, errorCode: -32002 /* Conflict */ },
+  { pattern: /status code 429/i, errorCode: -32003 /* RateLimited */ },
+  {
+    pattern: /status code 5\d\d/i,
+    errorCode: -32000 /* ServiceUnavailable */
+  },
+  {
+    pattern: /ECONNREFUSED|connection refused/i,
+    errorCode: -32000 /* ServiceUnavailable */
+  },
+  {
+    pattern: /ETIMEDOUT|connection timeout/i,
+    errorCode: -32004 /* Timeout */
+  },
+  {
+    pattern: /unique constraint|duplicate key/i,
+    errorCode: -32002 /* Conflict */
+  },
+  {
+    pattern: /foreign key constraint/i,
+    errorCode: -32007 /* ValidationError */
+  },
+  { pattern: /JWT expired/i, errorCode: -32006 /* Unauthorized */ },
+  {
+    pattern: /row level security/i,
+    errorCode: -32005 /* Forbidden */
+  },
+  {
+    pattern: /insufficient_quota|quota exceeded/i,
+    errorCode: -32003 /* RateLimited */
+  },
+  { pattern: /model_not_found/i, errorCode: -32001 /* NotFound */ },
+  {
+    pattern: /context_length_exceeded/i,
+    errorCode: -32007 /* ValidationError */
+  },
+  { pattern: /ENOTFOUND|DNS/i, errorCode: -32000 /* ServiceUnavailable */ },
+  {
+    pattern: /ECONNRESET|connection reset/i,
+    errorCode: -32000 /* ServiceUnavailable */
+  }
+];
+var COMPILED_PROVIDER_PATTERNS = PROVIDER_ERROR_PATTERNS.map((mapping) => ({
+  ...mapping,
+  compiledPattern: getCompiledPattern(mapping.pattern)
+}));
 
 // src/utils/internal/error-handler/helpers.ts
 function createSafeRegex(pattern) {
-  if (pattern instanceof RegExp) {
-    let flags = pattern.flags.replace("g", "");
-    if (!flags.includes("i")) {
-      flags += "i";
-    }
-    return new RegExp(pattern.source, flags);
-  }
-  return new RegExp(pattern, "i");
+  return getCompiledPattern(pattern);
 }
 function getErrorName(error) {
   if (error instanceof Error) {
@@ -118558,6 +118751,61 @@ function getErrorMessage(error) {
     return `Error converting error to string: ${conversionError instanceof Error ? conversionError.message : "Unknown conversion error"}`;
   }
 }
+function extractErrorCauseChain(error, maxDepth = 20) {
+  const chain = [];
+  const seen = new WeakSet;
+  let current = error;
+  let depth = 0;
+  while (current && depth < maxDepth) {
+    if (typeof current === "object" && current !== null) {
+      if (seen.has(current)) {
+        chain.push({
+          name: "CircularReference",
+          message: "Circular reference detected in error cause chain",
+          depth
+        });
+        break;
+      }
+      seen.add(current);
+    }
+    if (current instanceof Error) {
+      const node = {
+        name: current.name,
+        message: current.message,
+        depth,
+        ...current.stack !== undefined ? { stack: current.stack } : {}
+      };
+      if (current instanceof McpError && current.data) {
+        node.data = current.data;
+      }
+      chain.push(node);
+      current = current.cause;
+    } else if (typeof current === "string") {
+      chain.push({
+        name: "StringError",
+        message: current,
+        depth
+      });
+      break;
+    } else {
+      chain.push({
+        name: getErrorName(current),
+        message: getErrorMessage(current),
+        depth
+      });
+      break;
+    }
+    depth++;
+  }
+  if (depth >= maxDepth) {
+    chain.push({
+      name: "MaxDepthExceeded",
+      message: `Error cause chain exceeded maximum depth of ${maxDepth}`,
+      depth
+    });
+  }
+  return chain;
+}
 
 // src/utils/internal/error-handler/errorHandler.ts
 class ErrorHandler {
@@ -118571,9 +118819,13 @@ class ErrorHandler {
     if (mappedFromType) {
       return mappedFromType;
     }
-    for (const mapping of COMMON_ERROR_PATTERNS) {
-      const regex = createSafeRegex(mapping.pattern);
-      if (regex.test(errorMessage) || regex.test(errorName)) {
+    for (const mapping of COMPILED_PROVIDER_PATTERNS) {
+      if (mapping.compiledPattern.test(errorMessage) || mapping.compiledPattern.test(errorName)) {
+        return mapping.errorCode;
+      }
+    }
+    for (const mapping of COMPILED_ERROR_PATTERNS) {
+      if (mapping.compiledPattern.test(errorMessage) || mapping.compiledPattern.test(errorName)) {
         return mapping.errorCode;
       }
     }
@@ -118620,17 +118872,19 @@ class ErrorHandler {
       consolidatedData.originalStack = originalStack;
     }
     const cause = error instanceof Error ? error : undefined;
-    const rootCause = (() => {
-      let current = cause;
-      let depth = 0;
-      while (current && current instanceof Error && current.cause && depth < 5) {
-        current = current.cause;
-        depth += 1;
+    const causeChain = extractErrorCauseChain(error);
+    if (causeChain.length > 0) {
+      const rootCause = causeChain[causeChain.length - 1];
+      if (rootCause) {
+        consolidatedData["rootCause"] = {
+          name: rootCause.name,
+          message: rootCause.message
+        };
       }
-      return current instanceof Error ? { name: current.name, message: current.message } : undefined;
-    })();
-    if (rootCause) {
-      consolidatedData["rootCause"] = rootCause;
+      consolidatedData["causeChain"] = causeChain;
+    }
+    if (context && "metadata" in context && context.metadata && typeof context.metadata === "object" && "breadcrumbs" in context.metadata) {
+      consolidatedData["breadcrumbs"] = context.metadata.breadcrumbs;
     }
     if (error instanceof McpError) {
       loggedErrorCode = error.code;
@@ -118714,32 +118968,119 @@ class ErrorHandler {
       });
     }
   }
-}
-// src/utils/internal/runtime.ts
-var safeHas = (key) => {
-  try {
-    return typeof globalThis[key] !== "undefined";
-  } catch {
-    return false;
+  static async tryAsResult(fn, options) {
+    try {
+      const value = await Promise.resolve(fn());
+      return { ok: true, value };
+    } catch (caughtError) {
+      const error = ErrorHandler.handleError(caughtError, {
+        ...options,
+        rethrow: false
+      });
+      return { ok: false, error };
+    }
   }
-};
-var isNode = typeof process !== "undefined" && typeof process.versions?.node === "string";
-var hasProcess = typeof process !== "undefined";
-var hasBuffer = typeof Buffer !== "undefined";
-var hasTextEncoder = safeHas("TextEncoder");
-var hasPerformanceNow = typeof globalThis.performance?.now === "function";
-var isWorkerLike = !isNode && typeof globalThis.WorkerGlobalScope !== "undefined";
-var isBrowserLike = !isNode && !isWorkerLike && safeHas("window");
-var runtimeCaps = {
-  isNode,
-  isWorkerLike,
-  isBrowserLike,
-  hasProcess,
-  hasBuffer,
-  hasTextEncoder,
-  hasPerformanceNow
-};
-
+  static mapResult(result, fn) {
+    if (result.ok) {
+      try {
+        return { ok: true, value: fn(result.value) };
+      } catch (error) {
+        return {
+          ok: false,
+          error: new McpError(-32603 /* InternalError */, `Error mapping result: ${getErrorMessage(error)}`)
+        };
+      }
+    }
+    return result;
+  }
+  static flatMapResult(result, fn) {
+    if (result.ok) {
+      return fn(result.value);
+    }
+    return result;
+  }
+  static recoverResult(result, fallback) {
+    if (result.ok) {
+      return result.value;
+    }
+    return typeof fallback === "function" ? fallback(result.error) : fallback;
+  }
+  static addBreadcrumb(context, operation, additionalData) {
+    const breadcrumbs = context.metadata?.breadcrumbs || [];
+    breadcrumbs.push({
+      timestamp: new Date().toISOString(),
+      operation,
+      ...additionalData !== undefined ? { context: additionalData } : {}
+    });
+    return {
+      ...context,
+      metadata: {
+        ...context.metadata,
+        breadcrumbs
+      }
+    };
+  }
+  static async tryCatchWithRetry(fn, options, strategy) {
+    let lastError;
+    for (let attempt = 1;attempt <= strategy.maxAttempts; attempt++) {
+      try {
+        return await Promise.resolve(fn());
+      } catch (caughtError) {
+        lastError = caughtError instanceof Error ? caughtError : new Error(String(caughtError));
+        if (attempt < strategy.maxAttempts && strategy.shouldRetry(lastError, attempt)) {
+          const delay = strategy.getRetryDelay(attempt);
+          const retryContext = {
+            ...options.context,
+            requestId: options.context?.requestId || generateUUID(),
+            timestamp: new Date().toISOString(),
+            operation: options.operation,
+            error: lastError.message,
+            attempt
+          };
+          logger.warning(`Retry attempt ${attempt}/${strategy.maxAttempts} after ${delay}ms`, retryContext);
+          strategy.onRetry?.(lastError, attempt);
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        } else {
+          throw ErrorHandler.handleError(lastError, {
+            ...options,
+            rethrow: true,
+            context: {
+              ...options.context,
+              retryAttempts: attempt,
+              finalAttempt: true
+            }
+          });
+        }
+      }
+    }
+    throw ErrorHandler.handleError(lastError, {
+      ...options,
+      rethrow: true
+    });
+  }
+  static createExponentialBackoffStrategy(maxAttempts = 3, baseDelay = 1000, maxDelay = 30000) {
+    return {
+      maxAttempts,
+      shouldRetry: (error) => {
+        if (error instanceof McpError) {
+          const nonRetryableCodes = [
+            -32007 /* ValidationError */,
+            -32006 /* Unauthorized */,
+            -32005 /* Forbidden */,
+            -32001 /* NotFound */
+          ];
+          return !nonRetryableCodes.includes(error.code);
+        }
+        return true;
+      },
+      getRetryDelay: (attemptNumber) => {
+        const exponentialDelay = baseDelay * Math.pow(2, attemptNumber - 1);
+        const jitter = Math.random() * 0.3 * exponentialDelay;
+        return Math.min(exponentialDelay + jitter, maxDelay);
+      }
+    };
+  }
+}
 // src/utils/internal/performance.ts
 var import_api4 = __toESM(require_src(), 1);
 
@@ -125638,52 +125979,196 @@ class SpeechService2 {
 }
 // src/storage/core/StorageService.ts
 var import_tsyringe5 = __toESM(require_cjs3(), 1);
-function requireTenantId(context) {
-  const tenantId = context.tenantId;
-  if (tenantId === undefined || tenantId === null) {
-    throw new McpError(-32603 /* InternalError */, "Tenant ID is required for storage operations but was not found in the request context.", {
-      operation: "StorageService.requireTenantId",
-      requestId: context.requestId
-    });
+
+// src/utils/internal/encoding.ts
+function arrayBufferToBase64(buffer) {
+  if (runtimeCaps.hasBuffer) {
+    return Buffer.from(buffer).toString("base64");
+  } else {
+    let binary = "";
+    const bytes = new Uint8Array(buffer);
+    const len = bytes.byteLength;
+    for (let i = 0;i < len; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
   }
-  if (typeof tenantId !== "string" || tenantId.trim().length === 0) {
-    throw new McpError(-32602 /* InvalidParams */, "Tenant ID cannot be an empty string.", {
-      operation: "StorageService.requireTenantId",
-      requestId: context.requestId,
-      tenantId
-    });
+}
+function stringToBase64(str2) {
+  if (runtimeCaps.hasBuffer) {
+    return Buffer.from(str2, "utf-8").toString("base64");
+  } else {
+    const encoder = new TextEncoder;
+    const bytes = encoder.encode(str2);
+    return arrayBufferToBase64(bytes.buffer);
+  }
+}
+function base64ToString(base642) {
+  if (runtimeCaps.hasBuffer) {
+    return Buffer.from(base642, "base64").toString("utf-8");
+  } else {
+    const decoded = atob(base642);
+    const decoder = new TextDecoder;
+    const bytes = new Uint8Array(decoded.split("").map((c) => c.charCodeAt(0)));
+    return decoder.decode(bytes);
+  }
+}
+
+// src/storage/core/storageValidation.ts
+var MAX_TENANT_ID_LENGTH = 128;
+var MAX_KEY_LENGTH = 1024;
+var MAX_PREFIX_LENGTH = 512;
+var MAX_LIST_LIMIT = 1e4;
+var VALID_TENANT_ID_PATTERN = /^[a-zA-Z0-9]$|^[a-zA-Z0-9][a-zA-Z0-9._-]*[a-zA-Z0-9]$/;
+var VALID_KEY_PATTERN = /^[a-zA-Z0-9_.\-/]+$/;
+function validateTenantId(tenantId, context) {
+  if (typeof tenantId !== "string") {
+    throw new McpError(-32602 /* InvalidParams */, "Tenant ID must be a string.", { ...context, tenantId });
   }
   const trimmedTenantId = tenantId.trim();
-  if (trimmedTenantId.length > 128) {
-    throw new McpError(-32602 /* InvalidParams */, "Tenant ID exceeds maximum length of 128 characters.", {
-      operation: "StorageService.requireTenantId",
-      requestId: context.requestId,
-      tenantIdLength: trimmedTenantId.length
+  if (trimmedTenantId.length === 0) {
+    throw new McpError(-32602 /* InvalidParams */, "Tenant ID cannot be an empty string.", { ...context, tenantId });
+  }
+  if (trimmedTenantId.length > MAX_TENANT_ID_LENGTH) {
+    throw new McpError(-32602 /* InvalidParams */, `Tenant ID exceeds maximum length of ${MAX_TENANT_ID_LENGTH} characters.`, { ...context, tenantIdLength: trimmedTenantId.length });
+  }
+  if (!VALID_TENANT_ID_PATTERN.test(trimmedTenantId)) {
+    throw new McpError(-32602 /* InvalidParams */, "Tenant ID contains invalid characters. Only alphanumeric characters, hyphens, underscores, and dots are allowed. Must start and end with alphanumeric characters.", { ...context, tenantId: trimmedTenantId });
+  }
+  if (trimmedTenantId.includes("..")) {
+    throw new McpError(-32602 /* InvalidParams */, "Tenant ID contains consecutive dots, which are not allowed.", { ...context, tenantId: trimmedTenantId });
+  }
+  if (trimmedTenantId.includes("../") || trimmedTenantId.includes("..\\")) {
+    throw new McpError(-32602 /* InvalidParams */, "Tenant ID contains path traversal sequences, which are not allowed.", { ...context, tenantId: trimmedTenantId });
+  }
+}
+function validateKey(key, context) {
+  if (!key || typeof key !== "string") {
+    throw new McpError(-32007 /* ValidationError */, "Key must be a non-empty string.", { ...context, key });
+  }
+  if (key.length > MAX_KEY_LENGTH) {
+    throw new McpError(-32007 /* ValidationError */, `Key exceeds maximum length of ${MAX_KEY_LENGTH} characters.`, { ...context, key: key.substring(0, 50) + "..." });
+  }
+  if (!VALID_KEY_PATTERN.test(key)) {
+    throw new McpError(-32007 /* ValidationError */, "Key contains invalid characters. Only alphanumeric, hyphens, underscores, dots, and slashes are allowed.", { ...context, key });
+  }
+  if (key.includes("..")) {
+    throw new McpError(-32007 /* ValidationError */, 'Key must not contain ".." (path traversal attempt).', { ...context, key });
+  }
+}
+function validatePrefix(prefix, context) {
+  if (typeof prefix !== "string") {
+    throw new McpError(-32007 /* ValidationError */, "Prefix must be a string.", { ...context, operation: "validatePrefix", prefix });
+  }
+  if (prefix === "") {
+    return;
+  }
+  if (prefix.length > MAX_PREFIX_LENGTH) {
+    throw new McpError(-32007 /* ValidationError */, `Prefix exceeds maximum length of ${MAX_PREFIX_LENGTH} characters.`, {
+      ...context,
+      operation: "validatePrefix",
+      prefix: prefix.substring(0, 50) + "..."
     });
   }
-  const validTenantIdPattern = /^[a-zA-Z0-9]$|^[a-zA-Z0-9][a-zA-Z0-9._-]*[a-zA-Z0-9]$/;
-  if (!validTenantIdPattern.test(trimmedTenantId)) {
-    throw new McpError(-32602 /* InvalidParams */, "Tenant ID contains invalid characters. Only alphanumeric characters, hyphens, underscores, and dots are allowed. Must start and end with alphanumeric characters.", {
-      operation: "StorageService.requireTenantId",
-      requestId: context.requestId,
-      tenantId: trimmedTenantId
+  if (!VALID_KEY_PATTERN.test(prefix)) {
+    throw new McpError(-32007 /* ValidationError */, "Prefix contains invalid characters. Only alphanumeric, hyphens, underscores, dots, and slashes are allowed.", {
+      ...context,
+      operation: "validatePrefix",
+      prefix: prefix.length > 50 ? prefix.substring(0, 50) + "..." : prefix
     });
   }
-  if (trimmedTenantId.includes("../") || trimmedTenantId.includes("..\\")) {
-    throw new McpError(-32602 /* InvalidParams */, "Tenant ID contains path traversal sequences, which are not allowed.", {
-      operation: "StorageService.requireTenantId",
-      requestId: context.requestId,
-      tenantId: trimmedTenantId
+  if (prefix.includes("..")) {
+    throw new McpError(-32007 /* ValidationError */, 'Prefix must not contain ".." (path traversal attempt).', { ...context, operation: "validatePrefix", prefix });
+  }
+}
+function validateStorageOptions(options, context) {
+  if (!options) {
+    return;
+  }
+  if (options.ttl !== undefined) {
+    if (typeof options.ttl !== "number") {
+      throw new McpError(-32007 /* ValidationError */, "TTL must be a number (seconds).", { ...context, ttl: options.ttl });
+    }
+    if (options.ttl < 0) {
+      throw new McpError(-32007 /* ValidationError */, "TTL must be a non-negative number. Use 0 for immediate expiration.", { ...context, ttl: options.ttl });
+    }
+    if (!Number.isFinite(options.ttl)) {
+      throw new McpError(-32007 /* ValidationError */, "TTL must be a finite number.", { ...context, ttl: options.ttl });
+    }
+  }
+}
+function validateListOptions(options, context) {
+  if (!options) {
+    return;
+  }
+  if (options.limit !== undefined) {
+    if (typeof options.limit !== "number") {
+      throw new McpError(-32007 /* ValidationError */, "List limit must be a number.", { ...context, operation: "validateListOptions", limit: options.limit });
+    }
+    if (!Number.isInteger(options.limit)) {
+      throw new McpError(-32007 /* ValidationError */, "List limit must be an integer.", { ...context, operation: "validateListOptions", limit: options.limit });
+    }
+    if (options.limit < 1) {
+      throw new McpError(-32007 /* ValidationError */, "List limit must be at least 1.", { ...context, operation: "validateListOptions", limit: options.limit });
+    }
+    if (options.limit > MAX_LIST_LIMIT) {
+      throw new McpError(-32007 /* ValidationError */, `List limit exceeds maximum of ${MAX_LIST_LIMIT}.`, { ...context, operation: "validateListOptions", limit: options.limit });
+    }
+    if (!Number.isFinite(options.limit)) {
+      throw new McpError(-32007 /* ValidationError */, "List limit must be a finite number.", { ...context, operation: "validateListOptions", limit: options.limit });
+    }
+  }
+  if (options.cursor !== undefined) {
+    if (typeof options.cursor !== "string") {
+      throw new McpError(-32007 /* ValidationError */, "Cursor must be a string.", { ...context, operation: "validateListOptions" });
+    }
+    if (options.cursor.trim() === "") {
+      throw new McpError(-32007 /* ValidationError */, "Cursor must not be an empty string.", { ...context, operation: "validateListOptions" });
+    }
+    if (!/^[A-Za-z0-9+/=]+$/.test(options.cursor)) {
+      throw new McpError(-32007 /* ValidationError */, "Cursor contains invalid characters for base64.", { ...context, operation: "validateListOptions" });
+    }
+  }
+}
+function encodeCursor(lastKey, tenantId) {
+  const data = { k: lastKey, t: tenantId };
+  return stringToBase64(JSON.stringify(data));
+}
+function decodeCursor(cursor, tenantId, context) {
+  try {
+    const decoded = base64ToString(cursor);
+    const data = JSON.parse(decoded);
+    if (!data || typeof data !== "object" || !("k" in data) || !("t" in data)) {
+      throw new McpError(-32602 /* InvalidParams */, "Invalid cursor format.", { ...context, operation: "decodeCursor" });
+    }
+    if (data.t !== tenantId) {
+      throw new McpError(-32602 /* InvalidParams */, "Cursor tenant ID mismatch. Cursor may have been tampered with.", { ...context, operation: "decodeCursor" });
+    }
+    return data.k;
+  } catch (error2) {
+    if (error2 instanceof McpError) {
+      throw error2;
+    }
+    throw new McpError(-32602 /* InvalidParams */, "Failed to decode cursor. Cursor may be corrupted or invalid.", {
+      ...context,
+      operation: "decodeCursor",
+      rawError: error2 instanceof Error ? error2.stack : String(error2)
     });
   }
-  if (trimmedTenantId.includes("..")) {
-    throw new McpError(-32602 /* InvalidParams */, "Tenant ID contains consecutive dots, which are not allowed.", {
-      operation: "StorageService.requireTenantId",
+}
+
+// src/storage/core/StorageService.ts
+function requireTenantId(context) {
+  const tenantId = context.tenantId;
+  if (tenantId === undefined || tenantId === null) {
+    throw new McpError(-32603 /* InternalError */, "Tenant ID is required for storage operations but was not found in the request context.", {
+      operation: context.operation || "StorageService.requireTenantId",
       requestId: context.requestId,
-      tenantId: trimmedTenantId
+      calledFrom: "StorageService"
     });
   }
-  return trimmedTenantId;
+  validateTenantId(tenantId, context);
+  return tenantId.trim();
 }
 
 class StorageService2 {
@@ -125693,34 +126178,103 @@ class StorageService2 {
   }
   get(key, context) {
     const tenantId = requireTenantId(context);
+    validateKey(key, context);
+    logger.debug("[StorageService] get operation", {
+      ...context,
+      operation: "StorageService.get",
+      tenantId,
+      key
+    });
     return this.provider.get(tenantId, key, context);
   }
   set(key, value, context, options) {
     const tenantId = requireTenantId(context);
+    validateKey(key, context);
+    validateStorageOptions(options, context);
+    logger.debug("[StorageService] set operation", {
+      ...context,
+      operation: "StorageService.set",
+      tenantId,
+      key,
+      hasTTL: options?.ttl !== undefined,
+      ttl: options?.ttl
+    });
     return this.provider.set(tenantId, key, value, context, options);
   }
   delete(key, context) {
     const tenantId = requireTenantId(context);
+    validateKey(key, context);
+    logger.debug("[StorageService] delete operation", {
+      ...context,
+      operation: "StorageService.delete",
+      tenantId,
+      key
+    });
     return this.provider.delete(tenantId, key, context);
   }
   list(prefix, context, options) {
     const tenantId = requireTenantId(context);
+    validatePrefix(prefix, context);
+    validateListOptions(options, context);
+    logger.debug("[StorageService] list operation", {
+      ...context,
+      operation: "StorageService.list",
+      tenantId,
+      prefix,
+      limit: options?.limit,
+      hasCursor: !!options?.cursor
+    });
     return this.provider.list(tenantId, prefix, context, options);
   }
   getMany(keys, context) {
     const tenantId = requireTenantId(context);
+    for (const key of keys) {
+      validateKey(key, context);
+    }
+    logger.debug("[StorageService] getMany operation", {
+      ...context,
+      operation: "StorageService.getMany",
+      tenantId,
+      keyCount: keys.length
+    });
     return this.provider.getMany(tenantId, keys, context);
   }
   setMany(entries, context, options) {
     const tenantId = requireTenantId(context);
+    validateStorageOptions(options, context);
+    for (const key of entries.keys()) {
+      validateKey(key, context);
+    }
+    logger.debug("[StorageService] setMany operation", {
+      ...context,
+      operation: "StorageService.setMany",
+      tenantId,
+      entryCount: entries.size,
+      hasTTL: options?.ttl !== undefined,
+      ttl: options?.ttl
+    });
     return this.provider.setMany(tenantId, entries, context, options);
   }
   deleteMany(keys, context) {
     const tenantId = requireTenantId(context);
+    for (const key of keys) {
+      validateKey(key, context);
+    }
+    logger.debug("[StorageService] deleteMany operation", {
+      ...context,
+      operation: "StorageService.deleteMany",
+      tenantId,
+      keyCount: keys.length
+    });
     return this.provider.deleteMany(tenantId, keys, context);
   }
   clear(context) {
     const tenantId = requireTenantId(context);
+    logger.info("[StorageService] clear operation", {
+      ...context,
+      operation: "StorageService.clear",
+      tenantId
+    });
     return this.provider.clear(tenantId, context);
   }
 }
@@ -125779,9 +126333,12 @@ class FileSystemProvider {
     return filePath;
   }
   buildEnvelope(value, options) {
-    const expiresAt = options?.ttl ? Date.now() + options.ttl * 1000 : undefined;
+    const expiresAt = options?.ttl !== undefined ? Date.now() + options.ttl * 1000 : undefined;
     return {
-      __mcp: { v: FILE_ENVELOPE_VERSION, ...expiresAt ? { expiresAt } : {} },
+      __mcp: {
+        v: FILE_ENVELOPE_VERSION,
+        ...expiresAt !== undefined ? { expiresAt } : {}
+      },
       value
     };
   }
@@ -125889,13 +126446,14 @@ class FileSystemProvider {
       const limit2 = options?.limit ?? DEFAULT_LIST_LIMIT;
       let startIndex = 0;
       if (options?.cursor) {
-        const cursorIndex = validKeys.indexOf(options.cursor);
+        const lastKey = decodeCursor(options.cursor, tenantId, context);
+        const cursorIndex = validKeys.indexOf(lastKey);
         if (cursorIndex !== -1) {
           startIndex = cursorIndex + 1;
         }
       }
       const paginatedKeys = validKeys.slice(startIndex, startIndex + limit2);
-      const nextCursor = startIndex + limit2 < validKeys.length ? paginatedKeys[paginatedKeys.length - 1] : undefined;
+      const nextCursor = startIndex + limit2 < validKeys.length && paginatedKeys.length > 0 ? encodeCursor(paginatedKeys[paginatedKeys.length - 1], tenantId) : undefined;
       return {
         keys: paginatedKeys,
         nextCursor
@@ -125908,13 +126466,18 @@ class FileSystemProvider {
   }
   async getMany(tenantId, keys, context) {
     return ErrorHandler.tryCatch(async () => {
+      if (keys.length === 0) {
+        return new Map;
+      }
+      const promises = keys.map((key) => this.get(tenantId, key, context));
+      const values2 = await Promise.all(promises);
       const results = new Map;
-      for (const key of keys) {
-        const value = await this.get(tenantId, key, context);
+      keys.forEach((key, i) => {
+        const value = values2[i];
         if (value !== null) {
           results.set(key, value);
         }
-      }
+      });
       return results;
     }, {
       operation: "FileSystemProvider.getMany",
@@ -125924,9 +126487,11 @@ class FileSystemProvider {
   }
   async setMany(tenantId, entries, context, options) {
     return ErrorHandler.tryCatch(async () => {
-      for (const [key, value] of entries.entries()) {
-        await this.set(tenantId, key, value, context, options);
+      if (entries.size === 0) {
+        return;
       }
+      const promises = Array.from(entries.entries()).map(([key, value]) => this.set(tenantId, key, value, context, options));
+      await Promise.all(promises);
     }, {
       operation: "FileSystemProvider.setMany",
       context,
@@ -125935,14 +126500,12 @@ class FileSystemProvider {
   }
   async deleteMany(tenantId, keys, context) {
     return ErrorHandler.tryCatch(async () => {
-      let deletedCount = 0;
-      for (const key of keys) {
-        const deleted = await this.delete(tenantId, key, context);
-        if (deleted) {
-          deletedCount++;
-        }
+      if (keys.length === 0) {
+        return 0;
       }
-      return deletedCount;
+      const promises = keys.map((key) => this.delete(tenantId, key, context));
+      const results = await Promise.all(promises);
+      return results.filter((deleted) => deleted).length;
     }, {
       operation: "FileSystemProvider.deleteMany",
       context,
@@ -125999,10 +126562,10 @@ class InMemoryProvider {
   set(tenantId, key, value, context, options) {
     logger.debug(`[InMemoryProvider] Setting key: ${key} for tenant: ${tenantId}`, context);
     const tenantStore = this.getTenantStore(tenantId);
-    const expiresAt = options?.ttl ? Date.now() + options.ttl * 1000 : undefined;
+    const expiresAt = options?.ttl !== undefined ? Date.now() + options.ttl * 1000 : undefined;
     tenantStore.set(key, {
       value,
-      ...expiresAt && { expiresAt }
+      ...expiresAt !== undefined && { expiresAt }
     });
     return Promise.resolve();
   }
@@ -126029,44 +126592,54 @@ class InMemoryProvider {
     const limit2 = options?.limit ?? DEFAULT_LIST_LIMIT2;
     let startIndex = 0;
     if (options?.cursor) {
-      const cursorIndex = allKeys.indexOf(options.cursor);
+      const lastKey = decodeCursor(options.cursor, tenantId, context);
+      const cursorIndex = allKeys.indexOf(lastKey);
       if (cursorIndex !== -1) {
         startIndex = cursorIndex + 1;
       }
     }
     const paginatedKeys = allKeys.slice(startIndex, startIndex + limit2);
-    const nextCursor = startIndex + limit2 < allKeys.length ? paginatedKeys[paginatedKeys.length - 1] : undefined;
+    const nextCursor = startIndex + limit2 < allKeys.length && paginatedKeys.length > 0 ? encodeCursor(paginatedKeys[paginatedKeys.length - 1], tenantId) : undefined;
     return Promise.resolve({
       keys: paginatedKeys,
       nextCursor
     });
   }
   async getMany(tenantId, keys, context) {
+    if (keys.length === 0) {
+      return new Map;
+    }
     logger.debug(`[InMemoryProvider] Getting ${keys.length} keys for tenant: ${tenantId}`, context);
+    const promises = keys.map((key) => this.get(tenantId, key, context));
+    const values2 = await Promise.all(promises);
     const results = new Map;
-    for (const key of keys) {
-      const value = await this.get(tenantId, key, context);
+    keys.forEach((key, i) => {
+      const value = values2[i];
       if (value !== null) {
         results.set(key, value);
       }
-    }
+    });
+    logger.debug(`[InMemoryProvider] Retrieved ${results.size}/${keys.length} keys for tenant: ${tenantId}`, context);
     return results;
   }
   async setMany(tenantId, entries, context, options) {
-    logger.debug(`[InMemoryProvider] Setting ${entries.size} keys for tenant: ${tenantId}`, context);
-    for (const [key, value] of entries.entries()) {
-      await this.set(tenantId, key, value, context, options);
+    if (entries.size === 0) {
+      return;
     }
+    logger.debug(`[InMemoryProvider] Setting ${entries.size} keys for tenant: ${tenantId}`, context);
+    const promises = Array.from(entries.entries()).map(([key, value]) => this.set(tenantId, key, value, context, options));
+    await Promise.all(promises);
+    logger.debug(`[InMemoryProvider] Successfully set ${entries.size} keys for tenant: ${tenantId}`, context);
   }
   async deleteMany(tenantId, keys, context) {
-    logger.debug(`[InMemoryProvider] Deleting ${keys.length} keys for tenant: ${tenantId}`, context);
-    let deletedCount = 0;
-    for (const key of keys) {
-      const deleted = await this.delete(tenantId, key, context);
-      if (deleted) {
-        deletedCount++;
-      }
+    if (keys.length === 0) {
+      return 0;
     }
+    logger.debug(`[InMemoryProvider] Deleting ${keys.length} keys for tenant: ${tenantId}`, context);
+    const promises = keys.map((key) => this.delete(tenantId, key, context));
+    const results = await Promise.all(promises);
+    const deletedCount = results.filter((deleted) => deleted).length;
+    logger.debug(`[InMemoryProvider] Deleted ${deletedCount}/${keys.length} keys for tenant: ${tenantId}`, context);
     return deletedCount;
   }
   clear(tenantId, context) {
@@ -126116,7 +126689,7 @@ class SupabaseProvider {
   }
   async set(tenantId, key, value, context, options) {
     return ErrorHandler.tryCatch(async () => {
-      const expires_at = options?.ttl ? new Date(Date.now() + options.ttl * 1000).toISOString() : null;
+      const expires_at = options?.ttl !== undefined ? new Date(Date.now() + options.ttl * 1000).toISOString() : null;
       const { error: error2 } = await this.getClient().from(TABLE_NAME).upsert({
         tenant_id: tenantId,
         key,
@@ -126149,7 +126722,8 @@ class SupabaseProvider {
       const limit2 = options?.limit ?? DEFAULT_LIST_LIMIT3;
       let query = this.getClient().from(TABLE_NAME).select("key").eq("tenant_id", tenantId).like("key", `${prefix}%`).or(`expires_at.is.null,expires_at.gt.${now}`).order("key", { ascending: true }).limit(limit2 + 1);
       if (options?.cursor) {
-        query = query.gt("key", options.cursor);
+        const lastKey = decodeCursor(options.cursor, tenantId, context);
+        query = query.gt("key", lastKey);
       }
       const { data, error: error2 } = await query;
       if (error2)
@@ -126157,7 +126731,7 @@ class SupabaseProvider {
       const keys = data?.map((item) => item.key) ?? [];
       const hasMore = keys.length > limit2;
       const resultKeys = hasMore ? keys.slice(0, limit2) : keys;
-      const nextCursor = hasMore ? resultKeys[resultKeys.length - 1] : undefined;
+      const nextCursor = hasMore && resultKeys.length > 0 ? encodeCursor(resultKeys[resultKeys.length - 1], tenantId) : undefined;
       return {
         keys: resultKeys,
         nextCursor
@@ -126196,7 +126770,7 @@ class SupabaseProvider {
       if (entries.size === 0) {
         return;
       }
-      const expires_at = options?.ttl ? new Date(Date.now() + options.ttl * 1000).toISOString() : null;
+      const expires_at = options?.ttl !== undefined ? new Date(Date.now() + options.ttl * 1000).toISOString() : null;
       const rows = Array.from(entries.entries()).map(([key, value]) => ({
         tenant_id: tenantId,
         key,
@@ -126265,9 +126839,12 @@ class R2Provider {
     return `${tenantId}:${key}`;
   }
   buildEnvelope(value, options) {
-    const expiresAt = options?.ttl ? Date.now() + options.ttl * 1000 : undefined;
+    const expiresAt = options?.ttl !== undefined ? Date.now() + options.ttl * 1000 : undefined;
     return {
-      __mcp: { v: R2_ENVELOPE_VERSION, ...expiresAt ? { expiresAt } : {} },
+      __mcp: {
+        v: R2_ENVELOPE_VERSION,
+        ...expiresAt !== undefined ? { expiresAt } : {}
+      },
       value
     };
   }
@@ -126377,6 +126954,9 @@ class R2Provider {
   }
   async getMany(tenantId, keys, context) {
     return ErrorHandler.tryCatch(async () => {
+      if (keys.length === 0) {
+        return new Map;
+      }
       const results = new Map;
       for (const key of keys) {
         const value = await this.get(tenantId, key, context);
@@ -126393,6 +126973,9 @@ class R2Provider {
   }
   async setMany(tenantId, entries, context, options) {
     return ErrorHandler.tryCatch(async () => {
+      if (entries.size === 0) {
+        return;
+      }
       const promises = Array.from(entries.entries()).map(([key, value]) => this.set(tenantId, key, value, context, options));
       await Promise.all(promises);
     }, {
@@ -126403,6 +126986,9 @@ class R2Provider {
   }
   async deleteMany(tenantId, keys, context) {
     return ErrorHandler.tryCatch(async () => {
+      if (keys.length === 0) {
+        return 0;
+      }
       const promises = keys.map((key) => this.delete(tenantId, key, context));
       const results = await Promise.all(promises);
       return results.filter((deleted) => deleted).length;
@@ -126482,7 +127068,7 @@ class KvProvider {
       });
       const valueToStore = JSON.stringify(value);
       const putOptions = {};
-      if (options?.ttl) {
+      if (options?.ttl !== undefined) {
         putOptions.expirationTtl = options.ttl;
       }
       await this.kv.put(kvKey, valueToStore, putOptions);
@@ -126543,6 +127129,9 @@ class KvProvider {
   }
   async getMany(tenantId, keys, context) {
     return ErrorHandler.tryCatch(async () => {
+      if (keys.length === 0) {
+        return new Map;
+      }
       const results = new Map;
       for (const key of keys) {
         const value = await this.get(tenantId, key, context);
@@ -126559,6 +127148,9 @@ class KvProvider {
   }
   async setMany(tenantId, entries, context, options) {
     return ErrorHandler.tryCatch(async () => {
+      if (entries.size === 0) {
+        return;
+      }
       const promises = Array.from(entries.entries()).map(([key, value]) => this.set(tenantId, key, value, context, options));
       await Promise.all(promises);
     }, {
@@ -126569,6 +127161,9 @@ class KvProvider {
   }
   async deleteMany(tenantId, keys, context) {
     return ErrorHandler.tryCatch(async () => {
+      if (keys.length === 0) {
+        return 0;
+      }
       const promises = keys.map((key) => this.delete(tenantId, key, context));
       const results = await Promise.all(promises);
       return results.filter((deleted) => deleted).length;
@@ -130518,21 +131113,6 @@ var echoTool = {
   responseFormatter: responseFormatter3
 };
 
-// src/utils/internal/encoding.ts
-function arrayBufferToBase64(buffer) {
-  if (runtimeCaps.hasBuffer) {
-    return Buffer.from(buffer).toString("base64");
-  } else {
-    let binary = "";
-    const bytes = new Uint8Array(buffer);
-    const len = bytes.byteLength;
-    for (let i = 0;i < len; i++) {
-      binary += String.fromCharCode(bytes[i]);
-    }
-    return btoa(binary);
-  }
-}
-
 // src/mcp-server/tools/definitions/template-image-test.tool.ts
 var TOOL_NAME4 = "template_image_test";
 var TOOL_TITLE4 = "Template Image Test";
@@ -133589,7 +134169,6 @@ var cors = (options) => {
 
 // src/mcp-server/transports/http/httpTransport.ts
 import http from "http";
-import { randomUUID } from "node:crypto";
 // src/mcp-server/transports/auth/authFactory.ts
 var import_tsyringe16 = __toESM(require_cjs3(), 1);
 
@@ -135373,6 +135952,7 @@ function createAuthStrategy() {
   }
 }
 // src/mcp-server/transports/auth/authMiddleware.ts
+var import_api6 = __toESM(require_src(), 1);
 function createAuthMiddleware(strategy) {
   return async function authMiddleware(c, next) {
     const context = requestContextService.createRequestContext({
@@ -135404,6 +135984,20 @@ function createAuthMiddleware(strategy) {
         scopes: authInfo.scopes
       };
       logger.info("Authentication successful. Auth context populated.", authLogContext);
+      const activeSpan = import_api6.trace.getActiveSpan();
+      if (activeSpan) {
+        activeSpan.setAttributes({
+          "auth.client_id": authInfo.clientId,
+          "auth.tenant_id": authInfo.tenantId ?? "none",
+          "auth.scopes": authInfo.scopes.join(","),
+          "auth.subject": authInfo.subject ?? "unknown",
+          "auth.method": "bearer"
+        });
+        logger.debug("Added auth context to OpenTelemetry span", {
+          ...authLogContext,
+          spanId: activeSpan.spanContext().spanId
+        });
+      }
       await authContext.run({ authInfo }, next);
     } catch (error2) {
       logger.warning("Authentication verification failed.", {
@@ -135516,6 +136110,22 @@ var httpErrorHandler = async (err, c) => {
   return c.json(errorResponse);
 };
 
+// src/mcp-server/transports/http/sessionIdUtils.ts
+import { randomBytes as randomBytes2 } from "crypto";
+function generateSecureSessionId() {
+  if (runtimeCaps.isNode && runtimeCaps.hasBuffer) {
+    const bytes = randomBytes2(32);
+    return bytes.toString("hex");
+  } else {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  }
+}
+function validateSessionIdFormat(sessionId) {
+  return /^[a-f0-9]{64}$/.test(sessionId);
+}
+
 // src/mcp-server/transports/http/sessionStore.ts
 class SessionStore {
   sessions = new Map;
@@ -135525,6 +136135,14 @@ class SessionStore {
     setInterval(() => this.cleanupStaleSessions(), 60000);
   }
   getOrCreate(sessionId, identity) {
+    if (!validateSessionIdFormat(sessionId)) {
+      const context = requestContextService.createRequestContext({
+        operation: "SessionStore.getOrCreate",
+        sessionIdPrefix: sessionId.substring(0, 16)
+      });
+      logger.warning("Invalid session ID format rejected", context);
+      throw new McpError(-32602 /* InvalidParams */, "Invalid session ID format. Session IDs must be 64 hexadecimal characters.", context);
+    }
     let session = this.sessions.get(sessionId);
     if (!session) {
       const newSession = {
@@ -135697,15 +136315,26 @@ function createHttpApp(mcpServer, parentContext) {
   app.get("/healthz", (c) => c.json({ status: "ok" }));
   app.get("/.well-known/oauth-protected-resource", (c) => {
     if (!config.oauthIssuerUrl) {
+      logger.debug("OAuth Protected Resource Metadata requested but OAuth not configured", transportContext);
       return c.json({ error: "OAuth not configured on this server" }, { status: 404 });
     }
-    return c.json({
-      resource: config.mcpServerResourceIdentifier || config.oauthAudience,
+    const origin = new URL(c.req.url).origin;
+    const resourceIdentifier = config.mcpServerResourceIdentifier ?? config.oauthAudience ?? `${origin}/mcp`;
+    const metadata = {
+      resource: resourceIdentifier,
       authorization_servers: [config.oauthIssuerUrl],
       bearer_methods_supported: ["header"],
       resource_signing_alg_values_supported: ["RS256", "ES256", "PS256"],
+      resource_documentation: `${origin}/docs`,
       ...config.oauthJwksUri && { jwks_uri: config.oauthJwksUri }
+    };
+    c.header("Cache-Control", "public, max-age=3600");
+    c.header("Content-Type", "application/json");
+    logger.debug("Serving OAuth Protected Resource Metadata", {
+      ...transportContext,
+      resourceIdentifier
     });
+    return c.json(metadata);
   });
   app.get(config.mcpHttpEndpointPath, (c) => {
     return c.json({
@@ -135770,7 +136399,7 @@ function createHttpApp(mcpServer, parentContext) {
       }, 400);
     }
     const providedSessionId = c.req.header("mcp-session-id");
-    const sessionId = providedSessionId ?? randomUUID();
+    const sessionId = providedSessionId ?? generateSecureSessionId();
     const authStore = authContext.getStore();
     let sessionIdentity;
     if (authStore?.authInfo) {
@@ -136173,6 +136802,11 @@ var start = async () => {
     await shutdownOpenTelemetry();
     process.exit(1);
   }
+  try {
+    await initializeOpenTelemetry();
+  } catch (error2) {
+    console.error("[Startup] Failed to initialize OpenTelemetry:", error2);
+  }
   await initializePerformance_Hrt();
   const validMcpLogLevels = [
     "debug",