@yawlabs/caddy-mcp 2.2.0 → 2.3.0

package/README.md

@@ -78,12 +78,29 @@ That's it. Now ask your AI assistant:
 
 | Environment variable | Default | Description |
 |---|---|---|
-| `CADDY_ADMIN_URL` | `http://localhost:2019` | Caddy admin API URL. Set to `http://caddy:2019` inside Docker, or an https URL for remote admin. |
+| `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. |
 
+**Unix socket admin endpoints:**
+
+Caddy's recommended hardening is to move the admin API off a loopback port and
+onto a unix socket, where access is governed by filesystem permissions:
+
+```
+{
+  admin unix//var/run/caddy-admin.sock
+}
+```
+
+Point `CADDY_ADMIN_URL` at the same path (`unix:///var/run/caddy-admin.sock`)
+and requests are sent over the socket instead of TCP. The process running
+caddy-mcp needs read/write permission on the socket file. `CADDY_API_TOKEN`
+still applies if you have auth in front of the endpoint.
+
 **Alternate MCP clients:**
 
 | Client | Config file |
@@ -217,6 +234,17 @@ Browsable read-only data — MCP clients can fetch these directly without a tool
 - You have `admin.listen` or `admin.origins` restrictions set in your Caddy config, or you're missing an `Authorization` header.
 - Set `CADDY_API_TOKEN` in your MCP config env if Caddy expects a Bearer token.
 
+**`SIGUSR1` / `systemctl reload caddy` stops reloading the Caddyfile**
+
+- Expected, and not caused by a bug here. Since Caddy 2.11.1, `SIGUSR1` reloads
+  from the file on disk **only if the config has never been changed through the
+  admin API**. The first write from caddy-mcp (or any other API client) makes
+  Caddy consider the running config API-owned, and `SIGUSR1` becomes a no-op.
+- Pick one owner per instance. If the Caddyfile is the source of truth, use
+  caddy-mcp read-only tools (`caddy_status`, `caddy_list_routes`, `caddy_adapt`)
+  and reload from the file. If caddy-mcp owns the config, apply changes with
+  `caddy_load` instead of `SIGUSR1`.
+
 **Windows: MCP server doesn't start**
 
 - Use the `cmd /c npx ...` pattern from the Quick start section. Node 20+ can't spawn `.cmd` files directly.
@@ -224,7 +252,9 @@ Browsable read-only data — MCP clients can fetch these directly without a tool
 ## Requirements
 
 - Node.js 20+
-- Caddy 2.x with admin API enabled (default: `localhost:2019`)
+- Caddy 2.x with admin API enabled (default: `localhost:2019`). Verified against
+  Caddy 2.11.4; the `@id` write path relies on `PATCH` semantics that the live
+  integration suite pins per release.
 
 ## Contributing
 
@@ -235,7 +265,7 @@ npm install
 npm run lint       # Biome check
 npm run lint:fix   # Auto-fix
 npm run build      # tsup bundle
-npm test           # Vitest (230 unit tests; +8 live-Caddy integration tests gated by CADDY_MCP_INTEGRATION=1)
+npm test           # Vitest (357 unit tests, +9 POSIX-only unix-socket tests; +13 live-Caddy integration tests gated by CADDY_MCP_INTEGRATION=1)
 npm run typecheck  # tsc --noEmit
 ```
 

package/dist/index.js

@@ -6,6 +6,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/api.ts
+import { request as httpRequest } from "http";
 var DEFAULT_URL = "http://localhost:2019";
 var TIMEOUT = 1e4;
 var RETRY_BASE_MS = 100;
@@ -45,6 +46,15 @@ function invalidateRelated(path) {
 function getBaseUrl() {
   return (process.env.CADDY_ADMIN_URL || DEFAULT_URL).replace(/\/+$/, "");
 }
+function getUnixSocketPath() {
+  const raw = (process.env.CADDY_ADMIN_URL || "").trim();
+  if (!raw) return void 0;
+  const urlForm = /^unix:\/\/(\/.*)$/.exec(raw);
+  if (urlForm) return urlForm[1];
+  const caddyForm = /^unix\/(\/.*)$/.exec(raw);
+  if (caddyForm) return caddyForm[1];
+  return void 0;
+}
 var warnedRetryClamp = false;
 function getMaxRetries() {
   const raw = process.env.CADDY_MAX_RETRIES;
@@ -65,11 +75,12 @@ function getAdminOrigin() {
     return void 0;
   }
 }
-function getHeaders(contentType) {
+function getHeaders(contentType, overUnixSocket = false) {
   const headers = {};
   if (contentType) headers["Content-Type"] = contentType;
   const token = process.env.CADDY_API_TOKEN;
   if (token) headers.Authorization = `Bearer ${token}`;
+  if (overUnixSocket) return headers;
   const origin = getAdminOrigin();
   if (origin) headers.Origin = origin;
   return headers;
@@ -102,39 +113,85 @@ function isRetryableMethod(method, path) {
   if (method !== "POST") return true;
   return !path.startsWith("/config/") && !path.startsWith("/id/");
 }
-async function caddyRequest(method, path, body, contentType, timeout) {
+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) {
+  const malformed = getMalformedUnixUrl();
+  if (malformed) {
+    return {
+      ok: false,
+      status: 0,
+      error: `CADDY_ADMIN_URL="${malformed}" looks like a unix socket address but is not a recognized form. Use "unix:///absolute/path.sock" (URL form) or "unix//absolute/path.sock" (Caddy's own spelling). A single slash after "unix:", or a relative path, will not parse.`
+    };
+  }
   const maxRetries = getMaxRetries();
   let attempt = 0;
