@yawlabs/caddy-mcp 2.5.2 → 2.5.3

package/README.md

@@ -21,7 +21,7 @@ Other Caddy MCP servers wrap half the admin API and silently swallow errors. Thi
 - **Safe-by-default mutations** — `caddy_config_set` defaults to idempotent `overwrite` (PATCH), not `append` (POST). Calling twice doesn't duplicate your route.
 - **Defensive parsing** — `caddy_list_routes` never crashes on malformed config, even if routes are null, handlers are strings, or matchers are non-arrays. Regression-tested.
 - **No leaked credentials in errors** — if `CADDY_ADMIN_URL` contains a token in the path/query, the connect-failed message shows only the origin.
-- **Fallback error surfacing** — when a TLS write PATCH fails and the POST fallback also fails, both error bodies are returned so you know what actually went wrong.
+- **Fallback error surfacing** — when a TLS write PATCH fails and the PUT fallback also fails, both error bodies are returned so you know what actually went wrong.
 - **Tool annotations** — every tool declares `readOnlyHint`, `destructiveHint`, and `idempotentHint`, so MCP clients can skip confirmations for safe ops.
 - **Instant startup** — ships as a single bundle with two runtime deps (the MCP SDK + Zod). No 5-minute `node_modules` install.
 - **Input hardening** — adapter names, `@id` values, server names, and CA ids are all regex-validated with length caps. Blocks CRLF header injection and ReDoS.
@@ -81,9 +81,9 @@ That's it. Now ask your AI assistant:
 | `CADDY_ADMIN_URL` | `http://localhost:2019` | Caddy admin API URL. Set to `http://caddy:2019` inside Docker, or an https URL for remote admin. Also accepts a unix socket, in either `unix:///var/run/caddy-admin.sock` or Caddy's own `unix//var/run/caddy-admin.sock` spelling — see below. |
 | `CADDY_API_TOKEN` | (none) | Optional Bearer token for authenticated admin endpoints. Only needed if you've configured Caddy with auth. |
 | `CADDY_MCP_SNAPSHOT_DIR` | (none) | Directory for persisting `caddy_revert` snapshots. Unset, snapshots live in memory only and are lost when this server restarts. Snapshots are full Caddy configs and can contain secrets, so the location is opt-in rather than defaulted. |
-| `CADDY_MAX_RETRIES` | `2` | Number of retries on transient failures (5xx, network errors). 4xx and 412 never retry. POSTs to `/config/*` and `/id/*` also skip retry (non-idempotent appends/creates -- retrying could duplicate routes or 409 a half-applied create). POSTs to `/load`, `/adapt`, `/stop` still retry. Hard-capped at 5; values above the cap log a one-time stderr notice so the clamp is visible. Set to `0` to disable. |
-| `CADDY_TIMEOUT` | `10000` | Timeout in ms for all admin API requests except `/load` (which uses `CADDY_LOAD_TIMEOUT`). Non-numeric, `<= 0`, or fractional values below 1ms fall back to the default. |
-| `CADDY_LOAD_TIMEOUT` | `60000` | Timeout in ms for the `/load` endpoint; raise for ACME-heavy bring-ups where provisioning many certificates can exceed the default. Non-numeric, `<= 0`, or fractional values below 1ms fall back to the default. |
+| `CADDY_MAX_RETRIES` | `2` | Number of retries on transient failures: network errors, and 502/503/504 (which only a proxy in front of Caddy sends). Caddy's own 500s are deterministic rejections and never retry, nor do 4xx and 412. Requests a replay could change the outcome of also skip retry: POSTs to `/config/*` and `/id/*` (they append, or replace an existing key -- retrying could duplicate routes), and a PUT or DELETE at an array index such as `.../routes/0` (a replay would insert a second route, or remove the one that slid into that index), including a PUT to a bare `/id/<id>`, which Caddy resolves to the identified element's array index. A config change whose timeout fired is never retried (see `CADDY_LOAD_TIMEOUT`). A refused connection retries for every method, since nothing was sent. POSTs to `/load`, `/adapt`, `/stop` still retry. Hard-capped at 5; values above the cap log a one-time stderr notice so the clamp is visible. Set to `0` to disable. |
+| `CADDY_TIMEOUT` | `10000` | Timeout in ms for admin API requests that do not change the config: GETs, `/adapt`, `/stop`, PKI, upstreams and metrics. Config changes use `CADDY_LOAD_TIMEOUT`. Non-numeric, `<= 0`, or fractional values below 1ms fall back to the default. |
+| `CADDY_LOAD_TIMEOUT` | `55000` | Timeout in ms for every request that changes the config: `POST /load`, and every POST/PUT/PATCH/DELETE under `/config/*` and `/id/*`. Each is a full synchronous reload inside Caddy, which can legitimately run long -- Caddy sleeps through `apps.http.shutdown_delay` inside the reload whenever a change closes a listener, and a change can wait behind another reload. A timeout here is never retried: Caddy keeps applying a change after the client gives up, so the error says the outcome is unknown and to re-read the config before retrying (`caddy_load` and `caddy_revert` keep their snapshot in that case). Keep it below your MCP client's request timeout (60 s by default in the MCP SDK), or that error arrives after the client has given up and is never shown; the default sits 5 s under it. Non-numeric, `<= 0`, or fractional values below 1ms fall back to the default. |
 
 **Unix socket admin endpoints:**
 
