@yawlabs/caddy-mcp 2.5.5 → 2.5.7

package/README.md

@@ -123,9 +123,9 @@ Use the same JSON block shown above in any of these.
 - **caddy_config_get** — Read config at any JSON path (or the full config).
 - **caddy_config_set** — Write config at a path. Modes: `overwrite` (PATCH, default, idempotent; the key must exist, and the whole subtree at the path is replaced), `append` (POST: appends to an array, but replaces an existing non-array key and cannot create missing parents), `insert` (PUT: inserts at an array position, or strictly creates a key along with any missing parents and fails with 409 if it exists — the way to create a server or app, even on an instance with no config). `append` at a path ending in `/...` (e.g. `apps/http/servers/srv0/routes/...`) with an **array** value appends every element in one request — all or nothing, one reload; without the `/...`, an array value is added as a single element and Caddy rejects the load for typed arrays like `routes` or `listen`. A path that addresses the config **root** (`''`, `'/'`, `'config'`, `'/config/'`, a slash-only variant, or any of those followed by a lone `...` segment) addresses the **entire** config and requires `confirm=true`: `overwrite` and `append` there replace the whole configuration with `value`, exactly as `caddy_load` would, including the `admin` block unless `value` carries one — after which Caddy re-binds its admin endpoint to the new config's `admin.listen`, to its default address when it sets none, or to no address at all when it sets `admin.disabled`, and a `CADDY_ADMIN_URL` pointing anywhere else stops working. A root write auto-snapshots the prior config first (when it can be read) so `caddy_revert` can restore it; no other path is snapshotted. `insert` at the root only succeeds after a root `caddy_config_delete` (409 otherwise), and `overwrite` is the reverse: after a root delete it answers 404 until `append`, `insert` or `caddy_load` re-creates the config.
 - **caddy_config_delete** — Delete config at a path. Requires `confirm=true` (deleting a parent path also removes every descendant). A path that addresses the config root (`''`, `'/'`, `'config'`, `'/config/'`, a slash-only variant, or any of those followed by a lone `...` segment) addresses the **entire** config: it unloads every app and server plus the `admin` block, after which Caddy re-binds its admin endpoint to its default address (`localhost:2019`, or `$CADDY_ADMIN` in Caddy's environment) — if `CADDY_ADMIN_URL` points anywhere else, neither caddy-mcp nor `caddy_revert` can reach Caddy afterwards. A root delete auto-snapshots the prior config first (when it can be read), so `caddy_revert` can restore it while Caddy is still reachable; no other path is snapshotted. To replace the config rather than unload it, use `caddy_load`.
-- **caddy_config_by_id** — Get/set/delete config by `@id` tag — much easier than navigating deep paths. The `delete` action requires `confirm=true`.
+- **caddy_config_by_id** — Get/set/delete config by `@id` tag — much easier than navigating deep paths. The `delete` action requires `confirm=true`. Every `set` and `delete` first asks Caddy where the `id` resolves, and refuses one that does not resolve inside the config tree. If it resolves to the config root — normally because it is the config's own top-level `@id`, string or number — it names the **entire** config: `set` and `delete` with no subpath (or a lone `...`) then replace or unload the whole configuration, exactly as a root `caddy_config_set` / `caddy_config_delete` does — both require `confirm=true`, snapshot the prior config first, and report where the admin endpoint went. A subpath inside it is an ordinary write.
 - **caddy_load** — Replace the entire config atomically. Runs on `CADDY_LOAD_TIMEOUT` (55 seconds by default), like every config change. Auto-snapshots the prior config, and keeps that snapshot when the load times out with its outcome unknown. Lists the Caddyfile adapter's warnings, and reports a load that failed as an error even when Caddy answered HTTP 200 — which Caddy 2.11.4 does for a Caddyfile that adapted with warnings ([caddyserver/caddy#7246](https://github.com/caddyserver/caddy/issues/7246)). `format` is `json` (default) or `caddyfile`; stock Caddy registers only the `caddyfile` adapter, so for any other adapter compiled into a custom build, adapt first with `caddy_adapt` and load the JSON (the Atomic deploy example below).
-- **caddy_revert** — Manage config snapshots for rollback. Actions: `list`, `save`, `apply` (confirm-gated). In-memory, last 10. Auto-captured before `caddy_load`, and before a `caddy_config_delete` or `caddy_config_set` at the config root. An `apply` that times out with its outcome unknown keeps the pre-revert config as snapshot [0], which shifts every older snapshot down one index; the error says where the target now sits.
+- **caddy_revert** — Manage config snapshots for rollback. Actions: `list`, `save`, `apply` (confirm-gated). In-memory, last 10. Auto-captured before `caddy_load`, and before a `caddy_config_delete`, `caddy_config_set` or `caddy_config_by_id` that addresses the config root. An `apply` that times out with its outcome unknown keeps the pre-revert config as snapshot [0], which shifts every older snapshot down one index; the error says where the target now sits.
 
 ### Route operations (4)
 
@@ -284,9 +284,18 @@ Browsable read-only data — MCP clients can fetch these directly without a tool
     `mode: "insert"` on a route id, leaves two elements sharing one `@id`, and
     `/id/` resolves to only one of them.
 
-  Older 2.x mostly works, but the `If-Match` (ETag) concurrency guard needs Caddy
-  2.5.2 or later — before that Caddy ignores the header silently. The `@id` write
-  path relies on `PATCH` semantics that the live integration suite pins per release.
+  Older 2.x mostly works, with two exceptions that both come from how Caddy sends
+  its `ETag`. Caddy 2.8.0 and later send it as a response header. Caddy 2.5.2
+  through 2.7.x send it as an HTTP trailer, which this client cannot read, and
+  earlier versions send none. So before 2.8.0:
+  - the `If-Match` (ETag) concurrency guard is inactive, because no ETag is ever
+    cached to echo back;
+  - every `caddy_config_by_id` `set` and `delete` is refused, because the tool
+    reads the ETag to learn where Caddy resolves the `@id` before it writes
+    through it, and fails closed when it cannot.
+
+  The `@id` write path relies on `PATCH` semantics that the live integration
+  suite pins per release.
 
 ## Contributing
 
@@ -297,7 +306,7 @@ npm install
 npm run lint       # Biome check
 npm run lint:fix   # Auto-fix
 npm run build      # tsup bundle
-npm test           # Vitest (760 unit tests, +39 POSIX-only unix-socket and launcher tests; +37 live-Caddy integration tests gated by CADDY_MCP_INTEGRATION=1)
+npm test           # Vitest (781 unit tests, +39 POSIX-only unix-socket and launcher tests; +39 live-Caddy integration tests gated by CADDY_MCP_INTEGRATION=1)
 npm run typecheck  # tsc --noEmit
 ```
 

package/dist/api.d.ts

@@ -86,6 +86,29 @@ export declare function stop(): Promise<ApiResponse>;
 export declare function getUpstreams(): Promise<ApiResponse>;
 export declare function getPki(ca?: string): Promise<ApiResponse>;
 export declare function getPkiCertificates(ca?: string): Promise<ApiResponse>;
+/**
+ * The config path an @id resolves to, read from the ETag of `GET /id/<id>/@id`.
+ *
+ * Caddy decides where `/id/<id>` goes from its own index, not from anything a
+ * client can reconstruct: it builds each indexed path with `path.Join`, which
+ * collapses ".." INSIDE key names (caddy.go:311 at v2.11.4), and keys a numeric
+ * "@id" by its Go `%v` string. So a nested object under a key like "../../.."
+ * resolves to the config ROOT, and `{"@id": 7}` makes `/id/7` the root while a
+ * read of the top-level "@id" answers the number 7. The one reliable answer is
+ * where Caddy actually sends the request: handleConfigID rewrites the path and
+ * re-dispatches it internally, and the GET that lands in handleConfig writes an
+ * ETag of `"<that path> <hash>"` (makeEtag). Appending "@id" keeps the read to a
+ * few bytes. Verified against Caddy 2.11.4: a string or numeric top-level @id
+ * and a "../../.."-nested one all answer `"/config/@id <hash>"`; a route answers
+ * its own path; an id that collapses OUTSIDE the config tree (to `/load` or `/`)
+ * answers 404 with no ETag, because no config handler serves it.
+ *
+ * Returns the resolved object's path ("/config" for the root), or undefined when
+ * the ETag is absent or not of that shape. Header bytes arrive as latin1, like
+ * isEchoableEtag's input; the hash never contains a space, so the LAST space is
+ * the separator even when a key in the path contains whitespace.
+ */
+export declare function idObjectPath(etag: string | undefined): string | undefined;
 export declare function configByIdGet<T = any>(id: string, subpath?: string): Promise<ApiResponse<T>>;
 export declare function configByIdSet<T = any>(id: string, value: unknown, method?: "POST" | "PATCH" | "PUT", subpath?: string): Promise<ApiResponse<T>>;
 export declare function configByIdDelete<T = any>(id: string, subpath?: string): Promise<ApiResponse<T>>;

package/dist/index.js

@@ -557,6 +557,16 @@ function idPath(id, subpath) {
   const encodedId = encodePathSegments(id);
   return subpath ? `/id/${encodedId}/${encodePathSegments(subpath)}` : `/id/${encodedId}`;
 }
+function idObjectPath(etag) {
+  if (!etag) return void 0;
+  const decoded = Buffer.from(etag, "latin1").toString("utf8");
+  if (decoded.length < 2 || !decoded.startsWith('"') || !decoded.endsWith('"')) return void 0;
+  const inner = decoded.slice(1, -1);
+  const cut = inner.lastIndexOf(" ");
+  if (cut <= 0) return void 0;
+  const path = inner.slice(0, cut);
+  return path.endsWith("/@id") ? path.slice(0, -"/@id".length) : void 0;
+}
 function configByIdGet(id, subpath = "") {
   const badId = rejectTraversal(id);
   if (badId) return Promise.resolve(badId);
@@ -1116,6 +1126,90 @@ function rootWriteAdminNote(current, value) {
 function unreadablePriorAdminNote(verb) {
   return ` The ${verb} config could not be read, so this server cannot tell whether it set an admin.listen of its own. If it did, and that was not Caddy's default admin address, the endpoint has moved back to the default (localhost:2019, unless $CADDY_ADMIN is set in Caddy's environment) and CADDY_ADMIN_URL (${process.env.CADDY_ADMIN_URL || "http://localhost:2019"}) may no longer reach it.`;
 }
+function writeAt(mode, path, value) {
+  return mode === "overwrite" ? configPatch(path, value) : mode === "insert" ? configPut(path, value) : configPost(path, value);
+}
+function rootWriteRefusal(target, narrower) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: `Refusing to write the ENTIRE config without confirm=true. ${target} This call REPLACES the whole configuration with \`value\` ('overwrite' and 'append' both do, and Caddy runs it exactly as caddy_load would; after a root caddy_config_delete 'overwrite' answers 404 instead, while 'insert' succeeds only then and answers 409 otherwise): every app, server and route not in \`value\` is discarded, and so is the 'admin' block unless \`value\` carries one. Caddy then re-binds its admin endpoint to the new config's admin.listen, or to its default address (localhost:2019, or $CADDY_ADMIN in Caddy's environment) when it sets none, or to no address at all when it sets admin.disabled; and if CADDY_ADMIN_URL points anywhere else neither this server nor caddy_revert can reach Caddy afterwards. The current config is snapshotted first, so caddy_revert can restore it while Caddy is still reachable. To change one part of the config, ${narrower}; to replace all of it deliberately, caddy_load does the same behind the same gate. Re-run with confirm:true to proceed.`
+      }
+    ]
+  };
+}
+async function rootConfigWrite(mode, value, trigger) {
+  const current = await configGet();
+  const res = await writeAt(mode, "", value);
+  const kept = (res.ok || res.outcomeUnknown === true) && current.ok && isSnapshotableConfig(current.data);
+  if (kept) saveSnapshot(current.data, trigger);
+  const adminNote = rootWriteAdminNote(current, value);
+  if (!res.ok) {
+    if (res.outcomeUnknown && (kept || adminNote)) {
+      const snapshotPart = kept ? `The pre-write config was kept anyway, as snapshot [0] (trigger=${trigger}): if this write did apply, caddy_revert { action: "apply", index: 0, confirm: true } restores what it replaced, as long as this server can still reach Caddy's admin endpoint.` : "";
+      const adminPart = adminNote ? `If the write applied:${adminNote}` : "";
+      const tail = kept ? "If it did not apply, that snapshot is simply the config read just before it was sent." : "";
+      return formatResult({
+        ...res,
+        error: `${res.error}
+${[snapshotPart, adminPart, tail].filter(Boolean).join(" ")}`
+      });
+    }
+    return formatResult(res);
+  }
+  const note = priorConfigNote(kept, current, trigger);
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Replaced the entire config (every app and server, and the 'admin' block).${note}${adminNote}`
+      }
+    ]
+  };
+}
+function rootDeleteRefusal(target) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: `Refusing to delete the ENTIRE config without confirm=true. ${target} This unloads every app and server, and the 'admin' block with them: Caddy then re-binds its admin endpoint to its default address (localhost:2019, or $CADDY_ADMIN in Caddy's environment), and if CADDY_ADMIN_URL points anywhere else neither this server nor caddy_revert can reach Caddy afterwards. The current config is snapshotted first, so caddy_revert can restore it while Caddy is still reachable. To REPLACE the config rather than unload it, use caddy_load. Re-run with confirm:true to proceed.`
+      }
+    ]
+  };
+}
+async function rootConfigDelete(trigger) {
+  const current = await configGet();
+  const res = await configDelete("");
+  const kept = (res.ok || res.outcomeUnknown === true) && current.ok && isSnapshotableConfig(current.data);
+  if (kept) saveSnapshot(current.data, trigger);
+  if (!res.ok) {
+    if (res.outcomeUnknown && kept) {
+      return formatResult({
+        ...res,
+        error: `${res.error}
+The pre-delete config was kept anyway, as snapshot [0] (trigger=${trigger}): if this delete did apply, caddy_revert { action: "apply", index: 0, confirm: true } restores what it unloaded -- as long as this server can still reach Caddy's admin endpoint, which moves back to Caddy's default address when the deleted config set an admin.listen of its own. If the delete did not apply, that snapshot is simply the config read just before it was sent.`
+      });
+    }
+    return formatResult(res);
+  }
+  const note = priorConfigNote(kept, current, trigger);
+  const listen = kept ? adminListenOf(current.data) : void 0;
+  const adminNote = listen !== void 0 ? ` The unloaded config set admin.listen to "${listen}". If that was not already Caddy's default admin address, the endpoint has moved back to the default (localhost:2019, unless $CADDY_ADMIN is set in Caddy's environment) and CADDY_ADMIN_URL (${process.env.CADDY_ADMIN_URL || "http://localhost:2019"}) may no longer reach it.` : current.ok ? "" : unreadablePriorAdminNote("unloaded");
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Unloaded the entire config (every app and server, and the 'admin' block).${note}${adminNote}`
+      }
+    ]
+  };
+}
+function isAtIdentifiedObject(subpath) {
+  return /^\/*(\.\.\.\/*)?$/.test(subpath);
+}
 function registerConfigTools(server) {
   server.tool(
     "caddy_config_get",
@@ -1148,46 +1242,14 @@ function registerConfigTools(server) {
     // repeated call appends a second copy.
     { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
     async ({ path, value, mode, confirm }) => {
-      const write = (p) => mode === "overwrite" ? configPatch(p, value) : mode === "insert" ? configPut(p, value) : configPost(p, value);
-      if (!isRootConfigPath(path)) return formatResult(await write(path));
+      if (!isRootConfigPath(path)) return formatResult(await writeAt(mode, path, value));
       if (!confirm) {
-        return {
-          isError: true,
-          content: [
-            {
-              type: "text",
-              text: `Refusing to write the ENTIRE config without confirm=true. The path "${path}" addresses the config root, so this call REPLACES the whole configuration with \`value\` ('overwrite' and 'append' both do, and Caddy runs it exactly as caddy_load would; after a root caddy_config_delete 'overwrite' answers 404 instead, while 'insert' succeeds only then and answers 409 otherwise): every app, server and route not in \`value\` is discarded, and so is the 'admin' block unless \`value\` carries one. Caddy then re-binds its admin endpoint to the new config's admin.listen, or to its default address (localhost:2019, or $CADDY_ADMIN in Caddy's environment) when it sets none, or to no address at all when it sets admin.disabled; and if CADDY_ADMIN_URL points anywhere else neither this server nor caddy_revert can reach Caddy afterwards. The current config is snapshotted first, so caddy_revert can restore it while Caddy is still reachable. To change one part of the config, pass its path instead (e.g. 'apps/http/servers/srv0'); to replace all of it deliberately, caddy_load does the same behind the same gate. Re-run with confirm:true to proceed.`
-            }
-          ]
-        };
-      }
-      const current = await configGet();
-      const res = await write("");
-      const kept = (res.ok || res.outcomeUnknown === true) && current.ok && isSnapshotableConfig(current.data);
-      if (kept) saveSnapshot(current.data, "caddy_config_set");
-      const adminNote = rootWriteAdminNote(current, value);
-      if (!res.ok) {
-        if (res.outcomeUnknown && (kept || adminNote)) {
-          const snapshotPart = kept ? `The pre-write config was kept anyway, as snapshot [0] (trigger=caddy_config_set): if this write did apply, caddy_revert { action: "apply", index: 0, confirm: true } restores what it replaced, as long as this server can still reach Caddy's admin endpoint.` : "";
-          const adminPart = adminNote ? `If the write applied:${adminNote}` : "";
-          const tail = kept ? "If it did not apply, that snapshot is simply the config read just before it was sent." : "";
-          return formatResult({
-            ...res,
-            error: `${res.error}
-${[snapshotPart, adminPart, tail].filter(Boolean).join(" ")}`
-          });
-        }
-        return formatResult(res);
+        return rootWriteRefusal(
+          `The path "${path}" addresses the config root.`,
+          "pass its path instead (e.g. 'apps/http/servers/srv0')"
+        );
       }
