@yawlabs/caddy-mcp 2.5.3 → 2.5.5

package/README.md

@@ -1,24 +1,24 @@
 # @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)
 
-**Manage Caddy web servers from Claude Code, Cursor, and any MCP client.** 18 tools + 4 resources covering every endpoint of Caddy's admin API — config, routes, reverse proxies, TLS, PKI, metrics, snapshots.
+**Manage Caddy web servers from Claude Code, Cursor, and any MCP client.** 18 tools + 4 resources covering every endpoint in Caddy's admin API reference — config, routes, reverse proxies, TLS, PKI, metrics, snapshots.
 
 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 documented endpoint: `/load`, `/config/*`, `/id/*`, `/stop`, `/adapt`, `/pki/ca/*`, `/reverse_proxy/upstreams`, `/metrics`. No placeholder tools that 404.
+- **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.
@@ -78,10 +78,10 @@ That's it. Now ask your AI assistant:
 
 | Environment variable | Default | Description |
 |---|---|---|
-| `CADDY_ADMIN_URL` | `http://localhost:2019` | Caddy admin API URL. Set to `http://caddy:2019` inside Docker, or an https URL for remote admin. Also accepts a unix socket, in either `unix:///var/run/caddy-admin.sock` or Caddy's own `unix//var/run/caddy-admin.sock` spelling — see below. |
-| `CADDY_API_TOKEN` | (none) | Optional Bearer token for authenticated admin endpoints. Only needed if you've configured Caddy with auth. |
+| `CADDY_ADMIN_URL` | `http://localhost:2019` | Caddy admin API URL. Set to `http://caddy:2019` inside Docker, or an https URL for an admin endpoint behind a TLS-terminating reverse proxy — see Troubleshooting for the `Host` / `Origin` rules Caddy applies to anything that is not its own loopback address. Caddy's native remote admin listener (`admin.remote`, default `:2021`) is **not** supported: it requires a TLS client certificate, which caddy-mcp does not present. Also accepts a unix socket, in either `unix:///var/run/caddy-admin.sock` or Caddy's own `unix//var/run/caddy-admin.sock` spelling — see below. |
+| `CADDY_API_TOKEN` | (none) | Optional Bearer token, sent as `Authorization: Bearer <token>` on every request. Caddy's admin API has no token auth of its own and ignores this header — it matters only to an authenticating proxy in front of the admin endpoint, so leave it unset when caddy-mcp reaches Caddy directly. If the header does arrive at the admin listener, Caddy 2.0 through 2.11.2 writes it in clear into the `admin.api` "received request" log line, at INFO — on every path except `/metrics`, which has logged at DEBUG since 2.2.1. Run Caddy 2.11.3 or later, which logs it as `REDACTED`, or have the proxy strip the header once it has authenticated (Caddy: `header_up -Authorization`; nginx: `proxy_set_header Authorization "";`). |
 | `CADDY_MCP_SNAPSHOT_DIR` | (none) | Directory for persisting `caddy_revert` snapshots. Unset, snapshots live in memory only and are lost when this server restarts. Snapshots are full Caddy configs and can contain secrets, so the location is opt-in rather than defaulted. |
-| `CADDY_MAX_RETRIES` | `2` | Number of retries on transient failures: network errors, and 502/503/504 (which only a proxy in front of Caddy sends). Caddy's own 500s are deterministic rejections and never retry, nor do 4xx and 412. Requests a replay could change the outcome of also skip retry: POSTs to `/config/*` and `/id/*` (they append, or replace an existing key -- retrying could duplicate routes), and a PUT or DELETE at an array index such as `.../routes/0` (a replay would insert a second route, or remove the one that slid into that index), including a PUT to a bare `/id/<id>`, which Caddy resolves to the identified element's array index. A config change whose timeout fired is never retried (see `CADDY_LOAD_TIMEOUT`). A refused connection retries for every method, since nothing was sent. POSTs to `/load`, `/adapt`, `/stop` still retry. Hard-capped at 5; values above the cap log a one-time stderr notice so the clamp is visible. Set to `0` to disable. |
+| `CADDY_MAX_RETRIES` | `2` | Number of retries on transient failures: network errors, and 502/503/504 (which only a proxy in front of Caddy sends). Caddy's own 500s are deterministic rejections and never retry, nor do 4xx and 412. Requests a replay could change the outcome of also skip retry: POSTs to `/config/*` and `/id/*` (they append, or replace an existing key -- retrying could duplicate routes), and a PUT or DELETE at an array index such as `.../routes/0` (a replay would insert a second route, or remove the one that slid into that index), including a PUT to a bare `/id/<id>`, which Caddy resolves to the identified element's array index. Those match however the path is spelled — with trailing slashes, or with the trailing `/...` segment Caddy strips before it picks a method, so `.../routes/0/...` and `PUT /id/<id>/...` are covered too. A config change whose timeout fired is never retried (see `CADDY_LOAD_TIMEOUT`). A refused connection retries for every method, since nothing was sent. POSTs to `/load`, `/adapt`, `/stop` still retry. Hard-capped at 5; values above the cap log a one-time stderr notice so the clamp is visible. Set to `0` to disable. |
 | `CADDY_TIMEOUT` | `10000` | Timeout in ms for admin API requests that do not change the config: GETs, `/adapt`, `/stop`, PKI, upstreams and metrics. Config changes use `CADDY_LOAD_TIMEOUT`. Non-numeric, `<= 0`, or fractional values below 1ms fall back to the default. |
 | `CADDY_LOAD_TIMEOUT` | `55000` | Timeout in ms for every request that changes the config: `POST /load`, and every POST/PUT/PATCH/DELETE under `/config/*` and `/id/*`. Each is a full synchronous reload inside Caddy, which can legitimately run long -- Caddy sleeps through `apps.http.shutdown_delay` inside the reload whenever a change closes a listener, and a change can wait behind another reload. A timeout here is never retried: Caddy keeps applying a change after the client gives up, so the error says the outcome is unknown and to re-read the config before retrying (`caddy_load` and `caddy_revert` keep their snapshot in that case). Keep it below your MCP client's request timeout (60 s by default in the MCP SDK), or that error arrives after the client has given up and is never shown; the default sits 5 s under it. Non-numeric, `<= 0`, or fractional values below 1ms fall back to the default. |
 
