@yawlabs/caddy-mcp 2.3.2 → 2.4.1

package/README.md

@@ -3,6 +3,7 @@
 [![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)
+[![Follow @TokenLimitNews on X](https://img.shields.io/badge/follow-%40TokenLimitNews-000000?logo=x&logoColor=white)](https://x.com/TokenLimitNews)
 
 **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/bin/caddy-mcp.mjs

@@ -32,11 +32,25 @@
  * `CADDY_MCP_SANDBOX=1` runs the server under oam's permission model.
  *
  * The admin API endpoint is DERIVED from CADDY_ADMIN_URL (default
- * http://127.0.0.1:2019), host and port both pinned -- grants are prefix-matched,
- * so a bare host would also admit every other port on it. Filesystem AND
- * child-process both stay denied: this server drives Caddy entirely over its
- * admin HTTP API and never shells out to the `caddy` binary (the only
- * execFileSync calls in the repo are in src/tests/).
+ * http://localhost:2019 -- byte-identical to DEFAULT_URL in src/api.ts, see
+ * sandboxFlags). For a TCP endpoint the grant is the HOST, deliberately WITHOUT
+ * a port: oam checks `fetch` against the bare hostname and sockets against
+ * "host:port", and grants are prefix-matched, so pinning the port denies every
+ * fetch -- and fetch is the transport api.ts uses for everything but a unix
+ * socket. Granting the host therefore also admits its other ports; that is the
+ * cost of the check having no port to match against.
+ *
+ * A unix-socket CADDY_ADMIN_URL gets NO net grant, which DENIES the category
+ * outright -- it is not an oversight that it looks narrower than the TCP case.
+ * oam ships no unix socket transport, so the socket dial cannot work under the
+ * sandbox regardless; the alternative was a bare `--allow-net`, which grants
+ * every host on the network. See sandboxFlags for the mechanism.
+ *
+ * Child-process stays denied: this server drives Caddy entirely over its admin
+ * HTTP API and never shells out to the `caddy` binary (the only execFileSync
+ * calls in the repo are in src/tests/). Filesystem stays denied too, EXCEPT when
+ * CADDY_MCP_SNAPSHOT_DIR is set: snapshot persistence is the one feature that
+ * touches disk, so that directory -- and nothing else -- is granted read+write.
  *
  * Opt-in, not default: a denied environment variable is ABSENT from process.env
  * rather than throwing, so an under-granted CADDY_API_TOKEN reads as
@@ -111,6 +125,14 @@ function findOam() {
   // the full PATHEXT list would hand back a path this launcher cannot execute.
   // Discovery has to agree with execution. A skipped shim is still reported --
   // see findOamShim.
+  //
+  // scripts/runtime.mjs carries its OWN findOam that DOES walk the full PATHEXT.
+  // That is a deliberate difference, not drift: it probes each candidate with
+  // execFileSync before returning it, so a shim it cannot run is dropped anyway
+  // and a wider walk only ever finds more. This one is stat-only on the hot
+  // launch path -- no probe to filter with -- so whatever it returns it must be
+  // able to spawn. Same question, different constraint; change one and re-read
+  // the other.
   for (const dir of (process.env.PATH ?? "").split(delimiter)) {
     if (!dir) continue;
     const candidate = join(dir, exe);
@@ -164,25 +186,118 @@ function sandboxFlags() {
   if (process.env.CADDY_MCP_SANDBOX !== "1") return [];
 
   // Derived, not hardcoded: the only endpoint this server may reach is the one
-  // it was configured to reach. Grants are prefix-matched against "host:port"
-  // for sockets, so host alone would also admit any other port on that host --
-  // pin both. A DSN we cannot parse falls back to a bare grant rather than a
-  // broken one, because a wrong narrow grant fails at connect time.
-  const dsn = process.env.CADDY_ADMIN_URL ?? "http://127.0.0.1:2019";
-  let netFlag = "--allow-net";
-  if (dsn) {
+  // it was configured to reach. A DSN we cannot parse falls back to a bare grant
+  // rather than a broken one, because a wrong narrow grant fails at connect time.
+  //
+  // The default MUST stay byte-identical to DEFAULT_URL in src/api.ts. The grant
+  // and the dial are matched as TEXT, so "127.0.0.1" here against an api.ts that
+  // dials "localhost" denies every request while both files look right on their
+  // own. Change one, change the other.
+  //
+  // Empty and whitespace-only are treated as UNSET, which is what api.ts does:
+  // it reads the variable with `||`, so "" already falls through to DEFAULT_URL
+  // there. `??` would keep "" here, skip the parse, and leave the bare
+  // `--allow-net` below -- a wide-open sandbox produced by a shell exporting an
+  // empty variable, which is a shape shells produce easily.
+  const dsn = process.env.CADDY_ADMIN_URL?.trim() || "http://localhost:2019";
+
+  // A unix-socket admin endpoint gets NO net grant at all -- checked before the
+  // URL parse, because it is the one input that would otherwise produce the
+  // WIDEST grant instead of the narrowest.
+  //
+  // `new URL("unix:///run/caddy.sock").hostname` is "", so the `if (u.hostname)`
+  // below is false and netFlag would stay the bare `--allow-net`; Caddy's own
+  // spelling (`unix//run/caddy.sock`) throws ERR_INVALID_URL and reaches the
+  // catch for the same result. Either way the most hardened admin config --
+  // Caddy recommends the socket precisely because filesystem permissions beat a
+  // loopback port -- would switch the sandbox on and hand over the whole network.
+  // That is the same wide-open-by-accident shape the empty-string case above
+  // guards against, reached by a different route.
+  //
+  // Omitting the flag DENIES the category (oam reads an absent --allow-net as
+  // false, a bare one as "*"), and denial costs nothing here: oam has no unix
+  // socket transport at all, so api.ts's node:http `socketPath` dial cannot work
+  // under oam whether the grant is open or closed. Verified against oam 0.9.0 --
+  // bare grant lets an unrelated host through, omitted grant denies it.
+  //
+  // This mirrors getMalformedUnixUrl's predicate in src/api.ts, NOT the stricter
+  // getUnixSocketPath -- deliberately, and the difference is the whole point.
+  //
+  // getUnixSocketPath accepts only the two WELL-FORMED spellings; matching it
+  // here would leave the malformed ones ("unix:/one-slash", "unix://relative",
+  // "unix://", or any uppercase spelling, which getUnixSocketPath rejects for
+  // case) falling through to the parse, where they yield an empty hostname and
+  // the bare `--allow-net` -- fully open, for input that plainly meant a socket.
+  //
+  // Denying the category for those costs nothing: api.ts routes exactly this set
+  // to getMalformedUnixUrl, which fails the request up front with a message
+  // naming the spelling error, so no request is ever attempted. Matching the
+  // broad predicate is what makes the header's claim true for EVERY unix-ish
+  // input rather than just the two tidy ones.
+  //
+  // `[:/]` after "unix" rather than a bare "unix" prefix, so a real TCP host like
+  // "http://unix.example.com:2019" is not swept up -- the same care api.ts takes.
+  const isUnixDsn = /^unix[:/]/i.test(dsn);
+
+  let netFlag = isUnixDsn ? null : "--allow-net";
+  if (!isUnixDsn) {
     try {
       const u = new URL(dsn);
-      if (u.hostname) netFlag = `--allow-net=${u.hostname}:${u.port || 2019}`;
+      // HOST ONLY, no port, deliberately. Grants are prefix-matched against the
+      // resource string, and the resource `fetch` presents is the bare hostname
+      // ("localhost") while sockets present "host:port". "localhost" does not
+      // start with "localhost:2019", so pinning the port denies every fetch --
+      // and fetch is how api.ts talks to a TCP admin endpoint. Granting the host
+      // alone also admits the other ports on that host; that is the cost of the
+      // check having no port to match against, not an oversight here.
+      if (u.hostname) netFlag = `--allow-net=${u.hostname}`;
     } catch {
-      // Unparseable CADDY_ADMIN_URL: leave the grant open. The server will fail on
-      // its own connection error, which names the real problem.
+      // Genuinely unparseable CADDY_ADMIN_URL (not the unix forms -- those are
+      // handled above): leave the grant open. The server will fail on its own
+      // connection error, which names the real problem.
     }
   }
 
-  const env = ["CADDY_ADMIN_URL", "CADDY_API_TOKEN", "CADDY_LOAD_TIMEOUT", "CADDY_MAX_RETRIES", "CADDY_TIMEOUT"];
+  // Every variable the shipped bundle reads (`grep process.env src/`), including
+  // CADDY_MCP_SNAPSHOT_DIR in src/snapshots.ts. Omitting one is not a denial the
+  // operator can see: the variable is simply ABSENT, so the feature reads as
+  // "not configured" and degrades silently.
+  const env = [
+    "CADDY_ADMIN_URL",
+    "CADDY_API_TOKEN",
+    "CADDY_LOAD_TIMEOUT",
+    "CADDY_MAX_RETRIES",
+    "CADDY_MCP_SNAPSHOT_DIR",
+    "CADDY_TIMEOUT",
+  ];
+
+  // netFlag is null for a unix DSN -- an OMITTED --allow-net is what denies the
+  // category, so it must not survive as a stray "null" argv entry.
+  const flags = ["--permission", netFlag, `--allow-env=${env.join(",")}`].filter(Boolean);
+
+  // The filesystem grant exists only when snapshot persistence is switched on,
+  // and only for the directory it points at. Granting the variable without the
+  // directory would just move the silent failure: src/snapshots.ts swallows its
+  // own I/O errors and degrades to the in-memory ring, so `caddy_revert` would
+  // quietly stop surviving a restart -- the thing the operator turned the
+  // variable on to get.
+  //
+  // TWO spellings, because grants are matched as plain string PREFIXES against
+  // whatever path each call passes: snapshots.ts hands the raw variable to
+  // readdirSync/mkdirSync but builds per-file paths with path.join, which
+  // normalizes ("./snaps" -> "snaps"). The raw form alone then misses the files;
+  // the normalized form alone misses the directory listing.
+  //
+  // Two consequences worth naming rather than discovering: a prefix also admits
+  // a sibling path that merely starts with the same string ("/var/snap" grants
+  // "/var/snapshots-elsewhere"), and oam splits the list on commas with no
+  // escape, so a directory whose path contains a comma cannot be granted here.
+  const snapshotDir = process.env.CADDY_MCP_SNAPSHOT_DIR?.trim();
+  if (snapshotDir) {
+    const forms = [...new Set([snapshotDir, join(snapshotDir, ".")])].join(",");
+    flags.push(`--allow-fs-read=${forms}`, `--allow-fs-write=${forms}`);
+  }
 
-  const flags = ["--permission", netFlag, `--allow-env=${env.join(",")}`];
   return flags;
 }
 

package/dist/api.d.ts

@@ -5,6 +5,25 @@ export interface ApiResponse<T = any> {
     error?: string;
     etag?: string;
 }
+/**
+ * Caddy's "a segment of this config path does not exist" failure.
+ *
+ * Caddy walks a config path one segment at a time and reports the first segment it
+ * cannot enter as `invalid traversal path at: <path>`. The STATUS varies with the
+ * verb -- 400 on a GET, 500 on a POST, both observed on 2.11.4 -- so the body is
+ * the only signal that holds across call sites.
+ *
+ * DISTINCT from `404 key does not exist`, which Caddy emits when the object exists
+ * but the named sub-key does not (a PATCH of an absent issuer field, say). Both
+ * mean "what you named is not there", so a caller translating a missing parent
+ * usually wants both markers; matching only the 404 form leaves the traversal case
+ * falling through as a raw Go error.
+ *
+ * Exported because two tools need it and they live in different modules: the route
+ * tools translate it into "that server does not exist", and caddy_list_servers
+ * reads it as "no HTTP servers are configured at all".
+ */
+export declare function isMissingConfigPath(res: Pick<ApiResponse, "ok" | "error">): boolean;
 export declare function configGet<T = any>(path?: string): Promise<ApiResponse<T>>;
 export declare function configPost<T = any>(path: string, value: unknown): Promise<ApiResponse<T>>;
 export declare function configPut<T = any>(path: string, value: unknown): Promise<ApiResponse<T>>;

package/dist/index.js

@@ -88,6 +88,9 @@ function getHeaders(contentType, overUnixSocket = false) {
 function normalizePath(path) {
   return path.replace(/^\/?(config(\/|$))?/, "");
 }
+function encodePathSegments(path) {
+  return path.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+}
 function rejectTraversal(path) {
   if (/(^|\/)\.\.(\/|$)/.test(path)) {
     return {
@@ -107,6 +110,10 @@ function isTransientFailure(res) {
   if (res.status >= 500 && res.status <= 599) return true;
   return false;
 }
+function isMissingConfigPath(res) {
+  if (res.ok) return false;
+  return (res.error ?? "").toLowerCase().includes("invalid traversal path");
+}
 var ARRAY_INDEX_TAIL_RE = /\/\d+$/;
 function isRetryableMethod(method, path) {
   if (method === "PUT") return !ARRAY_INDEX_TAIL_RE.test(path);
@@ -263,31 +270,31 @@ function configGet(path = "") {
   const normalized = normalizePath(path);
   const bad = rejectTraversal(normalized);
   if (bad) return Promise.resolve(bad);
-  return caddyRequest("GET", `/config/${normalized}`);
+  return caddyRequest("GET", `/config/${encodePathSegments(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);
+  return caddyRequest("POST", `/config/${encodePathSegments(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);
+  return caddyRequest("PUT", `/config/${encodePathSegments(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);
+  return caddyRequest("PATCH", `/config/${encodePathSegments(normalized)}`, value);
 }
 function configDelete(path) {
   const normalized = normalizePath(path);
   const bad = rejectTraversal(normalized);
   if (bad) return Promise.resolve(bad);
-  return caddyRequest("DELETE", `/config/${normalized}`);
+  return caddyRequest("DELETE", `/config/${encodePathSegments(normalized)}`);
 }
 function getRequestTimeout() {
   const raw = process.env.CADDY_TIMEOUT;
@@ -324,19 +331,23 @@ function getUpstreams() {
 function getPki(ca = "local") {
   const bad = rejectTraversal(ca);
   if (bad) return Promise.resolve(bad);
-  return caddyRequest("GET", `/pki/ca/${ca}`);
+  return caddyRequest("GET", `/pki/ca/${encodePathSegments(ca)}`);
 }
 function getPkiCertificates(ca = "local") {
   const bad = rejectTraversal(ca);
   if (bad) return Promise.resolve(bad);
-  return caddyRequest("GET", `/pki/ca/${ca}/certificates`);
+  return caddyRequest("GET", `/pki/ca/${encodePathSegments(ca)}/certificates`);
+}
+function idPath(id, subpath) {
+  const encodedId = encodePathSegments(id);
+  return subpath ? `/id/${encodedId}/${encodePathSegments(subpath)}` : `/id/${encodedId}`;
 }
 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}`;
+  const path = idPath(id, subpath);
   return caddyRequest("GET", path);
 }
 function configByIdSet(id, value, method = "PATCH", subpath = "") {
@@ -344,7 +355,7 @@ function configByIdSet(id, value, method = "PATCH", subpath = "") {
   if (badId) return Promise.resolve(badId);
   const bad = rejectTraversal(subpath);
   if (bad) return Promise.resolve(bad);
-  const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
+  const path = idPath(id, subpath);
   return caddyRequest(method, path, value);
 }
 function configByIdDelete(id, subpath = "") {
@@ -352,7 +363,7 @@ function configByIdDelete(id, subpath = "") {
   if (badId) return Promise.resolve(badId);
   const bad = rejectTraversal(subpath);
   if (bad) return Promise.resolve(bad);
-  const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
+  const path = idPath(id, subpath);
   return caddyRequest("DELETE", path);
 }
 function getMetrics() {
@@ -381,7 +392,8 @@ function describeServer(rawValue) {
   const raw = rawValue !== null && typeof rawValue === "object" && !Array.isArray(rawValue) ? rawValue : {};
   const listen = Array.isArray(raw.listen) ? raw.listen : [];
   const routes = Array.isArray(raw.routes) ? raw.routes : [];
-  const hasExplicitTls = !!raw.tls_connection_policies;
+  const tlsPolicies = raw.tls_connection_policies;
+  const hasExplicitTls = Array.isArray(tlsPolicies) ? tlsPolicies.length > 0 : !!tlsPolicies;
   const listensHttps = listen.some((l) => typeof l === "string" && HTTPS_PORT_RE.test(l));
   const tls = hasExplicitTls ? "enabled" : listensHttps ? "auto (HTTPS)" : "off (HTTP only)";
   const listenStr = listen.length > 0 ? listen.map(String).join(", ") : "default";
@@ -465,6 +477,9 @@ ACME email: ${email}`);
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async () => {
       const res = await configGet("apps/http/servers");
+      if (isMissingConfigPath(res)) {
+        return { content: [{ type: "text", text: "No HTTP servers configured" }] };
+      }
       if (!res.ok) return formatResult(res);
       const servers = res.data ?? {};
       const names = Object.keys(servers);
@@ -535,6 +550,9 @@ ${lines.join("\n")}` }]
 }
 
 // src/resources.ts
+function errorText(res) {
+  return `Error: ${res.error || `HTTP ${res.status}`}`;
+}
 function registerResources(server) {
   server.resource("caddy-config", "caddy://config", { description: "Current Caddy JSON configuration" }, async () => {
     const res = await configGet();
@@ -543,7 +561,7 @@ function registerResources(server) {
         {
           uri: "caddy://config",
           mimeType: res.ok ? "application/json" : "text/plain",
-          text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : `Error: ${res.error}`
+          text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : errorText(res)
         }
       ]
     };
@@ -559,7 +577,7 @@ function registerResources(server) {
           {
             uri: "caddy://upstreams",
             mimeType: res.ok ? "application/json" : "text/plain",
-            text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : `Error: ${res.error}`
+            text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : errorText(res)
           }
         ]
       };
@@ -579,7 +597,7 @@ function registerResources(server) {
             {
               uri: "caddy://metrics",
               mimeType: "text/plain",
-              text: `Error: ${res.error}`
+              text: errorText(res)
             }
           ]
         };
@@ -607,7 +625,7 @@ function registerResources(server) {
           {
             uri: "caddy://servers",
             mimeType: res.ok ? "application/json" : "text/plain",
-            text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : `Error: ${res.error}`
+            text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : errorText(res)
           }
         ]
       };
@@ -768,7 +786,15 @@ function registerConfigTools(server) {
       path: z3.string().describe("Config path to delete (e.g., 'apps/http/servers/srv0/routes/0')"),
       confirm: z3.boolean().optional().default(false).describe("Must be true to actually delete the config node (safety)")
     },
-    { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    // idempotentHint is FALSE because the hint covers the whole tool and cannot see
+    // the path it is called with. This tool's own documented example ends in an
+    // array index -- 'apps/http/servers/srv0/routes/0' -- and Caddy re-packs an
+    // array after a delete, so repeating that call removes a DIFFERENT route each
+    // time. caddy_remove_route carries the same correction for the byte-identical
+    // underlying request; the two must agree. Nothing here is auto-recoverable
+    // either: only caddy_load captures a snapshot, so a spurious repeat cannot be
+    // undone with caddy_revert.
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
     async ({ path, confirm }) => {
       if (!confirm) {
         return {
@@ -880,13 +906,16 @@ ${lines.join("\n")}` }] };
       const current = await configGet();
       const res = await loadConfig(snap.config, "application/json");
       if (!res.ok) return formatResult(res);
-      if (current.ok && isSnapshotableConfig(current.data)) {
+      const capturedRollforward = current.ok && isSnapshotableConfig(current.data);
+      if (capturedRollforward) {
         saveSnapshot(current.data, "caddy_revert");
       }
       const when = new Date(snap.timestamp).toISOString();
+      const skipped = current.ok ? "the pre-revert config was empty or not a JSON object" : "the pre-revert config could not be read";
+      const note = capturedRollforward ? "" : ` Warning: ${skipped}, so no roll-forward snapshot was captured -- this revert cannot be rolled back to the config it replaced.`;
       return {
         content: [
-          { type: "text", text: `Reverted to snapshot [${index}] (${when}, trigger=${snap.trigger}).` }
+          { type: "text", text: `Reverted to snapshot [${index}] (${when}, trigger=${snap.trigger}).${note}` }
         ]
       };
     }
@@ -904,7 +933,13 @@ ${lines.join("\n")}` }] };
       ),
       confirm: z3.boolean().optional().default(false).describe("Must be true to actually delete (only enforced for action='delete')")
     },
-    { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    // destructiveHint is keyed to the worst thing this tool can do, not the
+    // default action: action='delete' removes the identified object and every
+    // descendant, exactly like caddy_config_delete. Hosts gate on the hint
+    // before they can see which action the call carries.
+    // idempotentHint stays false for the same reason -- action='set' with
+    // mode='append' is a POST, so a repeated call appends a second copy.
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
     async ({ id, action, value, subpath, mode, confirm }) => {
       if (action === "get") {
         return formatResult(await configByIdGet(id, subpath));
@@ -934,7 +969,8 @@ ${lines.join("\n")}` }] };
         }
         return formatResult(await configByIdDelete(id, subpath));
       }
-      return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
+      const unhandled = action;
+      return { isError: true, content: [{ type: "text", text: `Unknown action: ${String(unhandled)}` }] };
     }
   );
 }
@@ -945,7 +981,7 @@ var ROUTES_JSON_MAX_CHARS = 2e4;
 var ROUTES_SUMMARY_MAX = 500;
 function serializeRoutesCapped(routes) {
   const parts = [];
-  let used = 2;
+  let used = 3;
   for (const route of routes) {
     const entry = JSON.stringify(route, null, 2).split("\n").map((line) => `  ${line}`).join("\n");
     const cost = entry.length + (parts.length > 0 ? 2 : 1);
@@ -995,9 +1031,42 @@ function parseFrom(from) {
 function cleanUpstreamAddr(addr) {
   return addr.replace(/^https?:\/\//, "").replace(/\/+$/, "");
 }
+function withDefaultPort(dial, port) {
+  if (stripPort(dial) !== dial) return dial;
+  const bareIpv6 = !dial.startsWith("[") && dial.indexOf(":") !== dial.lastIndexOf(":");
+  return bareIpv6 ? `[${dial}]:${port}` : `${dial}:${port}`;
+}
+function planUpstreams(to) {
+  if (to.length === 0) {
+    return { error: `"to" must list at least one upstream address (e.g. ["localhost:3000"]).` };
+  }
+  const dials = [];
+  let secure = 0;
+  let plain = 0;
+  for (const raw of to) {
+    const trimmed = raw.trim();
+    const isTls = trimmed.startsWith("https://");
+    const dial = cleanUpstreamAddr(trimmed);
+    if (dial.length === 0) {
+      return {
+        error: `upstream ${JSON.stringify(raw)} has no address to dial. Each "to" entry needs a host and port (e.g. "localhost:3000", "https://backend.example.com:8443").`
+      };
+    }
+    if (isTls) secure++;
+    else plain++;
+    dials.push(isTls ? withDefaultPort(dial, 443) : dial);
+  }
+  if (secure > 0 && plain > 0) {
+    return {
+      error: `"to" mixes https:// and non-https upstreams. Caddy's TLS transport applies to the whole reverse_proxy handler, not per-upstream, so one scheme would be silently forced on the other's connection. Split them into two routes, or build the handler explicitly with caddy_add_route.`
+    };
+  }
+  return { dials, tls: secure > 0 };
+}
 function isParentMissing(res) {
   if (res.ok) return false;
   if (res.status === 404) return true;
+  if (isMissingConfigPath(res)) return true;
   return res.error?.includes("key does not exist") ?? false;
 }
 function isUnknownId(res) {
@@ -1016,7 +1085,18 @@ function serverNotFoundError(srv, op = "operation") {
     content: [
       {
         type: "text",
-        text: `Error: Server "${srv}" does not exist (${op}). Use caddy_list_servers to see available servers, or create one with caddy_load or caddy_config_set at path 'apps/http/servers/${srv}' with at minimum: { "listen": [":443"] }`
+        text: `Error: Server "${srv}" does not exist (${op}). Use caddy_list_servers to see what is configured. To create it: caddy_config_set { path: "apps/http/servers/${srv}", mode: "append", value: { "listen": [":443"], "routes": [] } }. Both arguments are load-bearing: mode "append" creates the key, while the default "overwrite" fails with "key does not exist"; and "routes": [] must be present, or adding the first route fails, because a POST creates a missing routes key as an object rather than an array. On an instance with no config at all, use caddy_load instead -- caddy_config_set cannot create the apps/http tree it would write into.`
+      }
+    ]
+  };
+}
+function serverNullError(srv) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: `Error: Server "${srv}" is not configured, or its config is null -- Caddy returns the same response (HTTP 200 with a body of null) for both, so they cannot be told apart from here. Use caddy_list_servers to see which servers exist, or create this one with caddy_load or caddy_config_set at path 'apps/http/servers/${srv}' with at minimum: { "listen": [":443"] }`
       }
     ]
   };
@@ -1024,10 +1104,12 @@ function serverNotFoundError(srv, op = "operation") {
 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']. 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 PATCH 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.",
+    "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 PATCH 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. Upstream scheme is honored: an `https://` upstream gets a TLS transport and defaults to port 443, anything else is dialed in the clear. A `to` list that MIXES https:// and non-https entries is refused \u2014 the TLS transport applies to the whole handler, not per-upstream \u2014 so split those into two routes or use caddy_add_route.",
     {
       from: z4.string().min(1).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'])"),
+      to: z4.array(z4.string().min(1)).min(1).describe(
+        "Upstream addresses, at least one (e.g., ['localhost:3000', 'localhost:3001']). An 'https://' prefix dials the upstream over TLS (port 443 unless one is given); http:// and bare addresses are dialed in the clear. Do not mix https:// and non-https entries in one call."
+      ),
       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."
@@ -1047,15 +1129,24 @@ function registerRouteTools(server) {
           ]
         };
       }
-      const cleanedTo = to.map(cleanUpstreamAddr);
+      const plan = planUpstreams(to);
+      if ("error" in plan) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: `Error: ${plan.error}` }]
+        };
+      }
+      const cleanedTo = plan.dials;
+      const proxyHandler = {
+        handler: "reverse_proxy",
+        upstreams: cleanedTo.map((addr) => ({ dial: addr }))
+      };
+      if (plan.tls) {
+        proxyHandler.transport = { protocol: "http", tls: {} };
+      }
       const route = {
         match: [match],
-        handle: [
-          {
-            handler: "reverse_proxy",
-            upstreams: cleanedTo.map((addr) => ({ dial: addr }))
-          }
-        ],
+        handle: [proxyHandler],
         terminal: true
       };
       if (id) {
@@ -1143,7 +1234,11 @@ function registerRouteTools(server) {
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async ({ server: srv }) => {
       const serverRes = await configGet(`apps/http/servers/${srv}`);
+      if (isMissingConfigPath(serverRes)) return serverNotFoundError(srv, "caddy_list_routes");
       if (!serverRes.ok) return formatResult(serverRes);
+      if (serverRes.data === null || serverRes.data === void 0) {
+        return serverNullError(srv);
+      }
       const serverConfig = serverRes.data || {};
       const routes = Array.isArray(serverConfig.routes) ? serverConfig.routes : [];
       const listen = Array.isArray(serverConfig.listen) ? serverConfig.listen : [];
@@ -1280,14 +1375,19 @@ 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. Index-based removal is a two-step read-then-delete and can race against concurrent edits; prefer @id when possible.",
+    "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. Only the @id mode is idempotent: a repeat call cannot remove a different route, it just reports the id as gone. The index mode is NOT \u2014 Caddy re-packs the routes array after a removal, so calling with index 2 twice removes TWO DIFFERENT routes. @ids are config-global in Caddy (NOT route-scoped): if `id` resolves to a non-route object (TLS issuer, server, etc.) the call refuses rather than deleting it.",
     {
       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)"),
       server: z4.string().regex(/^[\w-]{1,128}$/).optional().default("srv0").describe("Caddy server name when using index (default: srv0). Ignored when id is provided."),
       confirm: z4.boolean().optional().default(false).describe("Must be true to actually remove the route (safety)")
     },
-    { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    // idempotentHint is false because the hint covers the TOOL, and hosts gate
+    // on it before they can see which targeting mode a given call carries. The
+    // @id path is idempotent; the index path is not -- Caddy re-packs the
+    // routes array on removal, so a repeated index deletes a different route
+    // each time. The weaker of the two has to win.
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
     async ({ id, index, server: srv, confirm }) => {
       if (!id && index === void 0) {
         return {
@@ -1308,6 +1408,19 @@ function registerRouteTools(server) {
         };
       }
       if (id) {
+        const existing = await configByIdGet(id);
+        if (!existing.ok) return formatResult(existing);
+        if (!isRouteShape(existing.data)) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: `Error: @id "${id}" resolves to a non-route config object (no top-level "handle" array). @ids are config-global in Caddy, not route-scoped -- refusing to delete it as a route. Inspect it with caddy_config_by_id { id: "${id}", action: "get" }, and if you did mean to remove that object, delete it deliberately with caddy_config_by_id { id: "${id}", action: "delete", confirm: true }.`
+              }
+            ]
+          };
+        }
         const res2 = await configByIdDelete(id);
         if (res2.ok) return { content: [{ type: "text", text: `Route @id="${id}" removed.` }] };
         return formatResult(res2);
@@ -1419,6 +1532,30 @@ function validateIssuerShape(tls) {
   }
   return null;
 }
+var ACME_ISSUER_MODULE = "acme";
+function validateIssuerModule(tls) {
+  const automation = tls.automation;
+  const found = automation.policies[0].issuers[0].module;
+  if (found === ACME_ISSUER_MODULE) return null;
+  const describe = found === void 0 ? "absent" : JSON.stringify(found);
+  return `Refusing to write an ACME field onto a non-ACME issuer: apps/tls.automation.policies[0].issuers[0].module is ${describe}, not "${ACME_ISSUER_MODULE}". email/ca/profile are fields of the acme issuer module only. Use caddy_config_set with an explicit path to edit this issuer, or point this tool at a config whose first policy uses an acme issuer.`;
+}
+function refuseFallback(label, patchRes, detail) {
+  return {
+    kind: "tool-error",
+    result: {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Error: Failed to set ${label}.
+  PATCH attempt: ${patchRes.error || `HTTP ${patchRes.status}`}
+  ${detail}`
+        }
+      ]
+    }
+  };
+}
 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);
@@ -1431,37 +1568,23 @@ async function safeFallback(label, patchRes, fields) {
     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.`
-          }
-        ]
-      }
-    };
+    return refuseFallback(
+      label,
+      patchRes,
+      `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.`
-          }
-        ]
-      }
-    };
+    return refuseFallback(
+      label,
+      patchRes,
+      `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 moduleError = validateIssuerModule(getRes.data);
+  if (moduleError) {
+    return refuseFallback(label, patchRes, moduleError);
   }
   const merged = mergeIssuerFields(getRes.data, fields);
   const mergeRes = await configPatch("apps/tls", merged);
@@ -1481,7 +1604,7 @@ function missingArgError(text) {
 function registerTlsTools(server) {
   server.tool(
     "caddy_tls",
-    "Get or configure TLS/HTTPS settings. Actions: 'status' shows current TLS config, 'set_email' sets the ACME email, 'set_acme_ca' sets the ACME CA URL, 'set_acme_profile' sets the ACME profile (Caddy 2.10+), 'ech_status' reads the Encrypted ClientHello config (Caddy 2.10+, read-only here). Works on both fresh and existing Caddy instances. Writes target policies[0].issuers[0] only -- on a multi-policy TLS config, edit the intended policy with caddy_config_set instead.",
+    "Get or configure TLS/HTTPS settings. Actions: 'status' shows current TLS config, 'set_email' sets the ACME email, 'set_acme_ca' sets the ACME CA URL, 'set_acme_profile' sets the ACME profile (Caddy 2.10+), 'ech_status' reads the Encrypted ClientHello config (Caddy 2.10+, read-only here). Works on both fresh and existing Caddy instances. Writes target policies[0].issuers[0] only, and only when that issuer's module is 'acme' -- on a multi-policy TLS config, or one whose first issuer is 'internal' (Caddy's local CA), edit the intended issuer with caddy_config_set instead.",
     {
       action: z5.enum(["status", "set_email", "set_acme_ca", "set_acme_profile", "ech_status"]).describe("Action to perform"),
       email: z5.string().optional().describe("ACME email address (for 'set_email' action)"),
@@ -1522,7 +1645,8 @@ function registerTlsTools(server) {
         if (!profile) return missingArgError("profile is required for set_acme_profile action");
         return setIssuerField("profile", profile, "ACME profile");
       }
-      return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
+      const unhandled = action;
+      return { isError: true, content: [{ type: "text", text: `Unknown action: ${String(unhandled)}` }] };
     }
   );
 }

package/dist/server.js

@@ -86,6 +86,9 @@ function getHeaders(contentType, overUnixSocket = false) {
 function normalizePath(path) {
   return path.replace(/^\/?(config(\/|$))?/, "");
 }
+function encodePathSegments(path) {
+  return path.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+}
 function rejectTraversal(path) {
   if (/(^|\/)\.\.(\/|$)/.test(path)) {
     return {
@@ -105,6 +108,10 @@ function isTransientFailure(res) {
   if (res.status >= 500 && res.status <= 599) return true;
   return false;
 }
+function isMissingConfigPath(res) {
+  if (res.ok) return false;
+  return (res.error ?? "").toLowerCase().includes("invalid traversal path");
+}
 var ARRAY_INDEX_TAIL_RE = /\/\d+$/;
 function isRetryableMethod(method, path) {
   if (method === "PUT") return !ARRAY_INDEX_TAIL_RE.test(path);
@@ -261,31 +268,31 @@ function configGet(path = "") {
   const normalized = normalizePath(path);
   const bad = rejectTraversal(normalized);
   if (bad) return Promise.resolve(bad);
-  return caddyRequest("GET", `/config/${normalized}`);
+  return caddyRequest("GET", `/config/${encodePathSegments(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);
+  return caddyRequest("POST", `/config/${encodePathSegments(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);
+  return caddyRequest("PUT", `/config/${encodePathSegments(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);
+  return caddyRequest("PATCH", `/config/${encodePathSegments(normalized)}`, value);
 }
 function configDelete(path) {
   const normalized = normalizePath(path);
   const bad = rejectTraversal(normalized);
   if (bad) return Promise.resolve(bad);
-  return caddyRequest("DELETE", `/config/${normalized}`);
+  return caddyRequest("DELETE", `/config/${encodePathSegments(normalized)}`);
 }
 function getRequestTimeout() {
   const raw = process.env.CADDY_TIMEOUT;
@@ -322,19 +329,23 @@ function getUpstreams() {
 function getPki(ca = "local") {
   const bad = rejectTraversal(ca);
   if (bad) return Promise.resolve(bad);
-  return caddyRequest("GET", `/pki/ca/${ca}`);
+  return caddyRequest("GET", `/pki/ca/${encodePathSegments(ca)}`);
 }
 function getPkiCertificates(ca = "local") {
   const bad = rejectTraversal(ca);
   if (bad) return Promise.resolve(bad);
-  return caddyRequest("GET", `/pki/ca/${ca}/certificates`);
+  return caddyRequest("GET", `/pki/ca/${encodePathSegments(ca)}/certificates`);
+}
+function idPath(id, subpath) {
+  const encodedId = encodePathSegments(id);
+  return subpath ? `/id/${encodedId}/${encodePathSegments(subpath)}` : `/id/${encodedId}`;
 }
 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}`;
+  const path = idPath(id, subpath);
   return caddyRequest("GET", path);
 }
 function configByIdSet(id, value, method = "PATCH", subpath = "") {
@@ -342,7 +353,7 @@ function configByIdSet(id, value, method = "PATCH", subpath = "") {
   if (badId) return Promise.resolve(badId);
   const bad = rejectTraversal(subpath);
   if (bad) return Promise.resolve(bad);
-  const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
+  const path = idPath(id, subpath);
   return caddyRequest(method, path, value);
 }
 function configByIdDelete(id, subpath = "") {
@@ -350,7 +361,7 @@ function configByIdDelete(id, subpath = "") {
   if (badId) return Promise.resolve(badId);
   const bad = rejectTraversal(subpath);
   if (bad) return Promise.resolve(bad);
-  const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
+  const path = idPath(id, subpath);
   return caddyRequest("DELETE", path);
 }
 function getMetrics() {
@@ -379,7 +390,8 @@ function describeServer(rawValue) {
   const raw = rawValue !== null && typeof rawValue === "object" && !Array.isArray(rawValue) ? rawValue : {};
   const listen = Array.isArray(raw.listen) ? raw.listen : [];
   const routes = Array.isArray(raw.routes) ? raw.routes : [];
-  const hasExplicitTls = !!raw.tls_connection_policies;
+  const tlsPolicies = raw.tls_connection_policies;
+  const hasExplicitTls = Array.isArray(tlsPolicies) ? tlsPolicies.length > 0 : !!tlsPolicies;
   const listensHttps = listen.some((l) => typeof l === "string" && HTTPS_PORT_RE.test(l));
   const tls = hasExplicitTls ? "enabled" : listensHttps ? "auto (HTTPS)" : "off (HTTP only)";
   const listenStr = listen.length > 0 ? listen.map(String).join(", ") : "default";
@@ -463,6 +475,9 @@ ACME email: ${email}`);
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async () => {
       const res = await configGet("apps/http/servers");
+      if (isMissingConfigPath(res)) {
+        return { content: [{ type: "text", text: "No HTTP servers configured" }] };
+      }
       if (!res.ok) return formatResult(res);
       const servers = res.data ?? {};
       const names = Object.keys(servers);
@@ -533,6 +548,9 @@ ${lines.join("\n")}` }]
 }
 
 // src/resources.ts
+function errorText(res) {
+  return `Error: ${res.error || `HTTP ${res.status}`}`;
+}
 function registerResources(server) {
   server.resource("caddy-config", "caddy://config", { description: "Current Caddy JSON configuration" }, async () => {
     const res = await configGet();
@@ -541,7 +559,7 @@ function registerResources(server) {
         {
           uri: "caddy://config",
           mimeType: res.ok ? "application/json" : "text/plain",
-          text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : `Error: ${res.error}`
+          text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : errorText(res)
         }
       ]
     };
@@ -557,7 +575,7 @@ function registerResources(server) {
           {
             uri: "caddy://upstreams",
             mimeType: res.ok ? "application/json" : "text/plain",
-            text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : `Error: ${res.error}`
+            text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : errorText(res)
           }
         ]
       };
@@ -577,7 +595,7 @@ function registerResources(server) {
             {
               uri: "caddy://metrics",
               mimeType: "text/plain",
-              text: `Error: ${res.error}`
+              text: errorText(res)
             }
           ]
         };
@@ -605,7 +623,7 @@ function registerResources(server) {
           {
             uri: "caddy://servers",
             mimeType: res.ok ? "application/json" : "text/plain",
-            text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : `Error: ${res.error}`
+            text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : errorText(res)
           }
         ]
       };
@@ -766,7 +784,15 @@ function registerConfigTools(server) {
       path: z3.string().describe("Config path to delete (e.g., 'apps/http/servers/srv0/routes/0')"),
       confirm: z3.boolean().optional().default(false).describe("Must be true to actually delete the config node (safety)")
     },
-    { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    // idempotentHint is FALSE because the hint covers the whole tool and cannot see
+    // the path it is called with. This tool's own documented example ends in an
+    // array index -- 'apps/http/servers/srv0/routes/0' -- and Caddy re-packs an
+    // array after a delete, so repeating that call removes a DIFFERENT route each
+    // time. caddy_remove_route carries the same correction for the byte-identical
+    // underlying request; the two must agree. Nothing here is auto-recoverable
+    // either: only caddy_load captures a snapshot, so a spurious repeat cannot be
+    // undone with caddy_revert.
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
     async ({ path, confirm }) => {
       if (!confirm) {
         return {
@@ -878,13 +904,16 @@ ${lines.join("\n")}` }] };
       const current = await configGet();
       const res = await loadConfig(snap.config, "application/json");
       if (!res.ok) return formatResult(res);
-      if (current.ok && isSnapshotableConfig(current.data)) {
+      const capturedRollforward = current.ok && isSnapshotableConfig(current.data);
+      if (capturedRollforward) {
         saveSnapshot(current.data, "caddy_revert");
       }
       const when = new Date(snap.timestamp).toISOString();
+      const skipped = current.ok ? "the pre-revert config was empty or not a JSON object" : "the pre-revert config could not be read";
+      const note = capturedRollforward ? "" : ` Warning: ${skipped}, so no roll-forward snapshot was captured -- this revert cannot be rolled back to the config it replaced.`;
       return {
         content: [
-          { type: "text", text: `Reverted to snapshot [${index}] (${when}, trigger=${snap.trigger}).` }
+          { type: "text", text: `Reverted to snapshot [${index}] (${when}, trigger=${snap.trigger}).${note}` }
         ]
       };
     }
@@ -902,7 +931,13 @@ ${lines.join("\n")}` }] };
       ),
       confirm: z3.boolean().optional().default(false).describe("Must be true to actually delete (only enforced for action='delete')")
     },
-    { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    // destructiveHint is keyed to the worst thing this tool can do, not the
+    // default action: action='delete' removes the identified object and every
+    // descendant, exactly like caddy_config_delete. Hosts gate on the hint
+    // before they can see which action the call carries.
+    // idempotentHint stays false for the same reason -- action='set' with
+    // mode='append' is a POST, so a repeated call appends a second copy.
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
     async ({ id, action, value, subpath, mode, confirm }) => {
       if (action === "get") {
         return formatResult(await configByIdGet(id, subpath));
@@ -932,7 +967,8 @@ ${lines.join("\n")}` }] };
         }
         return formatResult(await configByIdDelete(id, subpath));
       }