-      const note = priorConfigNote(kept, current, "caddy_config_set");
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Replaced the entire config (every app and server, and the 'admin' block).${note}${adminNote}`
-          }
-        ]
-      };
+      return rootConfigWrite(mode, value, "caddy_config_set");
     }
   );
   server.tool(
@@ -1211,42 +1273,19 @@ ${[snapshotPart, adminPart, tail].filter(Boolean).join(" ")}`
     async ({ path, confirm }) => {
       const root = isRootConfigPath(path);
       if (!confirm) {
+        if (root) return rootDeleteRefusal(`The path "${path}" addresses the config root.`);
         return {
           isError: true,
           content: [
             {
               type: "text",
-              text: root ? `Refusing to delete the ENTIRE config without confirm=true. The path "${path}" addresses the config root, so this unloads every app and server, and the 'admin' block with them: Caddy then re-binds its admin endpoint to its default address (localhost:2019, or $CADDY_ADMIN in Caddy's environment), and if CADDY_ADMIN_URL points anywhere else neither this server nor caddy_revert can reach Caddy afterwards. The current config is snapshotted first, so caddy_revert can restore it while Caddy is still reachable. To REPLACE the config rather than unload it, use caddy_load. Re-run with confirm:true to proceed.` : `Refusing to delete "${path}" without confirm=true. Deleting a parent path also removes all descendants. Re-run with confirm:true to proceed.`
+              text: `Refusing to delete "${path}" without confirm=true. Deleting a parent path also removes all descendants. Re-run with confirm:true to proceed.`
             }
           ]
         };
       }
       if (!root) return formatResult(await configDelete(path));
-      const current = await configGet();
-      const res = await configDelete("");
-      const kept = (res.ok || res.outcomeUnknown === true) && current.ok && isSnapshotableConfig(current.data);
-      if (kept) saveSnapshot(current.data, "caddy_config_delete");
-      if (!res.ok) {
-        if (res.outcomeUnknown && kept) {
-          return formatResult({
-            ...res,
-            error: `${res.error}
-The pre-delete config was kept anyway, as snapshot [0] (trigger=caddy_config_delete): if this delete did apply, caddy_revert { action: "apply", index: 0, confirm: true } restores what it unloaded -- as long as this server can still reach Caddy's admin endpoint, which moves back to Caddy's default address when the deleted config set an admin.listen of its own. If the delete did not apply, that snapshot is simply the config read just before it was sent.`
-          });
-        }
-        return formatResult(res);
-      }
-      const note = priorConfigNote(kept, current, "caddy_config_delete");
-      const listen = kept ? adminListenOf(current.data) : void 0;
-      const adminNote = listen !== void 0 ? ` The unloaded config set admin.listen to "${listen}". If that was not already Caddy's default admin address, the endpoint has moved back to the default (localhost:2019, unless $CADDY_ADMIN is set in Caddy's environment) and CADDY_ADMIN_URL (${process.env.CADDY_ADMIN_URL || "http://localhost:2019"}) may no longer reach it.` : current.ok ? "" : unreadablePriorAdminNote("unloaded");
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Unloaded the entire config (every app and server, and the 'admin' block).${note}${adminNote}`
-          }
-        ]
-      };
+      return rootConfigDelete("caddy_config_delete");
     }
   );
   server.tool(
@@ -1287,7 +1326,7 @@ The pre-load config was kept anyway, as snapshot [0] (trigger=caddy_load): if th
   );
   server.tool(
     "caddy_revert",
-    "Manage config snapshots for rollback. Snapshots are auto-captured before caddy_load, and before a caddy_config_delete or caddy_config_set at the config root (any path that addresses the whole config); no other delete or set is snapshotted. Last 10. By default they live in memory only and are LOST when this server restarts -- set CADDY_MCP_SNAPSHOT_DIR to a writable directory to persist them across restarts (they contain full Caddy configs, so pick the location deliberately). Actions: 'list' shows snapshots with timestamps, 'save' manually captures the current config, 'apply' restores a snapshot (requires confirm=true).",
+    "Manage config snapshots for rollback. Snapshots are auto-captured before caddy_load, and before a caddy_config_delete or caddy_config_set at the config root (any path that addresses the whole config), and before a caddy_config_by_id set or delete whose @id resolves to the root with no subpath (or a lone '...'); no other delete or set is snapshotted. Last 10. By default they live in memory only and are LOST when this server restarts -- set CADDY_MCP_SNAPSHOT_DIR to a writable directory to persist them across restarts (they contain full Caddy configs, so pick the location deliberately). Actions: 'list' shows snapshots with timestamps, 'save' manually captures the current config, 'apply' restores a snapshot (requires confirm=true).",
     {
       action: z3.enum(["list", "save", "apply"]).describe("Action to perform"),
       index: z3.number().int().nonnegative().optional().default(0).describe("Snapshot index for 'apply' (0 = most recent, default)"),
@@ -1379,7 +1418,7 @@ The pre-revert config was kept anyway, as snapshot [0] (trigger=caddy_revert), s
   );
   server.tool(
     "caddy_config_by_id",
-    "Access config by @id tag. Any config object with an '@id' field can be read, updated, or deleted by its ID instead of needing its full path. This is the recommended way to manage individual routes and config objects. The 'delete' action requires confirm=true.",
+    "Access config by @id tag. Any config object with an '@id' field can be read, updated, or deleted by its ID instead of needing its full path. This is the recommended way to manage individual routes and config objects. The 'delete' action requires confirm=true. Every 'set' and 'delete' first asks Caddy where `id` resolves, and refuses an id that does not resolve inside the config tree (including an unknown one). If Caddy resolves `id` to the config ROOT -- normally because it is the config's own top-level '@id', string or number -- it names the ENTIRE config: 'set' and 'delete' with no subpath (or a lone '...') then act on the whole configuration exactly as caddy_config_set and caddy_config_delete do at the config root -- 'set' replaces it and 'delete' unloads it, the 'admin' block included, so Caddy's admin endpoint can move and CADDY_ADMIN_URL stop reaching it. Both then require confirm=true, snapshot the prior config first so caddy_revert can restore it, and report where the admin endpoint went. A subpath inside it (e.g. 'apps/http') is an ordinary write.",
     {
       id: z3.string().regex(/^[\w-]{1,128}$/).describe("The @id value of the config object"),
       action: z3.enum(["get", "set", "delete"]).optional().default("get").describe("Action to perform"),
@@ -1388,7 +1427,9 @@ The pre-revert config was kept anyway, as snapshot [0] (trigger=caddy_revert), s
       mode: z3.enum(["append", "overwrite", "insert"]).optional().default("overwrite").describe(
         "For 'set' action: 'overwrite' = PATCH (replace the identified object, or the value at subpath; default). 'append' = POST and 'insert' = PUT behave as in caddy_config_set at the resolved path: with a subpath into an array, POST appends and PUT inserts at the index; PUT also strictly creates an object key (409 if it exists). With NO subpath: for an array element (a route) neither replaces it \u2014 POST adds the value as a new element at the end of that array, PUT inserts it just before the identified one, and both are rejected with 'duplicate ID' if the value carries the same @id; for an object held under a key (a server) POST REPLACES it wholesale and PUT fails with 409. Use 'overwrite' to replace in place."
       ),
-      confirm: z3.boolean().optional().default(false).describe("Must be true to actually delete (only enforced for action='delete')")
+      confirm: z3.boolean().optional().default(false).describe(
+        "Must be true to actually delete, and to 'set' when Caddy resolves `id` to the config root (that replaces the ENTIRE config). Ignored for every other 'set'."
+      )
     },
     // destructiveHint is keyed to the worst thing this tool can do, not the
     // default action: action='delete' removes the identified object and every
@@ -1401,13 +1442,33 @@ The pre-revert config was kept anyway, as snapshot [0] (trigger=caddy_revert), s
       if (action === "get") {
         return formatResult(await configByIdGet(id, subpath));
       }
-      if (action === "set") {
-        if (value === void 0) {
-          return {
-            isError: true,
-            content: [{ type: "text", text: "Error: value is required for 'set' action" }]
-          };
+      if (action === "set" && value === void 0) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: "Error: value is required for 'set' action" }]
+        };
+      }
+      const probe = await configByIdGet(id, "@id");
+      if (!probe.ok) {
+        return formatResult({
+          ...probe,
+          error: `Could not check where Caddy resolves @id "${id}", so nothing was changed.
+${probe.error}`
+        });
+      }
+      const objectPath = idObjectPath(probe.etag);
+      if (objectPath === void 0 || !(objectPath === "/config" || objectPath.startsWith("/config/"))) {
+        const why = !probe.etag ? `Caddy's answer to a read of @id "${id}" carried no ETag header, so this tool cannot tell where Caddy resolves that id or what a write through it would change. Caddy sends that header from 2.8.0 on; earlier versions send it as a trailer or not at all, and a proxy in front of Caddy can strip it.` : objectPath !== void 0 ? `Caddy resolves @id "${id}" to ${objectPath || "/"}, which is outside the config tree, so this tool will not write through it.` : `Caddy's answer to a read of @id "${id}" carried an ETag this tool could not read a config path from, so it cannot tell what a write through that id would change.`;
+        return { isError: true, content: [{ type: "text", text: `${why} Nothing was changed.` }] };
+      }
+      if (objectPath === "/config" && isAtIdentifiedObject(subpath)) {
+        const target = `Caddy resolves @id "${id}" to the config root.`;
+        if (action === "set") {
+          return confirm ? rootConfigWrite(mode, value, "caddy_config_by_id") : rootWriteRefusal(target, "pass a subpath inside it instead (e.g. subpath 'apps/http')");
         }
+        return confirm ? rootConfigDelete("caddy_config_by_id") : rootDeleteRefusal(target);
+      }
+      if (action === "set") {
         const method = mode === "append" ? "POST" : mode === "insert" ? "PUT" : "PATCH";
         return formatResult(await configByIdSet(id, value, method, subpath));
       }

package/dist/server.js

@@ -555,6 +555,16 @@ function idPath(id, subpath) {
   const encodedId = encodePathSegments(id);
   return subpath ? `/id/${encodedId}/${encodePathSegments(subpath)}` : `/id/${encodedId}`;
 }
+function idObjectPath(etag) {
+  if (!etag) return void 0;
+  const decoded = Buffer.from(etag, "latin1").toString("utf8");
+  if (decoded.length < 2 || !decoded.startsWith('"') || !decoded.endsWith('"')) return void 0;
+  const inner = decoded.slice(1, -1);
+  const cut = inner.lastIndexOf(" ");
+  if (cut <= 0) return void 0;
+  const path = inner.slice(0, cut);
+  return path.endsWith("/@id") ? path.slice(0, -"/@id".length) : void 0;
+}
 function configByIdGet(id, subpath = "") {
   const badId = rejectTraversal(id);
   if (badId) return Promise.resolve(badId);
@@ -1114,6 +1124,90 @@ function rootWriteAdminNote(current, value) {
 function unreadablePriorAdminNote(verb) {
   return ` The ${verb} config could not be read, so this server cannot tell whether it set an admin.listen of its own. If it did, and that was not Caddy's default admin address, the endpoint has moved back to the default (localhost:2019, unless $CADDY_ADMIN is set in Caddy's environment) and CADDY_ADMIN_URL (${process.env.CADDY_ADMIN_URL || "http://localhost:2019"}) may no longer reach it.`;
 }
+function writeAt(mode, path, value) {
+  return mode === "overwrite" ? configPatch(path, value) : mode === "insert" ? configPut(path, value) : configPost(path, value);
+}
+function rootWriteRefusal(target, narrower) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: `Refusing to write the ENTIRE config without confirm=true. ${target} This call REPLACES the whole configuration with \`value\` ('overwrite' and 'append' both do, and Caddy runs it exactly as caddy_load would; after a root caddy_config_delete 'overwrite' answers 404 instead, while 'insert' succeeds only then and answers 409 otherwise): every app, server and route not in \`value\` is discarded, and so is the 'admin' block unless \`value\` carries one. Caddy then re-binds its admin endpoint to the new config's admin.listen, or to its default address (localhost:2019, or $CADDY_ADMIN in Caddy's environment) when it sets none, or to no address at all when it sets admin.disabled; and if CADDY_ADMIN_URL points anywhere else neither this server nor caddy_revert can reach Caddy afterwards. The current config is snapshotted first, so caddy_revert can restore it while Caddy is still reachable. To change one part of the config, ${narrower}; to replace all of it deliberately, caddy_load does the same behind the same gate. Re-run with confirm:true to proceed.`
+      }
+    ]
+  };
+}
+async function rootConfigWrite(mode, value, trigger) {
+  const current = await configGet();
+  const res = await writeAt(mode, "", value);
+  const kept = (res.ok || res.outcomeUnknown === true) && current.ok && isSnapshotableConfig(current.data);
+  if (kept) saveSnapshot(current.data, trigger);
+  const adminNote = rootWriteAdminNote(current, value);
+  if (!res.ok) {
+    if (res.outcomeUnknown && (kept || adminNote)) {
+      const snapshotPart = kept ? `The pre-write config was kept anyway, as snapshot [0] (trigger=${trigger}): if this write did apply, caddy_revert { action: "apply", index: 0, confirm: true } restores what it replaced, as long as this server can still reach Caddy's admin endpoint.` : "";
+      const adminPart = adminNote ? `If the write applied:${adminNote}` : "";
+      const tail = kept ? "If it did not apply, that snapshot is simply the config read just before it was sent." : "";
+      return formatResult({
+        ...res,
+        error: `${res.error}
+${[snapshotPart, adminPart, tail].filter(Boolean).join(" ")}`
+      });
+    }
+    return formatResult(res);
+  }
+  const note = priorConfigNote(kept, current, trigger);
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Replaced the entire config (every app and server, and the 'admin' block).${note}${adminNote}`
+      }
+    ]
+  };
+}
+function rootDeleteRefusal(target) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: `Refusing to delete the ENTIRE config without confirm=true. ${target} This unloads every app and server, and the 'admin' block with them: Caddy then re-binds its admin endpoint to its default address (localhost:2019, or $CADDY_ADMIN in Caddy's environment), and if CADDY_ADMIN_URL points anywhere else neither this server nor caddy_revert can reach Caddy afterwards. The current config is snapshotted first, so caddy_revert can restore it while Caddy is still reachable. To REPLACE the config rather than unload it, use caddy_load. Re-run with confirm:true to proceed.`
+      }
+    ]
+  };
+}
+async function rootConfigDelete(trigger) {
+  const current = await configGet();
+  const res = await configDelete("");
+  const kept = (res.ok || res.outcomeUnknown === true) && current.ok && isSnapshotableConfig(current.data);
+  if (kept) saveSnapshot(current.data, trigger);
+  if (!res.ok) {
+    if (res.outcomeUnknown && kept) {
+      return formatResult({
+        ...res,
+        error: `${res.error}
+The pre-delete config was kept anyway, as snapshot [0] (trigger=${trigger}): if this delete did apply, caddy_revert { action: "apply", index: 0, confirm: true } restores what it unloaded -- as long as this server can still reach Caddy's admin endpoint, which moves back to Caddy's default address when the deleted config set an admin.listen of its own. If the delete did not apply, that snapshot is simply the config read just before it was sent.`
+      });
+    }
+    return formatResult(res);
+  }
+  const note = priorConfigNote(kept, current, trigger);
+  const listen = kept ? adminListenOf(current.data) : void 0;
+  const adminNote = listen !== void 0 ? ` The unloaded config set admin.listen to "${listen}". If that was not already Caddy's default admin address, the endpoint has moved back to the default (localhost:2019, unless $CADDY_ADMIN is set in Caddy's environment) and CADDY_ADMIN_URL (${process.env.CADDY_ADMIN_URL || "http://localhost:2019"}) may no longer reach it.` : current.ok ? "" : unreadablePriorAdminNote("unloaded");
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Unloaded the entire config (every app and server, and the 'admin' block).${note}${adminNote}`
+      }
+    ]
+  };
+}
+function isAtIdentifiedObject(subpath) {
+  return /^\/*(\.\.\.\/*)?$/.test(subpath);
+}
 function registerConfigTools(server) {
   server.tool(
     "caddy_config_get",
@@ -1146,46 +1240,14 @@ function registerConfigTools(server) {
     // repeated call appends a second copy.
     { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
     async ({ path, value, mode, confirm }) => {
-      const write = (p) => mode === "overwrite" ? configPatch(p, value) : mode === "insert" ? configPut(p, value) : configPost(p, value);
-      if (!isRootConfigPath(path)) return formatResult(await write(path));
+      if (!isRootConfigPath(path)) return formatResult(await writeAt(mode, path, value));
       if (!confirm) {
-        return {
-          isError: true,
-          content: [
-            {
-              type: "text",
-              text: `Refusing to write the ENTIRE config without confirm=true. The path "${path}" addresses the config root, so this call REPLACES the whole configuration with \`value\` ('overwrite' and 'append' both do, and Caddy runs it exactly as caddy_load would; after a root caddy_config_delete 'overwrite' answers 404 instead, while 'insert' succeeds only then and answers 409 otherwise): every app, server and route not in \`value\` is discarded, and so is the 'admin' block unless \`value\` carries one. Caddy then re-binds its admin endpoint to the new config's admin.listen, or to its default address (localhost:2019, or $CADDY_ADMIN in Caddy's environment) when it sets none, or to no address at all when it sets admin.disabled; and if CADDY_ADMIN_URL points anywhere else neither this server nor caddy_revert can reach Caddy afterwards. The current config is snapshotted first, so caddy_revert can restore it while Caddy is still reachable. To change one part of the config, pass its path instead (e.g. 'apps/http/servers/srv0'); to replace all of it deliberately, caddy_load does the same behind the same gate. Re-run with confirm:true to proceed.`
-            }
-          ]
-        };
-      }
-      const current = await configGet();
-      const res = await write("");
-      const kept = (res.ok || res.outcomeUnknown === true) && current.ok && isSnapshotableConfig(current.data);
-      if (kept) saveSnapshot(current.data, "caddy_config_set");
-      const adminNote = rootWriteAdminNote(current, value);
-      if (!res.ok) {
-        if (res.outcomeUnknown && (kept || adminNote)) {
-          const snapshotPart = kept ? `The pre-write config was kept anyway, as snapshot [0] (trigger=caddy_config_set): if this write did apply, caddy_revert { action: "apply", index: 0, confirm: true } restores what it replaced, as long as this server can still reach Caddy's admin endpoint.` : "";
-          const adminPart = adminNote ? `If the write applied:${adminNote}` : "";
-          const tail = kept ? "If it did not apply, that snapshot is simply the config read just before it was sent." : "";
-          return formatResult({
-            ...res,
-            error: `${res.error}
-${[snapshotPart, adminPart, tail].filter(Boolean).join(" ")}`
-          });
-        }
-        return formatResult(res);
+        return rootWriteRefusal(
+          `The path "${path}" addresses the config root.`,
+          "pass its path instead (e.g. 'apps/http/servers/srv0')"
+        );
       }