-  let res = await attemptRequest(method, path, body, contentType, timeout);
+  let res = await attemptRequest(method, path, body, contentType, timeout, rawStringBody);
   while (isRetryableMethod(method, path) && isTransientFailure(res) && attempt < maxRetries) {
     attempt++;
     const backoff = Math.min(RETRY_BASE_MS * 2 ** (attempt - 1), RETRY_MAX_DELAY_MS);
     const delay = backoff + Math.random() * RETRY_MAX_JITTER_MS;
     await sleep(delay);
-    res = await attemptRequest(method, path, body, contentType, timeout);
+    res = await attemptRequest(method, path, body, contentType, timeout, rawStringBody);
   }
   return res;
 }
-async function attemptRequest(method, path, body, contentType, timeout) {
+function sendViaUnixSocket(socketPath, path, method, headers, body, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const req = httpRequest({ socketPath, path, method, headers, 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
+        });
+      });
+    });
+    req.on("error", reject);
+    if (body !== void 0) req.write(body);
+    req.end();
+  });
+}
+async function sendViaFetch(url, method, headers, body, timeoutMs) {
+  const res = await fetch(url, {
+    method,
+    headers,
+    body,
+    signal: AbortSignal.timeout(timeoutMs)
+  });
+  return {
+    ok: res.ok,
+    status: res.status,
+    text: await res.text(),
+    etag: res.headers.get("ETag") || void 0
+  };
+}
+async function attemptRequest(method, path, body, contentType, timeout, rawStringBody = false) {
+  const socketPath = getUnixSocketPath();
   const url = `${getBaseUrl()}${path}`;
   const effectiveTimeout = timeout ?? getRequestTimeout();
   try {
     const hasBody = body !== void 0;
-    const headers = getHeaders(hasBody ? contentType || "application/json" : void 0);
+    const headers = getHeaders(hasBody ? contentType || "application/json" : void 0, socketPath !== void 0);
     const isConfigPath = path.startsWith("/config/") || path.startsWith("/id/");
     const isWrite = method !== "GET";
     if (isWrite && isConfigPath) {
       const cachedEtag = etagCache.get(path);
       if (cachedEtag) headers["If-Match"] = cachedEtag;
     }
-    const res = await fetch(url, {
-      method,
-      headers,
-      body: hasBody ? typeof body === "string" ? body : JSON.stringify(body) : void 0,
-      signal: AbortSignal.timeout(effectiveTimeout)
-    });
-    const text = await res.text();
-    const etag = res.headers.get("ETag") || void 0;
+    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 text = res.text;
+    const etag = res.etag;
     if (method === "GET" && etag && isConfigPath) {
       setEtag(path, etag);
     }
@@ -158,10 +215,11 @@ async function attemptRequest(method, path, body, contentType, timeout) {
         return { ok: false, status: res.status, error: `HTTP ${res.status}${hint}` };
       }
       if (res.status === 403 && /origin/i.test(text)) {
+        const hint = socketPath ? `Over a unix socket caddy-mcp deliberately sends no Origin header, because Caddy builds no default origin allowlist for a unix listener (sending one would fail against an empty list). Reaching here means admin.enforce_origin is enabled -- disable it, or move the admin endpoint to a TCP address.` : `Set CADDY_ADMIN_URL to the exact origin Caddy allows (default http://localhost:2019), or add this origin to the admin.origins list in Caddy's config.`;
         return {
           ok: false,
           status: 403,
-          error: `${text.trim()} -- Caddy's admin API rejected this client's Origin. Set CADDY_ADMIN_URL to the exact origin Caddy allows (default http://localhost:2019), or add this origin to the admin.origins list in Caddy's config.`
+          error: `${text.trim()} -- Caddy's admin API rejected this client's Origin. ${hint}`
         };
       }
       return { ok: false, status: res.status, error: text };
@@ -174,17 +232,25 @@ async function attemptRequest(method, path, body, contentType, timeout) {
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
+    if (socketPath && msg.includes("ENOENT")) {
+      return {
+        ok: false,
+        status: 0,
+        error: `No socket at ${socketPath} \u2014 check the path in CADDY_ADMIN_URL and that Caddy's admin endpoint is configured to listen on it.`
+      };
+    }
     if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
-      const baseUrl = getBaseUrl();
-      let origin = baseUrl;
-      try {
-        origin = new URL(baseUrl).origin;
-      } catch {
+      let target = socketPath ?? getBaseUrl();
+      if (!socketPath) {
+        try {
+          target = new URL(target).origin;
+        } catch {
+        }
       }
       return {
         ok: false,
         status: 0,
-        error: `Cannot connect to Caddy admin API at ${origin} \u2014 is Caddy running?`
+        error: `Cannot connect to Caddy admin API at ${target} \u2014 is Caddy running?`
       };
     }
     if (msg.includes("abort") || msg.includes("timeout")) {
@@ -242,12 +308,12 @@ function getLoadTimeout() {
   return floored;
 }
 async function loadConfig(config, contentType) {
-  const res = await caddyRequest("POST", "/load", config, contentType, getLoadTimeout());
+  const res = await caddyRequest("POST", "/load", config, contentType, getLoadTimeout(), true);
   if (res.ok) etagCache.clear();
   return res;
 }
 function adapt(config, adapter = "caddyfile") {
-  return caddyRequest("POST", "/adapt", config, `text/${adapter}`);
+  return caddyRequest("POST", "/adapt", config, `text/${adapter}`, void 0, true);
 }
 function stop() {
   return caddyRequest("POST", "/stop");
@@ -594,25 +660,83 @@ ${warnLines.join("\n")}` });
 import { z as z3 } from "zod";
 
 // src/snapshots.ts
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
 var MAX_SNAPSHOTS = 10;
 var store = [];
+function isSnapshotableConfig(data) {
+  return data !== null && typeof data === "object" && !Array.isArray(data);
+}
+var SNAPSHOT_FILE_RE = /^snapshot-(\d+)-([\w-]+)\.json$/;
+function snapshotDir() {
+  const dir = process.env.CADDY_MCP_SNAPSHOT_DIR?.trim();
+  return dir ? dir : void 0;
+}
+var hydrated = false;
+function hydrate() {
+  if (hydrated) return;
+  hydrated = true;
+  const dir = snapshotDir();
+  if (!dir || !existsSync(dir)) return;
+  try {
+    const names = readdirSync(dir).filter((n) => SNAPSHOT_FILE_RE.test(n)).sort().reverse().slice(0, MAX_SNAPSHOTS);
+    const loaded = [];
+    for (const name of names) {
+      const m = SNAPSHOT_FILE_RE.exec(name);
+      if (!m) continue;
+      try {
+        const config = JSON.parse(readFileSync(join(dir, name), "utf-8"));
+        if (!isSnapshotableConfig(config)) continue;
+        loaded.push({ config, timestamp: Number(m[1]), trigger: m[2] });
+      } catch {
+      }
+    }
+    loaded.sort((a, b) => b.timestamp - a.timestamp);
+    store.push(...loaded);
+  } catch {
+  }
+}
+function persist(snap) {
+  const dir = snapshotDir();
+  if (!dir) return;
+  try {
+    mkdirSync(dir, { recursive: true });
+    const safeTrigger = snap.trigger.replace(/[^\w-]/g, "_");
+    writeFileSync(
+      join(dir, `snapshot-${snap.timestamp}-${safeTrigger}.json`),
+      JSON.stringify(snap.config, null, 2),
+      "utf-8"
+    );
+    const files = readdirSync(dir).filter((n) => SNAPSHOT_FILE_RE.test(n)).sort().reverse();
+    for (const stale of files.slice(MAX_SNAPSHOTS)) {
+      rmSync(join(dir, stale), { force: true });
+    }
+  } catch {
+  }
+}
 function saveSnapshot(config, trigger) {
-  store.unshift({ config, timestamp: Date.now(), trigger });
+  hydrate();
+  let timestamp = Date.now();
+  if (store.length > 0 && timestamp <= store[0].timestamp) {
+    timestamp = store[0].timestamp + 1;
+  }
+  const snap = { config, timestamp, trigger };
+  store.unshift(snap);
   if (store.length > MAX_SNAPSHOTS) {
     store.length = MAX_SNAPSHOTS;
   }
+  persist(snap);
 }
 function listSnapshots() {
+  hydrate();
   return store;
 }
 function getSnapshot(index) {
+  hydrate();
   return store[index];
 }
 
 // src/tools/config.ts
-function isSnapshotableConfig(data) {
-  return data !== null && typeof data === "object" && !Array.isArray(data);
-}
 function registerConfigTools(server) {
   server.tool(
     "caddy_config_get",
@@ -692,7 +816,7 @@ function registerConfigTools(server) {
   );
   server.tool(
     "caddy_revert",
-    "Manage config snapshots for rollback. Snapshots are auto-captured before caddy_load and kept in-memory (last 10). 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 (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)"),
@@ -1235,6 +1359,7 @@ function buildTlsConfig(fields) {
   const issuer = { module: "acme" };
   if (fields.email) issuer.email = fields.email;
   if (fields.ca) issuer.ca = fields.ca;
+  if (fields.profile) issuer.profile = fields.profile;
   return {
     automation: {
       policies: [{ issuers: [issuer] }]
@@ -1268,6 +1393,7 @@ function mergeIssuerFields(existing, fields) {
   const issuer = automation.policies[0].issuers[0];
   if (fields.email !== void 0) issuer.email = fields.email;
   if (fields.ca !== void 0) issuer.ca = fields.ca;
+  if (fields.profile !== void 0) issuer.profile = fields.profile;
   return merged;
 }
 function validateIssuerShape(tls) {
@@ -1338,47 +1464,63 @@ async function safeFallback(label, patchRes, fields) {
     };
   }
   const merged = mergeIssuerFields(getRes.data, fields);
-  const putRes = await configPut("apps/tls", merged);
-  if (putRes.ok) return { kind: "ok" };
-  return { kind: "tool-error", result: bothErrors(label, patchRes, putRes, "PUT") };
+  const mergeRes = await configPatch("apps/tls", merged);
+  if (mergeRes.ok) return { kind: "ok" };
+  return { kind: "tool-error", result: bothErrors(label, patchRes, mergeRes, "PATCH apps/tls") };
+}
+async function setIssuerField(field, value, label) {
+  const patchRes = await configPatch(`apps/tls/automation/policies/0/issuers/0/${field}`, value);
+  const ok = { content: [{ type: "text", text: `${label} set to: ${value}` }] };
+  if (patchRes.ok) return ok;
+  const outcome = await safeFallback(label, patchRes, { [field]: value });
+  return outcome.kind === "ok" ? ok : outcome.result;
+}
+function missingArgError(text) {
+  return { isError: true, content: [{ type: "text", text: `Error: ${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. Works on both fresh and existing Caddy instances.",
+    "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 -- on a multi-policy TLS config, edit the intended policy with caddy_config_set instead.",
     {
-      action: z5.enum(["status", "set_email", "set_acme_ca"]).describe("Action to perform"),
+      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)")
+      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."
+      )
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    async ({ action, email, ca }) => {
+    async ({ action, email, ca, profile }) => {
       if (action === "status") {
         return formatResult(await configGet("apps/tls"));
       }
-      if (action === "set_email") {
-        if (!email)
+      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) {
           return {
-            isError: true,
-            content: [{ type: "text", text: "Error: email is required for set_email action" }]
+            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."
+              }
+            ]
           };
-        const patchRes = await configPatch("apps/tls/automation/policies/0/issuers/0/email", email);
-        if (patchRes.ok) return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
-        const outcome = await safeFallback("ACME email", patchRes, { email });
-        if (outcome.kind === "ok") return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
-        return outcome.result;
+        }
+        return formatResult(echRes);
+      }
+      if (action === "set_email") {
+        if (!email) return missingArgError("email is required for set_email action");
+        return setIssuerField("email", email, "ACME email");
       }
       if (action === "set_acme_ca") {
-        if (!ca)
-          return {
-            isError: true,
-            content: [{ type: "text", text: "Error: ca is required for set_acme_ca action" }]
-          };
-        const patchRes = await configPatch("apps/tls/automation/policies/0/issuers/0/ca", ca);
-        if (patchRes.ok) return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
-        const outcome = await safeFallback("ACME CA", patchRes, { ca });
-        if (outcome.kind === "ok") return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
-        return outcome.result;
+        if (!ca) return missingArgError("ca is required for set_acme_ca action");
+        return setIssuerField("ca", ca, "ACME CA");
+      }
+      if (action === "set_acme_profile") {
+        if (!profile) return missingArgError("profile is required for set_acme_profile action");
+        return setIssuerField("profile", profile, "ACME profile");
       }
       return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
     }

package/dist/server.js

@@ -4,6 +4,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/api.ts
+import { request as httpRequest } from "http";
 var DEFAULT_URL = "http://localhost:2019";
 var TIMEOUT = 1e4;
 var RETRY_BASE_MS = 100;
@@ -43,6 +44,15 @@ function invalidateRelated(path) {
 function getBaseUrl() {
   return (process.env.CADDY_ADMIN_URL || DEFAULT_URL).replace(/\/+$/, "");
 }
+function getUnixSocketPath() {
+  const raw = (process.env.CADDY_ADMIN_URL || "").trim();
+  if (!raw) return void 0;
+  const urlForm = /^unix:\/\/(\/.*)$/.exec(raw);
+  if (urlForm) return urlForm[1];
+  const caddyForm = /^unix\/(\/.*)$/.exec(raw);
+  if (caddyForm) return caddyForm[1];
+  return void 0;
+}
 var warnedRetryClamp = false;
 function getMaxRetries() {
   const raw = process.env.CADDY_MAX_RETRIES;
@@ -63,11 +73,12 @@ function getAdminOrigin() {
     return void 0;
   }
 }
-function getHeaders(contentType) {
+function getHeaders(contentType, overUnixSocket = false) {
   const headers = {};
   if (contentType) headers["Content-Type"] = contentType;
   const token = process.env.CADDY_API_TOKEN;
   if (token) headers.Authorization = `Bearer ${token}`;
+  if (overUnixSocket) return headers;
   const origin = getAdminOrigin();
   if (origin) headers.Origin = origin;
   return headers;
@@ -100,39 +111,85 @@ function isRetryableMethod(method, path) {
   if (method !== "POST") return true;
   return !path.startsWith("/config/") && !path.startsWith("/id/");
 }
-async function caddyRequest(method, path, body, contentType, timeout) {
+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) {
+  const malformed = getMalformedUnixUrl();
+  if (malformed) {
+    return {
+      ok: false,
+      status: 0,
+      error: `CADDY_ADMIN_URL="${malformed}" looks like a unix socket address but is not a recognized form. Use "unix:///absolute/path.sock" (URL form) or "unix//absolute/path.sock" (Caddy's own spelling). A single slash after "unix:", or a relative path, will not parse.`
+    };
+  }
   const maxRetries = getMaxRetries();
   let attempt = 0;
-  let res = await attemptRequest(method, path, body, contentType, timeout);
+  let res = await attemptRequest(method, path, body, contentType, timeout, rawStringBody);
   while (isRetryableMethod(method, path) && isTransientFailure(res) && attempt < maxRetries) {
     attempt++;
     const backoff = Math.min(RETRY_BASE_MS * 2 ** (attempt - 1), RETRY_MAX_DELAY_MS);
     const delay = backoff + Math.random() * RETRY_MAX_JITTER_MS;
     await sleep(delay);
-    res = await attemptRequest(method, path, body, contentType, timeout);
+    res = await attemptRequest(method, path, body, contentType, timeout, rawStringBody);
   }
   return res;
 }
-async function attemptRequest(method, path, body, contentType, timeout) {
+function sendViaUnixSocket(socketPath, path, method, headers, body, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const req = httpRequest({ socketPath, path, method, headers, 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
+        });
+      });
+    });
+    req.on("error", reject);
+    if (body !== void 0) req.write(body);
+    req.end();
+  });
+}
+async function sendViaFetch(url, method, headers, body, timeoutMs) {
+  const res = await fetch(url, {
+    method,
+    headers,
+    body,
+    signal: AbortSignal.timeout(timeoutMs)
+  });
+  return {
+    ok: res.ok,
+    status: res.status,
+    text: await res.text(),
+    etag: res.headers.get("ETag") || void 0
+  };
+}
+async function attemptRequest(method, path, body, contentType, timeout, rawStringBody = false) {
+  const socketPath = getUnixSocketPath();
   const url = `${getBaseUrl()}${path}`;
   const effectiveTimeout = timeout ?? getRequestTimeout();
   try {
     const hasBody = body !== void 0;
-    const headers = getHeaders(hasBody ? contentType || "application/json" : void 0);
+    const headers = getHeaders(hasBody ? contentType || "application/json" : void 0, socketPath !== void 0);
     const isConfigPath = path.startsWith("/config/") || path.startsWith("/id/");
     const isWrite = method !== "GET";
     if (isWrite && isConfigPath) {
       const cachedEtag = etagCache.get(path);
       if (cachedEtag) headers["If-Match"] = cachedEtag;
     }
-    const res = await fetch(url, {
-      method,
-      headers,
-      body: hasBody ? typeof body === "string" ? body : JSON.stringify(body) : void 0,
-      signal: AbortSignal.timeout(effectiveTimeout)
-    });
-    const text = await res.text();
-    const etag = res.headers.get("ETag") || void 0;
+    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 text = res.text;
+    const etag = res.etag;
     if (method === "GET" && etag && isConfigPath) {
       setEtag(path, etag);
     }
@@ -156,10 +213,11 @@ async function attemptRequest(method, path, body, contentType, timeout) {
         return { ok: false, status: res.status, error: `HTTP ${res.status}${hint}` };
       }
       if (res.status === 403 && /origin/i.test(text)) {
+        const hint = socketPath ? `Over a unix socket caddy-mcp deliberately sends no Origin header, because Caddy builds no default origin allowlist for a unix listener (sending one would fail against an empty list). Reaching here means admin.enforce_origin is enabled -- disable it, or move the admin endpoint to a TCP address.` : `Set CADDY_ADMIN_URL to the exact origin Caddy allows (default http://localhost:2019), or add this origin to the admin.origins list in Caddy's config.`;
         return {
           ok: false,
           status: 403,
-          error: `${text.trim()} -- Caddy's admin API rejected this client's Origin. Set CADDY_ADMIN_URL to the exact origin Caddy allows (default http://localhost:2019), or add this origin to the admin.origins list in Caddy's config.`
+          error: `${text.trim()} -- Caddy's admin API rejected this client's Origin. ${hint}`
         };
       }
       return { ok: false, status: res.status, error: text };
@@ -172,17 +230,25 @@ async function attemptRequest(method, path, body, contentType, timeout) {
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
+    if (socketPath && msg.includes("ENOENT")) {
+      return {
+        ok: false,
+        status: 0,
+        error: `No socket at ${socketPath} \u2014 check the path in CADDY_ADMIN_URL and that Caddy's admin endpoint is configured to listen on it.`
+      };
+    }
     if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
-      const baseUrl = getBaseUrl();
-      let origin = baseUrl;
-      try {
-        origin = new URL(baseUrl).origin;
-      } catch {
+      let target = socketPath ?? getBaseUrl();
+      if (!socketPath) {
+        try {
+          target = new URL(target).origin;
+        } catch {
+        }
       }
       return {
         ok: false,
         status: 0,
-        error: `Cannot connect to Caddy admin API at ${origin} \u2014 is Caddy running?`
+        error: `Cannot connect to Caddy admin API at ${target} \u2014 is Caddy running?`
       };
     }
     if (msg.includes("abort") || msg.includes("timeout")) {
@@ -240,12 +306,12 @@ function getLoadTimeout() {
   return floored;
 }
 async function loadConfig(config, contentType) {
-  const res = await caddyRequest("POST", "/load", config, contentType, getLoadTimeout());
+  const res = await caddyRequest("POST", "/load", config, contentType, getLoadTimeout(), true);
   if (res.ok) etagCache.clear();
   return res;
 }
 function adapt(config, adapter = "caddyfile") {
-  return caddyRequest("POST", "/adapt", config, `text/${adapter}`);
+  return caddyRequest("POST", "/adapt", config, `text/${adapter}`, void 0, true);
 }
 function stop() {
   return caddyRequest("POST", "/stop");
@@ -592,25 +658,83 @@ ${warnLines.join("\n")}` });
 import { z as z3 } from "zod";
 
 // src/snapshots.ts
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
 var MAX_SNAPSHOTS = 10;
 var store = [];
+function isSnapshotableConfig(data) {
+  return data !== null && typeof data === "object" && !Array.isArray(data);
+}
+var SNAPSHOT_FILE_RE = /^snapshot-(\d+)-([\w-]+)\.json$/;
+function snapshotDir() {
+  const dir = process.env.CADDY_MCP_SNAPSHOT_DIR?.trim();
+  return dir ? dir : void 0;
+}
+var hydrated = false;
+function hydrate() {
+  if (hydrated) return;
+  hydrated = true;
+  const dir = snapshotDir();
+  if (!dir || !existsSync(dir)) return;
+  try {
+    const names = readdirSync(dir).filter((n) => SNAPSHOT_FILE_RE.test(n)).sort().reverse().slice(0, MAX_SNAPSHOTS);
+    const loaded = [];
+    for (const name of names) {
+      const m = SNAPSHOT_FILE_RE.exec(name);
+      if (!m) continue;
+      try {
+        const config = JSON.parse(readFileSync(join(dir, name), "utf-8"));
+        if (!isSnapshotableConfig(config)) continue;
+        loaded.push({ config, timestamp: Number(m[1]), trigger: m[2] });
+      } catch {
+      }
+    }
+    loaded.sort((a, b) => b.timestamp - a.timestamp);
+    store.push(...loaded);
+  } catch {
+  }
+}
+function persist(snap) {
+  const dir = snapshotDir();
+  if (!dir) return;
+  try {
+    mkdirSync(dir, { recursive: true });
+    const safeTrigger = snap.trigger.replace(/[^\w-]/g, "_");
+    writeFileSync(
+      join(dir, `snapshot-${snap.timestamp}-${safeTrigger}.json`),
+      JSON.stringify(snap.config, null, 2),
+      "utf-8"
+    );
+    const files = readdirSync(dir).filter((n) => SNAPSHOT_FILE_RE.test(n)).sort().reverse();
+    for (const stale of files.slice(MAX_SNAPSHOTS)) {
+      rmSync(join(dir, stale), { force: true });
+    }
+  } catch {
+  }
+}
 function saveSnapshot(config, trigger) {
-  store.unshift({ config, timestamp: Date.now(), trigger });
+  hydrate();
+  let timestamp = Date.now();
+  if (store.length > 0 && timestamp <= store[0].timestamp) {
+    timestamp = store[0].timestamp + 1;
+  }
+  const snap = { config, timestamp, trigger };
+  store.unshift(snap);
   if (store.length > MAX_SNAPSHOTS) {
     store.length = MAX_SNAPSHOTS;
   }
+  persist(snap);
 }
 function listSnapshots() {
+  hydrate();
   return store;
 }
 function getSnapshot(index) {
+  hydrate();
   return store[index];
 }
 
 // src/tools/config.ts
-function isSnapshotableConfig(data) {
-  return data !== null && typeof data === "object" && !Array.isArray(data);
-}
 function registerConfigTools(server) {
   server.tool(
     "caddy_config_get",
@@ -690,7 +814,7 @@ function registerConfigTools(server) {
   );
   server.tool(
     "caddy_revert",
-    "Manage config snapshots for rollback. Snapshots are auto-captured before caddy_load and kept in-memory (last 10). 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 (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)"),
@@ -1233,6 +1357,7 @@ function buildTlsConfig(fields) {
   const issuer = { module: "acme" };
   if (fields.email) issuer.email = fields.email;
   if (fields.ca) issuer.ca = fields.ca;
+  if (fields.profile) issuer.profile = fields.profile;
   return {
     automation: {
       policies: [{ issuers: [issuer] }]
@@ -1266,6 +1391,7 @@ function mergeIssuerFields(existing, fields) {
   const issuer = automation.policies[0].issuers[0];
   if (fields.email !== void 0) issuer.email = fields.email;
   if (fields.ca !== void 0) issuer.ca = fields.ca;
+  if (fields.profile !== void 0) issuer.profile = fields.profile;
   return merged;
 }
 function validateIssuerShape(tls) {
@@ -1336,47 +1462,63 @@ async function safeFallback(label, patchRes, fields) {
     };
   }
   const merged = mergeIssuerFields(getRes.data, fields);
-  const putRes = await configPut("apps/tls", merged);
-  if (putRes.ok) return { kind: "ok" };
-  return { kind: "tool-error", result: bothErrors(label, patchRes, putRes, "PUT") };
+  const mergeRes = await configPatch("apps/tls", merged);
+  if (mergeRes.ok) return { kind: "ok" };
+  return { kind: "tool-error", result: bothErrors(label, patchRes, mergeRes, "PATCH apps/tls") };
+}
+async function setIssuerField(field, value, label) {
+  const patchRes = await configPatch(`apps/tls/automation/policies/0/issuers/0/${field}`, value);
+  const ok = { content: [{ type: "text", text: `${label} set to: ${value}` }] };
+  if (patchRes.ok) return ok;
+  const outcome = await safeFallback(label, patchRes, { [field]: value });
+  return outcome.kind === "ok" ? ok : outcome.result;
+}
+function missingArgError(text) {
+  return { isError: true, content: [{ type: "text", text: `Error: ${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. Works on both fresh and existing Caddy instances.",
+    "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 -- on a multi-policy TLS config, edit the intended policy with caddy_config_set instead.",
     {
-      action: z5.enum(["status", "set_email", "set_acme_ca"]).describe("Action to perform"),
+      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)")
+      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."
+      )
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    async ({ action, email, ca }) => {
+    async ({ action, email, ca, profile }) => {
       if (action === "status") {
         return formatResult(await configGet("apps/tls"));
       }
-      if (action === "set_email") {
-        if (!email)
+      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) {
           return {
-            isError: true,
-            content: [{ type: "text", text: "Error: email is required for set_email action" }]
+            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."
+              }
+            ]
           };
-        const patchRes = await configPatch("apps/tls/automation/policies/0/issuers/0/email", email);
-        if (patchRes.ok) return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
-        const outcome = await safeFallback("ACME email", patchRes, { email });
-        if (outcome.kind === "ok") return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
-        return outcome.result;
+        }
+        return formatResult(echRes);
+      }
+      if (action === "set_email") {
+        if (!email) return missingArgError("email is required for set_email action");
+        return setIssuerField("email", email, "ACME email");
       }
       if (action === "set_acme_ca") {
-        if (!ca)
-          return {
-            isError: true,
-            content: [{ type: "text", text: "Error: ca is required for set_acme_ca action" }]
-          };
-        const patchRes = await configPatch("apps/tls/automation/policies/0/issuers/0/ca", ca);
-        if (patchRes.ok) return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
-        const outcome = await safeFallback("ACME CA", patchRes, { ca });
-        if (outcome.kind === "ok") return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
-        return outcome.result;
+        if (!ca) return missingArgError("ca is required for set_acme_ca action");
+        return setIssuerField("ca", ca, "ACME CA");
+      }
+      if (action === "set_acme_profile") {
+        if (!profile) return missingArgError("profile is required for set_acme_profile action");
+        return setIssuerField("profile", profile, "ACME profile");
       }
       return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
     }

package/dist/snapshots.d.ts

@@ -3,6 +3,16 @@ export interface Snapshot {
     timestamp: number;
     trigger: string;
 }
+/**
+ * A snapshot must be re-applyable via /load, which requires a JSON object root.
+ * Strings, arrays, null, and primitives are not valid Caddy configs -- refuse to
+ * capture them so a later `caddy_revert apply` can't replay garbage.
+ *
+ * Exported because both entry points into the ring have to agree: the in-memory
+ * save path in tools/config.ts, and the rehydration path below. A file on disk
+ * that merely parses as JSON is not automatically a config.
+ */
+export declare function isSnapshotableConfig(data: unknown): data is Record<string, unknown>;
 export declare function saveSnapshot(config: unknown, trigger: string): void;
 export declare function listSnapshots(): readonly Snapshot[];
 export declare function getSnapshot(index: number): Snapshot | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/caddy-mcp",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "mcpName": "io.github.YawLabs/caddy-mcp",
   "description": "MCP server for managing Caddy web servers via the admin API",
   "license": "MIT",