@chkp/harmony-email-mcp 0.1.1 → 0.1.4

package/dist/index.js

@@ -365,6 +365,84 @@ var init_ui_dialog = __esm({
   }
 });
 
+// ../mcp-utils/dist/cli-options.js
+function booleanOptionDefault(envValue, optionDefault) {
+  return envValue === "true" || optionDefault === "true";
+}
+function resolveTransportType(transportOption, env = process.env) {
+  return (transportOption || env.MCP_TRANSPORT_TYPE || "stdio").toLowerCase() === "http" ? "http" : "stdio";
+}
+function optionKey(flag) {
+  const long = flag.split(/[,\s]+/).find((part) => part.startsWith("--"));
+  if (!long)
+    return void 0;
+  const negated = long.startsWith("--no-");
+  return {
+    key: long.replace(/^--(no-)?/, "").replace(/-([a-z])/g, (_match, char) => char.toUpperCase()),
+    negated
+  };
+}
+function operatorValues(options, parsed, env = process.env) {
+  const values = { ...env };
+  for (const option of options) {
+    const derived = option.env ? optionKey(option.flag) : void 0;
+    if (!derived || derived.negated)
+      continue;
+    const value = parsed[derived.key];
+    if (value !== void 0)
+      values[option.env] = value;
+  }
+  return values;
+}
+
+// ../mcp-utils/dist/debug-view.js
+import { createHash } from "node:crypto";
+var BUILTIN_LOGGABLE_KEYS = [
+  "accept",
+  "accept-encoding",
+  "accept-language",
+  "connection",
+  "content-length",
+  "content-type",
+  "host",
+  "mcp-protocol-version",
+  "traceparent",
+  "user-agent",
+  "x-correlation-id",
+  "x-gw-auth-method",
+  "x-request-id",
+  // Launcher options
+  "debug",
+  "telemetry",
+  "telemetry-url",
+  "transport",
+  "transport-port"
+];
+function normalizeDebugKey(key) {
+  const split = /[-_]/.test(key) ? key : key.replace(/([a-z][0-9]*)([A-Z])/g, "$1-$2");
+  return split.replace(/_/g, "-").toLowerCase();
+}
+function debugLoggableKeys(extra = []) {
+  return new Set([...BUILTIN_LOGGABLE_KEYS, ...extra].map(normalizeDebugKey));
+}
+function describe(key, value, loggable) {
+  if (value === void 0 || value === null || value === "")
+    return "(unset)";
+  if (loggable.has(normalizeDebugKey(key))) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+  }
+  const text = typeof value === "string" ? value : Array.isArray(value) ? value.join(", ") : void 0;
+  return text === void 0 ? "(hidden)" : `(hidden, ${text.length} chars)`;
+}
+function debugView(record, loggable = debugLoggableKeys()) {
+  return Object.fromEntries(Object.entries(record ?? {}).map(([key, value]) => [key, describe(key, value, loggable)]));
+}
+function sessionLogLabel(sessionId) {
+  if (!sessionId || sessionId === "default")
+    return "default";
+  return `session#${createHash("sha256").update(sessionId).digest("hex").slice(0, 8)}`;
+}
+
 // ../mcp-utils/dist/launcher.js
 import { Command } from "commander";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -373,6 +451,89 @@ import fs from "fs";
 import http from "http";
 import { randomUUID } from "crypto";
 
+// ../mcp-utils/dist/connection-source.js
+function hasValue(value) {
+  return value !== void 0 && value !== null && value !== "" && !(Array.isArray(value) && value.length === 0);
+}
+function headersRead(fromHeaders, headers) {
+  const read = /* @__PURE__ */ new Set();
+  const recording = new Proxy(headers, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof prop === "string" && hasValue(value))
+        read.add(prop);
+      return value;
+    }
+  });
+  try {
+    fromHeaders(recording);
+  } catch {
+  }
+  return read;
+}
+function keySet(keys = []) {
+  return new Set(keys.map(normalizeDebugKey));
+}
+function chooseConnectionSource(read, basicKeys) {
+  for (const key of read) {
+    if (!basicKeys.has(normalizeDebugKey(key)))
+      return "caller";
+  }
+  return "operator";
+}
+function basicOnly(headers, basicKeys) {
+  return Object.fromEntries(Object.entries(headers).filter(([key]) => basicKeys.has(normalizeDebugKey(key))));
+}
+function mergeHeaders(base, overrides) {
+  const merged = {};
+  const index = /* @__PURE__ */ new Map();
+  for (const [key, value] of [...Object.entries(base), ...Object.entries(overrides)]) {
+    const id = normalizeDebugKey(key);
+    const previous = index.get(id);
+    if (previous !== void 0)
+      delete merged[previous];
+    index.set(id, key);
+    merged[key] = value;
+  }
+  return merged;
+}
+function operatorHeaders(values) {
+  const headers = {};
+  for (const [name, value] of Object.entries(values)) {
+    if (!hasValue(value))
+      continue;
+    headers[name.replace(/_/g, "-")] = Array.isArray(value) ? value.map(String) : String(value);
+  }
+  return headers;
+}
+function canonicalizeAliases(headers, aliases) {
+  if (aliases.size === 0)
+    return headers;
+  const canonical = new Set([...aliases.values()].map(normalizeDebugKey));
+  const present = new Set(Object.keys(headers).map(normalizeDebugKey).filter((key) => canonical.has(key)));
+  const result = {};
+  for (const [key, value] of Object.entries(headers)) {
+    const target = aliases.get(normalizeDebugKey(key));
+    if (target === void 0) {
+      result[key] = value;
+    } else if (!present.has(normalizeDebugKey(target))) {
+      result[target] = value;
+      present.add(normalizeDebugKey(target));
+    }
+  }
+  return result;
+}
+function aliasMap(aliases = {}) {
+  return new Map(Object.entries(aliases).map(([alias, target]) => [normalizeDebugKey(alias), target]));
+}
+function sessionHeaders(source, callerHeaders, operator, basicKeys, operatorSettingsOverHttp) {
+  if (source === "caller") {
+    return mergeHeaders(basicOnly(operator, basicKeys), callerHeaders);
+  }
+  const base = operatorSettingsOverHttp ? operator : basicOnly(operator, basicKeys);
+  return mergeHeaders(base, basicOnly(callerHeaders, basicKeys));
+}
+
 // ../mcp-utils/dist/settings-manager.js
 var SettingsManager = class _SettingsManager {
   /**
@@ -382,7 +543,13 @@ var SettingsManager = class _SettingsManager {
   constructor(settingsClass) {
     this.settingsMap = /* @__PURE__ */ new Map();
     this.defaultSessionId = "default";
+    this.operatorValues = {};
+    this.sessionSources = /* @__PURE__ */ new Map();
     this.settingsClass = settingsClass;
+    this.loggableKeys = debugLoggableKeys(settingsClass?.debugLoggableKeys ?? []);
+    this.basicKeys = keySet(settingsClass?.basicKeys ?? []);
+    this.headerAliases = aliasMap(settingsClass?.headerAliases);
+    this.operatorSettingsOverHttp = settingsClass?.operatorSettingsOverHttp !== false;
   }
   /**
    * Get settings for a specific session
@@ -409,12 +576,15 @@ var SettingsManager = class _SettingsManager {
    * Injects debug settings from source into settings object
    * @param settings The settings object to update
    * @param source Source object containing debug information
+   * @param scope 'process' when the operator set debug (CLI/env), which also
+   *   updates the process-wide state; 'session' when a caller set it through a
+   *   header, which affects only that session's settings
    * @private
    */