@@ -98,8 +98,11 @@ onto a unix socket, where access is governed by filesystem permissions:
 
 Point `CADDY_ADMIN_URL` at the same path (`unix:///var/run/caddy-admin.sock`)
 and requests are sent over the socket instead of TCP. The process running
-caddy-mcp needs read/write permission on the socket file. `CADDY_API_TOKEN`
-still applies if you have auth in front of the endpoint.
+caddy-mcp needs read/write permission on the socket file. Leave
+`CADDY_API_TOKEN` unset here unless an authenticating proxy actually listens on
+that socket: over a unix path caddy-mcp is usually talking to Caddy's own
+socket, where the token does nothing — and, before Caddy 2.11.3, is logged in
+clear.
 
 **Alternate MCP clients:**
 
@@ -118,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).
-- **caddy_config_delete** — Delete config at a path. Requires `confirm=true` (deleting a parent path also removes every descendant).
+- **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_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)).
-- **caddy_revert** — Manage config snapshots for rollback. Actions: `list`, `save`, `apply` (confirm-gated). In-memory, last 10. 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_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.
 
 ### Route operations (4)
 
@@ -133,14 +136,14 @@ Use the same JSON block shown above in any of these.
 
 ### TLS & config conversion (2)
 
-- **caddy_tls** — Check or set TLS settings. Actions: `status`, `set_email` (ACME email), `set_acme_ca` (ACME CA URL), `set_acme_profile` (ACME profile, Caddy 2.10+), and the read-only `ech_status` (the Encrypted ClientHello config at `apps/tls/encrypted_client_hello`, Caddy 2.10+). The set actions PATCH first; when `apps/tls` is not set they PUT a minimal config, which also creates any missing parents, so they work on an instance with no config at all. On an existing config they deep-merge into the issuer path and PATCH the result back, preserving siblings (custom certs, `on_demand`, additional policies). Refuses with a shape-specific error if the existing structure is unexpected — never clobbers.
-- **caddy_adapt** — Convert a config in any registered adapter format to Caddy JSON without applying it. `caddyfile` (built-in, default) plus any adapter module compiled into your Caddy binary — e.g., `nginx` ([caddy-nginx-adapter](https://github.com/caddyserver/nginx-adapter)), `yaml` ([caddy-yaml](https://github.com/abiosoft/caddy-yaml)). Great for previewing or porting from existing configs.
+- **caddy_tls** — Check or set TLS settings. Actions: `status`, `set_email` (ACME email), `set_acme_ca` (ACME CA URL), `set_acme_profile` (ACME profile, Caddy 2.10+ — experimental upstream: the ACME profiles spec is still a draft and Caddy marks the field subject to change. Caddy accepts any profile name on load, so a name the CA does not advertise fails only at issuance, in Caddy's own logs), and the read-only `ech_status` (the Encrypted ClientHello config at `apps/tls/encrypted_client_hello`, Caddy 2.10+). The set actions PATCH first; when `apps/tls` is not set they PUT a minimal config, which also creates any missing parents, so they work on an instance with no config at all. On an existing config they deep-merge into the issuer path and PATCH the result back, preserving siblings (custom certs, `on_demand`, additional policies). Refuses with a shape-specific error if the existing structure is unexpected — never clobbers.
+- **caddy_adapt** — Convert a config in any registered adapter format to Caddy JSON without applying it. `caddyfile` (built-in, default) plus any adapter module compiled into your Caddy binary — e.g., `nginx` ([caddy-nginx-adapter](https://github.com/caddyserver/nginx-adapter)), `yaml` ([caddy-yaml](https://github.com/abiosoft/caddy-yaml)). Great for previewing or porting from existing configs. One caveat on Caddy 2.11.4 and earlier: a Caddyfile `order` global option is not preview-only. It mutates that Caddy process's directive order, so it carries into later Caddyfile adapts and loads in the same process, and an `order` line that *fails* still removes the directive it names ([caddyserver/caddy#7995](https://github.com/caddyserver/caddy/pull/7995), fixed upstream but unreleased as of 2.11.4).
 
 ### Server operations (6)
 
-- **caddy_status** — Connectivity check + config summary (server count, routes, TLS mode).
-- **caddy_list_servers** — List all HTTP servers with names, addresses, route counts, and TLS status.
-- **caddy_upstreams** — Reverse proxy backend health.
+- **caddy_status** — Connectivity check + config summary (server count, routes, TLS mode). The TLS label replays Caddy's own automatic-HTTPS rule over the stored config instead of guessing from the listen port, so it reads `enabled`, `enabled (no listener gets TLS: all are on the HTTP port)`, `auto (HTTPS)`, `auto (HTTPS: host matchers on a non-HTTP port)`, `mixed (TLS on non-HTTP listeners only)`, `off (HTTP only)`, `off (no host matchers)`, `off (automatic HTTPS disabled)` or `off (empty tls_connection_policies)`. The two qualified `enabled` readings come from Caddy deciding TLS per socket rather than per server (`app.go:535`): connection policies are ignored on the HTTP-port listener, so a server that binds only that port is configured for TLS and serves none of it.
+- **caddy_list_servers** — List all HTTP servers with names, addresses, route counts, and TLS status. Same labels as `caddy_status`, but this tool reads only `apps/http/servers` and so assumes the default `http_port` 80 / `https_port` 443 — on an instance with custom ports, `caddy_status` is the one that gets the label right.
+- **caddy_upstreams** — Reverse proxy backend health, as Caddy's `/reverse_proxy/upstreams` array returned verbatim. On Caddy 2.11.2+ this is **not** the configured upstream list: dynamic upstreams stay listed about 1 h after the dynamic source last returned them (so an address can outlive the config that referenced it), and a backend with requests in flight can appear twice when its resolved address differs from the entry's dial text. The extra copy always shows `fails 0` and repeats `num_requests` — do not sum `num_requests` across entries.
 - **caddy_metrics** — Prometheus metrics (request counts, durations, connections, TLS handshakes). Optional `filter` (substring match on metric name, keeps `# HELP` / `# TYPE` lines for retained metrics) and `max_lines` (default 500) keep responses compact on busy servers.
 - **caddy_pki** — CA info and certificate chains (default CA: `local`).
 - **caddy_stop** — Graceful shutdown. Requires `confirm=true` to prevent accidents.
@@ -151,7 +154,7 @@ Browsable read-only data — MCP clients can fetch these directly without a tool
 
 - `caddy://config` — Current full Caddy JSON configuration.
 - `caddy://servers` — Summary of all configured HTTP servers.
-- `caddy://upstreams` — Reverse proxy upstream health status.
+- `caddy://upstreams` — Reverse proxy upstream health status, verbatim. Same 2.11.2+ caveat as `caddy_upstreams`: lingering dynamic upstreams and duplicate in-flight entries; do not sum `num_requests`.
 - `caddy://metrics` — Prometheus metrics (text exposition format). Capped at the first 500 lines to keep client context bounded; use the `caddy_metrics` tool with `filter` / `max_lines` for filtered or larger output.
 
 ## Examples
@@ -223,16 +226,27 @@ Browsable read-only data — MCP clients can fetch these directly without a tool
 - Make sure Caddy is running. `caddy run` or `systemctl status caddy`.
 - Check the admin endpoint. Default is `http://localhost:2019`. If Caddy is in Docker, use the container hostname.
 - Set `CADDY_ADMIN_URL` in your MCP config `env` to match.
+- Over an SSH tunnel, map the **same** port on both ends (`ssh -L 2019:localhost:2019 <host>`) and leave `CADDY_ADMIN_URL` at its default. Caddy checks the `Host` header against its own listen address, so a tunnel on a different local port answers `403 host not allowed: localhost:<port>`.
+- Behind a reverse proxy, add the proxy's `host:port` to the remote Caddy's `admin.origins`. Caddy checks both `Host` and `Origin`, and setting `admin.origins` **replaces** the default `localhost` / `127.0.0.1` / `::1` entries, so list `localhost:2019` too if local tools still need access. A non-loopback or wildcard `admin.listen` — the Docker `http://caddy:2019` above, for instance — does not allow an arbitrary `Host` either, so it needs `admin.origins` set as well.
+- Pointing `CADDY_ADMIN_URL` at Caddy's native remote admin listener (`admin.remote`, default `:2021`) fails before any HTTP is exchanged, because that listener requires a TLS client certificate and caddy-mcp does not present one. It surfaces as this message even though Caddy is running and accepted the connection.
 
 **"HTTP 412 Precondition Failed"**
 
 - Someone (or something) changed the config between your read and your write.
 - The cached ETag has been invalidated. Re-read the config and retry.
 
-**"HTTP 403" on /load or /config writes**
+**"HTTP 401" or "HTTP 403" on any request**
+
+- Caddy's own checks run on every admin request, reads included, and always answer with a JSON `{"error":...}` body. If you got one, it is Caddy: the `admin.listen` / `admin.origins` allowlists (`host not allowed: ...`, `client is not allowed to access from origin ...`, `required Origin header is missing or invalid` — see the tunnel and proxy bullets above), or, on `admin.remote`, its mTLS identity and permission checks.
+- A **bodiless** 401/403 came from something in front of Caddy — a proxy, a gateway, an SSO layer. `CADDY_API_TOKEN` applies there and only there, so a missing or wrong token is one cause and the proxy's other access rules are another.
+- Caddy's admin API has no bearer-token auth of its own, so setting `CADDY_API_TOKEN` will not clear a 401/403 that carries a Caddy error body.
+
+**"directive 'X' is not an ordered HTTP handler"** from `caddy_adapt`, or from `caddy_load` with `format: "caddyfile"`
 
-- You have `admin.listen` or `admin.origins` restrictions set in your Caddy config, or you're missing an `Authorization` header.
-- Set `CADDY_API_TOKEN` in your MCP config env if Caddy expects a Bearer token.
+- Two causes, and Caddy's error cannot tell them apart:
+  - The directive has no registered order — usually a plugin directive. Add an `order` global option, or wrap it in a `route` block.
+  - On Caddy 2.11.4 and earlier, an earlier failed or concurrent Caddyfile adaptation that used `order` in this same Caddy process removed that directive from the process-wide directive order. Restarting Caddy restores the default order ([caddyserver/caddy#7995](https://github.com/caddyserver/caddy/pull/7995), unreleased).
+- The second cause is why a Caddyfile that adapted a minute ago can start failing with no edit to it. Caddy's own advice ("try … using the order global option") fixes the first cause and papers over the second.
 
 **`SIGUSR1` / `systemctl reload caddy` stops reloading the Caddyfile**
 
@@ -244,6 +258,12 @@ Browsable read-only data — MCP clients can fetch these directly without a tool
   caddy-mcp read-only tools (`caddy_status`, `caddy_list_routes`, `caddy_adapt`)
   and reload from the file. If caddy-mcp owns the config, apply changes with
   `caddy_load` instead of `SIGUSR1`.
+- One qualification on Caddy 2.11.4 and earlier: `caddy_adapt` is read-only with
+  respect to the config, but not with respect to the adapter. A Caddyfile `order`
+  global option changes that process's directive order, and a failed `order` line
+  can break later in-process adaptations — which is what a `SIGUSR1` reload and
+  `caddy run --watch` do. `caddy reload`, which is what the packaged
+  `systemctl reload caddy` runs, adapts in the CLI process and is unaffected.
 
 **Windows: MCP server doesn't start**
 
@@ -252,9 +272,21 @@ Browsable read-only data — MCP clients can fetch these directly without a tool
 ## Requirements
 
 - Node.js 20+
-- Caddy 2.x with admin API enabled (default: `localhost:2019`). Verified against
-  Caddy 2.11.4; the `@id` write path relies on `PATCH` semantics that the live
-  integration suite pins per release.
+- Caddy 2.11.3 or later, with the admin API enabled (default: `localhost:2019`).
+  The latest 2.11.x is recommended; verified against Caddy 2.11.4. Two admin-side
+  reasons for that floor:
+  - Caddy 2.11.2 and earlier log every admin request's headers at INFO, so if the
+    `Authorization` header from `CADDY_API_TOKEN` reaches the admin listener, the
+    token is written to Caddy's log in plain text
+    ([caddyserver/caddy#7578](https://github.com/caddyserver/caddy/pull/7578)).
+  - Caddy 2.11.1 and earlier accept a duplicate `@id` silently. A racing
+    `caddy_reverse_proxy` create, or a `caddy_config_by_id` set with
+    `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.
 
 ## Contributing
 
@@ -265,7 +297,7 @@ npm install
 npm run lint       # Biome check
 npm run lint:fix   # Auto-fix
 npm run build      # tsup bundle
-npm test           # Vitest (636 unit tests, +39 POSIX-only unix-socket and launcher tests; +32 live-Caddy integration tests gated by CADDY_MCP_INTEGRATION=1)
+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 run typecheck  # tsc --noEmit
 ```
 
@@ -275,4 +307,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.
  *

package/dist/index.js

@@ -24,6 +24,54 @@ function setEtag(path, etag) {
   }
   etagCache.set(path, etag);
 }
+var GO_WHITESPACE = /* @__PURE__ */ new Set([
+  9,
+  10,
+  11,
+  12,
+  13,
+  32,
+  133,
+  160,
+  5760,
+  8192,
+  8193,
+  8194,
+  8195,
+  8196,
+  8197,
+  8198,
+  8199,
+  8200,
+  8201,
+  8202,
+  8232,
+  8233,
+  8239,
+  8287,
+  12288
+]);
+function goFields(text) {
+  const fields = [];
+  let current = "";
+  for (const ch of text) {
+    if (GO_WHITESPACE.has(ch.codePointAt(0))) {
+      if (current) fields.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  if (current) fields.push(current);
+  return fields;
+}
+function isEchoableEtag(etag) {
+  const decoded = Buffer.from(etag, "latin1").toString("utf8");
+  if (decoded.length < 2 || !decoded.startsWith('"') || !decoded.endsWith('"')) return false;
+  const inner = decoded.slice(1, -1);
+  const fields = goFields(inner);
+  return fields.length === 2 && fields.join(" ") === inner;
+}
 function isAncestorOf(ancestor, descendant) {
   const base = ancestor.endsWith("/") ? ancestor.slice(0, -1) : ancestor;
   return descendant.startsWith(`${base}/`);
@@ -90,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;
@@ -115,8 +166,8 @@ function isMissingConfigPath(res) {
   if (res.ok) return false;
   return (res.error ?? "").toLowerCase().includes("invalid traversal path");
 }
-var ARRAY_INDEX_TAIL_RE = /\/\d+\/*$/;
-var BARE_ID_RE = /^\/id\/[^/]+\/*$/;
+var ARRAY_INDEX_TAIL_RE = /\/\d+(\/+\.\.\.)?\/*$/;
+var BARE_ID_RE = /^\/id\/[^/]+(\/+\.\.\.)?\/*$/;
 function isConfigChange(method, path) {
   if (method === "GET") return false;
   return path === "/load" || path.startsWith("/config/") || path.startsWith("/id/");
@@ -350,7 +401,8 @@ async function sendOnce(transport, method, path, body, contentType, rawStringBod
     const text = res.text;
     const etag = res.etag;
     if (method === "GET" && etag && isConfigPath) {
-      setEtag(path, etag);
+      if (isEchoableEtag(etag)) setEtag(path, etag);
+      else etagCache.delete(path);
     }
     if (isWrite && res.ok && isConfigPath) {
       invalidateRelated(path);
@@ -573,15 +625,96 @@ function formatResult(res) {
 }
 
 // src/tools/operational.ts
-var HTTPS_PORT_RE = /:443(?:\D|$)/;
-function describeServer(rawValue) {
+var DEFAULT_HTTP_PORT = 80;
+var DEFAULT_HTTPS_PORT = 443;
+function appPort(value, fallback) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 && value <= 65535 ? value : fallback;
+}
+function splitPort(hostport) {
+  const i = hostport.lastIndexOf(":");
+  if (i < 0) return void 0;
+  if (hostport.startsWith("[")) {
+    const end = hostport.indexOf("]");
+    if (end < 0 || end + 1 !== i) return void 0;
+    if (hostport.slice(1).includes("[") || hostport.slice(end + 1).includes("]")) return void 0;
+  } else {
+    if (hostport.slice(0, i).includes(":")) return void 0;
+    if (hostport.includes("[") || hostport.includes("]")) return void 0;
+  }
+  return hostport.slice(i + 1);
+}
+function parseListenPortRange(entry) {
+  let rest = entry;
+  const slash = entry.indexOf("/");
+  if (slash >= 0) {
+    const network = entry.slice(0, slash).trim().toLowerCase();
+    rest = entry.slice(slash + 1);
+    if (network.startsWith("unix") || network.startsWith("fd")) return { start: 0, end: 0 };
+  }
+  const port = splitPort(rest);
+  if (port === void 0 || port === "") return { start: 0, end: 0 };
+  const dash = port.indexOf("-");
+  const start = parseUint16(dash < 0 ? port : port.slice(0, dash));
+  const end = parseUint16(dash < 0 ? port : port.slice(dash + 1));
+  if (start === void 0 || end === void 0 || end < start) return void 0;
+  return { start, end };
+}
+function parseUint16(s) {
+  if (!/^[0-9]+$/.test(s)) return void 0;
+  const n = Number(s);
+  return n <= 65535 ? n : void 0;
+}
+function hasQualifyingHost(routes, skip) {
+  for (const route of routes) {
+    if (!route || typeof route !== "object") continue;
+    const matcherSets = route.match;
+    if (!Array.isArray(matcherSets)) continue;
+    for (const set of matcherSets) {
+      if (!set || typeof set !== "object") continue;
+      const hosts = set.host;
+      if (!Array.isArray(hosts)) continue;
+      for (const host of hosts) {
+        if (typeof host === "string" && !skip.has(host)) return true;
+      }
+    }
+  }
+  return false;
+}
+function describeServer(rawValue, httpPort = DEFAULT_HTTP_PORT, httpsPort = DEFAULT_HTTPS_PORT) {
   const raw = rawValue !== null && typeof rawValue === "object" && !Array.isArray(rawValue) ? rawValue : {};
   const listen = Array.isArray(raw.listen) ? raw.listen : [];
   const routes = Array.isArray(raw.routes) ? raw.routes : [];
+  const ranges = [];
+  for (const entry of listen) {
+    if (typeof entry !== "string") continue;
+    const range = parseListenPortRange(entry);
+    if (range) ranges.push(range);
+  }
+  const usesAnyPortOtherThan = (port) => ranges.some((r) => port > r.end || port < r.start);
+  const bindsPort = (port) => ranges.some((r) => r.start <= port && port <= r.end);
+  const autoHttps = raw.automatic_https !== null && typeof raw.automatic_https === "object" && !Array.isArray(raw.automatic_https) ? raw.automatic_https : {};
+  const skip = new Set(
+    Array.isArray(autoHttps.skip) ? autoHttps.skip.filter((s) => typeof s === "string") : []
+  );
+  const allSocketsOnHttpPort = (port) => ranges.length > 0 && ranges.every((r) => r.start === port && r.end === port);
+  const perListener = (label) => allSocketsOnHttpPort(httpPort) ? "enabled (no listener gets TLS: all are on the HTTP port)" : bindsPort(httpPort) ? "mixed (TLS on non-HTTP listeners only)" : label;
   const tlsPolicies = raw.tls_connection_policies;
-  const hasExplicitTls = Array.isArray(tlsPolicies) ? tlsPolicies.length > 0 : !!tlsPolicies;
-  const listensHttps = listen.some((l) => typeof l === "string" && HTTPS_PORT_RE.test(l));
-  const tls = hasExplicitTls ? "enabled" : listensHttps ? "auto (HTTPS)" : "off (HTTP only)";
+  let tls;
+  if (Array.isArray(tlsPolicies) && tlsPolicies.length === 0) {
+    tls = "off (empty tls_connection_policies)";
+  } else if (tlsPolicies) {
+    tls = perListener("enabled");
+  } else if (autoHttps.disable === true) {
+    tls = "off (automatic HTTPS disabled)";
+  } else if (!usesAnyPortOtherThan(httpPort)) {
+    tls = "off (HTTP only)";
+  } else if (!usesAnyPortOtherThan(httpsPort)) {
+    tls = perListener("auto (HTTPS)");
+  } else if (hasQualifyingHost(routes, skip)) {
+    tls = perListener("auto (HTTPS: host matchers on a non-HTTP port)");
+  } else {
+    tls = "off (no host matchers)";
+  }
   const listenStr = listen.length > 0 ? listen.map(String).join(", ") : "default";
   return `${routes.length} route(s), listen: ${listenStr}, TLS: ${tls}`;
 }
@@ -640,14 +773,17 @@ function registerOperationalTools(server) {
       const res = await configGet();
       if (!res.ok) return formatResult(res);
       const config = res.data ?? {};
-      const servers = config.apps?.http?.servers ?? {};
+      const httpApp = config.apps?.http;
+      const servers = httpApp?.servers ?? {};
       const serverNames = Object.keys(servers);
+      const httpPort = appPort(httpApp?.http_port, DEFAULT_HTTP_PORT);
+      const httpsPort = appPort(httpApp?.https_port, DEFAULT_HTTPS_PORT);
       const lines = ["Caddy is running", ""];
       if (serverNames.length === 0) {
         lines.push("No HTTP servers configured");
       } else {
         for (const name of serverNames) {
-          lines.push(`Server "${name}": ${describeServer(servers[name])}`);
+          lines.push(`Server "${name}": ${describeServer(servers[name], httpPort, httpsPort)}`);
         }
       }
       const email = findAcmeEmail(config.apps?.tls?.automation?.policies);
@@ -681,7 +817,7 @@ ${lines.join("\n")}` }]
   );
   server.tool(
     "caddy_upstreams",
-    "Get the current health status of all reverse proxy upstreams. Shows address, active requests, and failure counts.",
+    "Caddy's /reverse_proxy/upstreams array (address, num_requests, fails), returned verbatim. On Caddy 2.11.2+ it is not the configured upstream list. Dynamic-upstream backends stay listed about 1 h (up to ~65 min) after the dynamic source last returned them, even after a config change removes them, so an address may appear that no current config references. A backend with requests in flight can appear twice when its resolved address differs from the entry's text (dynamic upstreams, tcp/ or unix// dials, placeholder dials). That extra copy always shows fails 0 and repeats num_requests, so do not sum num_requests across entries.",
     {},
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async () => formatResult(await getUpstreams())
@@ -755,7 +891,9 @@ function registerResources(server) {
   server.resource(
     "caddy-upstreams",
     "caddy://upstreams",
-    { description: "Reverse proxy upstream health status" },
+    {
+      description: "Reverse proxy upstream health: Caddy's /reverse_proxy/upstreams array, returned verbatim. On Caddy 2.11.2+ it is not the configured upstream list -- dynamic upstreams stay listed about 1 h after the dynamic source last returned them (so an address can outlive the config that referenced it), and a backend with requests in flight can appear twice when its resolved address differs from the entry's text. The extra copy always shows fails 0 and repeats num_requests, so do not sum num_requests. See the caddy_upstreams tool for the full caveat."
+    },
     async () => {
       const res = await getUpstreams();
       return {
@@ -831,7 +969,7 @@ function formatWarning2(w) {
 function registerAdaptTools(server) {
   server.tool(
     "caddy_adapt",
-    "Convert a config in any registered adapter format to Caddy JSON without loading it. Useful for previewing what a Caddyfile produces, or for porting from nginx/yaml configs when Caddy is built with the matching adapter module ('caddyfile' is built-in; 'nginx', 'yaml', etc. require their adapter modules to be compiled into the Caddy binary). Returns the adapted JSON and any warnings separately.",
+    `Convert a config in any registered adapter format to Caddy JSON without loading it. Useful for previewing what a Caddyfile produces, or for porting from nginx/yaml configs when Caddy is built with the matching adapter module ('caddyfile' is built-in; 'nginx', 'yaml', etc. require their adapter modules to be compiled into the Caddy binary). Returns the adapted JSON and any warnings separately. One exception to 'without loading it': on Caddy <= 2.11.4 a Caddyfile 'order' global option is not preview-only. It mutates that Caddy process's directive order, so it carries into every later Caddyfile adapt or load there, and an 'order' line that FAILS (unknown target, bad positional, extra arg) still removes the directive it names -- later Caddyfiles using that directive then fail with "directive 'X' is not an ordered HTTP handler" until another 'order' line re-places it or Caddy restarts. Fixed upstream in caddyserver/caddy#7995, unreleased as of v2.11.4.`,
     {
       config: z2.string().describe("The raw config text (e.g., Caddyfile contents, nginx.conf, yaml)"),
       adapter: z2.string().regex(/^[a-z0-9_-]+$/, "Adapter must be lowercase alphanumeric, hyphens, or underscores").max(64).optional().default("caddyfile").describe(
@@ -941,6 +1079,43 @@ function getSnapshot(index) {
 }
 
 // src/tools/config.ts
+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 registerConfigTools(server) {
   server.tool(
     "caddy_config_get",
@@ -951,23 +1126,73 @@ 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 }) => {
+      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 (!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);
+      }
+      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}`
+          }
+        ]
+      };
     }
   );
   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.",
+    "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)")
@@ -978,22 +1203,50 @@ 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: 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) {
         return {
           isError: true,
           content: [
             {
               type: "text",
-              text: `Refusing to delete "${path}" without confirm=true. Deleting a parent path also removes all descendants. Re-run with confirm:true to proceed.`
+              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.`
             }
           ]
         };
       }
-      return formatResult(await configDelete(path));
+      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}`
+          }
+        ]
+      };
     }
   );
   server.tool(
@@ -1034,7 +1287,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 (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); 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)"),
@@ -1821,7 +2074,7 @@ function registerTlsTools(server) {
       email: z5.string().optional().describe("ACME email address (for 'set_email' action)"),
       ca: z5.string().optional().describe("ACME CA URL (for 'set_acme_ca' action)"),
       profile: z5.string().optional().describe(
-        "ACME profile name (for 'set_acme_profile'). Requires Caddy 2.10+ and a CA that offers profiles; Let's Encrypt uses 'shortlived' for 6-day certificates. Valid names are defined by the CA, not by Caddy."
+        "ACME profile name (for 'set_acme_profile'). Requires Caddy 2.10+ and a CA that offers profiles; Let's Encrypt uses 'shortlived' for 6-day certificates. Valid names are defined by the CA, not by Caddy. EXPERIMENTAL upstream (the ACME profiles spec is still a draft; Caddy marks the field 'subject to change' and may rename or drop it). Caddy accepts any name on load, so a success here does not mean the CA offers it: if this issuer's CA does not advertise the name, every order from this issuer fails at issuance time, reported only in Caddy's own logs. Caddy then either falls through to the next issuer in the policy, which issues WITHOUT the profile, or -- when this is the policy's only issuer, which is the shape this tool creates -- keeps retrying and issues no certificate at all."
       )
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },

package/dist/server.js

@@ -22,6 +22,54 @@ function setEtag(path, etag) {
   }
   etagCache.set(path, etag);
 }
+var GO_WHITESPACE = /* @__PURE__ */ new Set([
+  9,
+  10,
+  11,
+  12,
+  13,
+  32,
+  133,
+  160,
+  5760,
+  8192,
+  8193,
+  8194,
+  8195,
+  8196,
+  8197,
+  8198,
+  8199,
+  8200,
+  8201,
+  8202,
+  8232,
+  8233,
+  8239,
+  8287,
+  12288
+]);
+function goFields(text) {
+  const fields = [];
+  let current = "";
+  for (const ch of text) {
+    if (GO_WHITESPACE.has(ch.codePointAt(0))) {
+      if (current) fields.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  if (current) fields.push(current);
+  return fields;
+}
+function isEchoableEtag(etag) {
+  const decoded = Buffer.from(etag, "latin1").toString("utf8");
+  if (decoded.length < 2 || !decoded.startsWith('"') || !decoded.endsWith('"')) return false;
+  const inner = decoded.slice(1, -1);
+  const fields = goFields(inner);
+  return fields.length === 2 && fields.join(" ") === inner;
+}
 function isAncestorOf(ancestor, descendant) {
   const base = ancestor.endsWith("/") ? ancestor.slice(0, -1) : ancestor;
   return descendant.startsWith(`${base}/`);
@@ -88,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;
@@ -113,8 +164,8 @@ function isMissingConfigPath(res) {
   if (res.ok) return false;
   return (res.error ?? "").toLowerCase().includes("invalid traversal path");
 }
-var ARRAY_INDEX_TAIL_RE = /\/\d+\/*$/;
-var BARE_ID_RE = /^\/id\/[^/]+\/*$/;
+var ARRAY_INDEX_TAIL_RE = /\/\d+(\/+\.\.\.)?\/*$/;
+var BARE_ID_RE = /^\/id\/[^/]+(\/+\.\.\.)?\/*$/;
 function isConfigChange(method, path) {
   if (method === "GET") return false;
   return path === "/load" || path.startsWith("/config/") || path.startsWith("/id/");
@@ -348,7 +399,8 @@ async function sendOnce(transport, method, path, body, contentType, rawStringBod
     const text = res.text;
     const etag = res.etag;
     if (method === "GET" && etag && isConfigPath) {
-      setEtag(path, etag);
+      if (isEchoableEtag(etag)) setEtag(path, etag);
+      else etagCache.delete(path);
     }
     if (isWrite && res.ok && isConfigPath) {
       invalidateRelated(path);
@@ -571,15 +623,96 @@ function formatResult(res) {
 }
 
 // src/tools/operational.ts
-var HTTPS_PORT_RE = /:443(?:\D|$)/;
-function describeServer(rawValue) {
+var DEFAULT_HTTP_PORT = 80;
+var DEFAULT_HTTPS_PORT = 443;
+function appPort(value, fallback) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 && value <= 65535 ? value : fallback;
+}
+function splitPort(hostport) {
+  const i = hostport.lastIndexOf(":");
+  if (i < 0) return void 0;
+  if (hostport.startsWith("[")) {
+    const end = hostport.indexOf("]");
+    if (end < 0 || end + 1 !== i) return void 0;
+    if (hostport.slice(1).includes("[") || hostport.slice(end + 1).includes("]")) return void 0;
+  } else {
+    if (hostport.slice(0, i).includes(":")) return void 0;
+    if (hostport.includes("[") || hostport.includes("]")) return void 0;
+  }
+  return hostport.slice(i + 1);
+}
+function parseListenPortRange(entry) {
+  let rest = entry;
+  const slash = entry.indexOf("/");
+  if (slash >= 0) {
+    const network = entry.slice(0, slash).trim().toLowerCase();
+    rest = entry.slice(slash + 1);
+    if (network.startsWith("unix") || network.startsWith("fd")) return { start: 0, end: 0 };
+  }
+  const port = splitPort(rest);
+  if (port === void 0 || port === "") return { start: 0, end: 0 };
+  const dash = port.indexOf("-");
+  const start = parseUint16(dash < 0 ? port : port.slice(0, dash));
+  const end = parseUint16(dash < 0 ? port : port.slice(dash + 1));
+  if (start === void 0 || end === void 0 || end < start) return void 0;
+  return { start, end };
+}
+function parseUint16(s) {
+  if (!/^[0-9]+$/.test(s)) return void 0;
+  const n = Number(s);
+  return n <= 65535 ? n : void 0;
+}
+function hasQualifyingHost(routes, skip) {
+  for (const route of routes) {
+    if (!route || typeof route !== "object") continue;
+    const matcherSets = route.match;
+    if (!Array.isArray(matcherSets)) continue;
+    for (const set of matcherSets) {
+      if (!set || typeof set !== "object") continue;
+      const hosts = set.host;
+      if (!Array.isArray(hosts)) continue;
+      for (const host of hosts) {
+        if (typeof host === "string" && !skip.has(host)) return true;
+      }
+    }
+  }
+  return false;
+}
+function describeServer(rawValue, httpPort = DEFAULT_HTTP_PORT, httpsPort = DEFAULT_HTTPS_PORT) {
   const raw = rawValue !== null && typeof rawValue === "object" && !Array.isArray(rawValue) ? rawValue : {};
   const listen = Array.isArray(raw.listen) ? raw.listen : [];
   const routes = Array.isArray(raw.routes) ? raw.routes : [];
+  const ranges = [];
+  for (const entry of listen) {
+    if (typeof entry !== "string") continue;
+    const range = parseListenPortRange(entry);
+    if (range) ranges.push(range);
+  }
+  const usesAnyPortOtherThan = (port) => ranges.some((r) => port > r.end || port < r.start);
+  const bindsPort = (port) => ranges.some((r) => r.start <= port && port <= r.end);
+  const autoHttps = raw.automatic_https !== null && typeof raw.automatic_https === "object" && !Array.isArray(raw.automatic_https) ? raw.automatic_https : {};
+  const skip = new Set(
+    Array.isArray(autoHttps.skip) ? autoHttps.skip.filter((s) => typeof s === "string") : []
+  );
+  const allSocketsOnHttpPort = (port) => ranges.length > 0 && ranges.every((r) => r.start === port && r.end === port);
+  const perListener = (label) => allSocketsOnHttpPort(httpPort) ? "enabled (no listener gets TLS: all are on the HTTP port)" : bindsPort(httpPort) ? "mixed (TLS on non-HTTP listeners only)" : label;
   const tlsPolicies = raw.tls_connection_policies;
-  const hasExplicitTls = Array.isArray(tlsPolicies) ? tlsPolicies.length > 0 : !!tlsPolicies;
-  const listensHttps = listen.some((l) => typeof l === "string" && HTTPS_PORT_RE.test(l));
-  const tls = hasExplicitTls ? "enabled" : listensHttps ? "auto (HTTPS)" : "off (HTTP only)";
+  let tls;
+  if (Array.isArray(tlsPolicies) && tlsPolicies.length === 0) {
+    tls = "off (empty tls_connection_policies)";
+  } else if (tlsPolicies) {
+    tls = perListener("enabled");
+  } else if (autoHttps.disable === true) {
+    tls = "off (automatic HTTPS disabled)";
+  } else if (!usesAnyPortOtherThan(httpPort)) {
+    tls = "off (HTTP only)";
+  } else if (!usesAnyPortOtherThan(httpsPort)) {
+    tls = perListener("auto (HTTPS)");
+  } else if (hasQualifyingHost(routes, skip)) {
+    tls = perListener("auto (HTTPS: host matchers on a non-HTTP port)");
+  } else {
+    tls = "off (no host matchers)";
+  }
   const listenStr = listen.length > 0 ? listen.map(String).join(", ") : "default";
   return `${routes.length} route(s), listen: ${listenStr}, TLS: ${tls}`;
 }
@@ -638,14 +771,17 @@ function registerOperationalTools(server) {
       const res = await configGet();
       if (!res.ok) return formatResult(res);
       const config = res.data ?? {};
-      const servers = config.apps?.http?.servers ?? {};
+      const httpApp = config.apps?.http;
+      const servers = httpApp?.servers ?? {};
       const serverNames = Object.keys(servers);
+      const httpPort = appPort(httpApp?.http_port, DEFAULT_HTTP_PORT);
+      const httpsPort = appPort(httpApp?.https_port, DEFAULT_HTTPS_PORT);
       const lines = ["Caddy is running", ""];
       if (serverNames.length === 0) {
         lines.push("No HTTP servers configured");
       } else {
         for (const name of serverNames) {
-          lines.push(`Server "${name}": ${describeServer(servers[name])}`);
+          lines.push(`Server "${name}": ${describeServer(servers[name], httpPort, httpsPort)}`);
         }
       }
       const email = findAcmeEmail(config.apps?.tls?.automation?.policies);
@@ -679,7 +815,7 @@ ${lines.join("\n")}` }]
   );
   server.tool(
     "caddy_upstreams",
-    "Get the current health status of all reverse proxy upstreams. Shows address, active requests, and failure counts.",
+    "Caddy's /reverse_proxy/upstreams array (address, num_requests, fails), returned verbatim. On Caddy 2.11.2+ it is not the configured upstream list. Dynamic-upstream backends stay listed about 1 h (up to ~65 min) after the dynamic source last returned them, even after a config change removes them, so an address may appear that no current config references. A backend with requests in flight can appear twice when its resolved address differs from the entry's text (dynamic upstreams, tcp/ or unix// dials, placeholder dials). That extra copy always shows fails 0 and repeats num_requests, so do not sum num_requests across entries.",
     {},
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async () => formatResult(await getUpstreams())
@@ -753,7 +889,9 @@ function registerResources(server) {
   server.resource(
     "caddy-upstreams",
     "caddy://upstreams",
-    { description: "Reverse proxy upstream health status" },
+    {
+      description: "Reverse proxy upstream health: Caddy's /reverse_proxy/upstreams array, returned verbatim. On Caddy 2.11.2+ it is not the configured upstream list -- dynamic upstreams stay listed about 1 h after the dynamic source last returned them (so an address can outlive the config that referenced it), and a backend with requests in flight can appear twice when its resolved address differs from the entry's text. The extra copy always shows fails 0 and repeats num_requests, so do not sum num_requests. See the caddy_upstreams tool for the full caveat."
+    },
     async () => {
       const res = await getUpstreams();
       return {
@@ -829,7 +967,7 @@ function formatWarning2(w) {
 function registerAdaptTools(server) {
   server.tool(
     "caddy_adapt",
-    "Convert a config in any registered adapter format to Caddy JSON without loading it. Useful for previewing what a Caddyfile produces, or for porting from nginx/yaml configs when Caddy is built with the matching adapter module ('caddyfile' is built-in; 'nginx', 'yaml', etc. require their adapter modules to be compiled into the Caddy binary). Returns the adapted JSON and any warnings separately.",
+    `Convert a config in any registered adapter format to Caddy JSON without loading it. Useful for previewing what a Caddyfile produces, or for porting from nginx/yaml configs when Caddy is built with the matching adapter module ('caddyfile' is built-in; 'nginx', 'yaml', etc. require their adapter modules to be compiled into the Caddy binary). Returns the adapted JSON and any warnings separately. One exception to 'without loading it': on Caddy <= 2.11.4 a Caddyfile 'order' global option is not preview-only. It mutates that Caddy process's directive order, so it carries into every later Caddyfile adapt or load there, and an 'order' line that FAILS (unknown target, bad positional, extra arg) still removes the directive it names -- later Caddyfiles using that directive then fail with "directive 'X' is not an ordered HTTP handler" until another 'order' line re-places it or Caddy restarts. Fixed upstream in caddyserver/caddy#7995, unreleased as of v2.11.4.`,
     {
       config: z2.string().describe("The raw config text (e.g., Caddyfile contents, nginx.conf, yaml)"),
       adapter: z2.string().regex(/^[a-z0-9_-]+$/, "Adapter must be lowercase alphanumeric, hyphens, or underscores").max(64).optional().default("caddyfile").describe(
@@ -939,6 +1077,43 @@ function getSnapshot(index) {
 }
 
 // src/tools/config.ts
+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 registerConfigTools(server) {
   server.tool(
     "caddy_config_get",
@@ -949,23 +1124,73 @@ 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 }) => {
+      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 (!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);
+      }
+      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}`
+          }
+        ]
+      };
     }
   );
   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.",
+    "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)")
@@ -976,22 +1201,50 @@ 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: 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) {
         return {
           isError: true,
           content: [
             {
               type: "text",
-              text: `Refusing to delete "${path}" without confirm=true. Deleting a parent path also removes all descendants. Re-run with confirm:true to proceed.`
+              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.`
             }
           ]
         };
       }
-      return formatResult(await configDelete(path));
+      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}`
+          }
+        ]
+      };
     }
   );
   server.tool(
@@ -1032,7 +1285,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 (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); 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)"),
@@ -1819,7 +2072,7 @@ function registerTlsTools(server) {
       email: z5.string().optional().describe("ACME email address (for 'set_email' action)"),
       ca: z5.string().optional().describe("ACME CA URL (for 'set_acme_ca' action)"),
       profile: z5.string().optional().describe(
-        "ACME profile name (for 'set_acme_profile'). Requires Caddy 2.10+ and a CA that offers profiles; Let's Encrypt uses 'shortlived' for 6-day certificates. Valid names are defined by the CA, not by Caddy."
+        "ACME profile name (for 'set_acme_profile'). Requires Caddy 2.10+ and a CA that offers profiles; Let's Encrypt uses 'shortlived' for 6-day certificates. Valid names are defined by the CA, not by Caddy. EXPERIMENTAL upstream (the ACME profiles spec is still a draft; Caddy marks the field 'subject to change' and may rename or drop it). Caddy accepts any name on load, so a success here does not mean the CA offers it: if this issuer's CA does not advertise the name, every order from this issuer fails at issuance time, reported only in Caddy's own logs. Caddy then either falls through to the next issuer in the policy, which issues WITHOUT the profile, or -- when this is the policy's only issuer, which is the shape this tool creates -- keeps retrying and issues no certificate at all."
       )
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/caddy-mcp",
-  "version": "2.5.3",
+  "version": "2.5.5",
   "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",