@yawlabs/caddy-mcp 2.5.4 → 2.5.6

package/README.md

@@ -1,5 +1,9 @@
 # @yawlabs/caddy-mcp
 
+[![Add to Yaw MCP](https://yaw.sh/yaw-mcp-button.svg)](https://yaw.sh/mcp/install?name=Caddy&command=npx&args=-y%2C%40yawlabs%2Fcaddy-mcp&description=Manage%20Caddy%20web%20servers%20-%20config%2C%20routes%2C%20TLS%2C%20PKI&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Fcaddy-mcp)
+
+One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.
+
 [![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)
@@ -8,17 +12,13 @@
 
 Built and maintained by [Yaw Labs](https://yaw.sh).
 
-[![Add to Yaw MCP](https://yaw.sh/yaw-mcp-button.svg)](https://yaw.sh/mcp/install?name=Caddy&command=npx&args=-y%2C%40yawlabs%2Fcaddy-mcp&description=Manage%20Caddy%20web%20servers%20-%20config%2C%20routes%2C%20TLS%2C%20PKI&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Fcaddy-mcp)
-
-One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.
-
 ## Why this one?
 
 Other Caddy MCP servers wrap half the admin API and silently swallow errors. This one doesn't.
 
 - **Complete admin API coverage** — every endpoint in [Caddy's admin API reference](https://caddyserver.com/docs/api): `/load`, `/config/*`, `/id/*`, `/stop`, `/adapt`, `/pki/ca/*`, `/reverse_proxy/upstreams`, `/metrics`. No placeholder tools that 404. Caddy's Go runtime debug endpoints (`/debug/pprof/*`, `/debug/vars`) are deliberately not wrapped — for leak trends use `caddy_metrics` with `filter: "go_goroutines"` or `"go_memstats"`, which come from the same admin registry; for stack dumps, CPU profiles and traces, curl the admin endpoint directly ([Caddy profiling docs](https://caddyserver.com/docs/profiling)).
 - **Safe concurrent writes** — uses ETags (`If-Match`) so your changes never silently overwrite someone else's. Surfaces `HTTP 412 Precondition Failed` as a clear message, not a cryptic error.
-- **Safe-by-default mutations** — `caddy_config_set` defaults to idempotent `overwrite` (PATCH), not `append` (POST). Calling twice doesn't duplicate your route.
+- **Safe-by-default mutations** — `caddy_config_set` defaults to idempotent `overwrite` (PATCH), not `append` (POST). Calling twice doesn't duplicate your route. A write to the config root — which replaces the *entire* config, admin endpoint included — is refused without `confirm=true` and snapshotted first, like `caddy_load`.
 - **Defensive parsing** — `caddy_list_routes` never crashes on malformed config, even if routes are null, handlers are strings, or matchers are non-arrays. Regression-tested.
 - **No leaked credentials in errors** — if `CADDY_ADMIN_URL` contains a token in the path/query, the connect-failed message shows only the origin.
 - **Fallback error surfacing** — when a TLS write PATCH fails and the PUT fallback also fails, both error bodies are returned so you know what actually went wrong.
@@ -121,11 +121,11 @@ Use the same JSON block shown above in any of these.
 ### Config management (6)
 
 - **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), `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`.
-- **caddy_config_delete** — Delete config at a path. Requires `confirm=true` (deleting a parent path also removes every descendant). An empty path (`''`, `'/'`, `'config'`, `'/config/'`) 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_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`. 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` 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 (692 unit tests, +39 POSIX-only unix-socket and launcher tests; +33 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
 ```
 
@@ -307,4 +316,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow, including release
 
 MIT
 
-[![Follow @TokenLimitNews on X](https://img.shields.io/badge/follow-%40TokenLimitNews-000000?logo=x&logoColor=white)](https://x.com/TokenLimitNews)
+[![Follow @YawLabs on X](https://img.shields.io/badge/follow-%40YawLabs-000000?logo=x&logoColor=white)](https://x.com/YawLabs)

package/dist/api.d.ts

@@ -25,6 +25,37 @@ export interface ApiResponse<T = any> {
      */
     outcomeUnknown?: boolean;
 }
+/**
+ * Does this config path address the ROOT -- the whole configuration?
+ *
+ * A write there is a different operation wearing the same request shape: PATCH
+ * and POST replace the entire config (Caddy sets `rawCfg["config"]` to the body,
+ * admin.go:1279 and :1296 at v2.11.4 -- exactly what `POST /load` does,
+ * caddy.go:136), and DELETE unloads it. Every tool that takes a config path has
+ * to know, because Caddy itself never distinguishes the root from a leaf.
+ *
+ * Root spellings, after normalizePath above has eaten one leading "/" and one
+ * "config/": nothing ("", "/", "config", "/config/"), only slashes ("//",
+ * "config//"), and any of those followed by a single "..." segment ("...",
+ * "/...", "config/...", "/config/.../"). The "..." form is Caddy's bulk-append
+ * spelling, and it is stripped BEFORE the method switch (admin.go:1196-1199),
+ * for every method, so `/config/...` lands on the same root branch as
+ * `/config/`. rejectTraversal below lets "..." through on purpose -- a trailing
+ * one under a real array is how `POST .../routes/...` appends in bulk -- so the
+ * root test has to absorb it here. Only ONE trailing "..." is stripped by Caddy:
+ * ".../..." writes a key literally named "...", which is a leaf.
+ *
+ * Verified against Caddy 2.11.4: PATCH and POST `/config/...` with an object
+ * body replaced the whole config, and DELETE `/config/...` unloaded it.
+ *
+ * Callers that branch on this must SEND the canonical "" rather than the
+ * caller's spelling (see caddy_config_delete in tools/config.ts): "//" would be
+ * encoded to `/config//`, which Go's ServeMux answers with a redirect to
+ * `/config/` instead of dispatching, so the ETag cached under "/config/" is
+ * never found and the request goes out with no If-Match; over a unix socket
+ * node:http does not follow the redirect at all.
+ */
+export declare function isRootConfigPath(path: string): boolean;
 /**
  * Caddy's "a segment of this config path does not exist" failure.
  *
@@ -55,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

@@ -138,15 +138,18 @@ function getHeaders(contentType, overUnixSocket = false) {
 function normalizePath(path) {
   return path.replace(/^\/?(config(\/|$))?/, "");
 }
+function isRootConfigPath(path) {
+  return /^\/*(\.\.\.\/*)?$/.test(normalizePath(path));
+}
 function encodePathSegments(path) {
   return path.split("/").map((segment) => encodeURIComponent(segment)).join("/");
 }
 function rejectTraversal(path) {
-  if (/(^|\/)\.\.(\/|$)/.test(path)) {
+  if (/(^|\/)\.\.?(\/|$)/.test(path)) {
     return {
       ok: false,
       status: 0,
-      error: `Invalid path "${path}": '..' segments are not allowed`
+      error: `Invalid path "${path}": '.' and '..' segments are not allowed`
     };
   }
   return null;
@@ -554,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);
@@ -1076,8 +1089,126 @@ function getSnapshot(index) {
 }
 
 // src/tools/config.ts
-function isRootConfigPath(path) {
-  return /^\/*$/.test(path.replace(/^\/?(config(\/|$))?/, ""));
+function adminListenOf(config) {
+  if (!isSnapshotableConfig(config)) return void 0;
+  const adm = config.admin;
+  if (adm === null || typeof adm !== "object" || Array.isArray(adm)) return void 0;
+  const listen = adm.listen;
+  return typeof listen === "string" && listen !== "" ? listen : void 0;
+}
+function adminDisabledIn(config) {
+  if (!isSnapshotableConfig(config)) return false;
+  const adm = config.admin;
+  return adm !== null && typeof adm === "object" && !Array.isArray(adm) && adm.disabled === true;
+}
+function priorConfigNote(kept, current, trigger) {
+  if (kept) {
+    return ` The prior config was saved as snapshot [0] (trigger=${trigger}): caddy_revert { action: "apply", index: 0, confirm: true } restores it.`;
+  }
+  return current.ok ? " Warning: the prior config was empty or not a JSON object, so no snapshot was captured -- there was nothing to restore." : " Warning: the prior config could not be read, so no snapshot was captured and this change cannot be reverted.";
+}
+function rootWriteAdminNote(current, value) {
+  if (adminDisabledIn(value)) {
+    return " The new config sets admin.disabled, so Caddy no longer answers on ANY admin address: neither this server nor caddy_revert can reach it until Caddy is restarted with a config that does not disable the admin endpoint.";
+  }
+  const adminUrl = process.env.CADDY_ADMIN_URL || "http://localhost:2019";
+  const before = current.ok ? adminListenOf(current.data) : void 0;
+  const after = adminListenOf(value);
+  if (before !== void 0 && after !== before) {
+    return ` The replaced config set admin.listen to "${before}"` + (after !== void 0 ? ` and the new one sets it to "${after}".` : " and the new one sets none.") + ` Unless those resolve to the same address, the admin endpoint has moved (to the new value, or back to the default: localhost:2019 unless $CADDY_ADMIN is set in Caddy's environment) and CADDY_ADMIN_URL (${adminUrl}) may no longer reach it.`;
+  }
+  if (before === void 0 && after !== void 0) {
+    return ` The new config sets admin.listen to "${after}". If that is not the address Caddy was already on, the admin endpoint has moved there and CADDY_ADMIN_URL (${adminUrl}) may no longer reach it.`;
+  }
+  if (!current.ok) return unreadablePriorAdminNote("replaced");
+  return "";
+}
+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(
@@ -1089,23 +1220,41 @@ function registerConfigTools(server) {
   );
   server.tool(
     "caddy_config_set",
-    "Write config at a JSON path. Mode 'overwrite' (default) replaces existing values (PATCH) \u2014 safe and idempotent. Mode 'append' (POST) adds to an array \u2014 NOT idempotent: calling twice with the same route duplicates it \u2014 but on a non-array key it REPLACES whatever is there, and it cannot create missing parent objects. Mode 'insert' (PUT) inserts at an array index (useful for route ordering), or strictly creates an object key together with any missing parents and fails with 409 if the key already exists \u2014 the safe way to create a server or app, including on an instance with no config at all.",
+    "Write config at a JSON path. Mode 'overwrite' (default) replaces the value at the path (PATCH) \u2014 idempotent, but it replaces the WHOLE subtree there: writing [] to '.../routes' drops every route. Mode 'append' (POST) adds to an array \u2014 NOT idempotent: calling twice with the same route duplicates it \u2014 but on a non-array key it REPLACES whatever is there, and it cannot create missing parent objects. Mode 'insert' (PUT) inserts at an array index (useful for route ordering), or strictly creates an object key together with any missing parents and fails with 409 if the key already exists \u2014 the safe way to create a server or app, including on an instance with no config at all. Any 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` \u2014 Caddy runs it exactly as caddy_load would \u2014 so 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; if CADDY_ADMIN_URL points anywhere else, neither this server nor caddy_revert can reach Caddy afterwards. A root write is snapshotted first, so caddy_revert can restore it while Caddy is still reachable; no other path is snapshotted. 'insert' at the root only succeeds after a root caddy_config_delete (Caddy answers 409 on any other instance, including one started with no config), and 'overwrite' is the reverse: after a root caddy_config_delete it answers 404 until 'append', 'insert' or caddy_load re-creates the config. To replace the whole config deliberately, caddy_load does the same thing behind the same gate and also accepts a Caddyfile.",
     {
       path: z3.string().describe("Config path to write to (e.g., 'apps/http/servers/srv0/routes')"),
       value: z3.any().describe("The JSON value to set at the path"),
       mode: z3.enum(["append", "overwrite", "insert"]).optional().default("overwrite").describe(
         "'overwrite' = PATCH (replace existing, default, idempotent; 404 if the key does not exist), 'append' = POST (appends to arrays, NOT idempotent; REPLACES an existing non-array key; cannot create missing parents), 'insert' = PUT (inserts at an array index, or strictly creates an object key and any missing parents; 409 if the key exists)"
+      ),
+      confirm: z3.boolean().optional().default(false).describe(
+        "Must be true when `path` addresses the config root ('', '/', 'config', '/config/', slash-only variants, or a lone '...' segment): that write replaces the ENTIRE config (safety). Ignored for every other path."
       )
     },
-    { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    async ({ path, value, mode }) => {
-      const res = mode === "overwrite" ? await configPatch(path, value) : mode === "insert" ? await configPut(path, value) : await configPost(path, value);
-      return formatResult(res);
+    // destructiveHint is TRUE because the hint covers the whole tool and a host
+    // gates on it before it can see the path or the mode: the default mode is a
+    // PATCH that replaces whatever subtree the path names -- a route list, a
+    // server, all of `apps` -- and at the root it replaces the entire config
+    // (below). MCP defines destructiveHint:false as "only additive updates".
+    // Appending to an array or strictly creating a key is additive; the
+    // default mode is not, and neither is 'append' on a non-array key, which
+    // replaces it. idempotentHint stays false for 'append', which is a POST: a
+    // repeated call appends a second copy.
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    async ({ path, value, mode, confirm }) => {
+      if (!isRootConfigPath(path)) return formatResult(await writeAt(mode, path, value));
+      if (!confirm) {
+        return rootWriteRefusal(
+          `The path "${path}" addresses the config root.`,
+          "pass its path instead (e.g. 'apps/http/servers/srv0')"
+        );
+      }
+      return rootConfigWrite(mode, value, "caddy_config_set");
     }
   );
   server.tool(
     "caddy_config_delete",
-    "Delete config at a JSON path. Removes the config node at the specified path. Deleting a parent node also deletes every descendant -- e.g. deleting 'apps/http/servers/srv0' removes that server and all of its routes. Requires confirm=true. Any path that addresses the config ROOT ('', '/', 'config', '/config/', and slash-only variants of those) addresses the ENTIRE config and unloads it: every app and server goes, and so does 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 this server nor caddy_revert can reach Caddy afterwards. A root delete is snapshotted first, 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.",
+    "Delete config at a JSON path. Removes the config node at the specified path. Deleting a parent node also deletes every descendant -- e.g. deleting 'apps/http/servers/srv0' removes that server and all of its routes. Requires confirm=true. Any path that addresses the config ROOT ('', '/', 'config', '/config/', slash-only variants of those, or any of those followed by a lone '...' segment) addresses the ENTIRE config and unloads it: every app and server goes, and so does 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 this server nor caddy_revert can reach Caddy afterwards. A root delete is snapshotted first, 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.",
     {
       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)")
@@ -1116,49 +1265,27 @@ function registerConfigTools(server) {
     // 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: apart from a root delete (below), only caddy_load captures a
-    // snapshot, so a spurious repeat cannot be undone with caddy_revert.
+    // either: apart from a root delete (below), only whole-config changes
+    // capture a snapshot -- caddy_load, a caddy_revert apply, and a root
+    // caddy_config_set -- so a spurious repeat cannot be undone with
+    // caddy_revert.
     { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
     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 = kept ? ` The prior config was saved as snapshot [0] (trigger=caddy_config_delete): caddy_revert { action: "apply", index: 0, confirm: true } restores it.` : current.ok ? " Warning: the prior config was empty or not a JSON object, so no snapshot was captured -- there was nothing to restore." : " Warning: the prior config could not be read, so no snapshot was captured and this unload cannot be reverted.";
-      const adm = kept ? current.data.admin : void 0;
-      const listen = adm !== null && typeof adm === "object" && !Array.isArray(adm) ? adm.listen : void 0;
-      const adminNote = typeof listen === "string" && listen !== "" ? ` 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.` : "";
-      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(
@@ -1199,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 that unloads the whole config (an empty path); no other delete 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)"),
@@ -1291,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"),
@@ -1300,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
@@ -1313,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

@@ -136,15 +136,18 @@ function getHeaders(contentType, overUnixSocket = false) {
 function normalizePath(path) {
   return path.replace(/^\/?(config(\/|$))?/, "");
 }
+function isRootConfigPath(path) {
+  return /^\/*(\.\.\.\/*)?$/.test(normalizePath(path));
+}
 function encodePathSegments(path) {
   return path.split("/").map((segment) => encodeURIComponent(segment)).join("/");
 }
 function rejectTraversal(path) {
-  if (/(^|\/)\.\.(\/|$)/.test(path)) {
+  if (/(^|\/)\.\.?(\/|$)/.test(path)) {
     return {
       ok: false,
       status: 0,
-      error: `Invalid path "${path}": '..' segments are not allowed`
+      error: `Invalid path "${path}": '.' and '..' segments are not allowed`
     };
   }
   return null;
@@ -552,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);
@@ -1074,8 +1087,126 @@ function getSnapshot(index) {
 }
 
 // src/tools/config.ts
-function isRootConfigPath(path) {
-  return /^\/*$/.test(path.replace(/^\/?(config(\/|$))?/, ""));
+function adminListenOf(config) {
+  if (!isSnapshotableConfig(config)) return void 0;
+  const adm = config.admin;
+  if (adm === null || typeof adm !== "object" || Array.isArray(adm)) return void 0;
+  const listen = adm.listen;
+  return typeof listen === "string" && listen !== "" ? listen : void 0;
+}
+function adminDisabledIn(config) {
+  if (!isSnapshotableConfig(config)) return false;
+  const adm = config.admin;
+  return adm !== null && typeof adm === "object" && !Array.isArray(adm) && adm.disabled === true;
+}
+function priorConfigNote(kept, current, trigger) {
+  if (kept) {
+    return ` The prior config was saved as snapshot [0] (trigger=${trigger}): caddy_revert { action: "apply", index: 0, confirm: true } restores it.`;
+  }
+  return current.ok ? " Warning: the prior config was empty or not a JSON object, so no snapshot was captured -- there was nothing to restore." : " Warning: the prior config could not be read, so no snapshot was captured and this change cannot be reverted.";
+}
+function rootWriteAdminNote(current, value) {
+  if (adminDisabledIn(value)) {
+    return " The new config sets admin.disabled, so Caddy no longer answers on ANY admin address: neither this server nor caddy_revert can reach it until Caddy is restarted with a config that does not disable the admin endpoint.";
+  }
+  const adminUrl = process.env.CADDY_ADMIN_URL || "http://localhost:2019";
+  const before = current.ok ? adminListenOf(current.data) : void 0;
+  const after = adminListenOf(value);
+  if (before !== void 0 && after !== before) {
+    return ` The replaced config set admin.listen to "${before}"` + (after !== void 0 ? ` and the new one sets it to "${after}".` : " and the new one sets none.") + ` Unless those resolve to the same address, the admin endpoint has moved (to the new value, or back to the default: localhost:2019 unless $CADDY_ADMIN is set in Caddy's environment) and CADDY_ADMIN_URL (${adminUrl}) may no longer reach it.`;
+  }
+  if (before === void 0 && after !== void 0) {
+    return ` The new config sets admin.listen to "${after}". If that is not the address Caddy was already on, the admin endpoint has moved there and CADDY_ADMIN_URL (${adminUrl}) may no longer reach it.`;
+  }
+  if (!current.ok) return unreadablePriorAdminNote("replaced");
+  return "";
+}
+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(
@@ -1087,23 +1218,41 @@ function registerConfigTools(server) {
   );
   server.tool(
     "caddy_config_set",
-    "Write config at a JSON path. Mode 'overwrite' (default) replaces existing values (PATCH) \u2014 safe and idempotent. Mode 'append' (POST) adds to an array \u2014 NOT idempotent: calling twice with the same route duplicates it \u2014 but on a non-array key it REPLACES whatever is there, and it cannot create missing parent objects. Mode 'insert' (PUT) inserts at an array index (useful for route ordering), or strictly creates an object key together with any missing parents and fails with 409 if the key already exists \u2014 the safe way to create a server or app, including on an instance with no config at all.",
+    "Write config at a JSON path. Mode 'overwrite' (default) replaces the value at the path (PATCH) \u2014 idempotent, but it replaces the WHOLE subtree there: writing [] to '.../routes' drops every route. Mode 'append' (POST) adds to an array \u2014 NOT idempotent: calling twice with the same route duplicates it \u2014 but on a non-array key it REPLACES whatever is there, and it cannot create missing parent objects. Mode 'insert' (PUT) inserts at an array index (useful for route ordering), or strictly creates an object key together with any missing parents and fails with 409 if the key already exists \u2014 the safe way to create a server or app, including on an instance with no config at all. Any 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` \u2014 Caddy runs it exactly as caddy_load would \u2014 so 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; if CADDY_ADMIN_URL points anywhere else, neither this server nor caddy_revert can reach Caddy afterwards. A root write is snapshotted first, so caddy_revert can restore it while Caddy is still reachable; no other path is snapshotted. 'insert' at the root only succeeds after a root caddy_config_delete (Caddy answers 409 on any other instance, including one started with no config), and 'overwrite' is the reverse: after a root caddy_config_delete it answers 404 until 'append', 'insert' or caddy_load re-creates the config. To replace the whole config deliberately, caddy_load does the same thing behind the same gate and also accepts a Caddyfile.",
     {
       path: z3.string().describe("Config path to write to (e.g., 'apps/http/servers/srv0/routes')"),
       value: z3.any().describe("The JSON value to set at the path"),
       mode: z3.enum(["append", "overwrite", "insert"]).optional().default("overwrite").describe(
         "'overwrite' = PATCH (replace existing, default, idempotent; 404 if the key does not exist), 'append' = POST (appends to arrays, NOT idempotent; REPLACES an existing non-array key; cannot create missing parents), 'insert' = PUT (inserts at an array index, or strictly creates an object key and any missing parents; 409 if the key exists)"
+      ),
+      confirm: z3.boolean().optional().default(false).describe(
+        "Must be true when `path` addresses the config root ('', '/', 'config', '/config/', slash-only variants, or a lone '...' segment): that write replaces the ENTIRE config (safety). Ignored for every other path."
       )
     },
-    { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    async ({ path, value, mode }) => {
-      const res = mode === "overwrite" ? await configPatch(path, value) : mode === "insert" ? await configPut(path, value) : await configPost(path, value);
-      return formatResult(res);
+    // destructiveHint is TRUE because the hint covers the whole tool and a host
+    // gates on it before it can see the path or the mode: the default mode is a
+    // PATCH that replaces whatever subtree the path names -- a route list, a
+    // server, all of `apps` -- and at the root it replaces the entire config
+    // (below). MCP defines destructiveHint:false as "only additive updates".
+    // Appending to an array or strictly creating a key is additive; the
+    // default mode is not, and neither is 'append' on a non-array key, which
+    // replaces it. idempotentHint stays false for 'append', which is a POST: a
+    // repeated call appends a second copy.
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    async ({ path, value, mode, confirm }) => {
+      if (!isRootConfigPath(path)) return formatResult(await writeAt(mode, path, value));
+      if (!confirm) {
+        return rootWriteRefusal(
+          `The path "${path}" addresses the config root.`,
+          "pass its path instead (e.g. 'apps/http/servers/srv0')"
+        );
+      }
+      return rootConfigWrite(mode, value, "caddy_config_set");
     }
   );
   server.tool(
     "caddy_config_delete",
-    "Delete config at a JSON path. Removes the config node at the specified path. Deleting a parent node also deletes every descendant -- e.g. deleting 'apps/http/servers/srv0' removes that server and all of its routes. Requires confirm=true. Any path that addresses the config ROOT ('', '/', 'config', '/config/', and slash-only variants of those) addresses the ENTIRE config and unloads it: every app and server goes, and so does 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 this server nor caddy_revert can reach Caddy afterwards. A root delete is snapshotted first, 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.",
+    "Delete config at a JSON path. Removes the config node at the specified path. Deleting a parent node also deletes every descendant -- e.g. deleting 'apps/http/servers/srv0' removes that server and all of its routes. Requires confirm=true. Any path that addresses the config ROOT ('', '/', 'config', '/config/', slash-only variants of those, or any of those followed by a lone '...' segment) addresses the ENTIRE config and unloads it: every app and server goes, and so does 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 this server nor caddy_revert can reach Caddy afterwards. A root delete is snapshotted first, 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.",
     {
       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)")
@@ -1114,49 +1263,27 @@ function registerConfigTools(server) {
     // 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: apart from a root delete (below), only caddy_load captures a
-    // snapshot, so a spurious repeat cannot be undone with caddy_revert.
+    // either: apart from a root delete (below), only whole-config changes
+    // capture a snapshot -- caddy_load, a caddy_revert apply, and a root
+    // caddy_config_set -- so a spurious repeat cannot be undone with
+    // caddy_revert.
     { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
     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 = kept ? ` The prior config was saved as snapshot [0] (trigger=caddy_config_delete): caddy_revert { action: "apply", index: 0, confirm: true } restores it.` : current.ok ? " Warning: the prior config was empty or not a JSON object, so no snapshot was captured -- there was nothing to restore." : " Warning: the prior config could not be read, so no snapshot was captured and this unload cannot be reverted.";
-      const adm = kept ? current.data.admin : void 0;
-      const listen = adm !== null && typeof adm === "object" && !Array.isArray(adm) ? adm.listen : void 0;
-      const adminNote = typeof listen === "string" && listen !== "" ? ` 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.` : "";
-      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(
@@ -1197,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 that unloads the whole config (an empty path); no other delete 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)"),
@@ -1289,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"),
@@ -1298,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
@@ -1311,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.4",
+  "version": "2.5.6",
   "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",