@yawlabs/caddy-mcp 1.0.1 → 1.2.0

package/README.md

@@ -3,7 +3,6 @@
 [![npm version](https://img.shields.io/npm/v/@yawlabs/caddy-mcp)](https://www.npmjs.com/package/@yawlabs/caddy-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![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.** 18 tools + 4 resources covering every endpoint of Caddy's admin API — config, routes, reverse proxies, TLS, PKI, metrics, snapshots.
 
@@ -108,14 +107,14 @@ Use the same JSON block shown above in any of these.
 
 ### Route operations (4)
 
-- **caddy_reverse_proxy** — Add a reverse proxy in one call: `from='api.local' to=['localhost:3000']`.
+- **caddy_reverse_proxy** — Add a reverse proxy in one call: `from='api.local' to=['localhost:3000']`. Pass an optional `id` for idempotent writes — repeat calls replace the route in place instead of duplicating.
 - **caddy_add_route** — Add a route with full match/handle control (any Caddy handler).
 - **caddy_remove_route** — Remove a route by `@id` (preferred) or by index. Requires `confirm=true`.
 - **caddy_list_routes** — Human-readable route summary. Defensive: never crashes on weird config.
 
 ### TLS & config conversion (2)
 
-- **caddy_tls** — Check or set TLS settings: ACME email, ACME CA URL. Falls back gracefully when paths don't yet exist.
+- **caddy_tls** — Check or set TLS settings: ACME email, ACME CA URL. PATCH first; on a fresh install, POSTs a minimal config. On an existing config it deep-merges into the issuer path and PUTs the result back, preserving siblings (custom certs, `on_demand`, additional policies). Refuses with a shape-specific error if the existing structure is unexpected — never clobbers.
 - **caddy_adapt** — Convert a Caddyfile (or nginx config) to Caddy JSON without applying it. Great for previewing.
 
 ### Server operations (6)
@@ -123,7 +122,7 @@ Use the same JSON block shown above in any of these.
 - **caddy_status** — Connectivity check + config summary (server count, routes, TLS mode).
 - **caddy_list_servers** — List all HTTP servers with names, addresses, route counts, and TLS status.
 - **caddy_upstreams** — Reverse proxy backend health.
-- **caddy_metrics** — Prometheus metrics (request counts, durations, connections, TLS handshakes).
+- **caddy_metrics** — Prometheus metrics (request counts, durations, connections, TLS handshakes). Optional `filter` (substring match on metric name, keeps `# HELP` / `# TYPE` lines for retained metrics) and `max_lines` (default 500) keep responses compact on busy servers.
 - **caddy_pki** — CA info and certificate chains (default CA: `local`).
 - **caddy_stop** — Graceful shutdown. Requires `confirm=true` to prevent accidents.
 
@@ -145,6 +144,26 @@ Browsable read-only data — MCP clients can fetch these directly without a tool
 → caddy_reverse_proxy({ from: "api.example.com", to: ["localhost:3000"] })
 ```
 
+### Idempotent reverse proxy (safe to re-run from automation)
+
+```
+> "Make sure api.example.com points at localhost:3000, with a stable id"
+→ caddy_reverse_proxy({ from: "api.example.com", to: ["localhost:3000"], id: "api-prod" })
+  # First call creates the route under @id="api-prod".
+  # Subsequent calls with the same id REPLACE in place — no duplicate routes.
+  # Refuses with a clear error if "api-prod" is already in use by a non-route
+  # config object (TLS issuer, server, etc.) — @ids are config-global in Caddy.
+```
+
+### Filter Prometheus metrics
+
+```
+> "Just the HTTP request metrics, please"
+→ caddy_metrics({ filter: "http_requests" })
+  # Keeps sample lines whose metric name contains "http_requests",
+  # plus their `# HELP` / `# TYPE` lines. Drops the rest.
+```
+
 ### Preview a Caddyfile before applying it
 
 ```
@@ -214,7 +233,7 @@ npm install
 npm run lint       # Biome check
 npm run lint:fix   # Auto-fix
 npm run build      # tsup bundle
-npm test           # Vitest (106 unit tests; +7 live-Caddy integration tests gated by CADDY_MCP_INTEGRATION=1)
+npm test           # Vitest (150 unit tests; +8 live-Caddy integration tests gated by CADDY_MCP_INTEGRATION=1)
 npm run typecheck  # tsc --noEmit
 ```
 

package/dist/index.js

@@ -97,7 +97,15 @@ async function attemptRequest(method, path, body, contentType, timeout) {
       setEtag(path, etag);
     }
     if (isWrite && res.ok && isConfigPath) {
-      etagCache.delete(path);
+      if (method === "PATCH" || method === "PUT") {
+        if (etag) {
+          setEtag(path, etag);
+        } else {
+          etagCache.delete(path);
+        }
+      } else {
+        etagCache.delete(path);
+      }
     }
     if (!res.ok) {
       if (res.status === 412) {
@@ -167,9 +175,17 @@ function configDelete(path) {
   if (bad) return Promise.resolve(bad);
   return caddyRequest("DELETE", `/config/${normalized}`);
 }
-var LOAD_TIMEOUT = 6e4;
+function getLoadTimeout() {
+  const raw = process.env.CADDY_LOAD_TIMEOUT;
+  if (raw === void 0) return 6e4;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return 6e4;
+  const floored = Math.floor(n);
+  if (floored < 1) return 6e4;
+  return floored;
+}
 async function loadConfig(config, contentType) {
-  const res = await caddyRequest("POST", "/load", config, contentType, LOAD_TIMEOUT);
+  const res = await caddyRequest("POST", "/load", config, contentType, getLoadTimeout());
   if (res.ok) etagCache.clear();
   return res;
 }
@@ -183,24 +199,34 @@ function getUpstreams() {
   return caddyRequest("GET", "/reverse_proxy/upstreams");
 }
 function getPki(ca = "local") {
+  const bad = rejectTraversal(ca);
+  if (bad) return Promise.resolve(bad);
   return caddyRequest("GET", `/pki/ca/${ca}`);
 }
 function getPkiCertificates(ca = "local") {
+  const bad = rejectTraversal(ca);
+  if (bad) return Promise.resolve(bad);
   return caddyRequest("GET", `/pki/ca/${ca}/certificates`);
 }
 function configByIdGet(id, subpath = "") {
+  const badId = rejectTraversal(id);
+  if (badId) return Promise.resolve(badId);
   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 badId = rejectTraversal(id);
+  if (badId) return Promise.resolve(badId);
   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 badId = rejectTraversal(id);
+  if (badId) return Promise.resolve(badId);
   const bad = rejectTraversal(subpath);
   if (bad) return Promise.resolve(bad);
   const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
@@ -351,6 +377,9 @@ function getSnapshot(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",
@@ -393,7 +422,7 @@ function registerConfigTools(server) {
     async ({ config, format }) => {
       const contentType = format === "caddyfile" ? "text/caddyfile" : "application/json";
       const current = await configGet();
-      if (current.ok && current.data !== void 0) {
+      if (current.ok && isSnapshotableConfig(current.data)) {
         saveSnapshot(current.data, "caddy_load");
       }
       return formatResult(await loadConfig(config, contentType));
@@ -425,10 +454,15 @@ ${lines.join("\n")}` }] };
       if (action === "save") {
         const current2 = await configGet();
         if (!current2.ok) return formatResult(current2);
-        if (current2.data === void 0) {
+        if (!isSnapshotableConfig(current2.data)) {
           return {
             isError: true,
-            content: [{ type: "text", text: "Error: no config loaded to snapshot" }]
+            content: [
+              {
+                type: "text",
+                text: "Error: cannot snapshot -- config response is empty or not a JSON object"
+              }
+            ]
           };
         }
         saveSnapshot(current2.data, "manual");
@@ -458,11 +492,11 @@ ${lines.join("\n")}` }] };
         };
       }
       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);
+      if (current.ok && isSnapshotableConfig(current.data)) {
+        saveSnapshot(current.data, "caddy_revert");
+      }
       const when = new Date(snap.timestamp).toISOString();
       return {
         content: [
@@ -517,19 +551,46 @@ function describeServer(raw) {
   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;
-    }
+var METRICS_DEFAULT_MAX_LINES = 500;
+function metricNameFromLine(line) {
+  const trimmed = line.trimStart();
+  if (trimmed === "") return void 0;
+  if (trimmed.startsWith("#")) {
+    const m2 = trimmed.match(/^#\s+(?:HELP|TYPE)\s+([A-Za-z_:][A-Za-z0-9_:]*)/);
+    return m2 ? m2[1] : void 0;
+  }
+  const m = trimmed.match(/^([A-Za-z_:][A-Za-z0-9_:]*)/);
+  return m ? m[1] : void 0;
+}
+function applyMetricsControls(raw, filter, maxLines) {
+  const lines = raw.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  let filtered;
+  if (filter && filter.length > 0) {
+    filtered = lines.filter((line) => {
+      if (line.trim() === "# EOF") return true;
+      const name = metricNameFromLine(line);
+      return name?.includes(filter) ?? false;
+    });
+  } else {
+    filtered = lines;
   }
-  return void 0;
+  if (filtered.length <= maxLines) return filtered.join("\n");
+  const dropped = filtered.length - maxLines;
+  const kept = filtered.slice(0, maxLines);
+  kept.push(`# [truncated, ${dropped} lines omitted -- use filter to narrow]`);
+  return kept.join("\n");
+}
+function findAcmeEmail(policies) {
+  if (!Array.isArray(policies) || policies.length === 0) return void 0;
+  const rawPolicy = policies[0];
+  if (!rawPolicy || typeof rawPolicy !== "object" || Array.isArray(rawPolicy)) return void 0;
+  const policy = rawPolicy;
+  if (!Array.isArray(policy.issuers) || policy.issuers.length === 0) return void 0;
+  const rawIssuer = policy.issuers[0];
+  if (!rawIssuer || typeof rawIssuer !== "object" || Array.isArray(rawIssuer)) return void 0;
+  const issuer = rawIssuer;
+  return typeof issuer.email === "string" ? issuer.email : void 0;
 }
 function registerOperationalTools(server) {
   server.tool(
@@ -599,10 +660,22 @@ ${lines.join("\n")}` }]
   );
   server.tool(
     "caddy_metrics",
-    "Get Prometheus metrics from Caddy. Shows request counts, durations, TLS handshake stats, active connections, and more.",
-    {},
+    "Get Prometheus metrics from Caddy. Shows request counts, durations, TLS handshake stats, active connections, and more. Output can be megabytes on busy servers -- use `filter` to keep only metrics whose name contains a substring (e.g. 'http_requests' or 'tls'); HELP/TYPE comment lines for retained metrics are kept. Filter-mode drops blank lines and free-form '# comment' lines (including '# EOF'); only '# HELP'/'# TYPE' lines for matching metrics are kept. Use `max_lines` to cap the response (default 500); a trailing comment reports how many lines were dropped.",
+    {
+      filter: z3.string().optional().describe(
+        "Substring to match against metric names. Keeps sample lines whose metric name contains this substring, plus their `# HELP` and `# TYPE` comment lines. Empty/absent = no filtering. Label values are NOT matched -- use a Prometheus-aware client for label filtering."
+      ),
+      max_lines: z3.number().int().positive().optional().describe("Maximum number of output lines (default 500). Excess lines are dropped and a summary is appended.")
+    },
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    async () => formatResult(await getMetrics())
+    async ({ filter, max_lines }) => {
+      const res = await getMetrics();
+      if (!res.ok) return formatResult(res);
+      const raw = typeof res.data === "string" ? res.data : res.data !== void 0 ? String(res.data) : "";
+      const limit = max_lines ?? METRICS_DEFAULT_MAX_LINES;
+      const text = applyMetricsControls(raw, filter, limit);
+      return { content: [{ type: "text", text: text || "OK" }] };
+    }
   );
   server.tool(
     "caddy_stop",
@@ -633,7 +706,10 @@ function parseFrom(from) {
   const slashIdx = cleaned.indexOf("/");
   if (slashIdx > 0) {
     match.host = [cleaned.substring(0, slashIdx)];
-    match.path = [cleaned.substring(slashIdx)];
+    const path = cleaned.substring(slashIdx);
+    if (path !== "/") {
+      match.path = [path];
+    }
   } else if (cleaned.startsWith("/")) {
     match.path = [cleaned];
   } else {
@@ -644,6 +720,21 @@ function parseFrom(from) {
 function cleanUpstreamAddr(addr) {
   return addr.replace(/^https?:\/\//, "").replace(/\/+$/, "");
 }
+function isParentMissing(res) {
+  if (res.ok) return false;
+  if (res.status === 404) return true;
+  return res.error?.includes("key does not exist") ?? false;
+}
+function isUnknownId(res) {
+  if (res.ok) return false;
+  if (res.status === 404) return true;
+  const body = (res.error ?? "").toLowerCase();
+  return body.includes("unknown object id") || body.includes("no id found");
+}
+function isRouteShape(obj) {
+  if (!obj || typeof obj !== "object") return false;
+  return Array.isArray(obj.handle);
+}
 function serverNotFoundError(srv) {
   return {
     isError: true,
@@ -658,14 +749,17 @@ function serverNotFoundError(srv) {
 function registerRouteTools(server) {
   server.tool(
     "caddy_reverse_proxy",
-    "Add a reverse proxy route. The most common operation \u2014 just specify where traffic comes from and where it goes. Example: from='api.local' to=['localhost:3000'].",
+    "Add a reverse proxy route. The most common operation \u2014 just specify where traffic comes from and where it goes. Example: from='api.local' to=['localhost:3000']. When `id` is OMITTED the route is appended to the server's routes array \u2014 calling the tool twice with the same args produces TWO duplicate routes (non-idempotent). When `id` is SUPPLIED the route is written via PUT under that @id, so repeat calls REPLACE in place (idempotent). Strongly recommended: supply a stable `id` for any route managed from automation or production tooling. Note: @ids are config-global in Caddy (NOT route-scoped). If `id` collides with an @id used by a non-route object (TLS issuer, server, etc.) the call refuses with an error rather than clobbering it. Once an @id is registered to a route under one server, subsequent calls update that route in place regardless of the `server` argument.",
     {
       from: z4.string().describe("Domain, path, or domain/path to match (e.g., 'api.local', '/api/*', 'app.local/ws')"),
       to: z4.array(z4.string()).describe("Upstream addresses (e.g., ['localhost:3000', 'localhost:3001'])"),
-      server: z4.string().regex(/^[\w-]{1,128}$/).optional().default("srv0").describe("Caddy server name (default: srv0)")
+      server: z4.string().regex(/^[\w-]{1,128}$/).optional().default("srv0").describe("Caddy server name (default: srv0)"),
+      id: z4.string().regex(/^[\w-]{1,128}$/).optional().describe(
+        "Optional stable @id for the route. When set, repeat calls REPLACE the route in place (idempotent). When omitted, the route is APPENDED \u2014 calling twice with identical args creates a duplicate route. @ids are config-global in Caddy: if this id is already used by a non-route object the call refuses rather than clobbering it."
+      )
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    async ({ from, to, server: srv }) => {
+    async ({ from, to, server: srv, id }) => {
       const match = parseFrom(from);
       const cleanedTo = to.map(cleanUpstreamAddr);
       const route = {
@@ -678,11 +772,58 @@ function registerRouteTools(server) {
         ],
         terminal: true
       };
+      if (id) {
+        route["@id"] = id;
+        const existing = await configByIdGet(id);
+        if (existing.ok) {
+          if (!isRouteShape(existing.data)) {
+            return {
+              isError: true,
+              content: [
+                {
+                  type: "text",
+                  text: `Error: @id "${id}" is already in use by a non-route config object (no top-level "handle" array). @ids are config-global in Caddy, not route-scoped -- pick a different id, or remove the existing object first with caddy_config_by_id { id: "${id}", action: "delete" }.`
+                }
+              ]
+            };
+          }
+          const putRes = await configByIdSet(id, route, "PUT");
+          if (putRes.ok) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Route set @id="${id}": ${from} \u2192 ${cleanedTo.join(", ")}`
+                }
+              ]
+            };
+          }
+          return formatResult(putRes);
+        }
+        if (!isUnknownId(existing)) {
+          return formatResult(existing);
+        }
+        const postRes = await configPost(`apps/http/servers/${srv}/routes`, route);
+        if (postRes.ok) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Route created @id="${id}": ${from} \u2192 ${cleanedTo.join(", ")}`
+              }
+            ]
+          };
+        }
+        if (isParentMissing(postRes)) {
+          return serverNotFoundError(srv);
+        }
+        return formatResult(postRes);
+      }
       const res = await configPost(`apps/http/servers/${srv}/routes`, route);
       if (res.ok) {
         return { content: [{ type: "text", text: `Route added: ${from} \u2192 ${cleanedTo.join(", ")}` }] };
       }
-      if (!res.ok && res.error?.includes("key does not exist")) {
+      if (isParentMissing(res)) {
         return serverNotFoundError(srv);
       }
       return formatResult(res);
@@ -701,7 +842,7 @@ function registerRouteTools(server) {
     async ({ match, handle, server: srv, terminal }) => {
       const route = { match, handle, terminal };
       const res = await configPost(`apps/http/servers/${srv}/routes`, route);
-      if (!res.ok && res.error?.includes("key does not exist")) {
+      if (isParentMissing(res)) {
         return serverNotFoundError(srv);
       }
       return formatResult(res);
@@ -914,9 +1055,9 @@ function buildTlsConfig(fields) {
     }
   };
 }
-function bothErrors(label, patchRes, postRes) {
+function bothErrors(label, patchRes, writeRes, writeLabel) {
   const patchErr = patchRes.error || `HTTP ${patchRes.status}`;
-  const postErr = postRes.error || `HTTP ${postRes.status}`;
+  const writeErr = writeRes.error || `HTTP ${writeRes.status}`;
   return {
     isError: true,
     content: [
@@ -924,11 +1065,97 @@ function bothErrors(label, patchRes, postRes) {
         type: "text",
         text: `Error: Failed to set ${label}.
   PATCH attempt: ${patchErr}
-  POST fallback: ${postErr}`
+  ${writeLabel} fallback: ${writeErr}`
       }
     ]
   };
 }
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function deepClone(v) {
+  return JSON.parse(JSON.stringify(v));
+}
+function mergeIssuerFields(existing, fields) {
+  const merged = deepClone(existing);
+  const automation = merged.automation;
+  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;
+  return merged;
+}
+function validateIssuerShape(tls) {
+  const automation = tls.automation;
+  if (!isPlainObject(automation)) {
+    return "apps/tls.automation is missing or not an object";
+  }
+  const policies = automation.policies;
+  if (!Array.isArray(policies) || policies.length === 0) {
+    return "apps/tls.automation.policies is missing, not an array, or empty";
+  }
+  const policy0 = policies[0];
+  if (!isPlainObject(policy0)) {
+    return "apps/tls.automation.policies[0] is not an object";
+  }
+  const issuers = policy0.issuers;
+  if (!Array.isArray(issuers) || issuers.length === 0) {
+    return "apps/tls.automation.policies[0].issuers is missing, not an array, or empty";
+  }
+  const issuer0 = issuers[0];
+  if (!isPlainObject(issuer0)) {
+    return "apps/tls.automation.policies[0].issuers[0] is not an object";
+  }
+  return null;
+}
+async function safeFallback(label, patchRes, fields) {
+  const getRes = await configGet("apps/tls");
+  const absent = !getRes.ok && getRes.status === 404 ? true : getRes.ok && (getRes.data === void 0 || getRes.data === null);
+  if (absent) {
+    const postRes = await configPost("apps/tls", buildTlsConfig(fields));
+    if (postRes.ok) return { kind: "ok" };
+    return { kind: "tool-error", result: bothErrors(label, patchRes, postRes, "POST") };
+  }
+  if (!getRes.ok) {
+    return { kind: "tool-error", result: bothErrors(label, patchRes, getRes, "GET apps/tls") };
+  }
+  if (!isPlainObject(getRes.data)) {
+    return {
+      kind: "tool-error",
+      result: {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Error: Failed to set ${label}.
+  PATCH attempt: ${patchRes.error || `HTTP ${patchRes.status}`}
+  Refusing to clobber existing apps/tls: GET returned a non-object value. Use caddy_config_set with an explicit path to update it safely.`
+          }
+        ]
+      }
+    };
+  }
+  const shapeError = validateIssuerShape(getRes.data);
+  if (shapeError) {
+    return {
+      kind: "tool-error",
+      result: {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Error: Failed to set ${label}.
+  PATCH attempt: ${patchRes.error || `HTTP ${patchRes.status}`}
+  Refusing to clobber existing apps/tls: ${shapeError}. Use caddy_config_set with an explicit path (e.g. apps/tls/automation/policies) to update it safely.`
+          }
+        ]
+      }
+    };
+  }
+  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") };
+}
 function registerTlsTools(server) {
   server.tool(
     "caddy_tls",
@@ -951,9 +1178,9 @@ function registerTlsTools(server) {
           };
         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 postRes = await configPost("apps/tls", buildTlsConfig({ email }));
-        if (postRes.ok) return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
-        return bothErrors("ACME email", patchRes, postRes);
+        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;
       }
       if (action === "set_acme_ca") {
         if (!ca)
@@ -963,9 +1190,9 @@ function registerTlsTools(server) {
           };
         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 postRes = await configPost("apps/tls", buildTlsConfig({ ca }));
-        if (postRes.ok) return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
-        return bothErrors("ACME CA", patchRes, postRes);
+        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;
       }
       return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
     }

package/dist/server.js

@@ -95,7 +95,15 @@ async function attemptRequest(method, path, body, contentType, timeout) {
       setEtag(path, etag);
     }
     if (isWrite && res.ok && isConfigPath) {
-      etagCache.delete(path);
+      if (method === "PATCH" || method === "PUT") {
+        if (etag) {
+          setEtag(path, etag);
+        } else {
+          etagCache.delete(path);
+        }
+      } else {
+        etagCache.delete(path);
+      }
     }
     if (!res.ok) {
       if (res.status === 412) {
@@ -165,9 +173,17 @@ function configDelete(path) {
   if (bad) return Promise.resolve(bad);
   return caddyRequest("DELETE", `/config/${normalized}`);
 }
-var LOAD_TIMEOUT = 6e4;
+function getLoadTimeout() {
+  const raw = process.env.CADDY_LOAD_TIMEOUT;
+  if (raw === void 0) return 6e4;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return 6e4;
+  const floored = Math.floor(n);
+  if (floored < 1) return 6e4;
+  return floored;
+}
 async function loadConfig(config, contentType) {
-  const res = await caddyRequest("POST", "/load", config, contentType, LOAD_TIMEOUT);
+  const res = await caddyRequest("POST", "/load", config, contentType, getLoadTimeout());
   if (res.ok) etagCache.clear();
   return res;
 }
@@ -181,24 +197,34 @@ function getUpstreams() {
   return caddyRequest("GET", "/reverse_proxy/upstreams");
 }
 function getPki(ca = "local") {
+  const bad = rejectTraversal(ca);
+  if (bad) return Promise.resolve(bad);
   return caddyRequest("GET", `/pki/ca/${ca}`);
 }
 function getPkiCertificates(ca = "local") {
+  const bad = rejectTraversal(ca);
+  if (bad) return Promise.resolve(bad);
   return caddyRequest("GET", `/pki/ca/${ca}/certificates`);
 }
 function configByIdGet(id, subpath = "") {
+  const badId = rejectTraversal(id);
+  if (badId) return Promise.resolve(badId);
   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 badId = rejectTraversal(id);
+  if (badId) return Promise.resolve(badId);
   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 badId = rejectTraversal(id);
+  if (badId) return Promise.resolve(badId);
   const bad = rejectTraversal(subpath);
   if (bad) return Promise.resolve(bad);
   const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
@@ -349,6 +375,9 @@ function getSnapshot(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",
@@ -391,7 +420,7 @@ function registerConfigTools(server) {
     async ({ config, format }) => {
       const contentType = format === "caddyfile" ? "text/caddyfile" : "application/json";
       const current = await configGet();
-      if (current.ok && current.data !== void 0) {
+      if (current.ok && isSnapshotableConfig(current.data)) {
         saveSnapshot(current.data, "caddy_load");
       }
       return formatResult(await loadConfig(config, contentType));
@@ -423,10 +452,15 @@ ${lines.join("\n")}` }] };
       if (action === "save") {
         const current2 = await configGet();
         if (!current2.ok) return formatResult(current2);
-        if (current2.data === void 0) {
+        if (!isSnapshotableConfig(current2.data)) {
           return {
             isError: true,
-            content: [{ type: "text", text: "Error: no config loaded to snapshot" }]
+            content: [
+              {
+                type: "text",
+                text: "Error: cannot snapshot -- config response is empty or not a JSON object"
+              }
+            ]
           };
         }
         saveSnapshot(current2.data, "manual");
@@ -456,11 +490,11 @@ ${lines.join("\n")}` }] };
         };
       }
       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);
+      if (current.ok && isSnapshotableConfig(current.data)) {
+        saveSnapshot(current.data, "caddy_revert");
+      }
       const when = new Date(snap.timestamp).toISOString();
       return {
         content: [
@@ -515,19 +549,46 @@ function describeServer(raw) {
   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;
-    }
+var METRICS_DEFAULT_MAX_LINES = 500;
+function metricNameFromLine(line) {
+  const trimmed = line.trimStart();
+  if (trimmed === "") return void 0;
+  if (trimmed.startsWith("#")) {
+    const m2 = trimmed.match(/^#\s+(?:HELP|TYPE)\s+([A-Za-z_:][A-Za-z0-9_:]*)/);
+    return m2 ? m2[1] : void 0;
+  }
+  const m = trimmed.match(/^([A-Za-z_:][A-Za-z0-9_:]*)/);
+  return m ? m[1] : void 0;
+}
+function applyMetricsControls(raw, filter, maxLines) {
+  const lines = raw.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  let filtered;
+  if (filter && filter.length > 0) {
+    filtered = lines.filter((line) => {
+      if (line.trim() === "# EOF") return true;
+      const name = metricNameFromLine(line);
+      return name?.includes(filter) ?? false;
+    });
+  } else {
+    filtered = lines;
   }
-  return void 0;
+  if (filtered.length <= maxLines) return filtered.join("\n");
+  const dropped = filtered.length - maxLines;
+  const kept = filtered.slice(0, maxLines);
+  kept.push(`# [truncated, ${dropped} lines omitted -- use filter to narrow]`);
+  return kept.join("\n");
+}
+function findAcmeEmail(policies) {
+  if (!Array.isArray(policies) || policies.length === 0) return void 0;
+  const rawPolicy = policies[0];
+  if (!rawPolicy || typeof rawPolicy !== "object" || Array.isArray(rawPolicy)) return void 0;
+  const policy = rawPolicy;
+  if (!Array.isArray(policy.issuers) || policy.issuers.length === 0) return void 0;
+  const rawIssuer = policy.issuers[0];
+  if (!rawIssuer || typeof rawIssuer !== "object" || Array.isArray(rawIssuer)) return void 0;
+  const issuer = rawIssuer;
+  return typeof issuer.email === "string" ? issuer.email : void 0;
 }
 function registerOperationalTools(server) {
   server.tool(
@@ -597,10 +658,22 @@ ${lines.join("\n")}` }]
   );
   server.tool(
     "caddy_metrics",
-    "Get Prometheus metrics from Caddy. Shows request counts, durations, TLS handshake stats, active connections, and more.",
-    {},
+    "Get Prometheus metrics from Caddy. Shows request counts, durations, TLS handshake stats, active connections, and more. Output can be megabytes on busy servers -- use `filter` to keep only metrics whose name contains a substring (e.g. 'http_requests' or 'tls'); HELP/TYPE comment lines for retained metrics are kept. Filter-mode drops blank lines and free-form '# comment' lines (including '# EOF'); only '# HELP'/'# TYPE' lines for matching metrics are kept. Use `max_lines` to cap the response (default 500); a trailing comment reports how many lines were dropped.",
+    {
+      filter: z3.string().optional().describe(
+        "Substring to match against metric names. Keeps sample lines whose metric name contains this substring, plus their `# HELP` and `# TYPE` comment lines. Empty/absent = no filtering. Label values are NOT matched -- use a Prometheus-aware client for label filtering."
+      ),
+      max_lines: z3.number().int().positive().optional().describe("Maximum number of output lines (default 500). Excess lines are dropped and a summary is appended.")
+    },
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    async () => formatResult(await getMetrics())
+    async ({ filter, max_lines }) => {
+      const res = await getMetrics();
+      if (!res.ok) return formatResult(res);
+      const raw = typeof res.data === "string" ? res.data : res.data !== void 0 ? String(res.data) : "";
+      const limit = max_lines ?? METRICS_DEFAULT_MAX_LINES;
+      const text = applyMetricsControls(raw, filter, limit);
+      return { content: [{ type: "text", text: text || "OK" }] };
+    }
   );
   server.tool(
     "caddy_stop",
@@ -631,7 +704,10 @@ function parseFrom(from) {
   const slashIdx = cleaned.indexOf("/");
   if (slashIdx > 0) {
     match.host = [cleaned.substring(0, slashIdx)];
-    match.path = [cleaned.substring(slashIdx)];
+    const path = cleaned.substring(slashIdx);
+    if (path !== "/") {
+      match.path = [path];
+    }
   } else if (cleaned.startsWith("/")) {
     match.path = [cleaned];
   } else {
@@ -642,6 +718,21 @@ function parseFrom(from) {
 function cleanUpstreamAddr(addr) {
   return addr.replace(/^https?:\/\//, "").replace(/\/+$/, "");
 }
+function isParentMissing(res) {
+  if (res.ok) return false;
+  if (res.status === 404) return true;
+  return res.error?.includes("key does not exist") ?? false;
+}
+function isUnknownId(res) {
+  if (res.ok) return false;
+  if (res.status === 404) return true;
+  const body = (res.error ?? "").toLowerCase();
+  return body.includes("unknown object id") || body.includes("no id found");
+}
+function isRouteShape(obj) {
+  if (!obj || typeof obj !== "object") return false;
+  return Array.isArray(obj.handle);
+}
 function serverNotFoundError(srv) {
   return {
     isError: true,
@@ -656,14 +747,17 @@ function serverNotFoundError(srv) {
 function registerRouteTools(server) {
   server.tool(
     "caddy_reverse_proxy",
-    "Add a reverse proxy route. The most common operation \u2014 just specify where traffic comes from and where it goes. Example: from='api.local' to=['localhost:3000'].",
+    "Add a reverse proxy route. The most common operation \u2014 just specify where traffic comes from and where it goes. Example: from='api.local' to=['localhost:3000']. When `id` is OMITTED the route is appended to the server's routes array \u2014 calling the tool twice with the same args produces TWO duplicate routes (non-idempotent). When `id` is SUPPLIED the route is written via PUT under that @id, so repeat calls REPLACE in place (idempotent). Strongly recommended: supply a stable `id` for any route managed from automation or production tooling. Note: @ids are config-global in Caddy (NOT route-scoped). If `id` collides with an @id used by a non-route object (TLS issuer, server, etc.) the call refuses with an error rather than clobbering it. Once an @id is registered to a route under one server, subsequent calls update that route in place regardless of the `server` argument.",
     {
       from: z4.string().describe("Domain, path, or domain/path to match (e.g., 'api.local', '/api/*', 'app.local/ws')"),
       to: z4.array(z4.string()).describe("Upstream addresses (e.g., ['localhost:3000', 'localhost:3001'])"),
-      server: z4.string().regex(/^[\w-]{1,128}$/).optional().default("srv0").describe("Caddy server name (default: srv0)")
+      server: z4.string().regex(/^[\w-]{1,128}$/).optional().default("srv0").describe("Caddy server name (default: srv0)"),
+      id: z4.string().regex(/^[\w-]{1,128}$/).optional().describe(
+        "Optional stable @id for the route. When set, repeat calls REPLACE the route in place (idempotent). When omitted, the route is APPENDED \u2014 calling twice with identical args creates a duplicate route. @ids are config-global in Caddy: if this id is already used by a non-route object the call refuses rather than clobbering it."
+      )
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    async ({ from, to, server: srv }) => {
+    async ({ from, to, server: srv, id }) => {
       const match = parseFrom(from);
       const cleanedTo = to.map(cleanUpstreamAddr);
       const route = {
@@ -676,11 +770,58 @@ function registerRouteTools(server) {
         ],
         terminal: true
       };
+      if (id) {
+        route["@id"] = id;
+        const existing = await configByIdGet(id);
+        if (existing.ok) {
+          if (!isRouteShape(existing.data)) {
+            return {
+              isError: true,
+              content: [
+                {
+                  type: "text",
+                  text: `Error: @id "${id}" is already in use by a non-route config object (no top-level "handle" array). @ids are config-global in Caddy, not route-scoped -- pick a different id, or remove the existing object first with caddy_config_by_id { id: "${id}", action: "delete" }.`
+                }
+              ]
+            };
+          }
+          const putRes = await configByIdSet(id, route, "PUT");
+          if (putRes.ok) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Route set @id="${id}": ${from} \u2192 ${cleanedTo.join(", ")}`
+                }
+              ]
+            };
+          }
+          return formatResult(putRes);
+        }
+        if (!isUnknownId(existing)) {
+          return formatResult(existing);
+        }
+        const postRes = await configPost(`apps/http/servers/${srv}/routes`, route);
+        if (postRes.ok) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Route created @id="${id}": ${from} \u2192 ${cleanedTo.join(", ")}`
+              }
+            ]
+          };
+        }
+        if (isParentMissing(postRes)) {
+          return serverNotFoundError(srv);
+        }
+        return formatResult(postRes);
+      }
       const res = await configPost(`apps/http/servers/${srv}/routes`, route);
       if (res.ok) {
         return { content: [{ type: "text", text: `Route added: ${from} \u2192 ${cleanedTo.join(", ")}` }] };
       }
-      if (!res.ok && res.error?.includes("key does not exist")) {
+      if (isParentMissing(res)) {
         return serverNotFoundError(srv);
       }
       return formatResult(res);
@@ -699,7 +840,7 @@ function registerRouteTools(server) {
     async ({ match, handle, server: srv, terminal }) => {
       const route = { match, handle, terminal };
       const res = await configPost(`apps/http/servers/${srv}/routes`, route);
-      if (!res.ok && res.error?.includes("key does not exist")) {
+      if (isParentMissing(res)) {
         return serverNotFoundError(srv);
       }
       return formatResult(res);
@@ -912,9 +1053,9 @@ function buildTlsConfig(fields) {
     }
   };
 }
-function bothErrors(label, patchRes, postRes) {
+function bothErrors(label, patchRes, writeRes, writeLabel) {
   const patchErr = patchRes.error || `HTTP ${patchRes.status}`;
-  const postErr = postRes.error || `HTTP ${postRes.status}`;
+  const writeErr = writeRes.error || `HTTP ${writeRes.status}`;
   return {
     isError: true,
     content: [
@@ -922,11 +1063,97 @@ function bothErrors(label, patchRes, postRes) {
         type: "text",
         text: `Error: Failed to set ${label}.
   PATCH attempt: ${patchErr}
-  POST fallback: ${postErr}`
+  ${writeLabel} fallback: ${writeErr}`
       }
     ]
   };
 }
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function deepClone(v) {
+  return JSON.parse(JSON.stringify(v));
+}
+function mergeIssuerFields(existing, fields) {
+  const merged = deepClone(existing);
+  const automation = merged.automation;
+  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;
+  return merged;
+}
+function validateIssuerShape(tls) {
+  const automation = tls.automation;
+  if (!isPlainObject(automation)) {
+    return "apps/tls.automation is missing or not an object";
+  }
+  const policies = automation.policies;
+  if (!Array.isArray(policies) || policies.length === 0) {
+    return "apps/tls.automation.policies is missing, not an array, or empty";
+  }
+  const policy0 = policies[0];
+  if (!isPlainObject(policy0)) {
+    return "apps/tls.automation.policies[0] is not an object";
+  }
+  const issuers = policy0.issuers;
+  if (!Array.isArray(issuers) || issuers.length === 0) {
+    return "apps/tls.automation.policies[0].issuers is missing, not an array, or empty";
+  }
+  const issuer0 = issuers[0];
+  if (!isPlainObject(issuer0)) {
+    return "apps/tls.automation.policies[0].issuers[0] is not an object";
+  }
+  return null;
+}
+async function safeFallback(label, patchRes, fields) {
+  const getRes = await configGet("apps/tls");
+  const absent = !getRes.ok && getRes.status === 404 ? true : getRes.ok && (getRes.data === void 0 || getRes.data === null);
+  if (absent) {
+    const postRes = await configPost("apps/tls", buildTlsConfig(fields));
+    if (postRes.ok) return { kind: "ok" };
+    return { kind: "tool-error", result: bothErrors(label, patchRes, postRes, "POST") };
+  }
+  if (!getRes.ok) {
+    return { kind: "tool-error", result: bothErrors(label, patchRes, getRes, "GET apps/tls") };
+  }
+  if (!isPlainObject(getRes.data)) {
+    return {
+      kind: "tool-error",
+      result: {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Error: Failed to set ${label}.
+  PATCH attempt: ${patchRes.error || `HTTP ${patchRes.status}`}
+  Refusing to clobber existing apps/tls: GET returned a non-object value. Use caddy_config_set with an explicit path to update it safely.`
+          }
+        ]
+      }
+    };
+  }
+  const shapeError = validateIssuerShape(getRes.data);
+  if (shapeError) {
+    return {
+      kind: "tool-error",
+      result: {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Error: Failed to set ${label}.
+  PATCH attempt: ${patchRes.error || `HTTP ${patchRes.status}`}
+  Refusing to clobber existing apps/tls: ${shapeError}. Use caddy_config_set with an explicit path (e.g. apps/tls/automation/policies) to update it safely.`
+          }
+        ]
+      }
+    };
+  }
+  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") };
+}
 function registerTlsTools(server) {
   server.tool(
     "caddy_tls",
@@ -949,9 +1176,9 @@ function registerTlsTools(server) {
           };
         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 postRes = await configPost("apps/tls", buildTlsConfig({ email }));
-        if (postRes.ok) return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
-        return bothErrors("ACME email", patchRes, postRes);
+        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;
       }
       if (action === "set_acme_ca") {
         if (!ca)
@@ -961,9 +1188,9 @@ function registerTlsTools(server) {
           };
         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 postRes = await configPost("apps/tls", buildTlsConfig({ ca }));
-        if (postRes.ok) return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
-        return bothErrors("ACME CA", patchRes, postRes);
+        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;
       }
       return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/caddy-mcp",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "MCP server for managing Caddy web servers via the admin API",
   "license": "MIT",
   "author": "Yaw Labs <contact@yaw.sh> (https://yaw.sh)",
@@ -40,7 +40,9 @@
   },
   "overrides": {
     "hono": "^4.12.14",
-    "@hono/node-server": "^1.19.13"
+    "@hono/node-server": "^1.19.13",
+    "postcss": "^8.5.10",
+    "ip-address": "^10.1.1"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",