-      const note = priorConfigNote(kept, current, "caddy_config_set");
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Replaced the entire config (every app and server, and the 'admin' block).${note}${adminNote}`
-          }
-        ]
-      };
+      return rootConfigWrite(mode, value, "caddy_config_set");
     }
   );
   server.tool(
@@ -1209,42 +1271,19 @@ ${[snapshotPart, adminPart, tail].filter(Boolean).join(" ")}`
     async ({ path, confirm }) => {
       const root = isRootConfigPath(path);
       if (!confirm) {
+        if (root) return rootDeleteRefusal(`The path "${path}" addresses the config root.`);
         return {
           isError: true,
           content: [
             {
               type: "text",
-              text: root ? `Refusing to delete the ENTIRE config without confirm=true. The path "${path}" addresses the config root, so this unloads every app and server, and the 'admin' block with them: Caddy then re-binds its admin endpoint to its default address (localhost:2019, or $CADDY_ADMIN in Caddy's environment), and if CADDY_ADMIN_URL points anywhere else neither this server nor caddy_revert can reach Caddy afterwards. The current config is snapshotted first, so caddy_revert can restore it while Caddy is still reachable. To REPLACE the config rather than unload it, use caddy_load. Re-run with confirm:true to proceed.` : `Refusing to delete "${path}" without confirm=true. Deleting a parent path also removes all descendants. Re-run with confirm:true to proceed.`
+              text: `Refusing to delete "${path}" without confirm=true. Deleting a parent path also removes all descendants. Re-run with confirm:true to proceed.`
             }
           ]
         };
       }
       if (!root) return formatResult(await configDelete(path));
-      const current = await configGet();
-      const res = await configDelete("");
-      const kept = (res.ok || res.outcomeUnknown === true) && current.ok && isSnapshotableConfig(current.data);
-      if (kept) saveSnapshot(current.data, "caddy_config_delete");
-      if (!res.ok) {
-        if (res.outcomeUnknown && kept) {
-          return formatResult({
-            ...res,
-            error: `${res.error}
-The pre-delete config was kept anyway, as snapshot [0] (trigger=caddy_config_delete): if this delete did apply, caddy_revert { action: "apply", index: 0, confirm: true } restores what it unloaded -- as long as this server can still reach Caddy's admin endpoint, which moves back to Caddy's default address when the deleted config set an admin.listen of its own. If the delete did not apply, that snapshot is simply the config read just before it was sent.`
-          });
-        }
-        return formatResult(res);
-      }
-      const note = priorConfigNote(kept, current, "caddy_config_delete");
-      const listen = kept ? adminListenOf(current.data) : void 0;
-      const adminNote = listen !== void 0 ? ` The unloaded config set admin.listen to "${listen}". If that was not already Caddy's default admin address, the endpoint has moved back to the default (localhost:2019, unless $CADDY_ADMIN is set in Caddy's environment) and CADDY_ADMIN_URL (${process.env.CADDY_ADMIN_URL || "http://localhost:2019"}) may no longer reach it.` : current.ok ? "" : unreadablePriorAdminNote("unloaded");
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Unloaded the entire config (every app and server, and the 'admin' block).${note}${adminNote}`
-          }
-        ]
-      };
+      return rootConfigDelete("caddy_config_delete");
     }
   );
   server.tool(
@@ -1285,7 +1324,7 @@ The pre-load config was kept anyway, as snapshot [0] (trigger=caddy_load): if th
   );
   server.tool(
     "caddy_revert",
-    "Manage config snapshots for rollback. Snapshots are auto-captured before caddy_load, and before a caddy_config_delete or caddy_config_set at the config root (any path that addresses the whole config); no other delete or set is snapshotted. Last 10. By default they live in memory only and are LOST when this server restarts -- set CADDY_MCP_SNAPSHOT_DIR to a writable directory to persist them across restarts (they contain full Caddy configs, so pick the location deliberately). Actions: 'list' shows snapshots with timestamps, 'save' manually captures the current config, 'apply' restores a snapshot (requires confirm=true).",
+    "Manage config snapshots for rollback. Snapshots are auto-captured before caddy_load, and before a caddy_config_delete or caddy_config_set at the config root (any path that addresses the whole config), and before a caddy_config_by_id set or delete whose @id resolves to the root with no subpath (or a lone '...'); no other delete or set is snapshotted. Last 10. By default they live in memory only and are LOST when this server restarts -- set CADDY_MCP_SNAPSHOT_DIR to a writable directory to persist them across restarts (they contain full Caddy configs, so pick the location deliberately). Actions: 'list' shows snapshots with timestamps, 'save' manually captures the current config, 'apply' restores a snapshot (requires confirm=true).",
     {
       action: z3.enum(["list", "save", "apply"]).describe("Action to perform"),
       index: z3.number().int().nonnegative().optional().default(0).describe("Snapshot index for 'apply' (0 = most recent, default)"),
@@ -1377,7 +1416,7 @@ The pre-revert config was kept anyway, as snapshot [0] (trigger=caddy_revert), s
   );
   server.tool(
     "caddy_config_by_id",
-    "Access config by @id tag. Any config object with an '@id' field can be read, updated, or deleted by its ID instead of needing its full path. This is the recommended way to manage individual routes and config objects. The 'delete' action requires confirm=true.",
+    "Access config by @id tag. Any config object with an '@id' field can be read, updated, or deleted by its ID instead of needing its full path. This is the recommended way to manage individual routes and config objects. The 'delete' action requires confirm=true. Every 'set' and 'delete' first asks Caddy where `id` resolves, and refuses an id that does not resolve inside the config tree (including an unknown one). If Caddy resolves `id` to the config ROOT -- normally because it is the config's own top-level '@id', string or number -- it names the ENTIRE config: 'set' and 'delete' with no subpath (or a lone '...') then act on the whole configuration exactly as caddy_config_set and caddy_config_delete do at the config root -- 'set' replaces it and 'delete' unloads it, the 'admin' block included, so Caddy's admin endpoint can move and CADDY_ADMIN_URL stop reaching it. Both then require confirm=true, snapshot the prior config first so caddy_revert can restore it, and report where the admin endpoint went. A subpath inside it (e.g. 'apps/http') is an ordinary write.",
     {
       id: z3.string().regex(/^[\w-]{1,128}$/).describe("The @id value of the config object"),
       action: z3.enum(["get", "set", "delete"]).optional().default("get").describe("Action to perform"),
@@ -1386,7 +1425,9 @@ The pre-revert config was kept anyway, as snapshot [0] (trigger=caddy_revert), s
       mode: z3.enum(["append", "overwrite", "insert"]).optional().default("overwrite").describe(
         "For 'set' action: 'overwrite' = PATCH (replace the identified object, or the value at subpath; default). 'append' = POST and 'insert' = PUT behave as in caddy_config_set at the resolved path: with a subpath into an array, POST appends and PUT inserts at the index; PUT also strictly creates an object key (409 if it exists). With NO subpath: for an array element (a route) neither replaces it \u2014 POST adds the value as a new element at the end of that array, PUT inserts it just before the identified one, and both are rejected with 'duplicate ID' if the value carries the same @id; for an object held under a key (a server) POST REPLACES it wholesale and PUT fails with 409. Use 'overwrite' to replace in place."
       ),
-      confirm: z3.boolean().optional().default(false).describe("Must be true to actually delete (only enforced for action='delete')")
+      confirm: z3.boolean().optional().default(false).describe(
+        "Must be true to actually delete, and to 'set' when Caddy resolves `id` to the config root (that replaces the ENTIRE config). Ignored for every other 'set'."
+      )
     },
     // destructiveHint is keyed to the worst thing this tool can do, not the
     // default action: action='delete' removes the identified object and every
@@ -1399,13 +1440,33 @@ The pre-revert config was kept anyway, as snapshot [0] (trigger=caddy_revert), s
       if (action === "get") {
         return formatResult(await configByIdGet(id, subpath));
       }
-      if (action === "set") {
-        if (value === void 0) {
-          return {
-            isError: true,
-            content: [{ type: "text", text: "Error: value is required for 'set' action" }]
-          };
+      if (action === "set" && value === void 0) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: "Error: value is required for 'set' action" }]
+        };
+      }
+      const probe = await configByIdGet(id, "@id");
+      if (!probe.ok) {
+        return formatResult({
+          ...probe,
+          error: `Could not check where Caddy resolves @id "${id}", so nothing was changed.
+${probe.error}`
+        });
+      }
+      const objectPath = idObjectPath(probe.etag);
+      if (objectPath === void 0 || !(objectPath === "/config" || objectPath.startsWith("/config/"))) {
+        const why = !probe.etag ? `Caddy's answer to a read of @id "${id}" carried no ETag header, so this tool cannot tell where Caddy resolves that id or what a write through it would change. Caddy sends that header from 2.8.0 on; earlier versions send it as a trailer or not at all, and a proxy in front of Caddy can strip it.` : objectPath !== void 0 ? `Caddy resolves @id "${id}" to ${objectPath || "/"}, which is outside the config tree, so this tool will not write through it.` : `Caddy's answer to a read of @id "${id}" carried an ETag this tool could not read a config path from, so it cannot tell what a write through that id would change.`;
+        return { isError: true, content: [{ type: "text", text: `${why} Nothing was changed.` }] };
+      }
+      if (objectPath === "/config" && isAtIdentifiedObject(subpath)) {
+        const target = `Caddy resolves @id "${id}" to the config root.`;
+        if (action === "set") {
+          return confirm ? rootConfigWrite(mode, value, "caddy_config_by_id") : rootWriteRefusal(target, "pass a subpath inside it instead (e.g. subpath 'apps/http')");
         }
+        return confirm ? rootConfigDelete("caddy_config_by_id") : rootDeleteRefusal(target);
+      }
+      if (action === "set") {
         const method = mode === "append" ? "POST" : mode === "insert" ? "PUT" : "PATCH";
         return formatResult(await configByIdSet(id, value, method, subpath));
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/caddy-mcp",
-  "version": "2.5.5",
+  "version": "2.5.7",
   "mcpName": "io.github.YawLabs/caddy-mcp",
   "description": "Caddy MCP server for Claude Code, Cursor, and any MCP client: admin API, config, routes, reverse proxy, TLS, PKI, metrics",
   "license": "MIT",