-  injectDebug(settings, source) {
+  injectDebug(settings, source, scope) {
     const debug = source?.debug ?? _SettingsManager.globalDebugState ?? process.env.DEBUG;
     if (typeof debug !== "undefined") {
-      if (source?.debug !== void 0) {
+      if (scope === "process" && source?.debug !== void 0) {
         _SettingsManager.globalDebugState = source.debug;
       }
       if (typeof settings.set === "function") {
@@ -423,8 +593,8 @@ var SettingsManager = class _SettingsManager {
         settings.debug = debug;
       }
       if (debug) {
-        console.error("Debug enabled. Source object contents:");
-        console.error(JSON.stringify(source, null, 2));
+        console.error("Debug enabled. Source:");
+        this.printDebugView(source);
       }
     }
   }
@@ -437,19 +607,21 @@ var SettingsManager = class _SettingsManager {
     if (typeof settings.get === "function") {
       console.error("Settings (using get method):");
       if (settings.data && typeof settings.data === "object") {
-        Object.entries(settings.data).forEach(([key, value]) => {
-          console.error(`  ${key}: ${JSON.stringify(value)}`);
-        });
+        this.printDebugView(settings.data);
       } else {
         console.error("  Unable to enumerate settings properties - no accessible data structure");
       }
     } else {
       console.error("Settings (plain object):");
-      Object.entries(settings).forEach(([key, value]) => {
-        console.error(`  ${key}: ${JSON.stringify(value)}`);
-      });
+      this.printDebugView(settings);
     }
   }
+  /** Print allowlisted values; everything else as "(hidden, N chars)". */
+  printDebugView(record) {
+    Object.entries(debugView(record, this.loggableKeys)).forEach(([key, value]) => {
+      console.error(`  ${key}: ${value}`);
+    });
+  }
   /**
    * Create settings from command-line arguments
    * @param args Command line arguments
@@ -458,10 +630,19 @@ var SettingsManager = class _SettingsManager {
    */
   createFromArgs(args, sessionId) {
     const settings = this.settingsClass.fromArgs(args);
-    this.injectDebug(settings, args);
+    this.injectDebug(settings, args, "process");
     this.setSettings(settings, sessionId);
     return settings;
   }
+  /**
+   * Record the operator's values (environment variables and parsed CLI
+   * options, keyed by environment-variable name). HTTP sessions take basic
+   * keys from them when the caller doesn't send its own, and their whole
+   * connection set when the caller sends none of it.
+   */
+  setOperatorValues(values) {
+    this.operatorValues = canonicalizeAliases(operatorHeaders(values), this.headerAliases);
+  }
   /**
    * Create settings from HTTP headers
    * @param headers HTTP headers
@@ -471,13 +652,13 @@ var SettingsManager = class _SettingsManager {
   createFromHeaders(headers, sessionId) {
     const verbose = _SettingsManager.globalDebugState;
     if (verbose) {
-      console.error("[SettingsManager.createFromHeaders] Verbose: Starting with sessionId:", sessionId || "(default)");
+      console.error("[SettingsManager.createFromHeaders] Verbose: Starting with session:", sessionLogLabel(sessionId));
       console.error("[SettingsManager.createFromHeaders] Verbose: Incoming headers count:", Object.keys(headers).length);
     }
     if (_SettingsManager.globalDebugState) {
       console.error("=== createFromHeaders Debug Info ===");
       console.error("Incoming headers:");
-      console.error(JSON.stringify(headers, null, 2));
+      this.printDebugView(headers);
     }
     if (verbose && (!headers || Object.keys(headers).length === 0)) {
       console.error("[SettingsManager.createFromHeaders] Verbose: WARNING - Headers object is empty or undefined");
@@ -494,26 +675,32 @@ var SettingsManager = class _SettingsManager {
       console.error("[SettingsManager.createFromHeaders] Verbose: Normalized headers count:", Object.keys(normalizedHeaders).length);
     }
     if (_SettingsManager.globalDebugState) {
-      console.error("Normalized headers:");
-      console.error(JSON.stringify(normalizedHeaders, null, 2));
+      console.error("Normalized header names:", Object.keys(normalizedHeaders));
     }
     const debugHeader = normalizedHeaders["debug"] || normalizedHeaders["Debug"] || normalizedHeaders["DEBUG"];
-    const debugSource = { debug: debugHeader !== void 0 ? debugHeader : _SettingsManager.globalDebugState };
+    const requestedDebug = Array.isArray(debugHeader) ? debugHeader[0] : debugHeader;
+    const debugSource = {
+      debug: requestedDebug !== void 0 ? requestedDebug.toLowerCase() === "true" : _SettingsManager.globalDebugState
+    };
+    const callerHeaders = canonicalizeAliases(normalizedHeaders, this.headerAliases);
+    const source = this.connectionSource(callerHeaders, sessionId);
+    const inputHeaders = sessionHeaders(source, callerHeaders, this.operatorValues, this.basicKeys, this.operatorSettingsOverHttp);
     if (verbose) {
+      console.error("[SettingsManager.createFromHeaders] Verbose: Connection settings source:", source);
       console.error("[SettingsManager.createFromHeaders] Verbose: Calling settingsClass.fromHeaders");
     }
-    const settings = this.settingsClass.fromHeaders(normalizedHeaders);
+    const settings = this.settingsClass.fromHeaders(inputHeaders);
     if (verbose) {
       console.error("[SettingsManager.createFromHeaders] Verbose: Settings object created");
     }
-    this.injectDebug(settings, debugSource);
+    this.injectDebug(settings, debugSource, "session");
     if (_SettingsManager.globalDebugState) {
-      console.error("Final settings object for session:", sessionId || "(default)");
+      console.error("Final settings object for session:", sessionLogLabel(sessionId));
       this.printSettingsDebug(settings);
       console.error("=== End createFromHeaders Debug Info ===");
     }
     if (verbose) {
-      console.error("[SettingsManager.createFromHeaders] Verbose: Storing settings for session:", sessionId || "(default)");
+      console.error("[SettingsManager.createFromHeaders] Verbose: Storing settings for session:", sessionLogLabel(sessionId));
     }
     this.setSettings(settings, sessionId);
     return settings;
@@ -525,14 +712,28 @@ var SettingsManager = class _SettingsManager {
   clearSession(sessionId) {
     if (sessionId !== this.defaultSessionId) {
       this.settingsMap.delete(sessionId);
+      this.sessionSources.delete(sessionId);
     }
   }
+  /**
+   * The session's connection source: decided by the request that creates the
+   * session and kept for its lifetime, so a later request cannot switch it.
+   */
+  connectionSource(headers, sessionId) {
+    const known = sessionId ? this.sessionSources.get(sessionId) : void 0;
+    if (known)
+      return known;
+    const source = chooseConnectionSource(headersRead((h) => this.settingsClass.fromHeaders(h), headers), this.basicKeys);
+    if (sessionId)
+      this.sessionSources.set(sessionId, source);
+    return source;
+  }
 };
 SettingsManager.globalDebugState = void 0;
 
 // ../mcp-utils/dist/telemetry.js
 import machineIdPkg from "node-machine-id";
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 var { machineIdSync } = machineIdPkg;
 var machineId = null;
 var hashedMachineId = null;
@@ -547,7 +748,7 @@ function getTelemetryUrl() {
   return process.env.TELEMETRY_URL || "https://metrics.security.ai.checkpoint.com/api/v1/metrics/collect";
 }
 function hashString(input) {
-  return createHash("sha256").update(input).digest("hex");
+  return createHash2("sha256").update(input).digest("hex");
 }
 function getMachineId() {
   if (!machineId) {
@@ -595,6 +796,21 @@ async function trackToolCall(mcpName, toolName, clientVersion, extra) {
 }
 
 // ../mcp-utils/dist/launcher.js
+function mirrorBooleanFlagsToEnv(config, options) {
+  for (const option of config.options) {
+    if (option.type !== "boolean" || !option.env)
+      continue;
+    const derived = optionKey(option.flag);
+    if (!derived)
+      continue;
+    if (derived.negated) {
+      throw new Error(`Option '${option.flag}' in the configuration for '${config.name}' is a negatable flag paired with env var '${option.env}', which cannot be mirrored automatically: commander keys it as '${derived.key}' and inverts its meaning, so whether the flag being present should set '${option.env}' to 'true' or 'false' depends on how that variable is named. Mirror it explicitly in launchMCPServer instead, the way --no-telemetry does for TELEMETRY_DISABLED.`);
+    }
+    if (options[derived.key] === true) {
+      process.env[option.env] = "true";
+    }
+  }
+}
 async function launchMCPServer(configPath, serverModule2) {
   const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
   const program = new Command();
@@ -605,7 +821,7 @@ async function launchMCPServer(configPath, serverModule2) {
     const envValue = option.env ? process.env[option.env] : void 0;
     const defaultValue = envValue || option.default;
     if (option.type === "boolean") {
-      const boolDefault = envValue === "true" || option.default === "true";
+      const boolDefault = booleanOptionDefault(envValue, option.default);
       program.option(option.flag, option.description, boolDefault);
     } else {
       program.option(option.flag, option.description, defaultValue);
@@ -629,17 +845,24 @@ async function launchMCPServer(configPath, serverModule2) {
   if (options.telemetryUrl) {
     process.env.TELEMETRY_URL = options.telemetryUrl;
   }
+  mirrorBooleanFlagsToEnv(config, options);
+  const transportType2 = resolveTransportType(options.transport);
+  process.env.MCP_TRANSPORT_TYPE = transportType2;
   if (!serverModule2.settingsManager) {
     throw new Error("ServerModule must have a settingsManager. Create it with createServerModule.");
   }
   const settings = serverModule2.settingsManager.createFromArgs(options);
+  serverModule2.settingsManager.setOperatorValues?.(operatorValues(config.options, options));
   if (typeof serverModule2.server.applyToolPolicy === "function") {
     console.error("[launchMCPServer] Applying tool policy before connecting");
     serverModule2.server.applyToolPolicy();
   }
-  const transportType2 = (options.transport || process.env.MCP_TRANSPORT_TYPE || "stdio").toLowerCase() === "http" ? "http" : "stdio";
   const transportPort = options.transportPort ? parseInt(options.transportPort, 10) : process.env.MCP_TRANSPORT_PORT ? parseInt(process.env.MCP_TRANSPORT_PORT, 10) : 3e3;
   if (transportType2 === "http") {
+    const refusal = serverModule2.httpStartupCheck?.();
+    if (refusal) {
+      throw new Error(refusal);
+    }
     setTransportType("http");
     await launchHTTPServer(config, serverModule2, transportPort);
   } else {
@@ -688,7 +911,7 @@ async function launchHTTPServer(config, serverModule2, port) {
           if (sessionId && transports[sessionId]) {
             const verbose = SettingsManager.globalDebugState;
             if (verbose) {
-              console.error("[launchHTTPServer] Verbose: Reusing existing transport for session:", sessionId);
+              console.error("[launchHTTPServer] Verbose: Reusing existing transport for session:", sessionLogLabel(sessionId));
             }
             transport = transports[sessionId];
             if (!serverModule2.settingsManager) {
@@ -708,7 +931,7 @@ async function launchHTTPServer(config, serverModule2, port) {
               onsessioninitialized: (sid) => {
                 const verbose = SettingsManager.globalDebugState;
                 if (verbose) {
-                  console.error("[launchHTTPServer] Verbose: New session initialized:", sid);
+                  console.error("[launchHTTPServer] Verbose: New session initialized:", sessionLogLabel(sid));
                 }
                 transports[sid] = transport;
                 if (verbose) {
@@ -911,7 +1134,6 @@ function headersToEnvVars(headers, config) {
   }
   if (verbose) {
     console.error("[headersToEnvVars] Verbose: Final result keys:", Object.keys(result));
-    console.error("[headersToEnvVars] Verbose: Final result (sanitized):", Object.fromEntries(Object.entries(result).map(([k, v]) => [k, k.toLowerCase().includes("key") || k.toLowerCase().includes("token") || k.toLowerCase().includes("password") ? "***" : v])));
   }
   return result;
 }
@@ -938,7 +1160,7 @@ var APIManagerFactory = class {
     const verbose = SettingsManager.globalDebugState;
     const sid = sessionId || this.defaultSessionId;
     if (verbose) {
-      console.error("[APIManagerFactory.getAPIManager] Verbose: Getting API manager for session:", sid);
+      console.error("[APIManagerFactory.getAPIManager] Verbose: Getting API manager for session:", sessionLogLabel(sid));
     }
     if (!this.apiManagerMap.has(sid)) {
       if (verbose) {
@@ -1036,16 +1258,15 @@ var SessionContext = class {
   /**
    * Get the current session ID from the MCP extra context
    * @param extra Extra context passed to MCP tool callbacks
-   * @returns The session ID or DEFAULT_SESSION_ID if not available
+   * @returns The session ID, or DEFAULT_SESSION_ID under stdio
+   * @throws Under HTTP transport when the context carries no session ID
    */
   static getSessionId(extra) {
-    if (!extra)
-      return this.DEFAULT_SESSION_ID;
-    if (extra.transport && extra.transport.sessionId) {
-      return extra.transport.sessionId;
-    }
-    if (extra.sessionId) {
-      return extra.sessionId;
+    const sessionId = extra?.transport?.sessionId || extra?.sessionId;
+    if (sessionId)
+      return sessionId;
+    if (process.env.MCP_TRANSPORT_TYPE === "http") {
+      throw new Error("No MCP session in this request context; HTTP transport requires one");
     }
     return this.DEFAULT_SESSION_ID;
   }
@@ -1162,10 +1383,10 @@ var SessionContext = class {
           }
         }
       }
-      console.error(`Using cached user data for session: ${sessionId}, key: ${options.cacheKey}`);
+      console.error(`Using cached user data for ${sessionLogLabel(sessionId)}, key: ${options.cacheKey}`);
       return { cancelled: false, data: dataToReturn2 };
     }
-    console.error(`Prompting user for data for session: ${sessionId}, key: ${options.cacheKey}`);
+    console.error(`Prompting user for data for ${sessionLogLabel(sessionId)}, key: ${options.cacheKey}`);
     let result;
     if (options.showLoginDialog) {
       const { showLoginDialog: showLoginDialog2 } = await Promise.resolve().then(() => (init_ui_dialog(), ui_dialog_exports));
@@ -1367,10 +1588,11 @@ function wrapServerWithTracking(server2, createServerFn) {
         newServer[reg.method](...reg.args);
       }
     }
-    if (typeof server2.setToolPolicy === "function" && typeof newServer.setToolPolicy === "function") {
-      const toolPolicy = server2._toolPolicyCallback;
-      if (toolPolicy) {
-        newServer.setToolPolicy(toolPolicy);
+    const toolPolicy = typeof server2.getToolPolicy === "function" ? server2.getToolPolicy() : void 0;
+    if (toolPolicy && typeof newServer.setToolPolicy === "function") {
+      newServer.setToolPolicy(toolPolicy);
+      if (typeof newServer.applyToolPolicy === "function") {
+        newServer.applyToolPolicy();
       }
     }
     return newServer;
@@ -1426,35 +1648,61 @@ var CPMcpServer = class extends McpServer {
     console.error("[CPMcpServer] Setting tool policy callback");
     this.toolPolicyCallback = callback;
   }
+  /**
+   * Get the tool policy callback, if one was set.
+   *
+   * Needed so the policy can be carried onto the per-session server instances
+   * created for HTTP transport. A typed accessor keeps that transfer honest:
+   * callers do not have to reach into the private field, where a misspelling
+   * would go unnoticed by the compiler.
+   */
+  getToolPolicy() {
+    return this.toolPolicyCallback;
+  }
   /**
    * Apply the tool policy by checking all registered tools
    * This should be called after all tools are registered but before connecting
+   *
+   * Per-tool tracing is behind the debug flag. This used to run once per process
+   * on the template server, where a line per tool was a cheap startup banner.
+   * It now also runs per session under HTTP transport, so unconditional tracing
+   * would scale stderr with sessions x tools and bury the summary. The summary
+   * line always prints — it is the fact worth having for every session.
    */
   applyToolPolicy() {
+    const verbose = SettingsManager.globalDebugState === true || SettingsManager.globalDebugState === "true";
     if (!this.toolPolicyCallback) {
-      console.error("[CPMcpServer] No tool policy callback set, allowing all tools");
+      if (verbose) {
+        console.error("[CPMcpServer] No tool policy callback set, allowing all tools");
+      }
       return;
     }
-    console.error("[CPMcpServer] Applying tool policy");
     const registeredTools = this._registeredTools;
     if (!registeredTools || typeof registeredTools !== "object") {
       console.error("[CPMcpServer] No tools registered yet");
       return;
     }
     const toolNames = Object.keys(registeredTools);
-    console.error(`[CPMcpServer] Found ${toolNames.length} registered tools:`, toolNames);
+    if (verbose) {
+      console.error(`[CPMcpServer] Applying tool policy`);
+      console.error(`[CPMcpServer] Found ${toolNames.length} registered tools:`, toolNames);
+    }
     let enabledCount = 0;
     let disabledCount = 0;
     for (const [toolName, tool] of Object.entries(registeredTools)) {
       const isAllowed = this.toolPolicyCallback(toolName);
       if (!isAllowed) {
-        console.error(`[CPMcpServer] Tool '${toolName}' is NOT allowed by policy - disabling`);
+        if (verbose) {
+          console.error(`[CPMcpServer] Tool '${toolName}' is NOT allowed by policy - disabling`);
+        }
         if (typeof tool.disable === "function") {
           tool.disable();
           disabledCount++;
         }
       } else {
-        console.error(`[CPMcpServer] Tool '${toolName}' is allowed by policy`);
+        if (verbose) {
+          console.error(`[CPMcpServer] Tool '${toolName}' is allowed by policy`);
+        }
         enabledCount++;
       }
     }
@@ -1792,7 +2040,7 @@ function unwrapSingleton(data, where) {
 }
 
 // src/core/providers/avanan.ts
-import { createHash as createHash2 } from "node:crypto";
+import { createHash as createHash3 } from "node:crypto";
 var V1_PREFIX = "/v1.0";
 var AUTH_PATH = "/v1.0/auth";
 var REGION_HOSTS = {
@@ -1815,7 +2063,7 @@ function avananSignature(reqId, appId, date, secret, requestPath) {
   if (requestPath !== null) parts.push(requestPath);
   parts.push(secret);
   const base64 = Buffer.from(parts.join(""), "utf8").toString("base64");
-  return createHash2("sha256").update(base64, "utf8").digest("hex");
+  return createHash3("sha256").update(base64, "utf8").digest("hex");
 }
 function formatAvananDate(now) {
   return `${now.toISOString().replace("Z", "")}000`;
@@ -2708,6 +2956,251 @@ function neverReachedUpstream(error) {
   return code !== null && PRE_FLIGHT_ERROR_CODES.has(code);
 }
 
+// src/tools/shared/schemas.ts
+import { z as z2 } from "zod";
+function orNull(value) {
+  return value ?? null;
+}
+function compact(obj) {
+  return Object.fromEntries(
+    Object.entries(obj).filter(
+      ([, value]) => value !== null && value !== void 0
+    )
+  );
+}
+var looseString = z2.unknown().transform((v) => typeof v === "string" ? v : null);
+var looseRecord = z2.unknown().transform(
+  (v) => v !== null && typeof v === "object" && !Array.isArray(v) ? v : null
+);
+var SEVERITY_BY_DIGIT = {
+  "1": "lowest",
+  "2": "low",
+  "3": "medium",
+  "4": "high",
+  "5": "critical"
+};
+function normalizeSeverity(value) {
+  if (typeof value !== "string") return null;
+  return SEVERITY_BY_DIGIT[value] ?? (value || null);
+}
+var eventSchema = z2.object({
+  eventId: z2.unknown(),
+  type: looseString,
+  state: looseString,
+  severity: z2.unknown(),
+  saas: looseString,
+  description: looseString,
+  entityId: looseString,
+  eventCreated: looseString,
+  confidenceIndicator: looseString
+}).passthrough().transform((raw) => ({
+  eventId: typeof raw.eventId === "string" ? raw.eventId : String(raw.eventId ?? ""),
+  type: raw.type,
+  state: raw.state,
+  severity: normalizeSeverity(raw.severity),
+  saas: raw.saas,
+  description: raw.description,
+  entityId: raw.entityId,
+  eventCreated: raw.eventCreated,
+  confidenceIndicator: raw.confidenceIndicator
+}));
+function toEvent(raw) {
+  return eventSchema.parse(raw);
+}
+var sectoolResultSchema = z2.object({
+  entityId: looseString,
+  entityType: looseString,
+  payload: looseRecord,
+  score: looseString,
+  securityResultEntityId: looseString,
+  securityResultEntityType: looseString,
+  statusCode: looseString,
+  statusDescription: looseString,
+  verdict: z2.unknown().transform((v) => typeof v === "string" ? v : "unknown")
+}).passthrough().transform((raw) => ({
+  entityId: raw.entityId,
+  entityType: raw.entityType,
+  payload: raw.payload,
+  score: raw.score,
+  securityResultEntityId: raw.securityResultEntityId,
+  securityResultEntityType: raw.securityResultEntityType,
+  statusCode: raw.statusCode,
+  statusDescription: raw.statusDescription,
+  verdict: raw.verdict
+}));
+var engineResultsSchema = z2.array(sectoolResultSchema).nullish().transform((v) => orNull(v));
+var entitySecurityResultSchema = z2.object({
+  combinedVerdict: looseRecord,
+  ap: engineResultsSchema,
+  dlp: engineResultsSchema,
+  clicktimeProtection: engineResultsSchema,
+  shadowIt: engineResultsSchema,
+  av: engineResultsSchema
+}).passthrough().transform((raw) => ({
+  combinedVerdict: raw.combinedVerdict,
+  ap: raw.ap,
+  dlp: raw.dlp,
+  clicktimeProtection: raw.clicktimeProtection,
+  shadowIt: raw.shadowIt,
+  av: raw.av
+}));
+var entityActionSchema = z2.object({
+  entityActionName: z2.string(),
+  entityActionDate: looseString,
+  entityActionResponseCode: looseString,
+  entityActionResponseText: looseString,
+  entityActionState: looseString
+}).passthrough().transform((raw) => ({
+  entityActionName: raw.entityActionName,
+  entityActionDate: raw.entityActionDate,
+  entityActionResponseCode: raw.entityActionResponseCode,
+  entityActionResponseText: raw.entityActionResponseText,
+  entityActionState: raw.entityActionState
+}));
+var entityInfoSchema = z2.object({
+  entityId: z2.string(),
+  customerId: looseString,
+  saas: looseString,
+  saasEntityType: looseString,
+  entityCreated: looseString,
+  entityUpdated: looseString,
+  entityActionState: looseString
+}).passthrough().transform((raw) => ({
+  entityId: raw.entityId,
+  customerId: raw.customerId,
+  saas: raw.saas,
+  saasEntityType: raw.saasEntityType,
+  entityCreated: raw.entityCreated,
+  entityUpdated: raw.entityUpdated,
+  entityActionState: raw.entityActionState
+}));
+var entitySchema = z2.object({
+  entityInfo: entityInfoSchema,
+  saasInfo: looseRecord,
+  entityPayload: looseRecord,
+  entitySecurityResult: entitySecurityResultSchema.nullish().transform((v) => orNull(v)),
+  entityActions: z2.array(entityActionSchema).nullish(),
+  entityAvailableActions: z2.array(z2.string()).nullish()
+}).passthrough().transform((raw) => ({
+  entityInfo: raw.entityInfo,
+  saasInfo: raw.saasInfo,
+  entityPayload: raw.entityPayload,
+  entitySecurityResult: raw.entitySecurityResult,
+  entityActions: raw.entityActions ?? [],
+  entityAvailableActions: raw.entityAvailableActions ?? []
+}));
+function toEntity(raw) {
+  return entitySchema.parse(raw);
+}
+function toEntitySummary(raw) {
+  const {
+    entityPayload: _payload,
+    saasInfo: _saasInfo,
+    ...rest
+  } = toEntity(raw);
+  return rest;
+}
+var TASK_STATUSES = [
+  "init",
+  "inprogress",
+  "completed",
+  "failed",
+  "stopped",
+  "paused"
+];
+var taskSchema = z2.object({
+  taskId: z2.string(),
+  status: z2.enum(TASK_STATUSES),
+  actor: looseString,
+  startedAt: looseString,
+  finishedAt: looseString
+}).passthrough().transform((raw) => ({
+  taskId: raw.taskId,
+  status: raw.status,
+  actor: raw.actor,
+  startedAt: raw.startedAt,
+  finishedAt: raw.finishedAt
+}));
+function toTask(raw) {
+  return taskSchema.parse(raw);
+}
+var EXCEPTION_TYPES = [
+  "whitelist",
+  "blacklist",
+  "spam_whitelist"
+];
+var AP_EXCEPTION_CRITERIA = [
+  ["senderEmail", "senderEmailMatching"],
+  ["senderName", "senderNameMatching"],
+  ["senderDomain", "senderDomainMatching"],
+  ["senderIp", null],
+  ["senderClientIp", null],
+  ["recipient", "recipientMatching"],
+  ["domain", null],
+  ["linkDomains", "linkDomainMatching"],
+  ["subject", "subjectMatching"],
+  ["attachmentMd5", null]
+];
+var nonEmpty = (v) => typeof v === "string" && v !== "";
+function exceptionIdOf(row) {
+  if (!row || typeof row !== "object" || Array.isArray(row)) return null;
+  const { id, entityId } = row;
+  for (const v of [id, entityId]) {
+    if (nonEmpty(v)) return v;
+    if (typeof v === "number") return String(v);
+  }
+  return null;
+}
+function withExceptionId(raw) {
+  const id = exceptionIdOf(raw);
+  return id === null ? raw : { ...raw, id };
+}
+var apExceptionRowSchema = z2.preprocess(
+  withExceptionId,
+  z2.object({
+    id: z2.string(),
+    comment: looseString,
+    actionNeeded: looseString,
+    ignoringSpfCheck: z2.unknown().transform((v) => {
+      if (typeof v === "boolean") return v;
+      if (v === 1 || v === "true") return true;
+      if (v === 0 || v === "false") return false;
+      return null;
+    }),
+    editedBy: looseString,
+    addedBy: looseString,
+    updateTime: looseString
+  }).passthrough()
+);
+function criteriaOf(row) {
+  const match = {};
+  for (const [field, modeField] of AP_EXCEPTION_CRITERIA) {
+    const value = row[field];
+    if (value === null || value === void 0 || value === "" || Array.isArray(value) && value.length === 0) {
+      continue;
+    }
+    const mode = modeField ? row[modeField] : null;
+    match[field] = {
+      value,
+      matching: typeof mode === "string" ? mode : null
+    };
+  }
+  return match;
+}
+function toApException(raw, type) {
+  const row = apExceptionRowSchema.parse(raw);
+  return {
+    id: row.id,
+    type,
+    match: criteriaOf(row),
+    comment: row.comment,
+    actionNeeded: row.actionNeeded,
+    ignoringSpfCheck: row.ignoringSpfCheck,
+    actor: nonEmpty(row.editedBy) ? row.editedBy : row.addedBy,
+    updatedAt: row.updateTime
+  };
+}
+
 // src/check.ts
 function maskId(value) {
   return value.length <= 8 ? `${value.slice(0, 2)}\u2026` : `${value.slice(0, 6)}\u2026`;
@@ -2732,8 +3225,8 @@ function firstExceptionId(whitelist, blacklist) {
     ["blacklist", blacklist]
   ];
   for (const [excType, rows] of candidates) {
-    const value = rows?.[0]?.id ?? rows?.[0]?.exceptionId;
-    if (typeof value === "string") return [excType, value];
+    const value = exceptionIdOf(rows?.[0]);
+    if (value !== null) return [excType, value];
   }
   return [null, null];
 }
@@ -3061,7 +3554,7 @@ query tools.
 `;
 
 // src/prompts/index.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 
 // src/content/glossary.ts
 var GLOSSARY = {
@@ -3435,7 +3928,7 @@ var GLOSSARY = {
 };
 
 // src/tools/shared/result.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 function jsonResult(payload) {
   return { content: [{ type: "text", text: JSON.stringify(payload) }] };
 }
@@ -3449,7 +3942,7 @@ function errorResult(tool, error) {
       isError: true
     };
   }
-  if (error instanceof z2.ZodError) {
+  if (error instanceof z3.ZodError) {
     const detail = error.issues.map(
       (issue) => `${issue.path.join(".") || "input"}: ${issue.message}`
     ).join("; ");
@@ -3739,7 +4232,7 @@ function registerPrompts(server2) {
     "security_activity_summary",
     ACTIVITY_DESCRIPTION,
     {
-      time_window: z3.string().optional().describe(
+      time_window: z4.string().optional().describe(
         'Rolling window, e.g. "last 24 hours" or "this week".'
       )
     },
@@ -3752,8 +4245,8 @@ function registerPrompts(server2) {
     {
       // Deliberately free-form, so model-invented synonyms ("open",
       // "active") still land on the pending branch.
-      mode: z3.string().optional().describe("pending, resolved, or trend."),
-      time_window: z3.string().optional().describe("Rolling window for the resolved and trend modes.")
+      mode: z4.string().optional().describe("pending, resolved, or trend."),
+      time_window: z4.string().optional().describe("Rolling window for the resolved and trend modes.")
     },
     (args) => promptMessage(
       restoreTemplate(
@@ -3767,7 +4260,7 @@ function registerPrompts(server2) {
     "single_email_investigation",
     SINGLE_DESCRIPTION,
     {
-      entity_id: z3.string().describe("The HEC entity id to investigate.")
+      entity_id: z4.string().describe("The HEC entity id to investigate.")
     },
     (args) => promptMessage(singleTemplate(args.entity_id ?? ""))
   );
@@ -3854,48 +4347,19 @@ function firstOf(...values) {
   return values.find((v) => v !== void 0 && v !== "");
 }
 var Settings = class _Settings {
+  // Takes only what it is given; fromArgs reads the environment.
   constructor({
-    domain = firstOf(
-      process.env.HEC_DOMAIN,
-      process.env.SMARTAPI_MCP_DOMAIN
-    ),
-    clientId = firstOf(
-      process.env.HEC_CLIENT_ID,
-      process.env.SMARTAPI_MCP_CLIENT_ID
-    ),
-    secret = firstOf(
-      process.env.HEC_SECRET,
-      process.env.SMARTAPI_MCP_SECRET
-    ),
-    authMethod = firstOf(
-      process.env.HEC_AUTH_METHOD,
-      process.env.SMARTAPI_MCP_AUTH_METHOD
-    ),
-    region = firstOf(
-      process.env.HEC_REGION,
-      process.env.SMARTAPI_MCP_REGION
-    ),
-    scope = firstOf(process.env.HEC_SCOPE, process.env.SMARTAPI_MCP_SCOPE),
-    requestTimeout = firstOf(
-      process.env.HEC_REQUEST_TIMEOUT,
-      process.env.SMARTAPI_MCP_REQUEST_TIMEOUT
-    ),
-    maxRetries = firstOf(
-      process.env.HEC_MAX_RETRIES,
-      process.env.SMARTAPI_MCP_MAX_RETRIES
-    ),
-    retryBaseSeconds = firstOf(
-      process.env.HEC_RETRY_BASE_SECONDS,
-      process.env.SMARTAPI_MCP_RETRY_BASE_SECONDS
-    ),
-    maxConcurrency = firstOf(
-      process.env.HEC_MAX_CONCURRENCY,
-      process.env.SMARTAPI_MCP_MAX_CONCURRENCY
-    ),
-    actionBatchLimit = firstOf(
-      process.env.HEC_ACTION_BATCH_LIMIT,
-      process.env.SMARTAPI_MCP_ACTION_BATCH_LIMIT
-    )
+    domain,
+    clientId,
+    secret,
+    authMethod,
+    region,
+    scope,
+    requestTimeout,
+    maxRetries,
+    retryBaseSeconds,
+    maxConcurrency,
+    actionBatchLimit
   } = {}) {
     this.domain = "";
     this.clientId = "";
@@ -3920,6 +4384,67 @@ var Settings = class _Settings {
       "actionBatchLimit"
     );
   }
+  static {
+    /**
+     * Keys whose values debug output may print (see debugView in mcp-utils).
+     * Anything not listed, including every credential, is shown hidden.
+     * Lists both the header/CLI names (hec-*) and the property names.
+     */
+    this.debugLoggableKeys = [
+      "hec-domain",
+      "domain",
+      "hec-region",
+      "region",
+      "hec-scope",
+      "scope",
+      "hec-auth-method",
+      "auth-method",
+      "hec-request-timeout",
+      "request-timeout",
+      "hec-max-retries",
+      "max-retries",
+      "hec-retry-base-seconds",
+      "retry-base-seconds",
+      "hec-max-concurrency",
+      "max-concurrency",
+      "hec-action-batch-limit",
+      "action-batch-limit"
+    ];
+  }
+  static {
+    /**
+     * Headers an HTTP session may mix with the operator's values (see
+     * connection-source in mcp-utils): the numeric tunables, which are
+     * deployment-wide rather than per tenant, under both spellings.
+     */
+    this.basicKeys = [
+      "HEC-REQUEST-TIMEOUT",
+      "HEC-MAX-RETRIES",
+      "HEC-RETRY-BASE-SECONDS",
+      "HEC-MAX-CONCURRENCY",
+      "HEC-ACTION-BATCH-LIMIT"
+    ];
+  }
+  static {
+    /**
+     * The Python server's names for the tunables (alias -> canonical), so a
+     * caller's SMARTAPI-MCP-* header overrides the operator's HEC_* value.
+     */
+    this.headerAliases = {
+      "SMARTAPI-MCP-REQUEST-TIMEOUT": "HEC-REQUEST-TIMEOUT",
+      "SMARTAPI-MCP-MAX-RETRIES": "HEC-MAX-RETRIES",
+      "SMARTAPI-MCP-RETRY-BASE-SECONDS": "HEC-RETRY-BASE-SECONDS",
+      "SMARTAPI-MCP-MAX-CONCURRENCY": "HEC-MAX-CONCURRENCY",
+      "SMARTAPI-MCP-ACTION-BATCH-LIMIT": "HEC-ACTION-BATCH-LIMIT"
+    };
+  }
+  static {
+    /**
+     * An HTTP session never uses the operator's tenant: a client must not be
+     * able to act as whichever tenant the operator configured.
+     */
+    this.operatorSettingsOverHttp = false;
+  }
   /**
    * Under HTTP transport credentials arrive per request as headers, so the
    * process starts with none and validating at boot would be wrong.
@@ -3936,30 +4461,27 @@ var Settings = class _Settings {
     return true;
   }
   static fromArgs(options) {
+    const env = process.env;
     return new _Settings({
-      domain: options.hecDomain,
-      clientId: options.hecClientId,
-      secret: options.hecSecret,
-      authMethod: options.hecAuthMethod,
-      region: options.hecRegion,
-      scope: options.hecScope,
-      requestTimeout: options.hecRequestTimeout,
-      maxRetries: options.hecMaxRetries,
-      retryBaseSeconds: options.hecRetryBaseSeconds,
-      maxConcurrency: options.hecMaxConcurrency,
-      actionBatchLimit: options.hecActionBatchLimit
+      domain: options.hecDomain ?? firstOf(env.HEC_DOMAIN, env.SMARTAPI_MCP_DOMAIN),
+      clientId: options.hecClientId ?? firstOf(env.HEC_CLIENT_ID, env.SMARTAPI_MCP_CLIENT_ID),
+      secret: options.hecSecret ?? firstOf(env.HEC_SECRET, env.SMARTAPI_MCP_SECRET),
+      authMethod: options.hecAuthMethod ?? firstOf(env.HEC_AUTH_METHOD, env.SMARTAPI_MCP_AUTH_METHOD),
+      region: options.hecRegion ?? firstOf(env.HEC_REGION, env.SMARTAPI_MCP_REGION),
+      scope: options.hecScope ?? firstOf(env.HEC_SCOPE, env.SMARTAPI_MCP_SCOPE),
+      requestTimeout: options.hecRequestTimeout ?? firstOf(env.HEC_REQUEST_TIMEOUT, env.SMARTAPI_MCP_REQUEST_TIMEOUT),
+      maxRetries: options.hecMaxRetries ?? firstOf(env.HEC_MAX_RETRIES, env.SMARTAPI_MCP_MAX_RETRIES),
+      retryBaseSeconds: options.hecRetryBaseSeconds ?? firstOf(env.HEC_RETRY_BASE_SECONDS, env.SMARTAPI_MCP_RETRY_BASE_SECONDS),
+      maxConcurrency: options.hecMaxConcurrency ?? firstOf(env.HEC_MAX_CONCURRENCY, env.SMARTAPI_MCP_MAX_CONCURRENCY),
+      actionBatchLimit: options.hecActionBatchLimit ?? firstOf(env.HEC_ACTION_BATCH_LIMIT, env.SMARTAPI_MCP_ACTION_BATCH_LIMIT)
     });
   }
   /**
-   * Per-request settings, built from headers alone.
-   *
-   * Every tenant-scoped field is passed as an explicit empty string when its
-   * header is absent, because `undefined` would hand the field back to the
-   * constructor's env default. Under HTTP transport that would let a request
-   * with no credentials inherit the server process's own tenant and act as
-   * it, so the empty string is what makes a header-less request fail closed.
-   * The numeric tunables are deployment-wide, not per tenant, so they keep
-   * their defaults.
+   * Per-request settings, built from headers alone. A missing tenant-scoped
+   * header leaves its field empty, so a request without credentials fails
+   * closed. The numeric tunables are deployment-wide, not per tenant: they
+   * are basic keys, so the operator's values apply when the caller sends
+   * none.
    */
   static fromHeaders(headers) {
     return new _Settings({
@@ -3969,11 +4491,26 @@ var Settings = class _Settings {
       authMethod: getHeaderValue(headers, "HEC-AUTH-METHOD") ?? "",
       region: getHeaderValue(headers, "HEC-REGION") ?? "",
       scope: getHeaderValue(headers, "HEC-SCOPE") ?? "",
-      requestTimeout: getHeaderValue(headers, "HEC-REQUEST-TIMEOUT"),
-      maxRetries: getHeaderValue(headers, "HEC-MAX-RETRIES"),
-      retryBaseSeconds: getHeaderValue(headers, "HEC-RETRY-BASE-SECONDS"),
-      maxConcurrency: getHeaderValue(headers, "HEC-MAX-CONCURRENCY"),
-      actionBatchLimit: getHeaderValue(headers, "HEC-ACTION-BATCH-LIMIT")
+      requestTimeout: firstOf(
+        getHeaderValue(headers, "HEC-REQUEST-TIMEOUT"),
+        getHeaderValue(headers, "SMARTAPI-MCP-REQUEST-TIMEOUT")
+      ),
+      maxRetries: firstOf(
+        getHeaderValue(headers, "HEC-MAX-RETRIES"),
+        getHeaderValue(headers, "SMARTAPI-MCP-MAX-RETRIES")
+      ),
+      retryBaseSeconds: firstOf(
+        getHeaderValue(headers, "HEC-RETRY-BASE-SECONDS"),
+        getHeaderValue(headers, "SMARTAPI-MCP-RETRY-BASE-SECONDS")
+      ),
+      maxConcurrency: firstOf(
+        getHeaderValue(headers, "HEC-MAX-CONCURRENCY"),
+        getHeaderValue(headers, "SMARTAPI-MCP-MAX-CONCURRENCY")
+      ),
+      actionBatchLimit: firstOf(
+        getHeaderValue(headers, "HEC-ACTION-BATCH-LIMIT"),
+        getHeaderValue(headers, "SMARTAPI-MCP-ACTION-BATCH-LIMIT")
+      )
     });
   }
 };
@@ -3981,198 +4518,6 @@ var Settings = class _Settings {
 // src/tools/actions.ts
 import { z as z5 } from "zod";
 
-// src/tools/shared/schemas.ts
-import { z as z4 } from "zod";
-function orNull(value) {
-  return value ?? null;
-}
-function compact(obj) {
-  return Object.fromEntries(
-    Object.entries(obj).filter(
-      ([, value]) => value !== null && value !== void 0
-    )
-  );
-}
-var looseString = z4.unknown().transform((v) => typeof v === "string" ? v : null);
-var looseRecord = z4.unknown().transform(
-  (v) => v !== null && typeof v === "object" && !Array.isArray(v) ? v : null
-);
-var SEVERITY_BY_DIGIT = {
-  "1": "lowest",
-  "2": "low",
-  "3": "medium",
-  "4": "high",
-  "5": "critical"
-};
-function normalizeSeverity(value) {
-  if (typeof value !== "string") return null;
-  return SEVERITY_BY_DIGIT[value] ?? (value || null);
-}
-var eventSchema = z4.object({
-  eventId: z4.unknown(),
-  type: looseString,
-  state: looseString,
-  severity: z4.unknown(),
-  saas: looseString,
-  description: looseString,
-  entityId: looseString,
-  eventCreated: looseString,
-  confidenceIndicator: looseString
-}).passthrough().transform((raw) => ({
-  eventId: typeof raw.eventId === "string" ? raw.eventId : String(raw.eventId ?? ""),
-  type: raw.type,
-  state: raw.state,
-  severity: normalizeSeverity(raw.severity),
-  saas: raw.saas,
-  description: raw.description,
-  entityId: raw.entityId,
-  eventCreated: raw.eventCreated,
-  confidenceIndicator: raw.confidenceIndicator
-}));
-function toEvent(raw) {
-  return eventSchema.parse(raw);
-}
-var sectoolResultSchema = z4.object({
-  entityId: looseString,
-  entityType: looseString,
-  payload: looseRecord,
-  score: looseString,
-  securityResultEntityId: looseString,
-  securityResultEntityType: looseString,
-  statusCode: looseString,
-  statusDescription: looseString,
-  verdict: z4.unknown().transform((v) => typeof v === "string" ? v : "unknown")
-}).passthrough().transform((raw) => ({
-  entityId: raw.entityId,
-  entityType: raw.entityType,
-  payload: raw.payload,
-  score: raw.score,
-  securityResultEntityId: raw.securityResultEntityId,
-  securityResultEntityType: raw.securityResultEntityType,
-  statusCode: raw.statusCode,
-  statusDescription: raw.statusDescription,
-  verdict: raw.verdict
-}));
-var engineResultsSchema = z4.array(sectoolResultSchema).nullish().transform((v) => orNull(v));
-var entitySecurityResultSchema = z4.object({
-  combinedVerdict: looseRecord,
-  ap: engineResultsSchema,
-  dlp: engineResultsSchema,
-  clicktimeProtection: engineResultsSchema,
-  shadowIt: engineResultsSchema,
-  av: engineResultsSchema
-}).passthrough().transform((raw) => ({
-  combinedVerdict: raw.combinedVerdict,
-  ap: raw.ap,
-  dlp: raw.dlp,
-  clicktimeProtection: raw.clicktimeProtection,
-  shadowIt: raw.shadowIt,
-  av: raw.av
-}));
-var entityActionSchema = z4.object({
-  entityActionName: z4.string(),
-  entityActionDate: looseString,
-  entityActionResponseCode: looseString,
-  entityActionResponseText: looseString,
-  entityActionState: looseString
-}).passthrough().transform((raw) => ({
-  entityActionName: raw.entityActionName,
-  entityActionDate: raw.entityActionDate,
-  entityActionResponseCode: raw.entityActionResponseCode,
-  entityActionResponseText: raw.entityActionResponseText,
-  entityActionState: raw.entityActionState
-}));
-var entityInfoSchema = z4.object({
-  entityId: z4.string(),
-  customerId: looseString,
-  saas: looseString,
-  saasEntityType: looseString,
-  entityCreated: looseString,
-  entityUpdated: looseString,
-  entityActionState: looseString
-}).passthrough().transform((raw) => ({
-  entityId: raw.entityId,
-  customerId: raw.customerId,
-  saas: raw.saas,
-  saasEntityType: raw.saasEntityType,
-  entityCreated: raw.entityCreated,
-  entityUpdated: raw.entityUpdated,
-  entityActionState: raw.entityActionState
-}));
-var entitySchema = z4.object({
-  entityInfo: entityInfoSchema,
-  saasInfo: looseRecord,
-  entityPayload: looseRecord,
-  entitySecurityResult: entitySecurityResultSchema.nullish().transform((v) => orNull(v)),
-  entityActions: z4.array(entityActionSchema).nullish(),
-  entityAvailableActions: z4.array(z4.string()).nullish()
-}).passthrough().transform((raw) => ({
-  entityInfo: raw.entityInfo,
-  saasInfo: raw.saasInfo,
-  entityPayload: raw.entityPayload,
-  entitySecurityResult: raw.entitySecurityResult,
-  entityActions: raw.entityActions ?? [],
-  entityAvailableActions: raw.entityAvailableActions ?? []
-}));
-function toEntity(raw) {
-  return entitySchema.parse(raw);
-}
-function toEntitySummary(raw) {
-  const {
-    entityPayload: _payload,
-    saasInfo: _saasInfo,
-    ...rest
-  } = toEntity(raw);
-  return rest;
-}
-var TASK_STATUSES = [
-  "init",
-  "inprogress",
-  "completed",
-  "failed",
-  "stopped",
-  "paused"
-];
-var taskSchema = z4.object({
-  taskId: z4.string(),
-  status: z4.enum(TASK_STATUSES),
-  actor: looseString,
-  startedAt: looseString,
-  finishedAt: looseString
-}).passthrough().transform((raw) => ({
-  taskId: raw.taskId,
-  status: raw.status,
-  actor: raw.actor,
-  startedAt: raw.startedAt,
-  finishedAt: raw.finishedAt
-}));
-function toTask(raw) {
-  return taskSchema.parse(raw);
-}
-var EXCEPTION_TYPES = [
-  "whitelist",
-  "blacklist",
-  "spam_whitelist"
-];
-var apExceptionSchema = z4.object({
-  id: z4.string(),
-  type: z4.enum(EXCEPTION_TYPES).nullish().transform((v) => orNull(v)),
-  value: looseString,
-  actor: looseString,
-  createdAt: looseString,
-  updatedAt: looseString
-}).passthrough().transform((raw) => ({
-  id: raw.id,
-  type: raw.type,
-  value: raw.value,
-  actor: raw.actor,
-  createdAt: raw.createdAt,
-  updatedAt: raw.updatedAt
-}));
-function toApException(raw) {
-  return apExceptionSchema.parse(raw);
-}
-
 // src/tools/shared/session.ts
 function apiFor(serverModule2, extra) {
   return SessionContext.getAPIManager(
@@ -5241,6 +5586,7 @@ WHEN TO USE:
 PURPOSE:
 - \`whitelist\` always allows, \`blacklist\` always blocks, \`spam_whitelist\` allows through the spam filter only
 - Each entry can match by sender email, domain or IP, recipient, subject, link domain, or attachment hash
+- Each entry returns \`id\`, \`type\`, \`match\` (only the criteria that are set, each as {value, matching}; matching is exact, contains, endswith...), \`comment\`, \`actionNeeded\` (the verdict the entry applies, e.g. phishing), \`ignoringSpfCheck\`, \`actor\` (who last edited it) and \`updatedAt\`
 - Read-only`;
 var GET_DESCRIPTION = `Fetch one Anti-Phishing exception entry by id.
 
@@ -5248,7 +5594,8 @@ WHEN TO USE:
 - Drilling into a specific entry surfaced by \`list_ap_exceptions\`
 
 PURPOSE:
-- \`exc_id\` is the entry id from \`list_ap_exceptions\`; \`exc_type\` must match the list it came from
+- \`exc_id\` is the entry \`id\` from \`list_ap_exceptions\`; \`exc_type\` must match the list it came from
+- Returns the same fields as a \`list_ap_exceptions\` entry
 - Read-only`;
 var excTypeSchema = z11.enum(EXCEPTION_TYPES).describe(
   "Which exception list to read: whitelist, blacklist or spam_whitelist."
@@ -5266,7 +5613,11 @@ function registerExceptionTools(server2, serverModule2) {
         args.exc_type,
         args.scope
       );
-      return { exceptions: rows.map(toApException) };
+      return {
+        exceptions: rows.map(
+          (row) => toApException(row, args.exc_type)
+        )
+      };
     })
   );
   registerTool(
@@ -5285,7 +5636,8 @@ function registerExceptionTools(server2, serverModule2) {
           args.exc_type,
           args.exc_id,
           args.scope
-        )
+        ),
+        args.exc_type
       );
     })
   );