@yawlabs/caddy-mcp 0.3.1 → 1.0.1

package/README.md

@@ -5,7 +5,7 @@
 [![GitHub stars](https://img.shields.io/github/stars/YawLabs/caddy-mcp)](https://github.com/YawLabs/caddy-mcp/stargazers)
 [![CI](https://github.com/YawLabs/caddy-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/YawLabs/caddy-mcp/actions/workflows/ci.yml) [![Release](https://github.com/YawLabs/caddy-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/YawLabs/caddy-mcp/actions/workflows/release.yml)
 
-**Manage Caddy web servers from Claude Code, Cursor, and any MCP client.** 17 tools + 4 resources covering every endpoint of Caddy's admin API — config, routes, reverse proxies, TLS, PKI, metrics.
+**Manage Caddy web servers from Claude Code, Cursor, and any MCP client.** 18 tools + 4 resources covering every endpoint of Caddy's admin API — config, routes, reverse proxies, TLS, PKI, metrics, snapshots.
 
 Built and maintained by [Yaw Labs](https://yaw.sh).
 
@@ -81,6 +81,7 @@ 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. |
 | `CADDY_API_TOKEN` | (none) | Optional Bearer token for authenticated admin endpoints. Only needed if you've configured Caddy with auth. |
+| `CADDY_MAX_RETRIES` | `2` | Number of retries on transient failures (5xx, network errors). 4xx and 412 never retry. Hard-capped at 5. Set to `0` to disable. |
 
 **Alternate MCP clients:**
 
@@ -96,13 +97,14 @@ Use the same JSON block shown above in any of these.
 
 ## Tools
 
-### Config management (5)
+### 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_delete** — Delete config at a path.
 - **caddy_config_by_id** — Get/set/delete config by `@id` tag — much easier than navigating deep paths.
-- **caddy_load** — Replace the entire config atomically. 60-second timeout for cert provisioning.
+- **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.
 
 ### Route operations (4)
 
@@ -212,7 +214,7 @@ npm install
 npm run lint       # Biome check
 npm run lint:fix   # Auto-fix
 npm run build      # tsup bundle
-npm test           # Vitest (83 tests)
+npm test           # Vitest (106 unit tests; +7 live-Caddy integration tests gated by CADDY_MCP_INTEGRATION=1)
 npm run typecheck  # tsc --noEmit
 ```
 

package/dist/index.js

@@ -8,6 +8,10 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // src/api.ts
 var DEFAULT_URL = "http://localhost:2019";
 var TIMEOUT = 1e4;
+var RETRY_BASE_MS = 100;
+var RETRY_MAX_DELAY_MS = 2e3;
+var RETRY_MAX_JITTER_MS = 50;
+var RETRY_HARD_CAP = 5;
 var etagCache = /* @__PURE__ */ new Map();
 var MAX_ETAG_CACHE = 256;
 function setEtag(path, etag) {
@@ -20,6 +24,13 @@ function setEtag(path, etag) {
 function getBaseUrl() {
   return (process.env.CADDY_ADMIN_URL || DEFAULT_URL).replace(/\/+$/, "");
 }
+function getMaxRetries() {
+  const raw = process.env.CADDY_MAX_RETRIES;
+  if (raw === void 0) return 2;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return 2;
+  return Math.min(Math.floor(n), RETRY_HARD_CAP);
+}
 function getHeaders(contentType) {
   const headers = {};
   if (contentType) headers["Content-Type"] = contentType;
@@ -30,7 +41,39 @@ function getHeaders(contentType) {
 function normalizePath(path) {
   return path.replace(/^\/?(config(\/|$))?/, "");
 }
+function rejectTraversal(path) {
+  if (/(^|\/)\.\.(\/|$)/.test(path)) {
+    return {
+      ok: false,
+      status: 0,
+      error: `Invalid path "${path}": '..' segments are not allowed`
+    };
+  }
+  return null;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, 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;
+}
 async function caddyRequest(method, path, body, contentType, timeout) {
+  const maxRetries = getMaxRetries();
+  let attempt = 0;
+  let res = await attemptRequest(method, path, body, contentType, timeout);
+  while (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);
+  }
+  return res;
+}
+async function attemptRequest(method, path, body, contentType, timeout) {
   const url = `${getBaseUrl()}${path}`;
   const effectiveTimeout = timeout ?? TIMEOUT;
   try {
@@ -96,22 +139,32 @@ async function caddyRequest(method, path, body, contentType, timeout) {
 }
 function configGet(path = "") {
   const normalized = normalizePath(path);
+  const bad = rejectTraversal(normalized);
+  if (bad) return Promise.resolve(bad);
   return caddyRequest("GET", `/config/${normalized}`);
 }
 function configPost(path, value) {
   const normalized = normalizePath(path);
+  const bad = rejectTraversal(normalized);
+  if (bad) return Promise.resolve(bad);
   return caddyRequest("POST", `/config/${normalized}`, value);
 }
 function configPut(path, value) {
   const normalized = normalizePath(path);
+  const bad = rejectTraversal(normalized);
+  if (bad) return Promise.resolve(bad);
   return caddyRequest("PUT", `/config/${normalized}`, value);
 }
 function configPatch(path, value) {
   const normalized = normalizePath(path);
+  const bad = rejectTraversal(normalized);
+  if (bad) return Promise.resolve(bad);
   return caddyRequest("PATCH", `/config/${normalized}`, value);
 }
 function configDelete(path) {
   const normalized = normalizePath(path);
+  const bad = rejectTraversal(normalized);
+  if (bad) return Promise.resolve(bad);
   return caddyRequest("DELETE", `/config/${normalized}`);
 }
 var LOAD_TIMEOUT = 6e4;
@@ -136,14 +189,20 @@ function getPkiCertificates(ca = "local") {
   return caddyRequest("GET", `/pki/ca/${ca}/certificates`);
 }
 function configByIdGet(id, subpath = "") {
+  const bad = rejectTraversal(subpath);
+  if (bad) return Promise.resolve(bad);
   const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
   return caddyRequest("GET", path);
 }
 function configByIdSet(id, value, method = "PATCH", subpath = "") {
+  const bad = rejectTraversal(subpath);
+  if (bad) return Promise.resolve(bad);
   const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
   return caddyRequest(method, path, value);
 }
 function configByIdDelete(id, subpath = "") {
+  const bad = rejectTraversal(subpath);
+  if (bad) return Promise.resolve(bad);
   const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
   return caddyRequest("DELETE", path);
 }
@@ -235,6 +294,13 @@ function formatResult(res) {
 }
 
 // src/tools/adapt.ts
+function formatWarning(w) {
+  if (!w || typeof w !== "object") return `  - unknown: ${JSON.stringify(w)}`;
+  const obj = w;
+  const directive = typeof obj.directive === "string" ? obj.directive : "unknown";
+  const message = typeof obj.message === "string" ? obj.message : JSON.stringify(w);
+  return `  - ${directive}: ${message}`;
+}
 function registerAdaptTools(server) {
   server.tool(
     "caddy_adapt",
@@ -247,13 +313,12 @@ function registerAdaptTools(server) {
     async ({ config, adapter }) => {
       const res = await adapt(config, adapter);
       if (!res.ok) return formatResult(res);
-      const warnings = res.data?.warnings || [];
-      const result = res.data?.result;
+      const data = res.data ?? {};
+      const warnings = Array.isArray(data.warnings) ? data.warnings : [];
+      const result = data.result;
       const content = [];
       if (warnings.length > 0) {
-        const warnLines = warnings.map(
-          (w) => `  - ${w.directive || "unknown"}: ${w.message || JSON.stringify(w)}`
-        );
+        const warnLines = warnings.map(formatWarning);
         content.push({ type: "text", text: `Warnings:
 ${warnLines.join("\n")}` });
       }
@@ -268,6 +333,24 @@ ${warnLines.join("\n")}` });
 
 // src/tools/config.ts
 import { z as z2 } from "zod";
+
+// src/snapshots.ts
+var MAX_SNAPSHOTS = 10;
+var store = [];
+function saveSnapshot(config, trigger) {
+  store.unshift({ config, timestamp: Date.now(), trigger });
+  if (store.length > MAX_SNAPSHOTS) {
+    store.length = MAX_SNAPSHOTS;
+  }
+}
+function listSnapshots() {
+  return store;
+}
+function getSnapshot(index) {
+  return store[index];
+}
+
+// src/tools/config.ts
 function registerConfigTools(server) {
   server.tool(
     "caddy_config_get",
@@ -309,9 +392,85 @@ function registerConfigTools(server) {
     { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     async ({ config, format }) => {
       const contentType = format === "caddyfile" ? "text/caddyfile" : "application/json";
+      const current = await configGet();
+      if (current.ok && current.data !== void 0) {
+        saveSnapshot(current.data, "caddy_load");
+      }
       return formatResult(await loadConfig(config, contentType));
     }
   );
+  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).",
+    {
+      action: z2.enum(["list", "save", "apply"]).describe("Action to perform"),
+      index: z2.number().int().nonnegative().optional().default(0).describe("Snapshot index for 'apply' (0 = most recent, default)"),
+      confirm: z2.boolean().optional().default(false).describe("Must be true to actually apply a snapshot (safety)")
+    },
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    async ({ action, index, confirm }) => {
+      if (action === "list") {
+        const snaps = listSnapshots();
+        if (snaps.length === 0) {
+          return { content: [{ type: "text", text: "No snapshots available" }] };
+        }
+        const lines = snaps.map((s, i) => {
+          const when2 = new Date(s.timestamp).toISOString();
+          const size = JSON.stringify(s.config).length;
+          return `  [${i}] ${when2} trigger=${s.trigger} size=${size}B`;
+        });
+        return { content: [{ type: "text", text: `Snapshots:
+${lines.join("\n")}` }] };
+      }
+      if (action === "save") {
+        const current2 = await configGet();
+        if (!current2.ok) return formatResult(current2);
+        if (current2.data === void 0) {
+          return {
+            isError: true,
+            content: [{ type: "text", text: "Error: no config loaded to snapshot" }]
+          };
+        }
+        saveSnapshot(current2.data, "manual");
+        return { content: [{ type: "text", text: "Snapshot saved." }] };
+      }
+      if (!confirm) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Refusing to apply snapshot [${index}] without confirm=true. Re-run with confirm:true to proceed.`
+            }
+          ]
+        };
+      }
+      const snap = getSnapshot(index);
+      if (!snap) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Error: no snapshot at index ${index}. Use action='list' to see available snapshots.`
+            }
+          ]
+        };
+      }
+      const current = await configGet();
+      if (current.ok && current.data !== void 0) {
+        saveSnapshot(current.data, "caddy_revert");
+      }
+      const res = await loadConfig(snap.config, "application/json");
+      if (!res.ok) return formatResult(res);
+      const when = new Date(snap.timestamp).toISOString();
+      return {
+        content: [
+          { type: "text", text: `Reverted to snapshot [${index}] (${when}, trigger=${snap.trigger}).` }
+        ]
+      };
+    }
+  );
   server.tool(
     "caddy_config_by_id",
     "Access config by @id tag. Any config object with an '@id' field can be read, updated, or deleted by its ID instead of needing its full path. This is the recommended way to manage individual routes and config objects.",
@@ -349,6 +508,29 @@ function registerConfigTools(server) {
 
 // src/tools/operational.ts
 import { z as z3 } from "zod";
+function describeServer(raw) {
+  const listen = Array.isArray(raw.listen) ? raw.listen : [];
+  const routes = Array.isArray(raw.routes) ? raw.routes : [];
+  const hasExplicitTls = !!raw.tls_connection_policies;
+  const listensHttps = listen.some((l) => typeof l === "string" && l.includes(":443"));
+  const tls = hasExplicitTls ? "enabled" : listensHttps ? "auto (HTTPS)" : "off (HTTP only)";
+  const listenStr = listen.length > 0 ? listen.map(String).join(", ") : "default";
+  return `${routes.length} route(s), listen: ${listenStr}, TLS: ${tls}`;
+}
+function findAcmeEmail(policies) {
+  if (!Array.isArray(policies)) return void 0;
+  for (const rawPolicy of policies) {
+    if (!rawPolicy || typeof rawPolicy !== "object") continue;
+    const policy = rawPolicy;
+    if (!Array.isArray(policy.issuers)) continue;
+    for (const rawIssuer of policy.issuers) {
+      if (!rawIssuer || typeof rawIssuer !== "object") continue;
+      const issuer = rawIssuer;
+      if (typeof issuer.email === "string") return issuer.email;
+    }
+  }
+  return void 0;
+}
 function registerOperationalTools(server) {
   server.tool(
     "caddy_status",
@@ -358,32 +540,20 @@ function registerOperationalTools(server) {
     async () => {
       const res = await configGet();
       if (!res.ok) return formatResult(res);
-      const config = res.data || {};
-      const httpApp = config?.apps?.http;
-      const servers = httpApp?.servers || {};
+      const config = res.data ?? {};
+      const servers = config.apps?.http?.servers ?? {};
       const serverNames = Object.keys(servers);
       const lines = ["Caddy is running", ""];
       if (serverNames.length === 0) {
         lines.push("No HTTP servers configured");
       } else {
         for (const name of serverNames) {
-          const srv = servers[name];
-          const listen = srv.listen || [];
-          const routes = srv.routes || [];
-          const hasExplicitTls = !!srv.tls_connection_policies;
-          const listensHttps = listen.some((l) => l.includes(":443"));
-          const tls = hasExplicitTls ? "enabled" : listensHttps ? "auto (HTTPS)" : "off (HTTP only)";
-          lines.push(
-            `Server "${name}": ${routes.length} route(s), listen: ${listen.join(", ") || "default"}, TLS: ${tls}`
-          );
+          lines.push(`Server "${name}": ${describeServer(servers[name])}`);
         }
       }
-      const tlsApp = config?.apps?.tls;
-      if (tlsApp?.automation?.policies) {
-        const email = tlsApp.automation.policies.find((p) => p.issuers)?.issuers?.[0]?.email;
-        if (email) lines.push(`
+      const email = findAcmeEmail(config.apps?.tls?.automation?.policies);
+      if (email) lines.push(`
 ACME email: ${email}`);
-      }
       return { content: [{ type: "text", text: lines.join("\n") }] };
     }
   );
@@ -395,21 +565,12 @@ ACME email: ${email}`);
     async () => {
       const res = await configGet("apps/http/servers");
       if (!res.ok) return formatResult(res);
-      const servers = res.data || {};
+      const servers = res.data ?? {};
       const names = Object.keys(servers);
       if (names.length === 0) {
         return { content: [{ type: "text", text: "No HTTP servers configured" }] };
       }
-      const lines = [];
-      for (const name of names) {
-        const srv = servers[name];
-        const listen = srv.listen || [];
-        const routes = srv.routes || [];
-        const hasExplicitTls = !!srv.tls_connection_policies;
-        const listensHttps = listen.some((l) => l.includes(":443"));
-        const tls = hasExplicitTls ? "enabled" : listensHttps ? "auto (HTTPS)" : "off (HTTP only)";
-        lines.push(`  ${name}: ${routes.length} route(s), listen: ${listen.join(", ") || "default"}, TLS: ${tls}`);
-      }
+      const lines = names.map((name) => `  ${name}: ${describeServer(servers[name])}`);
       return {
         content: [{ type: "text", text: `HTTP Servers:
 ${lines.join("\n")}` }]
@@ -680,7 +841,7 @@ function registerRouteTools(server) {
   );
   server.tool(
     "caddy_remove_route",
-    "Remove a route. Target by @id (preferred \u2014 stable across reorderings) or by array index on a specific server. Uses ETags to prevent concurrent overwrites.",
+    "Remove a route. Target by @id (preferred \u2014 stable across reorderings) or by array index on a specific server. Index-based removal is a two-step read-then-delete and can race against concurrent edits; prefer @id when possible.",
     {
       id: z4.string().regex(/^[\w-]{1,128}$/).optional().describe("The @id of the route to remove (preferred \u2014 stable even if routes get reordered)"),
       index: z4.number().int().nonnegative().optional().describe("Zero-based index of the route in the server's routes array (only used if id is not provided)"),

package/dist/server.js

@@ -6,6 +6,10 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // src/api.ts
 var DEFAULT_URL = "http://localhost:2019";
 var TIMEOUT = 1e4;
+var RETRY_BASE_MS = 100;
+var RETRY_MAX_DELAY_MS = 2e3;
+var RETRY_MAX_JITTER_MS = 50;
+var RETRY_HARD_CAP = 5;
 var etagCache = /* @__PURE__ */ new Map();
 var MAX_ETAG_CACHE = 256;
 function setEtag(path, etag) {
@@ -18,6 +22,13 @@ function setEtag(path, etag) {
 function getBaseUrl() {
   return (process.env.CADDY_ADMIN_URL || DEFAULT_URL).replace(/\/+$/, "");
 }
+function getMaxRetries() {
+  const raw = process.env.CADDY_MAX_RETRIES;
+  if (raw === void 0) return 2;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return 2;
+  return Math.min(Math.floor(n), RETRY_HARD_CAP);
+}
 function getHeaders(contentType) {
   const headers = {};
   if (contentType) headers["Content-Type"] = contentType;
@@ -28,7 +39,39 @@ function getHeaders(contentType) {
 function normalizePath(path) {
   return path.replace(/^\/?(config(\/|$))?/, "");
 }
+function rejectTraversal(path) {
+  if (/(^|\/)\.\.(\/|$)/.test(path)) {
+    return {
+      ok: false,
+      status: 0,
+      error: `Invalid path "${path}": '..' segments are not allowed`
+    };
+  }
+  return null;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, 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;
+}
 async function caddyRequest(method, path, body, contentType, timeout) {
+  const maxRetries = getMaxRetries();
+  let attempt = 0;
+  let res = await attemptRequest(method, path, body, contentType, timeout);
+  while (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);
+  }
+  return res;
+}
+async function attemptRequest(method, path, body, contentType, timeout) {
   const url = `${getBaseUrl()}${path}`;
   const effectiveTimeout = timeout ?? TIMEOUT;
   try {
@@ -94,22 +137,32 @@ async function caddyRequest(method, path, body, contentType, timeout) {
 }
 function configGet(path = "") {
   const normalized = normalizePath(path);
+  const bad = rejectTraversal(normalized);
+  if (bad) return Promise.resolve(bad);
   return caddyRequest("GET", `/config/${normalized}`);
 }
 function configPost(path, value) {
   const normalized = normalizePath(path);
+  const bad = rejectTraversal(normalized);
+  if (bad) return Promise.resolve(bad);
   return caddyRequest("POST", `/config/${normalized}`, value);
 }
 function configPut(path, value) {
   const normalized = normalizePath(path);
+  const bad = rejectTraversal(normalized);
+  if (bad) return Promise.resolve(bad);
   return caddyRequest("PUT", `/config/${normalized}`, value);
 }
 function configPatch(path, value) {
   const normalized = normalizePath(path);
+  const bad = rejectTraversal(normalized);
+  if (bad) return Promise.resolve(bad);
   return caddyRequest("PATCH", `/config/${normalized}`, value);
 }
 function configDelete(path) {
   const normalized = normalizePath(path);
+  const bad = rejectTraversal(normalized);
+  if (bad) return Promise.resolve(bad);
   return caddyRequest("DELETE", `/config/${normalized}`);
 }
 var LOAD_TIMEOUT = 6e4;
@@ -134,14 +187,20 @@ function getPkiCertificates(ca = "local") {
   return caddyRequest("GET", `/pki/ca/${ca}/certificates`);
 }
 function configByIdGet(id, subpath = "") {
+  const bad = rejectTraversal(subpath);
+  if (bad) return Promise.resolve(bad);
   const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
   return caddyRequest("GET", path);
 }
 function configByIdSet(id, value, method = "PATCH", subpath = "") {
+  const bad = rejectTraversal(subpath);
+  if (bad) return Promise.resolve(bad);
   const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
   return caddyRequest(method, path, value);
 }
 function configByIdDelete(id, subpath = "") {
+  const bad = rejectTraversal(subpath);
+  if (bad) return Promise.resolve(bad);
   const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
   return caddyRequest("DELETE", path);
 }
@@ -233,6 +292,13 @@ function formatResult(res) {
 }
 
 // src/tools/adapt.ts
+function formatWarning(w) {
+  if (!w || typeof w !== "object") return `  - unknown: ${JSON.stringify(w)}`;
+  const obj = w;
+  const directive = typeof obj.directive === "string" ? obj.directive : "unknown";
+  const message = typeof obj.message === "string" ? obj.message : JSON.stringify(w);
+  return `  - ${directive}: ${message}`;
+}
 function registerAdaptTools(server) {
   server.tool(
     "caddy_adapt",
@@ -245,13 +311,12 @@ function registerAdaptTools(server) {
     async ({ config, adapter }) => {
       const res = await adapt(config, adapter);
       if (!res.ok) return formatResult(res);
-      const warnings = res.data?.warnings || [];
-      const result = res.data?.result;
+      const data = res.data ?? {};
+      const warnings = Array.isArray(data.warnings) ? data.warnings : [];
+      const result = data.result;
       const content = [];
       if (warnings.length > 0) {
-        const warnLines = warnings.map(
-          (w) => `  - ${w.directive || "unknown"}: ${w.message || JSON.stringify(w)}`
-        );
+        const warnLines = warnings.map(formatWarning);
         content.push({ type: "text", text: `Warnings:
 ${warnLines.join("\n")}` });
       }
@@ -266,6 +331,24 @@ ${warnLines.join("\n")}` });
 
 // src/tools/config.ts
 import { z as z2 } from "zod";
+
+// src/snapshots.ts
+var MAX_SNAPSHOTS = 10;
+var store = [];
+function saveSnapshot(config, trigger) {
+  store.unshift({ config, timestamp: Date.now(), trigger });
+  if (store.length > MAX_SNAPSHOTS) {
+    store.length = MAX_SNAPSHOTS;
+  }
+}
+function listSnapshots() {
+  return store;
+}
+function getSnapshot(index) {
+  return store[index];
+}
+
+// src/tools/config.ts
 function registerConfigTools(server) {
   server.tool(
     "caddy_config_get",
@@ -307,9 +390,85 @@ function registerConfigTools(server) {
     { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     async ({ config, format }) => {
       const contentType = format === "caddyfile" ? "text/caddyfile" : "application/json";
+      const current = await configGet();
+      if (current.ok && current.data !== void 0) {
+        saveSnapshot(current.data, "caddy_load");
+      }
       return formatResult(await loadConfig(config, contentType));
     }
   );
+  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).",
+    {
+      action: z2.enum(["list", "save", "apply"]).describe("Action to perform"),
+      index: z2.number().int().nonnegative().optional().default(0).describe("Snapshot index for 'apply' (0 = most recent, default)"),
+      confirm: z2.boolean().optional().default(false).describe("Must be true to actually apply a snapshot (safety)")
+    },
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    async ({ action, index, confirm }) => {
+      if (action === "list") {
+        const snaps = listSnapshots();
+        if (snaps.length === 0) {
+          return { content: [{ type: "text", text: "No snapshots available" }] };
+        }
+        const lines = snaps.map((s, i) => {
+          const when2 = new Date(s.timestamp).toISOString();
+          const size = JSON.stringify(s.config).length;
+          return `  [${i}] ${when2} trigger=${s.trigger} size=${size}B`;
+        });
+        return { content: [{ type: "text", text: `Snapshots:
+${lines.join("\n")}` }] };
+      }
+      if (action === "save") {
+        const current2 = await configGet();
+        if (!current2.ok) return formatResult(current2);
+        if (current2.data === void 0) {
+          return {
+            isError: true,
+            content: [{ type: "text", text: "Error: no config loaded to snapshot" }]
+          };
+        }
+        saveSnapshot(current2.data, "manual");
+        return { content: [{ type: "text", text: "Snapshot saved." }] };
+      }
+      if (!confirm) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Refusing to apply snapshot [${index}] without confirm=true. Re-run with confirm:true to proceed.`
+            }
+          ]
+        };
+      }
+      const snap = getSnapshot(index);
+      if (!snap) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Error: no snapshot at index ${index}. Use action='list' to see available snapshots.`
+            }
+          ]
+        };
+      }
+      const current = await configGet();
+      if (current.ok && current.data !== void 0) {
+        saveSnapshot(current.data, "caddy_revert");
+      }
+      const res = await loadConfig(snap.config, "application/json");
+      if (!res.ok) return formatResult(res);
+      const when = new Date(snap.timestamp).toISOString();
+      return {
+        content: [
+          { type: "text", text: `Reverted to snapshot [${index}] (${when}, trigger=${snap.trigger}).` }
+        ]
+      };
+    }
+  );
   server.tool(
     "caddy_config_by_id",
     "Access config by @id tag. Any config object with an '@id' field can be read, updated, or deleted by its ID instead of needing its full path. This is the recommended way to manage individual routes and config objects.",
@@ -347,6 +506,29 @@ function registerConfigTools(server) {
 
 // src/tools/operational.ts
 import { z as z3 } from "zod";
+function describeServer(raw) {
+  const listen = Array.isArray(raw.listen) ? raw.listen : [];
+  const routes = Array.isArray(raw.routes) ? raw.routes : [];
+  const hasExplicitTls = !!raw.tls_connection_policies;
+  const listensHttps = listen.some((l) => typeof l === "string" && l.includes(":443"));
+  const tls = hasExplicitTls ? "enabled" : listensHttps ? "auto (HTTPS)" : "off (HTTP only)";
+  const listenStr = listen.length > 0 ? listen.map(String).join(", ") : "default";
+  return `${routes.length} route(s), listen: ${listenStr}, TLS: ${tls}`;
+}
+function findAcmeEmail(policies) {
+  if (!Array.isArray(policies)) return void 0;
+  for (const rawPolicy of policies) {
+    if (!rawPolicy || typeof rawPolicy !== "object") continue;
+    const policy = rawPolicy;
+    if (!Array.isArray(policy.issuers)) continue;
+    for (const rawIssuer of policy.issuers) {
+      if (!rawIssuer || typeof rawIssuer !== "object") continue;
+      const issuer = rawIssuer;
+      if (typeof issuer.email === "string") return issuer.email;
+    }
+  }
+  return void 0;
+}
 function registerOperationalTools(server) {
   server.tool(
     "caddy_status",
@@ -356,32 +538,20 @@ function registerOperationalTools(server) {
     async () => {
       const res = await configGet();
       if (!res.ok) return formatResult(res);
-      const config = res.data || {};
-      const httpApp = config?.apps?.http;
-      const servers = httpApp?.servers || {};
+      const config = res.data ?? {};
+      const servers = config.apps?.http?.servers ?? {};
       const serverNames = Object.keys(servers);
       const lines = ["Caddy is running", ""];
       if (serverNames.length === 0) {
         lines.push("No HTTP servers configured");
       } else {
         for (const name of serverNames) {
-          const srv = servers[name];
-          const listen = srv.listen || [];
-          const routes = srv.routes || [];
-          const hasExplicitTls = !!srv.tls_connection_policies;
-          const listensHttps = listen.some((l) => l.includes(":443"));
-          const tls = hasExplicitTls ? "enabled" : listensHttps ? "auto (HTTPS)" : "off (HTTP only)";
-          lines.push(
-            `Server "${name}": ${routes.length} route(s), listen: ${listen.join(", ") || "default"}, TLS: ${tls}`
-          );
+          lines.push(`Server "${name}": ${describeServer(servers[name])}`);
         }
       }
-      const tlsApp = config?.apps?.tls;
-      if (tlsApp?.automation?.policies) {
-        const email = tlsApp.automation.policies.find((p) => p.issuers)?.issuers?.[0]?.email;
-        if (email) lines.push(`
+      const email = findAcmeEmail(config.apps?.tls?.automation?.policies);
+      if (email) lines.push(`
 ACME email: ${email}`);
-      }
       return { content: [{ type: "text", text: lines.join("\n") }] };
     }
   );
@@ -393,21 +563,12 @@ ACME email: ${email}`);
     async () => {
       const res = await configGet("apps/http/servers");
       if (!res.ok) return formatResult(res);
-      const servers = res.data || {};
+      const servers = res.data ?? {};
       const names = Object.keys(servers);
       if (names.length === 0) {
         return { content: [{ type: "text", text: "No HTTP servers configured" }] };
       }
-      const lines = [];
-      for (const name of names) {
-        const srv = servers[name];
-        const listen = srv.listen || [];
-        const routes = srv.routes || [];
-        const hasExplicitTls = !!srv.tls_connection_policies;
-        const listensHttps = listen.some((l) => l.includes(":443"));
-        const tls = hasExplicitTls ? "enabled" : listensHttps ? "auto (HTTPS)" : "off (HTTP only)";
-        lines.push(`  ${name}: ${routes.length} route(s), listen: ${listen.join(", ") || "default"}, TLS: ${tls}`);
-      }
+      const lines = names.map((name) => `  ${name}: ${describeServer(servers[name])}`);
       return {
         content: [{ type: "text", text: `HTTP Servers:
 ${lines.join("\n")}` }]
@@ -678,7 +839,7 @@ function registerRouteTools(server) {
   );
   server.tool(
     "caddy_remove_route",
-    "Remove a route. Target by @id (preferred \u2014 stable across reorderings) or by array index on a specific server. Uses ETags to prevent concurrent overwrites.",
+    "Remove a route. Target by @id (preferred \u2014 stable across reorderings) or by array index on a specific server. Index-based removal is a two-step read-then-delete and can race against concurrent edits; prefer @id when possible.",
     {
       id: z4.string().regex(/^[\w-]{1,128}$/).optional().describe("The @id of the route to remove (preferred \u2014 stable even if routes get reordered)"),
       index: z4.number().int().nonnegative().optional().describe("Zero-based index of the route in the server's routes array (only used if id is not provided)"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/caddy-mcp",
-  "version": "0.3.1",
+  "version": "1.0.1",
   "description": "MCP server for managing Caddy web servers via the admin API",
   "license": "MIT",
   "author": "Yaw Labs <contact@yaw.sh> (https://yaw.sh)",