@yawlabs/caddy-mcp 1.0.1 → 1.1.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.
 

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) {
@@ -183,24 +191,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}`;
@@ -517,6 +535,35 @@ function describeServer(raw) {
   const listenStr = listen.length > 0 ? listen.map(String).join(", ") : "default";
   return `${routes.length} route(s), listen: ${listenStr}, TLS: ${tls}`;
 }
+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) => {
+      const name = metricNameFromLine(line);
+      return name?.includes(filter) ?? false;
+    });
+  } else {
+    filtered = lines;
+  }
+  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)) return void 0;
   for (const rawPolicy of policies) {
@@ -599,10 +646,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."
+      ),
+      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 +692,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 +706,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 +735,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 +758,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 +828,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 +1041,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 +1051,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 +1164,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 +1176,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) {
@@ -181,24 +189,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}`;
@@ -515,6 +533,35 @@ function describeServer(raw) {
   const listenStr = listen.length > 0 ? listen.map(String).join(", ") : "default";
   return `${routes.length} route(s), listen: ${listenStr}, TLS: ${tls}`;
 }
+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) => {
+      const name = metricNameFromLine(line);
+      return name?.includes(filter) ?? false;
+    });
+  } else {
+    filtered = lines;
+  }
+  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)) return void 0;
   for (const rawPolicy of policies) {
@@ -597,10 +644,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."
+      ),
+      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 +690,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 +704,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 +733,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 +756,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 +826,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 +1039,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 +1049,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 +1162,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 +1174,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.1.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,8 @@
   },
   "overrides": {
     "hono": "^4.12.14",
-    "@hono/node-server": "^1.19.13"
+    "@hono/node-server": "^1.19.13",
+    "postcss": "^8.5.10"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",