@yawlabs/caddy-mcp 2.2.0 → 2.3.1

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}` }] };
     }