@@ -118,11 +118,11 @@ Use the same JSON block shown above in any of these.
 ### Config management (6)
 
 - **caddy_config_get** — Read config at any JSON path (or the full config).
-- **caddy_config_set** — Write config at a path. Modes: `overwrite` (PATCH, default, idempotent), `append` (POST), `insert` (PUT, for array positions).
+- **caddy_config_set** — Write config at a path. Modes: `overwrite` (PATCH, default, idempotent; the key must exist), `append` (POST: appends to an array, but replaces an existing non-array key and cannot create missing parents), `insert` (PUT: inserts at an array position, or strictly creates a key along with any missing parents and fails with 409 if it exists — the way to create a server or app, even on an instance with no config).
 - **caddy_config_delete** — Delete config at a path. Requires `confirm=true` (deleting a parent path also removes every descendant).
 - **caddy_config_by_id** — Get/set/delete config by `@id` tag — much easier than navigating deep paths. The `delete` action requires `confirm=true`.
-- **caddy_load** — Replace the entire config atomically. 60-second timeout for cert provisioning. Auto-snapshots the prior config.
-- **caddy_revert** — Manage config snapshots for rollback. Actions: `list`, `save`, `apply` (confirm-gated). In-memory, last 10.
+- **caddy_load** — Replace the entire config atomically. Runs on `CADDY_LOAD_TIMEOUT` (55 seconds by default), like every config change. Auto-snapshots the prior config, and keeps that snapshot when the load times out with its outcome unknown. Lists the Caddyfile adapter's warnings, and reports a load that failed as an error even when Caddy answered HTTP 200 — which Caddy 2.11.4 does for a Caddyfile that adapted with warnings ([caddyserver/caddy#7246](https://github.com/caddyserver/caddy/issues/7246)).
+- **caddy_revert** — Manage config snapshots for rollback. Actions: `list`, `save`, `apply` (confirm-gated). In-memory, last 10. An `apply` that times out with its outcome unknown keeps the pre-revert config as snapshot [0], which shifts every older snapshot down one index; the error says where the target now sits.
 
 ### Route operations (4)
 
@@ -133,7 +133,7 @@ Use the same JSON block shown above in any of these.
 
 ### TLS & config conversion (2)
 