-      return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
+      const unhandled = action;
+      return { isError: true, content: [{ type: "text", text: `Unknown action: ${String(unhandled)}` }] };
     }
   );
 }
@@ -943,7 +979,7 @@ var ROUTES_JSON_MAX_CHARS = 2e4;
 var ROUTES_SUMMARY_MAX = 500;
 function serializeRoutesCapped(routes) {
   const parts = [];
-  let used = 2;
+  let used = 3;
   for (const route of routes) {
     const entry = JSON.stringify(route, null, 2).split("\n").map((line) => `  ${line}`).join("\n");
     const cost = entry.length + (parts.length > 0 ? 2 : 1);
@@ -993,9 +1029,42 @@ function parseFrom(from) {
 function cleanUpstreamAddr(addr) {
   return addr.replace(/^https?:\/\//, "").replace(/\/+$/, "");
 }
+function withDefaultPort(dial, port) {
+  if (stripPort(dial) !== dial) return dial;
+  const bareIpv6 = !dial.startsWith("[") && dial.indexOf(":") !== dial.lastIndexOf(":");
+  return bareIpv6 ? `[${dial}]:${port}` : `${dial}:${port}`;
+}
+function planUpstreams(to) {
+  if (to.length === 0) {
+    return { error: `"to" must list at least one upstream address (e.g. ["localhost:3000"]).` };
+  }
+  const dials = [];
+  let secure = 0;
+  let plain = 0;
+  for (const raw of to) {
+    const trimmed = raw.trim();
+    const isTls = trimmed.startsWith("https://");
+    const dial = cleanUpstreamAddr(trimmed);
+    if (dial.length === 0) {
+      return {
+        error: `upstream ${JSON.stringify(raw)} has no address to dial. Each "to" entry needs a host and port (e.g. "localhost:3000", "https://backend.example.com:8443").`
+      };
+    }
+    if (isTls) secure++;
+    else plain++;
+    dials.push(isTls ? withDefaultPort(dial, 443) : dial);
+  }
+  if (secure > 0 && plain > 0) {
+    return {
+      error: `"to" mixes https:// and non-https upstreams. Caddy's TLS transport applies to the whole reverse_proxy handler, not per-upstream, so one scheme would be silently forced on the other's connection. Split them into two routes, or build the handler explicitly with caddy_add_route.`
+    };
+  }
+  return { dials, tls: secure > 0 };
+}
 function isParentMissing(res) {
   if (res.ok) return false;
   if (res.status === 404) return true;
+  if (isMissingConfigPath(res)) return true;
   return res.error?.includes("key does not exist") ?? false;
 }
 function isUnknownId(res) {
@@ -1014,7 +1083,18 @@ function serverNotFoundError(srv, op = "operation") {
     content: [
       {
         type: "text",
-        text: `Error: Server "${srv}" does not exist (${op}). Use caddy_list_servers to see available servers, or create one with caddy_load or caddy_config_set at path 'apps/http/servers/${srv}' with at minimum: { "listen": [":443"] }`
+        text: `Error: Server "${srv}" does not exist (${op}). Use caddy_list_servers to see what is configured. To create it: caddy_config_set { path: "apps/http/servers/${srv}", mode: "append", value: { "listen": [":443"], "routes": [] } }. Both arguments are load-bearing: mode "append" creates the key, while the default "overwrite" fails with "key does not exist"; and "routes": [] must be present, or adding the first route fails, because a POST creates a missing routes key as an object rather than an array. On an instance with no config at all, use caddy_load instead -- caddy_config_set cannot create the apps/http tree it would write into.`
+      }
+    ]
+  };
+}
+function serverNullError(srv) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: `Error: Server "${srv}" is not configured, or its config is null -- Caddy returns the same response (HTTP 200 with a body of null) for both, so they cannot be told apart from here. Use caddy_list_servers to see which servers exist, or create this one with caddy_load or caddy_config_set at path 'apps/http/servers/${srv}' with at minimum: { "listen": [":443"] }`
       }
     ]
   };
@@ -1022,10 +1102,12 @@ function serverNotFoundError(srv, op = "operation") {
 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']. 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 PATCH 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.",
+    "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 PATCH 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. Upstream scheme is honored: an `https://` upstream gets a TLS transport and defaults to port 443, anything else is dialed in the clear. A `to` list that MIXES https:// and non-https entries is refused \u2014 the TLS transport applies to the whole handler, not per-upstream \u2014 so split those into two routes or use caddy_add_route.",
     {
       from: z4.string().min(1).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'])"),
+      to: z4.array(z4.string().min(1)).min(1).describe(
+        "Upstream addresses, at least one (e.g., ['localhost:3000', 'localhost:3001']). An 'https://' prefix dials the upstream over TLS (port 443 unless one is given); http:// and bare addresses are dialed in the clear. Do not mix https:// and non-https entries in one call."
+      ),
       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."
@@ -1045,15 +1127,24 @@ function registerRouteTools(server) {
           ]
         };
       }
-      const cleanedTo = to.map(cleanUpstreamAddr);
+      const plan = planUpstreams(to);
+      if ("error" in plan) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: `Error: ${plan.error}` }]
+        };
+      }
+      const cleanedTo = plan.dials;
+      const proxyHandler = {
+        handler: "reverse_proxy",
+        upstreams: cleanedTo.map((addr) => ({ dial: addr }))
+      };
+      if (plan.tls) {
+        proxyHandler.transport = { protocol: "http", tls: {} };
+      }
       const route = {
         match: [match],
-        handle: [
-          {
-            handler: "reverse_proxy",
-            upstreams: cleanedTo.map((addr) => ({ dial: addr }))
-          }
-        ],
+        handle: [proxyHandler],
         terminal: true
       };
       if (id) {
@@ -1141,7 +1232,11 @@ function registerRouteTools(server) {
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async ({ server: srv }) => {
       const serverRes = await configGet(`apps/http/servers/${srv}`);
+      if (isMissingConfigPath(serverRes)) return serverNotFoundError(srv, "caddy_list_routes");
       if (!serverRes.ok) return formatResult(serverRes);
+      if (serverRes.data === null || serverRes.data === void 0) {
+        return serverNullError(srv);
+      }
       const serverConfig = serverRes.data || {};
       const routes = Array.isArray(serverConfig.routes) ? serverConfig.routes : [];
       const listen = Array.isArray(serverConfig.listen) ? serverConfig.listen : [];
@@ -1278,14 +1373,19 @@ 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. Index-based removal is a two-step read-then-delete and can race against concurrent edits; prefer @id when possible.",
+    "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. Only the @id mode is idempotent: a repeat call cannot remove a different route, it just reports the id as gone. The index mode is NOT \u2014 Caddy re-packs the routes array after a removal, so calling with index 2 twice removes TWO DIFFERENT routes. @ids are config-global in Caddy (NOT route-scoped): if `id` resolves to a non-route object (TLS issuer, server, etc.) the call refuses rather than deleting it.",
     {
       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)"),
       server: z4.string().regex(/^[\w-]{1,128}$/).optional().default("srv0").describe("Caddy server name when using index (default: srv0). Ignored when id is provided."),
       confirm: z4.boolean().optional().default(false).describe("Must be true to actually remove the route (safety)")
     },
-    { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    // idempotentHint is false because the hint covers the TOOL, and hosts gate
+    // on it before they can see which targeting mode a given call carries. The
+    // @id path is idempotent; the index path is not -- Caddy re-packs the
+    // routes array on removal, so a repeated index deletes a different route
+    // each time. The weaker of the two has to win.
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
     async ({ id, index, server: srv, confirm }) => {
       if (!id && index === void 0) {
         return {
@@ -1306,6 +1406,19 @@ function registerRouteTools(server) {
         };
       }
       if (id) {
+        const existing = await configByIdGet(id);
+        if (!existing.ok) return formatResult(existing);
+        if (!isRouteShape(existing.data)) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: `Error: @id "${id}" resolves to a non-route config object (no top-level "handle" array). @ids are config-global in Caddy, not route-scoped -- refusing to delete it as a route. Inspect it with caddy_config_by_id { id: "${id}", action: "get" }, and if you did mean to remove that object, delete it deliberately with caddy_config_by_id { id: "${id}", action: "delete", confirm: true }.`
+              }
+            ]
+          };
+        }
         const res2 = await configByIdDelete(id);
         if (res2.ok) return { content: [{ type: "text", text: `Route @id="${id}" removed.` }] };
         return formatResult(res2);
@@ -1417,6 +1530,30 @@ function validateIssuerShape(tls) {
   }
   return null;
 }
+var ACME_ISSUER_MODULE = "acme";
+function validateIssuerModule(tls) {
+  const automation = tls.automation;
+  const found = automation.policies[0].issuers[0].module;
+  if (found === ACME_ISSUER_MODULE) return null;
+  const describe = found === void 0 ? "absent" : JSON.stringify(found);
+  return `Refusing to write an ACME field onto a non-ACME issuer: apps/tls.automation.policies[0].issuers[0].module is ${describe}, not "${ACME_ISSUER_MODULE}". email/ca/profile are fields of the acme issuer module only. Use caddy_config_set with an explicit path to edit this issuer, or point this tool at a config whose first policy uses an acme issuer.`;
+}
+function refuseFallback(label, patchRes, detail) {
+  return {
+    kind: "tool-error",
+    result: {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Error: Failed to set ${label}.
+  PATCH attempt: ${patchRes.error || `HTTP ${patchRes.status}`}
+  ${detail}`
+        }
+      ]
+    }
+  };
+}
 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);
@@ -1429,37 +1566,23 @@ async function safeFallback(label, patchRes, fields) {
     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.`
-          }
-        ]
-      }
-    };
+    return refuseFallback(
+      label,
+      patchRes,
+      `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.`
-          }
-        ]
-      }
-    };
+    return refuseFallback(
+      label,
+      patchRes,
+      `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 moduleError = validateIssuerModule(getRes.data);
+  if (moduleError) {
+    return refuseFallback(label, patchRes, moduleError);
   }
   const merged = mergeIssuerFields(getRes.data, fields);
   const mergeRes = await configPatch("apps/tls", merged);
@@ -1479,7 +1602,7 @@ function missingArgError(text) {
 function registerTlsTools(server) {
   server.tool(
     "caddy_tls",
-    "Get or configure TLS/HTTPS settings. Actions: 'status' shows current TLS config, 'set_email' sets the ACME email, 'set_acme_ca' sets the ACME CA URL, 'set_acme_profile' sets the ACME profile (Caddy 2.10+), 'ech_status' reads the Encrypted ClientHello config (Caddy 2.10+, read-only here). Works on both fresh and existing Caddy instances. Writes target policies[0].issuers[0] only -- on a multi-policy TLS config, edit the intended policy with caddy_config_set instead.",
+    "Get or configure TLS/HTTPS settings. Actions: 'status' shows current TLS config, 'set_email' sets the ACME email, 'set_acme_ca' sets the ACME CA URL, 'set_acme_profile' sets the ACME profile (Caddy 2.10+), 'ech_status' reads the Encrypted ClientHello config (Caddy 2.10+, read-only here). Works on both fresh and existing Caddy instances. Writes target policies[0].issuers[0] only, and only when that issuer's module is 'acme' -- on a multi-policy TLS config, or one whose first issuer is 'internal' (Caddy's local CA), edit the intended issuer with caddy_config_set instead.",
     {
       action: z5.enum(["status", "set_email", "set_acme_ca", "set_acme_profile", "ech_status"]).describe("Action to perform"),
       email: z5.string().optional().describe("ACME email address (for 'set_email' action)"),
@@ -1520,7 +1643,8 @@ function registerTlsTools(server) {
         if (!profile) return missingArgError("profile is required for set_acme_profile action");
         return setIssuerField("profile", profile, "ACME profile");
       }
-      return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
+      const unhandled = action;
+      return { isError: true, content: [{ type: "text", text: `Unknown action: ${String(unhandled)}` }] };
     }
   );
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@yawlabs/caddy-mcp",
-  "version": "2.3.2",
+  "version": "2.4.1",
   "mcpName": "io.github.YawLabs/caddy-mcp",
-  "description": "MCP server for managing Caddy web servers via the admin API",
+  "description": "Caddy MCP server for Claude Code, Cursor, and any MCP client: admin API, config, routes, reverse proxy, TLS, PKI, metrics",
   "license": "MIT",
   "author": "Yaw Labs <contact@yaw.sh> (https://yaw.sh)",
   "type": "module",
@@ -28,8 +28,8 @@
     "build": "tsup && tsc -p tsconfig.build.json",
     "dev": "tsup --watch",
     "test": "vitest run",
-    "lint": "biome check src/ bin/ scripts/",
-    "lint:fix": "biome check --write src/ bin/ scripts/",
+    "lint": "node scripts/lint.mjs check src/ bin/ scripts/",
+    "lint:fix": "node scripts/lint.mjs check --write src/ bin/ scripts/",
     "typecheck": "node scripts/typecheck.mjs",
     "typecheck:tsc": "tsc --noEmit",
     "test:ci": "npm run build && npm test",
@@ -53,6 +53,7 @@
   "devDependencies": {
     "@biomejs/biome": "~2.4.11",
     "@types/node": "^26.0.0",
+    "esbuild": "^0.28.1",
     "postject": "^1.0.0-alpha.6",
     "tsup": "^8.4.0",
     "typescript": "^7.0.2",
@@ -62,12 +63,22 @@
     "node": ">=20"
   },
   "keywords": [
+    "caddy",
+    "caddy-mcp",
+    "caddy-server",
+    "caddyfile",
     "mcp",
+    "mcp-server",
     "model-context-protocol",
-    "caddy",
     "reverse-proxy",
     "web-server",
-    "mcp-server",
+    "admin-api",
+    "tls",
+    "acme",
+    "pki",
+    "prometheus",
+    "claude-code",
+    "cursor",
     "devtools",
     "ai"
   ],
@@ -78,5 +89,5 @@
   "bugs": {
     "url": "https://github.com/YawLabs/caddy-mcp/issues"
   },
-  "homepage": "https://github.com/YawLabs/caddy-mcp"
+  "homepage": "https://yaw.sh/mcp-servers/caddy-mcp/"
 }