@yawlabs/caddy-mcp 1.0.0 → 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

@@ -41,6 +41,16 @@ 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));
 }
@@ -87,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) {
@@ -129,22 +147,32 @@ async function attemptRequest(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;
@@ -163,20 +191,36 @@ 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}`;
   return caddyRequest("DELETE", path);
 }
@@ -399,6 +443,12 @@ ${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." }] };
       }
@@ -485,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) {
@@ -567,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",
@@ -601,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 {
@@ -612,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,
@@ -626,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 = {
@@ -646,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);
@@ -669,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);
@@ -809,7 +968,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)"),
@@ -882,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: [
@@ -892,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",
@@ -919,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)
@@ -931,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

@@ -39,6 +39,16 @@ 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));
 }
@@ -85,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) {
@@ -127,22 +145,32 @@ async function attemptRequest(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;
@@ -161,20 +189,36 @@ 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}`;
   return caddyRequest("DELETE", path);
 }
@@ -397,6 +441,12 @@ ${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." }] };
       }
@@ -483,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) {
@@ -565,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",
@@ -599,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 {
@@ -610,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,
@@ -624,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 = {
@@ -644,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);
@@ -667,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);
@@ -807,7 +966,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)"),
@@ -880,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: [
@@ -890,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",
@@ -917,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)
@@ -929,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.0",
+  "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",