-- **caddy_tls** — Check or set TLS settings: ACME email, ACME CA URL. PATCH first; on a fresh install, POSTs a minimal config. On an existing config it deep-merges into the issuer path and PUTs the result back, preserving siblings (custom certs, `on_demand`, additional policies). Refuses with a shape-specific error if the existing structure is unexpected — never clobbers.
+- **caddy_tls** — Check or set TLS settings. Actions: `status`, `set_email` (ACME email), `set_acme_ca` (ACME CA URL), `set_acme_profile` (ACME profile, Caddy 2.10+), and the read-only `ech_status` (the Encrypted ClientHello config at `apps/tls/encrypted_client_hello`, Caddy 2.10+). The set actions PATCH first; when `apps/tls` is not set they PUT a minimal config, which also creates any missing parents, so they work on an instance with no config at all. On an existing config they deep-merge into the issuer path and PATCH the result back, preserving siblings (custom certs, `on_demand`, additional policies). Refuses with a shape-specific error if the existing structure is unexpected — never clobbers.
 - **caddy_adapt** — Convert a config in any registered adapter format to Caddy JSON without applying it. `caddyfile` (built-in, default) plus any adapter module compiled into your Caddy binary — e.g., `nginx` ([caddy-nginx-adapter](https://github.com/caddyserver/nginx-adapter)), `yaml` ([caddy-yaml](https://github.com/abiosoft/caddy-yaml)). Great for previewing or porting from existing configs.
 
 ### Server operations (6)
@@ -265,7 +265,7 @@ npm install
 npm run lint       # Biome check
 npm run lint:fix   # Auto-fix
 npm run build      # tsup bundle
-npm test           # Vitest (357 unit tests, +9 POSIX-only unix-socket tests; +13 live-Caddy integration tests gated by CADDY_MCP_INTEGRATION=1)
+npm test           # Vitest (636 unit tests, +39 POSIX-only unix-socket and launcher tests; +32 live-Caddy integration tests gated by CADDY_MCP_INTEGRATION=1)
 npm run typecheck  # tsc --noEmit
 ```
 

package/dist/api.d.ts

@@ -4,6 +4,26 @@ export interface ApiResponse<T = any> {
     data?: T;
     error?: string;
     etag?: string;
+    /**
+     * Config-adapter warnings Caddy attached to a `POST /load` answer, set on a
+     * load that applied and on one that failed alike (see readLoadBody). Kept
+     * apart from `data` and `error` so neither has to be a rendered string;
+     * formatResult prints them for every consumer, so none can drop them.
+     * Elements are whatever Caddy sent -- `{file, line, directive, message}` on
+     * 2.11.4 -- and are not validated here.
+     */
+    warnings?: unknown[];
+    /**
+     * Set (to true) only on a failure where this client's deadline fired on a
+     * config change (isConfigChange): no answer came, and Caddy may have applied
+     * the change, may still apply it, or may never have received it. `ok` is
+     * false, because nothing confirmed success -- but unlike every other failure
+     * it does NOT mean "nothing changed", and a caller that skips its bookkeeping
+     * on `!ok` needs to know the difference. caddy_load and caddy_revert apply key
+     * on it to keep the snapshot they would otherwise drop. A flag rather than a
+     * match on the error text, so rewording the message cannot change behaviour.
+     */
+    outcomeUnknown?: boolean;
 }
 /**
  * Caddy's "a segment of this config path does not exist" failure.

package/dist/format.d.ts

@@ -1,5 +1,14 @@
 import type { ApiResponse } from "./api.js";
-/** Convert an API response to MCP tool result format */
+/**
+ * Convert an API response to MCP tool result format.
+ *
+ * `warnings` are appended to the SAME text item as the result, on a success and
+ * on an error alike, rather than sent as a second content item. They are set
+ * only by `POST /load` today, where they matter most on the failure path -- a
+ * load Caddy refused, reported next to the adapter warnings that came with it --
+ * and a client that reads only `content[0]` must still see both. Rendering them
+ * here, not in caddy_load, means no consumer of an ApiResponse can drop them.
+ */
 export declare function formatResult(res: ApiResponse): {
     isError: boolean;
     content: {

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) {
@@ -108,25 +109,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 +148,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 +171,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 +267,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;
 }
-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 parseJsonOrUndefined(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
 }
-async function sendOnce(transport, method, path, body, contentType, timeout, rawStringBody = false) {
+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 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,6 +337,15 @@ 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;
@@ -298,6 +382,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 +412,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 +467,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,16 +537,39 @@ 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
@@ -702,7 +821,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";
@@ -728,7 +847,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")}` });
       }
@@ -832,12 +951,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 },
@@ -879,7 +998,7 @@ function registerConfigTools(server) {
   );
   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,8 +1020,14 @@ 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);
     }
@@ -972,7 +1097,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 +1133,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 +1289,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 +1300,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 +1683,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 +1693,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 +1765,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,7 +1815,7 @@ 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)"),
@@ -1683,17 +1827,27 @@ function registerTlsTools(server) {
     { 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."
               }
             ]
           };

package/dist/server.js

@@ -12,6 +12,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) {
@@ -106,25 +107,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 {
@@ -134,16 +146,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;
@@ -157,27 +169,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();
   });
@@ -236,19 +265,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;
 }
-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 parseJsonOrUndefined(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
 }
-async function sendOnce(transport, method, path, body, contentType, timeout, rawStringBody = false) {
+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 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);
@@ -260,6 +335,15 @@ 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;
@@ -296,6 +380,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 {
@@ -325,8 +410,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 };
   }
@@ -372,20 +465,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");
@@ -439,16 +535,39 @@ 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
@@ -700,7 +819,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";
@@ -726,7 +845,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")}` });
       }
@@ -830,12 +949,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 },
@@ -877,7 +996,7 @@ function registerConfigTools(server) {
   );
   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'"),
@@ -899,8 +1018,14 @@ 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);
     }
@@ -970,7 +1095,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");
@@ -994,7 +1131,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')")
     },
@@ -1150,7 +1287,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.`
       }
     ]
   };
@@ -1161,7 +1298,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.`
       }
     ]
   };
@@ -1544,7 +1681,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 {
@@ -1554,11 +1691,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);
 }
@@ -1621,13 +1763,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") };
@@ -1669,7 +1813,7 @@ 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)"),
@@ -1681,17 +1825,27 @@ function registerTlsTools(server) {
     { 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."
               }
             ]
           };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/caddy-mcp",
-  "version": "2.5.2",
+  "version": "2.5.3",
   "mcpName": "io.github.YawLabs/caddy-mcp",
   "description": "Caddy MCP server for Claude Code, Cursor, and any MCP client: admin API, config, routes, reverse proxy, TLS, PKI, metrics",
   "license": "MIT",