@yawlabs/caddy-mcp 2.5.2 → 2.5.4

package/dist/index.js

@@ -14,6 +14,7 @@ var RETRY_MAX_DELAY_MS = 2e3;
 var RETRY_MAX_JITTER_MS = 50;
 var RETRY_HARD_CAP = 5;
 var ADMIN_RESTART_SETTLE_MS = 250;
+var LOAD_TIMEOUT = 55e3;
 var etagCache = /* @__PURE__ */ new Map();
 var MAX_ETAG_CACHE = 256;
 function setEtag(path, etag) {
@@ -23,6 +24,54 @@ function setEtag(path, etag) {
   }
   etagCache.set(path, etag);
 }
+var GO_WHITESPACE = /* @__PURE__ */ new Set([
+  9,
+  10,
+  11,
+  12,
+  13,
+  32,
+  133,
+  160,
+  5760,
+  8192,
+  8193,
+  8194,
+  8195,
+  8196,
+  8197,
+  8198,
+  8199,
+  8200,
+  8201,
+  8202,
+  8232,
+  8233,
+  8239,
+  8287,
+  12288
+]);
+function goFields(text) {
+  const fields = [];
+  let current = "";
+  for (const ch of text) {
+    if (GO_WHITESPACE.has(ch.codePointAt(0))) {
+      if (current) fields.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  if (current) fields.push(current);
+  return fields;
+}
+function isEchoableEtag(etag) {
+  const decoded = Buffer.from(etag, "latin1").toString("utf8");
+  if (decoded.length < 2 || !decoded.startsWith('"') || !decoded.endsWith('"')) return false;
+  const inner = decoded.slice(1, -1);
+  const fields = goFields(inner);
+  return fields.length === 2 && fields.join(" ") === inner;
+}
 function isAncestorOf(ancestor, descendant) {
   const base = ancestor.endsWith("/") ? ancestor.slice(0, -1) : ancestor;
   return descendant.startsWith(`${base}/`);
@@ -108,25 +157,36 @@ function sleep(ms) {
 function isTransientFailure(res) {
   if (res.ok) return false;
   if (res.status === 0) return true;
-  if (res.status >= 500 && res.status <= 599) return true;
-  return false;
+  return res.status === 502 || res.status === 503 || res.status === 504;
 }
 function isMissingConfigPath(res) {
   if (res.ok) return false;
   return (res.error ?? "").toLowerCase().includes("invalid traversal path");
 }
-var ARRAY_INDEX_TAIL_RE = /\/\d+$/;
+var ARRAY_INDEX_TAIL_RE = /\/\d+(\/+\.\.\.)?\/*$/;
+var BARE_ID_RE = /^\/id\/[^/]+(\/+\.\.\.)?\/*$/;
+function isConfigChange(method, path) {
+  if (method === "GET") return false;
+  return path === "/load" || path.startsWith("/config/") || path.startsWith("/id/");
+}
 function isRetryableMethod(method, path) {
-  if (method === "PUT") return !ARRAY_INDEX_TAIL_RE.test(path);
+  if (method === "PUT" && BARE_ID_RE.test(path)) return false;
+  if (method === "PUT" || method === "DELETE") return !ARRAY_INDEX_TAIL_RE.test(path);
   if (method !== "POST") return true;
   return !path.startsWith("/config/") && !path.startsWith("/id/");
 }
+function shouldRetry(method, path, attempt) {
+  if (!isTransientFailure(attempt.res)) return false;
+  if (attempt.refused) return true;
+  if (attempt.timedOut && isConfigChange(method, path)) return false;
+  return isRetryableMethod(method, path);
+}
 function getMalformedUnixUrl() {
   const raw = (process.env.CADDY_ADMIN_URL || "").trim();
   if (!raw || !/^unix[:/]/i.test(raw)) return void 0;
   return getUnixSocketPath() === void 0 ? raw : void 0;
 }
-async function caddyRequest(method, path, body, contentType, timeout, rawStringBody = false) {
+async function caddyRequest(method, path, body, contentType, rawStringBody = false) {
   const malformed = getMalformedUnixUrl();
   if (malformed) {
     return {
@@ -136,16 +196,16 @@ async function caddyRequest(method, path, body, contentType, timeout, rawStringB
     };
   }
   const maxRetries = getMaxRetries();
-  let attempt = 0;
-  let { res, refused } = await attemptRequest(method, path, body, contentType, timeout, rawStringBody);
-  while (isTransientFailure(res) && (refused || isRetryableMethod(method, path)) && attempt < maxRetries) {
-    attempt++;
-    const backoff = Math.min(RETRY_BASE_MS * 2 ** (attempt - 1), RETRY_MAX_DELAY_MS);
+  let retries = 0;
+  let attempt = await attemptRequest(method, path, body, contentType, rawStringBody);
+  while (retries < maxRetries && shouldRetry(method, path, attempt)) {
+    retries++;
+    const backoff = Math.min(RETRY_BASE_MS * 2 ** (retries - 1), RETRY_MAX_DELAY_MS);
     const delay = backoff + Math.random() * RETRY_MAX_JITTER_MS;
     await sleep(delay);
-    ({ res, refused } = await attemptRequest(method, path, body, contentType, timeout, rawStringBody));
+    attempt = await attemptRequest(method, path, body, contentType, rawStringBody);
   }
-  return res;
+  return attempt.res;
 }
 function isConnectionRefused(err) {
   let current = err;
@@ -159,27 +219,44 @@ function isConnectionRefused(err) {
   }
   return false;
 }
+function isTimeoutError(err) {
+  let current = err;
+  for (let depth = 0; depth < 5 && current !== null && typeof current === "object"; depth++) {
+    const e = current;
+    if (e.name === "TimeoutError" || e.name === "AbortError") return true;
+    current = e.cause;
+  }
+  return false;
+}
 function sendViaUnixSocket(socketPath, path, method, headers, body, timeoutMs) {
   return new Promise((resolve, reject) => {
-    const req = httpRequest(
-      { socketPath, path, method, headers, agent: false, signal: AbortSignal.timeout(timeoutMs) },
-      (res) => {
-        const chunks = [];
-        res.on("data", (chunk) => chunks.push(chunk));
-        res.on("error", reject);
-        res.on("end", () => {
-          const status = res.statusCode ?? 0;
-          const etag = res.headers.etag;
-          resolve({
-            ok: status >= 200 && status < 300,
-            status,
-            text: Buffer.concat(chunks).toString("utf8"),
-            etag: typeof etag === "string" ? etag : void 0
-          });
+    let deadlineHit = false;
+    const deadline = Object.assign(new Error(`timed out after ${timeoutMs}ms`), { name: "TimeoutError" });
+    function fail(err) {
+      clearTimeout(timer);
+      reject(deadlineHit ? deadline : err);
+    }
+    const req = httpRequest({ socketPath, path, method, headers, agent: false }, (res) => {
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("error", fail);
+      res.on("end", () => {
+        clearTimeout(timer);
+        const status = res.statusCode ?? 0;
+        const etag = res.headers.etag;
+        resolve({
+          ok: status >= 200 && status < 300,
+          status,
+          text: Buffer.concat(chunks).toString("utf8"),
+          etag: typeof etag === "string" ? etag : void 0
         });
-      }
-    );
-    req.on("error", reject);
+      });
+    });
+    const timer = setTimeout(() => {
+      deadlineHit = true;
+      req.destroy(deadline);
+    }, timeoutMs);
+    req.on("error", fail);
     if (body !== void 0) req.write(body);
     req.end();
   });
@@ -238,19 +315,65 @@ function settleAdminRestart(origin) {
     socketWaiters.add(check);
   });
 }
-function isConfigChange(method, path) {
-  if (method === "GET") return false;
-  return path === "/load" || path.startsWith("/config/") || path.startsWith("/id/");
+function endOfFirstJsonValue(text) {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') inString = true;
+    else if (ch === "[" || ch === "{") depth++;
+    else if (ch === "]" || ch === "}") {
+      depth--;
+      if (depth <= 0) return depth === 0 ? i + 1 : -1;
+    }
+  }
+  return -1;
+}
+function parseJsonOrUndefined(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
 }
-async function attemptRequest(method, path, body, contentType, timeout, rawStringBody = false) {
-  const transport = { refused: false };
-  const res = await sendOnce(transport, method, path, body, contentType, timeout, rawStringBody);
-  return { res, refused: transport.refused };
+function readLoadBody(text) {
+  const body = text.trim();
+  if (body.startsWith("[")) {
+    const end = endOfFirstJsonValue(body);
+    if (end === -1) return void 0;
+    const warnings = parseJsonOrUndefined(body.slice(0, end));
+    if (!Array.isArray(warnings)) return void 0;
+    const tail = body.slice(end).trim();
+    if (!tail) return { warnings };
+    const trailing = parseJsonOrUndefined(tail);
+    if (trailing === null || typeof trailing !== "object" || Array.isArray(trailing)) return void 0;
+    if (typeof trailing.error !== "string") return void 0;
+    return { warnings, errorText: tail };
+  }
+  if (body.startsWith("{")) {
+    const parsed = parseJsonOrUndefined(body);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return void 0;
+    const warnings = parsed.warnings;
+    if (Array.isArray(warnings) && Object.keys(parsed).length === 1) return { warnings };
+  }
+  return void 0;
 }
-async function sendOnce(transport, method, path, body, contentType, timeout, rawStringBody = false) {
+async function attemptRequest(method, path, body, contentType, rawStringBody = false) {
+  const transport = { refused: false, timedOut: false };
+  const res = await sendOnce(transport, method, path, body, contentType, rawStringBody);
+  return { res, refused: transport.refused, timedOut: transport.timedOut };
+}
+async function sendOnce(transport, method, path, body, contentType, rawStringBody = false) {
   const socketPath = getUnixSocketPath();
   const url = `${getBaseUrl()}${path}`;
-  const effectiveTimeout = timeout ?? getRequestTimeout();
+  const effectiveTimeout = getTimeoutFor(method, path);
   try {
     const hasBody = body !== void 0;
     const headers = getHeaders(hasBody ? contentType || "application/json" : void 0, socketPath !== void 0);
@@ -262,11 +385,21 @@ async function sendOnce(transport, method, path, body, contentType, timeout, raw
     }
     const serializedBody = hasBody ? rawStringBody && typeof body === "string" ? body : JSON.stringify(body) : void 0;
     const res = socketPath ? await sendViaUnixSocket(socketPath, path, method, headers, serializedBody, effectiveTimeout) : await sendViaFetch(url, method, headers, serializedBody, effectiveTimeout);
+    const loadBody = path === "/load" && res.ok ? readLoadBody(res.text) : void 0;
+    if (loadBody?.errorText !== void 0) {
+      return {
+        ok: false,
+        status: res.status,
+        error: `${loadBody.errorText} -- Caddy answered HTTP ${res.status}, but the response body carries this load error after its config-adapter warnings, so caddy-mcp reports the load as failed. Caddy writes the warnings before it runs the load, which fixes the status at 200 whatever the load then does (caddyserver/caddy#7246); without warnings it answers the same failure with 400. Re-read the config to confirm what is running.`,
+        warnings: loadBody.warnings
+      };
+    }
     if (!socketPath && res.ok && isConfigChange(method, path)) await settleAdminRestart(getAdminOrigin());
     const text = res.text;
     const etag = res.etag;
     if (method === "GET" && etag && isConfigPath) {
-      setEtag(path, etag);
+      if (isEchoableEtag(etag)) setEtag(path, etag);
+      else etagCache.delete(path);
     }
     if (isWrite && res.ok && isConfigPath) {
       invalidateRelated(path);
@@ -298,6 +431,7 @@ async function sendOnce(transport, method, path, body, contentType, timeout, raw
       return { ok: false, status: res.status, error: text };
     }
     if (!text) return { ok: true, status: res.status, etag };
+    if (loadBody) return { ok: true, status: res.status, warnings: loadBody.warnings, etag };
     try {
       return { ok: true, status: res.status, data: JSON.parse(text), etag };
     } catch {
@@ -327,8 +461,16 @@ async function sendOnce(transport, method, path, body, contentType, timeout, raw
         error: `Cannot connect to Caddy admin API at ${target} \u2014 is Caddy running?`
       };
     }
-    if (msg.includes("abort") || msg.includes("timeout")) {
-      return { ok: false, status: 0, error: `Request timed out after ${effectiveTimeout}ms` };
+    if (isTimeoutError(err) || msg.includes("abort") || msg.includes("timeout") || msg.includes("timed out")) {
+      transport.timedOut = true;
+      const timedOutMsg = `Request timed out after ${effectiveTimeout}ms`;
+      if (!isConfigChange(method, path)) return { ok: false, status: 0, error: timedOutMsg };
+      return {
+        ok: false,
+        status: 0,
+        outcomeUnknown: true,
+        error: `${timedOutMsg} -- the outcome is unknown: Caddy may still be applying this change. A config change blocks until Caddy finishes reloading, and a client timeout does not cancel it, so it may have applied, may yet apply, or may not apply at all; caddy-mcp never replays a timed-out config change. Re-read the config before retrying. If reloads on this instance legitimately take this long, raise CADDY_LOAD_TIMEOUT, keeping it below your MCP client's request timeout (60 s by default in the MCP SDK), or this error never reaches the client.`
+      };
     }
     return { ok: false, status: 0, error: msg };
   }
@@ -374,20 +516,23 @@ function getRequestTimeout() {
 }
 function getLoadTimeout() {
   const raw = process.env.CADDY_LOAD_TIMEOUT;
-  if (raw === void 0) return 6e4;
+  if (raw === void 0) return LOAD_TIMEOUT;
   const n = Number(raw);
-  if (!Number.isFinite(n)) return 6e4;
+  if (!Number.isFinite(n)) return LOAD_TIMEOUT;
   const floored = Math.floor(n);
-  if (floored < 1) return 6e4;
+  if (floored < 1) return LOAD_TIMEOUT;
   return floored;
 }
+function getTimeoutFor(method, path) {
+  return isConfigChange(method, path) ? getLoadTimeout() : getRequestTimeout();
+}
 async function loadConfig(config, contentType) {
-  const res = await caddyRequest("POST", "/load", config, contentType, getLoadTimeout(), true);
+  const res = await caddyRequest("POST", "/load", config, contentType, true);
   if (res.ok) etagCache.clear();
   return res;
 }
 function adapt(config, adapter = "caddyfile") {
-  return caddyRequest("POST", "/adapt", config, `text/${adapter}`, void 0, true);
+  return caddyRequest("POST", "/adapt", config, `text/${adapter}`, true);
 }
 function stop() {
   return caddyRequest("POST", "/stop");
@@ -441,28 +586,132 @@ function getMetrics() {
 import { z } from "zod";
 
 // src/format.ts
+var WARNING_KEYS = /* @__PURE__ */ new Set(["file", "line", "directive", "message"]);
+function formatWarning(w) {
+  const asJson = () => `  - ${JSON.stringify(w)}`;
+  if (w === null || typeof w !== "object" || Array.isArray(w)) return asJson();
+  const obj = w;
+  if (Object.keys(obj).some((key) => !WARNING_KEYS.has(key))) return asJson();
+  const { file, line, directive, message } = obj;
+  if (typeof message !== "string" || message === "") return asJson();
+  if (file !== void 0 && typeof file !== "string") return asJson();
+  if (line !== void 0 && typeof line !== "number") return asJson();
+  if (directive !== void 0 && typeof directive !== "string") return asJson();
+  const where = file && line !== void 0 ? `${file}:${line}` : file || (line !== void 0 ? `line ${line}` : "");
+  const prefix = [where, directive ? `(${directive})` : ""].filter(Boolean).join(" ");
+  return `  - ${prefix ? `${prefix}: ` : ""}${message}`;
+}
+function formatWarnings(warnings) {
+  if (!warnings || warnings.length === 0) return "";
+  return `
+
+Adapter warnings (${warnings.length}):
+${warnings.map(formatWarning).join("\n")}`;
+}
 function formatResult(res) {
+  const warnings = formatWarnings(res.warnings);
   if (!res.ok) {
     return {
       isError: true,
-      content: [{ type: "text", text: `Error: ${res.error || `HTTP ${res.status}`}` }]
+      content: [{ type: "text", text: `Error: ${res.error || `HTTP ${res.status}`}${warnings}` }]
     };
   }
   const raw = res.data !== void 0 ? typeof res.data === "string" ? res.data : JSON.stringify(res.data, null, 2) : "";
   const text = raw || "OK";
-  return { content: [{ type: "text", text }] };
+  return { content: [{ type: "text", text: `${text}${warnings}` }] };
 }
 
 // src/tools/operational.ts
-var HTTPS_PORT_RE = /:443(?:\D|$)/;
-function describeServer(rawValue) {
+var DEFAULT_HTTP_PORT = 80;
+var DEFAULT_HTTPS_PORT = 443;
+function appPort(value, fallback) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 && value <= 65535 ? value : fallback;
+}
+function splitPort(hostport) {
+  const i = hostport.lastIndexOf(":");
+  if (i < 0) return void 0;
+  if (hostport.startsWith("[")) {
+    const end = hostport.indexOf("]");
+    if (end < 0 || end + 1 !== i) return void 0;
+    if (hostport.slice(1).includes("[") || hostport.slice(end + 1).includes("]")) return void 0;
+  } else {
+    if (hostport.slice(0, i).includes(":")) return void 0;
+    if (hostport.includes("[") || hostport.includes("]")) return void 0;
+  }
+  return hostport.slice(i + 1);
+}
+function parseListenPortRange(entry) {
+  let rest = entry;
+  const slash = entry.indexOf("/");
+  if (slash >= 0) {
+    const network = entry.slice(0, slash).trim().toLowerCase();
+    rest = entry.slice(slash + 1);
+    if (network.startsWith("unix") || network.startsWith("fd")) return { start: 0, end: 0 };
+  }
+  const port = splitPort(rest);
+  if (port === void 0 || port === "") return { start: 0, end: 0 };
+  const dash = port.indexOf("-");
+  const start = parseUint16(dash < 0 ? port : port.slice(0, dash));
+  const end = parseUint16(dash < 0 ? port : port.slice(dash + 1));
+  if (start === void 0 || end === void 0 || end < start) return void 0;
+  return { start, end };
+}
+function parseUint16(s) {
+  if (!/^[0-9]+$/.test(s)) return void 0;
+  const n = Number(s);
+  return n <= 65535 ? n : void 0;
+}
+function hasQualifyingHost(routes, skip) {
+  for (const route of routes) {
+    if (!route || typeof route !== "object") continue;
+    const matcherSets = route.match;
+    if (!Array.isArray(matcherSets)) continue;
+    for (const set of matcherSets) {
+      if (!set || typeof set !== "object") continue;
+      const hosts = set.host;
+      if (!Array.isArray(hosts)) continue;
+      for (const host of hosts) {
+        if (typeof host === "string" && !skip.has(host)) return true;
+      }
+    }
+  }
+  return false;
+}
+function describeServer(rawValue, httpPort = DEFAULT_HTTP_PORT, httpsPort = DEFAULT_HTTPS_PORT) {
   const raw = rawValue !== null && typeof rawValue === "object" && !Array.isArray(rawValue) ? rawValue : {};
   const listen = Array.isArray(raw.listen) ? raw.listen : [];
   const routes = Array.isArray(raw.routes) ? raw.routes : [];
+  const ranges = [];
+  for (const entry of listen) {
+    if (typeof entry !== "string") continue;
+    const range = parseListenPortRange(entry);
+    if (range) ranges.push(range);
+  }
+  const usesAnyPortOtherThan = (port) => ranges.some((r) => port > r.end || port < r.start);
+  const bindsPort = (port) => ranges.some((r) => r.start <= port && port <= r.end);
+  const autoHttps = raw.automatic_https !== null && typeof raw.automatic_https === "object" && !Array.isArray(raw.automatic_https) ? raw.automatic_https : {};
+  const skip = new Set(
+    Array.isArray(autoHttps.skip) ? autoHttps.skip.filter((s) => typeof s === "string") : []
+  );
+  const allSocketsOnHttpPort = (port) => ranges.length > 0 && ranges.every((r) => r.start === port && r.end === port);
+  const perListener = (label) => allSocketsOnHttpPort(httpPort) ? "enabled (no listener gets TLS: all are on the HTTP port)" : bindsPort(httpPort) ? "mixed (TLS on non-HTTP listeners only)" : label;
   const tlsPolicies = raw.tls_connection_policies;
-  const hasExplicitTls = Array.isArray(tlsPolicies) ? tlsPolicies.length > 0 : !!tlsPolicies;
-  const listensHttps = listen.some((l) => typeof l === "string" && HTTPS_PORT_RE.test(l));
-  const tls = hasExplicitTls ? "enabled" : listensHttps ? "auto (HTTPS)" : "off (HTTP only)";
+  let tls;
+  if (Array.isArray(tlsPolicies) && tlsPolicies.length === 0) {
+    tls = "off (empty tls_connection_policies)";
+  } else if (tlsPolicies) {
+    tls = perListener("enabled");
+  } else if (autoHttps.disable === true) {
+    tls = "off (automatic HTTPS disabled)";
+  } else if (!usesAnyPortOtherThan(httpPort)) {
+    tls = "off (HTTP only)";
+  } else if (!usesAnyPortOtherThan(httpsPort)) {
+    tls = perListener("auto (HTTPS)");
+  } else if (hasQualifyingHost(routes, skip)) {
+    tls = perListener("auto (HTTPS: host matchers on a non-HTTP port)");
+  } else {
+    tls = "off (no host matchers)";
+  }
   const listenStr = listen.length > 0 ? listen.map(String).join(", ") : "default";
   return `${routes.length} route(s), listen: ${listenStr}, TLS: ${tls}`;
 }
@@ -521,14 +770,17 @@ function registerOperationalTools(server) {
       const res = await configGet();
       if (!res.ok) return formatResult(res);
       const config = res.data ?? {};
-      const servers = config.apps?.http?.servers ?? {};
+      const httpApp = config.apps?.http;
+      const servers = httpApp?.servers ?? {};
       const serverNames = Object.keys(servers);
+      const httpPort = appPort(httpApp?.http_port, DEFAULT_HTTP_PORT);
+      const httpsPort = appPort(httpApp?.https_port, DEFAULT_HTTPS_PORT);
       const lines = ["Caddy is running", ""];
       if (serverNames.length === 0) {
         lines.push("No HTTP servers configured");
       } else {
         for (const name of serverNames) {
-          lines.push(`Server "${name}": ${describeServer(servers[name])}`);
+          lines.push(`Server "${name}": ${describeServer(servers[name], httpPort, httpsPort)}`);
         }
       }
       const email = findAcmeEmail(config.apps?.tls?.automation?.policies);
@@ -562,7 +814,7 @@ ${lines.join("\n")}` }]
   );
   server.tool(
     "caddy_upstreams",
-    "Get the current health status of all reverse proxy upstreams. Shows address, active requests, and failure counts.",
+    "Caddy's /reverse_proxy/upstreams array (address, num_requests, fails), returned verbatim. On Caddy 2.11.2+ it is not the configured upstream list. Dynamic-upstream backends stay listed about 1 h (up to ~65 min) after the dynamic source last returned them, even after a config change removes them, so an address may appear that no current config references. A backend with requests in flight can appear twice when its resolved address differs from the entry's text (dynamic upstreams, tcp/ or unix// dials, placeholder dials). That extra copy always shows fails 0 and repeats num_requests, so do not sum num_requests across entries.",
     {},
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async () => formatResult(await getUpstreams())
@@ -636,7 +888,9 @@ function registerResources(server) {
   server.resource(
     "caddy-upstreams",
     "caddy://upstreams",
-    { description: "Reverse proxy upstream health status" },
+    {
+      description: "Reverse proxy upstream health: Caddy's /reverse_proxy/upstreams array, returned verbatim. On Caddy 2.11.2+ it is not the configured upstream list -- dynamic upstreams stay listed about 1 h after the dynamic source last returned them (so an address can outlive the config that referenced it), and a backend with requests in flight can appear twice when its resolved address differs from the entry's text. The extra copy always shows fails 0 and repeats num_requests, so do not sum num_requests. See the caddy_upstreams tool for the full caveat."
+    },
     async () => {
       const res = await getUpstreams();
       return {
@@ -702,7 +956,7 @@ function registerResources(server) {
 
 // src/tools/adapt.ts
 import { z as z2 } from "zod";
-function formatWarning(w) {
+function formatWarning2(w) {
   if (!w || typeof w !== "object") return `  - unknown: ${JSON.stringify(w)}`;
   const obj = w;
   const directive = typeof obj.directive === "string" ? obj.directive : "unknown";
@@ -712,7 +966,7 @@ function formatWarning(w) {
 function registerAdaptTools(server) {
   server.tool(
     "caddy_adapt",
-    "Convert a config in any registered adapter format to Caddy JSON without loading it. Useful for previewing what a Caddyfile produces, or for porting from nginx/yaml configs when Caddy is built with the matching adapter module ('caddyfile' is built-in; 'nginx', 'yaml', etc. require their adapter modules to be compiled into the Caddy binary). Returns the adapted JSON and any warnings separately.",
+    `Convert a config in any registered adapter format to Caddy JSON without loading it. Useful for previewing what a Caddyfile produces, or for porting from nginx/yaml configs when Caddy is built with the matching adapter module ('caddyfile' is built-in; 'nginx', 'yaml', etc. require their adapter modules to be compiled into the Caddy binary). Returns the adapted JSON and any warnings separately. One exception to 'without loading it': on Caddy <= 2.11.4 a Caddyfile 'order' global option is not preview-only. It mutates that Caddy process's directive order, so it carries into every later Caddyfile adapt or load there, and an 'order' line that FAILS (unknown target, bad positional, extra arg) still removes the directive it names -- later Caddyfiles using that directive then fail with "directive 'X' is not an ordered HTTP handler" until another 'order' line re-places it or Caddy restarts. Fixed upstream in caddyserver/caddy#7995, unreleased as of v2.11.4.`,
     {
       config: z2.string().describe("The raw config text (e.g., Caddyfile contents, nginx.conf, yaml)"),
       adapter: z2.string().regex(/^[a-z0-9_-]+$/, "Adapter must be lowercase alphanumeric, hyphens, or underscores").max(64).optional().default("caddyfile").describe(
@@ -728,7 +982,7 @@ function registerAdaptTools(server) {
       const result = data.result;
       const content = [];
       if (warnings.length > 0) {
-        const warnLines = warnings.map(formatWarning);
+        const warnLines = warnings.map(formatWarning2);
         content.push({ type: "text", text: `Warnings:
 ${warnLines.join("\n")}` });
       }
@@ -822,6 +1076,9 @@ function getSnapshot(index) {
 }
 
 // src/tools/config.ts
+function isRootConfigPath(path) {
+  return /^\/*$/.test(path.replace(/^\/?(config(\/|$))?/, ""));
+}
 function registerConfigTools(server) {
   server.tool(
     "caddy_config_get",
@@ -832,12 +1089,12 @@ function registerConfigTools(server) {
   );
   server.tool(
     "caddy_config_set",
-    "Write config at a JSON path. Mode 'overwrite' (default) replaces existing values (PATCH) \u2014 safe and idempotent. Mode 'append' adds to arrays or creates keys (POST) \u2014 NOT idempotent: calling twice with the same route duplicates it. Mode 'insert' places at a specific array index (PUT) \u2014 useful for route ordering.",
+    "Write config at a JSON path. Mode 'overwrite' (default) replaces existing values (PATCH) \u2014 safe and idempotent. Mode 'append' (POST) adds to an array \u2014 NOT idempotent: calling twice with the same route duplicates it \u2014 but on a non-array key it REPLACES whatever is there, and it cannot create missing parent objects. Mode 'insert' (PUT) inserts at an array index (useful for route ordering), or strictly creates an object key together with any missing parents and fails with 409 if the key already exists \u2014 the safe way to create a server or app, including on an instance with no config at all.",
     {
       path: z3.string().describe("Config path to write to (e.g., 'apps/http/servers/srv0/routes')"),
       value: z3.any().describe("The JSON value to set at the path"),
       mode: z3.enum(["append", "overwrite", "insert"]).optional().default("overwrite").describe(
-        "'overwrite' = PATCH (replace existing, default, idempotent), 'append' = POST (add to arrays / create keys, NOT idempotent), 'insert' = PUT (insert at array index)"
+        "'overwrite' = PATCH (replace existing, default, idempotent; 404 if the key does not exist), 'append' = POST (appends to arrays, NOT idempotent; REPLACES an existing non-array key; cannot create missing parents), 'insert' = PUT (inserts at an array index, or strictly creates an object key and any missing parents; 409 if the key exists)"
       )
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
@@ -848,7 +1105,7 @@ function registerConfigTools(server) {
   );
   server.tool(
     "caddy_config_delete",
-    "Delete config at a JSON path. Removes the config node at the specified path. Deleting a parent node also deletes every descendant -- e.g. deleting 'apps/http/servers/srv0' removes that server and all of its routes. Requires confirm=true.",
+    "Delete config at a JSON path. Removes the config node at the specified path. Deleting a parent node also deletes every descendant -- e.g. deleting 'apps/http/servers/srv0' removes that server and all of its routes. Requires confirm=true. Any path that addresses the config ROOT ('', '/', 'config', '/config/', and slash-only variants of those) addresses the ENTIRE config and unloads it: every app and server goes, and so does the 'admin' block, after which Caddy re-binds its admin endpoint to its default address (localhost:2019, or $CADDY_ADMIN in Caddy's environment). If CADDY_ADMIN_URL points anywhere else, neither this server nor caddy_revert can reach Caddy afterwards. A root delete is snapshotted first, so caddy_revert can restore it while Caddy is still reachable; no other path is snapshotted. To REPLACE the config rather than unload it, use caddy_load.",
     {
       path: z3.string().describe("Config path to delete (e.g., 'apps/http/servers/srv0/routes/0')"),
       confirm: z3.boolean().optional().default(false).describe("Must be true to actually delete the config node (safety)")
@@ -859,27 +1116,54 @@ function registerConfigTools(server) {
     // array after a delete, so repeating that call removes a DIFFERENT route each
     // time. caddy_remove_route carries the same correction for the byte-identical
     // underlying request; the two must agree. Nothing here is auto-recoverable
-    // either: only caddy_load captures a snapshot, so a spurious repeat cannot be
-    // undone with caddy_revert.
+    // either: apart from a root delete (below), only caddy_load captures a
+    // snapshot, so a spurious repeat cannot be undone with caddy_revert.
     { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
     async ({ path, confirm }) => {
+      const root = isRootConfigPath(path);
       if (!confirm) {
         return {
           isError: true,
           content: [
             {
               type: "text",
-              text: `Refusing to delete "${path}" without confirm=true. Deleting a parent path also removes all descendants. Re-run with confirm:true to proceed.`
+              text: root ? `Refusing to delete the ENTIRE config without confirm=true. The path "${path}" addresses the config root, so this unloads every app and server, and the 'admin' block with them: Caddy then re-binds its admin endpoint to its default address (localhost:2019, or $CADDY_ADMIN in Caddy's environment), and if CADDY_ADMIN_URL points anywhere else neither this server nor caddy_revert can reach Caddy afterwards. The current config is snapshotted first, so caddy_revert can restore it while Caddy is still reachable. To REPLACE the config rather than unload it, use caddy_load. Re-run with confirm:true to proceed.` : `Refusing to delete "${path}" without confirm=true. Deleting a parent path also removes all descendants. Re-run with confirm:true to proceed.`
             }
           ]
         };
       }
-      return formatResult(await configDelete(path));
+      if (!root) return formatResult(await configDelete(path));
+      const current = await configGet();
+      const res = await configDelete("");
+      const kept = (res.ok || res.outcomeUnknown === true) && current.ok && isSnapshotableConfig(current.data);
+      if (kept) saveSnapshot(current.data, "caddy_config_delete");
+      if (!res.ok) {
+        if (res.outcomeUnknown && kept) {
+          return formatResult({
+            ...res,
+            error: `${res.error}
+The pre-delete config was kept anyway, as snapshot [0] (trigger=caddy_config_delete): if this delete did apply, caddy_revert { action: "apply", index: 0, confirm: true } restores what it unloaded -- as long as this server can still reach Caddy's admin endpoint, which moves back to Caddy's default address when the deleted config set an admin.listen of its own. If the delete did not apply, that snapshot is simply the config read just before it was sent.`
+          });
+        }
+        return formatResult(res);
+      }
+      const note = kept ? ` The prior config was saved as snapshot [0] (trigger=caddy_config_delete): caddy_revert { action: "apply", index: 0, confirm: true } restores it.` : current.ok ? " Warning: the prior config was empty or not a JSON object, so no snapshot was captured -- there was nothing to restore." : " Warning: the prior config could not be read, so no snapshot was captured and this unload cannot be reverted.";
+      const adm = kept ? current.data.admin : void 0;
+      const listen = adm !== null && typeof adm === "object" && !Array.isArray(adm) ? adm.listen : void 0;
+      const adminNote = typeof listen === "string" && listen !== "" ? ` The unloaded config set admin.listen to "${listen}". If that was not already Caddy's default admin address, the endpoint has moved back to the default (localhost:2019, unless $CADDY_ADMIN is set in Caddy's environment) and CADDY_ADMIN_URL (${process.env.CADDY_ADMIN_URL || "http://localhost:2019"}) may no longer reach it.` : "";
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Unloaded the entire config (every app and server, and the 'admin' block).${note}${adminNote}`
+          }
+        ]
+      };
     }
   );
   server.tool(
     "caddy_load",
-    "Replace the entire Caddy configuration atomically. Accepts a JSON config object, or a Caddyfile string with format='caddyfile'. This is the safest way to make large config changes. Has a 60-second timeout to allow for TLS provisioning. Requires confirm=true: this DISCARDS the entire running config, including servers and routes not present in the supplied config. The prior config is snapshotted first and can be restored with caddy_revert.",
+    "Replace the entire Caddy configuration atomically. Accepts a JSON config object, or a Caddyfile string with format='caddyfile'. This is the safest way to make large config changes. Runs on CADDY_LOAD_TIMEOUT (55 s by default), like every config change; a load that times out is not retried and may still apply, so re-read the config before loading again. Requires confirm=true: this DISCARDS the entire running config, including servers and routes not present in the supplied config. The prior config is snapshotted first and can be restored with caddy_revert.",
     {
       config: z3.union([z3.record(z3.string(), z3.any()), z3.string()]).describe("Full config \u2014 JSON object or Caddyfile text string"),
       format: z3.enum(["json", "caddyfile"]).optional().default("json").describe("Config format: 'json' (default) or 'caddyfile'"),
@@ -901,15 +1185,21 @@ function registerConfigTools(server) {
       const contentType = format === "caddyfile" ? "text/caddyfile" : "application/json";
       const current = await configGet();
       const res = await loadConfig(config, contentType);
-      if (res.ok && current.ok && isSnapshotableConfig(current.data)) {
-        saveSnapshot(current.data, "caddy_load");
+      const kept = (res.ok || res.outcomeUnknown === true) && current.ok && isSnapshotableConfig(current.data);
+      if (kept) saveSnapshot(current.data, "caddy_load");
+      if (res.outcomeUnknown && kept) {
+        return formatResult({
+          ...res,
+          error: `${res.error}
+The pre-load config was kept anyway, as snapshot [0] (trigger=caddy_load): if this load did apply, caddy_revert { action: "apply", index: 0, confirm: true } restores what it replaced. If it did not, that snapshot is simply the config read just before the load was sent.`
+        });
       }
       return formatResult(res);
     }
   );
   server.tool(
     "caddy_revert",
-    "Manage config snapshots for rollback. Snapshots are auto-captured before caddy_load (last 10). By default they live in memory only and are LOST when this server restarts -- set CADDY_MCP_SNAPSHOT_DIR to a writable directory to persist them across restarts (they contain full Caddy configs, so pick the location deliberately). Actions: 'list' shows snapshots with timestamps, 'save' manually captures the current config, 'apply' restores a snapshot (requires confirm=true).",
+    "Manage config snapshots for rollback. Snapshots are auto-captured before caddy_load, and before a caddy_config_delete that unloads the whole config (an empty path); no other delete is snapshotted. Last 10. By default they live in memory only and are LOST when this server restarts -- set CADDY_MCP_SNAPSHOT_DIR to a writable directory to persist them across restarts (they contain full Caddy configs, so pick the location deliberately). Actions: 'list' shows snapshots with timestamps, 'save' manually captures the current config, 'apply' restores a snapshot (requires confirm=true).",
     {
       action: z3.enum(["list", "save", "apply"]).describe("Action to perform"),
       index: z3.number().int().nonnegative().optional().default(0).describe("Snapshot index for 'apply' (0 = most recent, default)"),
@@ -972,7 +1262,19 @@ ${lines.join("\n")}` }] };
       }
       const current = await configGet();
       const res = await loadConfig(snap.config, "application/json");
-      if (!res.ok) return formatResult(res);
+      if (!res.ok) {
+        if (res.outcomeUnknown && current.ok && isSnapshotableConfig(current.data)) {
+          saveSnapshot(current.data, "caddy_revert");
+          const now = listSnapshots().indexOf(snap);
+          const target = now === -1 ? `the snapshot you asked to apply ([${index}]) has dropped out of the ring` : `the snapshot you asked to apply is now [${now}]`;
+          return formatResult({
+            ...res,
+            error: `${res.error}
+The pre-revert config was kept anyway, as snapshot [0] (trigger=caddy_revert), so this revert can still be rolled back if it did apply. That moved every older snapshot down one index: ${target}, so re-running apply with index ${index} would load a different snapshot. List the snapshots before retrying.`
+          });
+        }
+        return formatResult(res);
+      }
       const capturedRollforward = current.ok && isSnapshotableConfig(current.data);
       if (capturedRollforward) {
         saveSnapshot(current.data, "caddy_revert");
@@ -996,7 +1298,7 @@ ${lines.join("\n")}` }] };
       value: z3.any().optional().describe("New value (required for 'set' action)"),
       subpath: z3.string().optional().default("").describe("Optional sub-path within the identified object"),
       mode: z3.enum(["append", "overwrite", "insert"]).optional().default("overwrite").describe(
-        "For 'set' action: 'overwrite' = PATCH (replace existing, default), 'append' = POST (add to arrays, create on objects), 'insert' = PUT (insert at array index)"
+        "For 'set' action: 'overwrite' = PATCH (replace the identified object, or the value at subpath; default). 'append' = POST and 'insert' = PUT behave as in caddy_config_set at the resolved path: with a subpath into an array, POST appends and PUT inserts at the index; PUT also strictly creates an object key (409 if it exists). With NO subpath: for an array element (a route) neither replaces it \u2014 POST adds the value as a new element at the end of that array, PUT inserts it just before the identified one, and both are rejected with 'duplicate ID' if the value carries the same @id; for an object held under a key (a server) POST REPLACES it wholesale and PUT fails with 409. Use 'overwrite' to replace in place."
       ),
       confirm: z3.boolean().optional().default(false).describe("Must be true to actually delete (only enforced for action='delete')")
     },
@@ -1152,7 +1454,7 @@ function serverNotFoundError(srv, op = "operation") {
     content: [
       {
         type: "text",
-        text: `Error: Server "${srv}" does not exist (${op}). Use caddy_list_servers to see what is configured. To create it: caddy_config_set { path: "apps/http/servers/${srv}", mode: "append", value: { "listen": [":443"], "routes": [] } }. Both arguments are load-bearing: mode "append" creates the key, while the default "overwrite" fails with "key does not exist"; and "routes": [] must be present, or adding the first route fails, because a POST creates a missing routes key as an object rather than an array. On an instance with no config at all, use caddy_load instead -- caddy_config_set cannot create the apps/http tree it would write into.`
+        text: `Error: Server "${srv}" does not exist (${op}). Use caddy_list_servers to see what is configured. To create it: caddy_config_set { path: "apps/http/servers/${srv}", mode: "insert", value: { "listen": [":443"], "routes": [] } }. Both arguments are load-bearing: mode "insert" (PUT) creates the key along with any missing apps/http/servers parents, so it works even on an instance with no config at all, and fails with 409 if the server already exists -- whereas "append" (POST) would replace an existing server and cannot create missing parents, and the default "overwrite" fails with "key does not exist"; and "routes": [] must be present, or adding the first route fails, because a POST creates a missing routes key as an object rather than an array.`
       }
     ]
   };
@@ -1163,7 +1465,7 @@ function serverNullError(srv) {
     content: [
       {
         type: "text",
-        text: `Error: Server "${srv}" is not configured, or its config is null -- Caddy returns the same response (HTTP 200 with a body of null) for both, so they cannot be told apart from here. Use caddy_list_servers to see which servers exist, or create this one with caddy_load or caddy_config_set at path 'apps/http/servers/${srv}' with at minimum: { "listen": [":443"] }`
+        text: `Error: Server "${srv}" is not configured, or its config is null -- Caddy returns the same response (HTTP 200 with a body of null) for both, so they cannot be told apart from here. Use caddy_list_servers to see which servers exist. To create this one: caddy_config_set { path: "apps/http/servers/${srv}", mode: "insert", value: { "listen": [":443"], "routes": [] } }. Mode "insert" (PUT) strictly creates the key, so it never overwrites anything. If it fails with 409 "key already exists", the key is there now: it may hold a null config, or it may have been created after this read (by another writer, or by an earlier attempt of this same write whose response was lost). Re-read it with caddy_config_get { path: "apps/http/servers/${srv}" }, and use mode "overwrite" only if that read still shows null -- overwrite (PATCH) replaces the whole server, routes included.`
       }
     ]
   };
@@ -1546,7 +1848,7 @@ function buildTlsConfig(fields) {
     }
   };
 }
-function bothErrors(label, patchRes, writeRes, writeLabel) {
+function bothErrors(label, patchRes, writeRes, writeLabel, hint) {
   const patchErr = patchRes.error || `HTTP ${patchRes.status}`;
   const writeErr = writeRes.error || `HTTP ${writeRes.status}`;
   return {
@@ -1556,11 +1858,16 @@ function bothErrors(label, patchRes, writeRes, writeLabel) {
         type: "text",
         text: `Error: Failed to set ${label}.
   PATCH attempt: ${patchErr}
-  ${writeLabel} fallback: ${writeErr}`
+  ${writeLabel} fallback: ${writeErr}` + (hint ? `
+  ${hint}` : "")
       }
     ]
   };
 }
+function isAbsentOnGet(res) {
+  if (res.ok) return res.data === void 0 || res.data === null;
+  return isMissingConfigPath(res);
+}
 function isPlainObject(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -1623,13 +1930,15 @@ function refuseFallback(label, patchRes, detail) {
     }
   };
 }
+var CREATE_CONFLICT_HINT = "apps/tls read as not set, but Caddy now reports the key exists, so nothing was overwritten. Either something else created it between the read and this write, or an earlier attempt of this same write landed and only its response was lost. Check caddy_tls status, then re-run this action so it merges into what is there instead of creating it.";
 async function safeFallback(label, patchRes, fields) {
   const getRes = await configGet("apps/tls");
-  const absent = !getRes.ok && getRes.status === 404 ? true : getRes.ok && (getRes.data === void 0 || getRes.data === null);
+  const absent = isAbsentOnGet(getRes);
   if (absent) {
-    const postRes = await configPost("apps/tls", buildTlsConfig(fields));
-    if (postRes.ok) return { kind: "ok" };
-    return { kind: "tool-error", result: bothErrors(label, patchRes, postRes, "POST") };
+    const putRes = await configPut("apps/tls", buildTlsConfig(fields));
+    if (putRes.ok) return { kind: "ok" };
+    const hint = putRes.status === 409 ? CREATE_CONFLICT_HINT : void 0;
+    return { kind: "tool-error", result: bothErrors(label, patchRes, putRes, "PUT", hint) };
   }
   if (!getRes.ok) {
     return { kind: "tool-error", result: bothErrors(label, patchRes, getRes, "GET apps/tls") };
@@ -1671,29 +1980,39 @@ function missingArgError(text) {
 function registerTlsTools(server) {
   server.tool(
     "caddy_tls",
-    "Get or configure TLS/HTTPS settings. Actions: 'status' shows current TLS config, 'set_email' sets the ACME email, 'set_acme_ca' sets the ACME CA URL, 'set_acme_profile' sets the ACME profile (Caddy 2.10+), 'ech_status' reads the Encrypted ClientHello config (Caddy 2.10+, read-only here). Works on both fresh and existing Caddy instances. Writes target policies[0].issuers[0] only, and only when that issuer's module is 'acme' -- on a multi-policy TLS config, or one whose first issuer is 'internal' (Caddy's local CA), edit the intended issuer with caddy_config_set instead.",
+    "Get or configure TLS/HTTPS settings. Actions: 'status' shows current TLS config, 'set_email' sets the ACME email, 'set_acme_ca' sets the ACME CA URL, 'set_acme_profile' sets the ACME profile (Caddy 2.10+), 'ech_status' reads the Encrypted ClientHello config at apps/tls/encrypted_client_hello (Caddy 2.10+, read-only here). Works on both fresh and existing Caddy instances, including one with no config at all: the set_* actions create apps/tls, and any missing parents, when it is not set. Writes target policies[0].issuers[0] only, and only when that issuer's module is 'acme' -- on a multi-policy TLS config, or one whose first issuer is 'internal' (Caddy's local CA), edit the intended issuer with caddy_config_set instead.",
     {
       action: z5.enum(["status", "set_email", "set_acme_ca", "set_acme_profile", "ech_status"]).describe("Action to perform"),
       email: z5.string().optional().describe("ACME email address (for 'set_email' action)"),
       ca: z5.string().optional().describe("ACME CA URL (for 'set_acme_ca' action)"),
       profile: z5.string().optional().describe(
-        "ACME profile name (for 'set_acme_profile'). Requires Caddy 2.10+ and a CA that offers profiles; Let's Encrypt uses 'shortlived' for 6-day certificates. Valid names are defined by the CA, not by Caddy."
+        "ACME profile name (for 'set_acme_profile'). Requires Caddy 2.10+ and a CA that offers profiles; Let's Encrypt uses 'shortlived' for 6-day certificates. Valid names are defined by the CA, not by Caddy. EXPERIMENTAL upstream (the ACME profiles spec is still a draft; Caddy marks the field 'subject to change' and may rename or drop it). Caddy accepts any name on load, so a success here does not mean the CA offers it: if this issuer's CA does not advertise the name, every order from this issuer fails at issuance time, reported only in Caddy's own logs. Caddy then either falls through to the next issuer in the policy, which issues WITHOUT the profile, or -- when this is the policy's only issuer, which is the shape this tool creates -- keeps retrying and issues no certificate at all."
       )
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async ({ action, email, ca, profile }) => {
       if (action === "status") {
-        return formatResult(await configGet("apps/tls"));
+        const tlsRes = await configGet("apps/tls");
+        if (isAbsentOnGet(tlsRes)) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "No TLS config is set on this instance (apps/tls is not set), so Caddy's TLS defaults apply. The set_email / set_acme_ca / set_acme_profile actions create it."
+              }
+            ]
+          };
+        }
+        return formatResult(tlsRes);
       }
       if (action === "ech_status") {
-        const echRes = await configGet("apps/tls/ech");
-        const absent = !echRes.ok && echRes.status === 404 || echRes.ok && (echRes.data === void 0 || echRes.data === null);
-        if (absent) {
+        const echRes = await configGet("apps/tls/encrypted_client_hello");
+        if (isAbsentOnGet(echRes)) {
           return {
             content: [
               {
                 type: "text",
-                text: "ECH (Encrypted ClientHello) is not configured on this instance. Requires Caddy 2.10+; enable it by applying a config with apps/tls/ech via caddy_load."
+                text: "ECH (Encrypted ClientHello) is not configured on this instance: apps/tls/encrypted_client_hello is not set. Requires Caddy 2.10+; enable it by applying a config that sets apps.tls.encrypted_client_hello via caddy_load. The JSON key is 'encrypted_client_hello' -- 'ech' is only the Caddyfile global option name, and Caddy rejects apps.tls.ech as an unknown field."
               }
             ]
           };