@yawlabs/caddy-mcp 2.3.0 → 2.3.1

package/README.md

@@ -1,276 +1,276 @@
-# @yawlabs/caddy-mcp
-
-[![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.
-
-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.
-- **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.
-- **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 POST fallback also fails, both error bodies are returned so you know what actually went wrong.
-- **Tool annotations** — every tool declares `readOnlyHint`, `destructiveHint`, and `idempotentHint`, so MCP clients can skip confirmations for safe ops.
-- **Instant startup** — ships as a single bundle with two runtime deps (the MCP SDK + Zod). No 5-minute `node_modules` install.
-- **Input hardening** — adapter names, `@id` values, server names, and CA ids are all regex-validated with length caps. Blocks CRLF header injection and ReDoS.
-
-## Quick start
-
-**1. Enable the Caddy admin API**
-
-Caddy ships with the admin API enabled on `localhost:2019` by default. If you're running Caddy in Docker or on a remote host, expose it via `CADDY_ADMIN_URL`.
-
-**2. Create `.mcp.json` in your project root**
-
-macOS / Linux / WSL:
-
-```json
-{
-  "mcpServers": {
-    "caddy": {
-      "command": "npx",
-      "args": ["-y", "@yawlabs/caddy-mcp@latest"]
-    }
-  }
-}
-```
-
-Windows:
-
-```json
-{
-  "mcpServers": {
-    "caddy": {
-      "command": "cmd",
-      "args": ["/c", "npx", "-y", "@yawlabs/caddy-mcp@latest"]
-    }
-  }
-}
-```
-
-> **Why the extra step on Windows?** Since Node 20, `child_process.spawn` cannot directly execute `.cmd` files (that's what `npx` is on Windows). Wrapping with `cmd /c` is the standard workaround. This file is safe to commit — it contains no secrets.
-
-**3. Restart and approve**
-
-Restart Claude Code (or your MCP client) and approve the Caddy MCP server when prompted.
-
-That's it. Now ask your AI assistant:
-
-> "Proxy api.local to localhost:3000"
->
-> "What routes are configured on srv0?"
->
-> "Show me the Prometheus metrics"
-
-## Configuration
-
-| 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_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 (5xx, network errors). 4xx and 412 never retry. POSTs to `/config/*` and `/id/*` also skip retry (non-idempotent appends/creates -- retrying could duplicate routes or 409 a half-applied create). 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 all admin API requests except `/load` (which uses `CADDY_LOAD_TIMEOUT`). Non-numeric, `<= 0`, or fractional values below 1ms fall back to the default. |
-| `CADDY_LOAD_TIMEOUT` | `60000` | Timeout in ms for the `/load` endpoint; raise for ACME-heavy bring-ups where provisioning many certificates can exceed the default. Non-numeric, `<= 0`, or fractional values below 1ms fall back to the default. |
-
-**Unix socket admin endpoints:**
-
-Caddy's recommended hardening is to move the admin API off a loopback port and
-onto a unix socket, where access is governed by filesystem permissions:
-
-```
-{
-  admin unix//var/run/caddy-admin.sock
-}
-```
-
-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.
-
-**Alternate MCP clients:**
-
-| Client | Config file |
-|---|---|
-| Claude Code | `.mcp.json` (project root) or `~/.claude.json` (global) |
-| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
-| Cursor | `~/.cursor/mcp.json` |
-| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
-| VS Code | `.vscode/mcp.json` |
-
-Use the same JSON block shown above in any of these.
-
-## Tools
-
-### 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), `append` (POST), `insert` (PUT, for array positions).
-- **caddy_config_delete** — Delete config at a path. Requires `confirm=true` (deleting a parent path also removes every descendant).
-- **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. 60-second timeout for cert provisioning. Auto-snapshots the prior config.
-- **caddy_revert** — Manage config snapshots for rollback. Actions: `list`, `save`, `apply` (confirm-gated). In-memory, last 10.
-
-### Route operations (4)
-
-- **caddy_reverse_proxy** — Add a reverse proxy in one call: `from='api.local' to=['localhost:3000']`. Pass an optional `id` for idempotent writes — repeat calls replace the route in place instead of duplicating.
-- **caddy_add_route** — Add a route with full match/handle control (any Caddy handler).
-- **caddy_remove_route** — Remove a route by `@id` (preferred) or by index. Requires `confirm=true`.
-- **caddy_list_routes** — Human-readable route summary. Defensive: never crashes on weird config.
-
-### TLS & config conversion (2)
-
-- **caddy_tls** — Check or set TLS settings: ACME email, ACME CA URL. PATCH first; on a fresh install, POSTs a minimal config. On an existing config it deep-merges into the issuer path and PUTs 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.
-
-### 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_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.
-
-## Resources
-
-Browsable read-only data — MCP clients can fetch these directly without a tool call:
-
-- `caddy://config` — Current full Caddy JSON configuration.
-- `caddy://servers` — Summary of all configured HTTP servers.
-- `caddy://upstreams` — Reverse proxy upstream health status.
-- `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
-
-### Add a reverse proxy
-
-```
-> "Proxy api.example.com to my app on port 3000"
-→ caddy_reverse_proxy({ from: "api.example.com", to: ["localhost:3000"] })
-```
-
-### Idempotent reverse proxy (safe to re-run from automation)
-
-```
-> "Make sure api.example.com points at localhost:3000, with a stable id"
-→ caddy_reverse_proxy({ from: "api.example.com", to: ["localhost:3000"], id: "api-prod" })
-  # First call creates the route under @id="api-prod".
-  # Subsequent calls with the same id REPLACE in place — no duplicate routes.
-  # Refuses with a clear error if "api-prod" is already in use by a non-route
-  # config object (TLS issuer, server, etc.) — @ids are config-global in Caddy.
-```
-
-### Filter Prometheus metrics
-
-```
-> "Just the HTTP request metrics, please"
-→ caddy_metrics({ filter: "http_requests" })
-  # Keeps sample lines whose metric name contains "http_requests",
-  # plus their `# HELP` / `# TYPE` lines. Drops the rest.
-```
-
-### Preview a Caddyfile before applying it
-
-```
-> "Convert this Caddyfile to JSON so I can review it:
-   example.com {
-     reverse_proxy localhost:8080
-   }"
-→ caddy_adapt({ config: "..." })
-```
-
-### Diagnose slow routes
-
-```
-> "Fetch Prometheus metrics and tell me which route is slowest"
-→ caddy_metrics()
-```
-
-### Safely update a route by @id
-
-```
-> "Update the route with @id 'api-v2' to point to the new backend"
-→ caddy_config_by_id({ id: "api-v2", action: "set", value: {...} })
-  # Uses ETags — you'll get HTTP 412 if someone else changed it first
-```
-
-### Atomic deploy
-
-```
-> "Replace the whole config with this Caddyfile"
-→ caddy_adapt({ config: "..." })  # validate first
-→ caddy_load({ config: adaptedJson })  # apply atomically
-```
-
-## Troubleshooting
-
-**"Cannot connect to Caddy admin API"**
-
-- 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.
-
-**"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**
-
-- 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.
-
-**`SIGUSR1` / `systemctl reload caddy` stops reloading the Caddyfile**
-
-- Expected, and not caused by a bug here. Since Caddy 2.11.1, `SIGUSR1` reloads
-  from the file on disk **only if the config has never been changed through the
-  admin API**. The first write from caddy-mcp (or any other API client) makes
-  Caddy consider the running config API-owned, and `SIGUSR1` becomes a no-op.
-- Pick one owner per instance. If the Caddyfile is the source of truth, use
-  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`.
-
-**Windows: MCP server doesn't start**
-
-- Use the `cmd /c npx ...` pattern from the Quick start section. Node 20+ can't spawn `.cmd` files directly.
-
-## 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.
-
-## Contributing
-
-```bash
-git clone https://github.com/YawLabs/caddy-mcp.git
-cd caddy-mcp
-npm install
-npm run lint       # Biome check
-npm run lint:fix   # Auto-fix
-npm run build      # tsup bundle
-npm test           # Vitest (357 unit tests, +9 POSIX-only unix-socket tests; +13 live-Caddy integration tests gated by CADDY_MCP_INTEGRATION=1)
-npm run typecheck  # tsc --noEmit
-```
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow, including release process.
-
-## License
-
-MIT
+# @yawlabs/caddy-mcp
+
+[![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.
+
+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.
+- **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.
+- **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 POST fallback also fails, both error bodies are returned so you know what actually went wrong.
+- **Tool annotations** — every tool declares `readOnlyHint`, `destructiveHint`, and `idempotentHint`, so MCP clients can skip confirmations for safe ops.
+- **Instant startup** — ships as a single bundle with two runtime deps (the MCP SDK + Zod). No 5-minute `node_modules` install.
+- **Input hardening** — adapter names, `@id` values, server names, and CA ids are all regex-validated with length caps. Blocks CRLF header injection and ReDoS.
+
+## Quick start
+
+**1. Enable the Caddy admin API**
+
+Caddy ships with the admin API enabled on `localhost:2019` by default. If you're running Caddy in Docker or on a remote host, expose it via `CADDY_ADMIN_URL`.
+
+**2. Create `.mcp.json` in your project root**
+
+macOS / Linux / WSL:
+
+```json
+{
+  "mcpServers": {
+    "caddy": {
+      "command": "npx",
+      "args": ["-y", "@yawlabs/caddy-mcp@latest"]
+    }
+  }
+}
+```
+
+Windows:
+
+```json
+{
+  "mcpServers": {
+    "caddy": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@yawlabs/caddy-mcp@latest"]
+    }
+  }
+}
+```
+
+> **Why the extra step on Windows?** Since Node 20, `child_process.spawn` cannot directly execute `.cmd` files (that's what `npx` is on Windows). Wrapping with `cmd /c` is the standard workaround. This file is safe to commit — it contains no secrets.
+
+**3. Restart and approve**
+
+Restart Claude Code (or your MCP client) and approve the Caddy MCP server when prompted.
+
+That's it. Now ask your AI assistant:
+
+> "Proxy api.local to localhost:3000"
+>
+> "What routes are configured on srv0?"
+>
+> "Show me the Prometheus metrics"
+
+## Configuration
+
+| 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_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 (5xx, network errors). 4xx and 412 never retry. POSTs to `/config/*` and `/id/*` also skip retry (non-idempotent appends/creates -- retrying could duplicate routes or 409 a half-applied create). 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 all admin API requests except `/load` (which uses `CADDY_LOAD_TIMEOUT`). Non-numeric, `<= 0`, or fractional values below 1ms fall back to the default. |
+| `CADDY_LOAD_TIMEOUT` | `60000` | Timeout in ms for the `/load` endpoint; raise for ACME-heavy bring-ups where provisioning many certificates can exceed the default. Non-numeric, `<= 0`, or fractional values below 1ms fall back to the default. |
+
+**Unix socket admin endpoints:**
+
+Caddy's recommended hardening is to move the admin API off a loopback port and
+onto a unix socket, where access is governed by filesystem permissions:
+
+```
+{
+  admin unix//var/run/caddy-admin.sock
+}
+```
+
+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.
+
+**Alternate MCP clients:**
+
+| Client | Config file |
+|---|---|
+| Claude Code | `.mcp.json` (project root) or `~/.claude.json` (global) |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
+| Cursor | `~/.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| VS Code | `.vscode/mcp.json` |
+
+Use the same JSON block shown above in any of these.
+
+## Tools
+
+### 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), `append` (POST), `insert` (PUT, for array positions).
+- **caddy_config_delete** — Delete config at a path. Requires `confirm=true` (deleting a parent path also removes every descendant).
+- **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. 60-second timeout for cert provisioning. Auto-snapshots the prior config.
+- **caddy_revert** — Manage config snapshots for rollback. Actions: `list`, `save`, `apply` (confirm-gated). In-memory, last 10.
+
+### Route operations (4)
+
+- **caddy_reverse_proxy** — Add a reverse proxy in one call: `from='api.local' to=['localhost:3000']`. Pass an optional `id` for idempotent writes — repeat calls replace the route in place instead of duplicating.
+- **caddy_add_route** — Add a route with full match/handle control (any Caddy handler).
+- **caddy_remove_route** — Remove a route by `@id` (preferred) or by index. Requires `confirm=true`.
+- **caddy_list_routes** — Human-readable route summary. Defensive: never crashes on weird config.
+
+### TLS & config conversion (2)
+
+- **caddy_tls** — Check or set TLS settings: ACME email, ACME CA URL. PATCH first; on a fresh install, POSTs a minimal config. On an existing config it deep-merges into the issuer path and PUTs 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.
+
+### 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_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.
+
+## Resources
+
+Browsable read-only data — MCP clients can fetch these directly without a tool call:
+
+- `caddy://config` — Current full Caddy JSON configuration.
+- `caddy://servers` — Summary of all configured HTTP servers.
+- `caddy://upstreams` — Reverse proxy upstream health status.
+- `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
+
+### Add a reverse proxy
+
+```
+> "Proxy api.example.com to my app on port 3000"
+→ caddy_reverse_proxy({ from: "api.example.com", to: ["localhost:3000"] })
+```
+
+### Idempotent reverse proxy (safe to re-run from automation)
+
+```
+> "Make sure api.example.com points at localhost:3000, with a stable id"
+→ caddy_reverse_proxy({ from: "api.example.com", to: ["localhost:3000"], id: "api-prod" })
+  # First call creates the route under @id="api-prod".
+  # Subsequent calls with the same id REPLACE in place — no duplicate routes.
+  # Refuses with a clear error if "api-prod" is already in use by a non-route
+  # config object (TLS issuer, server, etc.) — @ids are config-global in Caddy.
+```
+
+### Filter Prometheus metrics
+
+```
+> "Just the HTTP request metrics, please"
+→ caddy_metrics({ filter: "http_requests" })
+  # Keeps sample lines whose metric name contains "http_requests",
+  # plus their `# HELP` / `# TYPE` lines. Drops the rest.
+```
+
+### Preview a Caddyfile before applying it
+
+```
+> "Convert this Caddyfile to JSON so I can review it:
+   example.com {
+     reverse_proxy localhost:8080
+   }"
+→ caddy_adapt({ config: "..." })
+```
+
+### Diagnose slow routes
+
+```
+> "Fetch Prometheus metrics and tell me which route is slowest"
+→ caddy_metrics()
+```
+
+### Safely update a route by @id
+
+```
+> "Update the route with @id 'api-v2' to point to the new backend"
+→ caddy_config_by_id({ id: "api-v2", action: "set", value: {...} })
+  # Uses ETags — you'll get HTTP 412 if someone else changed it first
+```
+
+### Atomic deploy
+
+```
+> "Replace the whole config with this Caddyfile"
+→ caddy_adapt({ config: "..." })  # validate first
+→ caddy_load({ config: adaptedJson })  # apply atomically
+```
+
+## Troubleshooting
+
+**"Cannot connect to Caddy admin API"**
+
+- 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.
+
+**"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**
+
+- 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.
+
+**`SIGUSR1` / `systemctl reload caddy` stops reloading the Caddyfile**
+
+- Expected, and not caused by a bug here. Since Caddy 2.11.1, `SIGUSR1` reloads
+  from the file on disk **only if the config has never been changed through the
+  admin API**. The first write from caddy-mcp (or any other API client) makes
+  Caddy consider the running config API-owned, and `SIGUSR1` becomes a no-op.
+- Pick one owner per instance. If the Caddyfile is the source of truth, use
+  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`.
+
+**Windows: MCP server doesn't start**
+
+- Use the `cmd /c npx ...` pattern from the Quick start section. Node 20+ can't spawn `.cmd` files directly.
+
+## 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.
+
+## Contributing
+
+```bash
+git clone https://github.com/YawLabs/caddy-mcp.git
+cd caddy-mcp
+npm install
+npm run lint       # Biome check
+npm run lint:fix   # Auto-fix
+npm run build      # tsup bundle
+npm test           # Vitest (357 unit tests, +9 POSIX-only unix-socket tests; +13 live-Caddy integration tests gated by CADDY_MCP_INTEGRATION=1)
+npm run typecheck  # tsc --noEmit
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow, including release process.
+
+## License
+
+MIT

package/bin/caddy-mcp.mjs

@@ -1,33 +1,33 @@
-#!/usr/bin/env node
-/**
- * Runtime launcher for @yawlabs/caddy-mcp.
- *
- * Prefers the oam runtime (https://oamjs.org) and falls back to the Node
- * process already running this file.
- *
- * Unlike npmjs-mcp, this server is NOT a zero-dependency bundle -- dist/
- * imports @modelcontextprotocol/sdk and zod from node_modules at runtime. That
- * is fine on both paths: oam does npm resolution against an existing
- * node_modules with CommonJS interop, and it was verified here before this
- * launcher was written (`oam run dist/index.js -- --version` prints the same
- * version Node does).
- *
- * WHY THE FALLBACK COSTS NOTHING
- * npm has already started Node to run this launcher, so falling back is a
- * plain `import()` of the server into THIS process: no extra spawn, no extra
- * startup, byte-identical to invoking dist/index.js directly. Discovery is
- * stat-only -- never a subprocess -- so the miss case stays sub-millisecond.
- *
- * WHAT THE OAM PATH COSTS
- * Reaching oam through an npm `bin` means Node boots first and oam boots
- * second, so the launcher is slower than either runtime alone. Measured on
- * npmjs-mcp (windows-arm64, n=12 medians, spawn to first MCP initialize):
- * oam 116ms, node 172ms, launcher 243ms. oam is the fastest runtime and the
- * launcher is the slowest path -- it exists for `npx` convenience.
- *
- * For an MCP host config, point straight at oam and skip this file:
- *   { "command": "oam", "args": ["run", "<abs>/dist/index.js"] }
- *
+#!/usr/bin/env node
+/**
+ * Runtime launcher for @yawlabs/caddy-mcp.
+ *
+ * Prefers the oam runtime (https://oamjs.org) and falls back to the Node
+ * process already running this file.
+ *
+ * Unlike npmjs-mcp, this server is NOT a zero-dependency bundle -- dist/
+ * imports @modelcontextprotocol/sdk and zod from node_modules at runtime. That
+ * is fine on both paths: oam does npm resolution against an existing
+ * node_modules with CommonJS interop, and it was verified here before this
+ * launcher was written (`oam run dist/index.js -- --version` prints the same
+ * version Node does).
+ *
+ * WHY THE FALLBACK COSTS NOTHING
+ * npm has already started Node to run this launcher, so falling back is a
+ * plain `import()` of the server into THIS process: no extra spawn, no extra
+ * startup, byte-identical to invoking dist/index.js directly. Discovery is
+ * stat-only -- never a subprocess -- so the miss case stays sub-millisecond.
+ *
+ * WHAT THE OAM PATH COSTS
+ * Reaching oam through an npm `bin` means Node boots first and oam boots
+ * second, so the launcher is slower than either runtime alone. Measured on
+ * npmjs-mcp (windows-arm64, n=12 medians, spawn to first MCP initialize):
+ * oam 116ms, node 172ms, launcher 243ms. oam is the fastest runtime and the
+ * launcher is the slowest path -- it exists for `npx` convenience.
+ *
+ * For an MCP host config, point straight at oam and skip this file:
+ *   { "command": "oam", "args": ["run", "<abs>/dist/index.js"] }
+ *
  * THE `--permission` SANDBOX (oam 0.9.0+, opt-in)
  * `CADDY_MCP_SANDBOX=1` runs the server under oam's permission model.
  *
@@ -52,71 +52,74 @@
  * An older oam is not an error: the launcher falls back to Node and says so on
  * stderr. Pinning the floor here is what makes that fallback automatic.
  *
- * SELECTION
- *   CADDY_MCP_RUNTIME=oam    require oam; fail loudly if it is missing
- *   CADDY_MCP_RUNTIME=node   never use oam
- *   CADDY_MCP_RUNTIME=auto   prefer oam, silently fall back (default)
+ * SELECTION
+ *   CADDY_MCP_RUNTIME=oam    require oam; fail loudly if it is missing
+ *   CADDY_MCP_RUNTIME=node   never use oam
+ *   CADDY_MCP_RUNTIME=auto   prefer oam, silently fall back (default)
  *   CADDY_MCP_SANDBOX=1      run oam under --permission (oam 0.9.0+)
- *   OAM_BIN=/path/to/oam     explicit binary, checked before any discovery
- */
-
-import { execFileSync, spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { constants, homedir } from "node:os";
-import { delimiter, join } from "node:path";
+ *   OAM_BIN=/path/to/oam     explicit binary, checked before any discovery
+ */
+
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { constants, homedir } from "node:os";
+import { delimiter, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 /** Oldest oam whose `child_process` matches Node. See MINIMUM OAM VERSION above. */
-const OAM_MIN = [0, 9, 0];
-
-// Two forms, deliberately. `import()` on Windows REJECTS a bare `C:\...` path
-// with ERR_UNSUPPORTED_ESM_URL_SCHEME (it reads `c:` as a protocol), so the
-// in-process fallback must use the file:// URL. spawn() needs a real path.
-const SERVER_URL = new URL("../dist/index.js", import.meta.url);
-const SERVER_ENTRY = fileURLToPath(SERVER_URL);
-const isWin = process.platform === "win32";
-const exe = isWin ? "oam.exe" : "oam";
-
-/** Locate an oam binary, or null. Every branch is a stat, never a subprocess. */
-function findOam() {
-  // 1. Explicit override wins and is never second-guessed.
-  const override = process.env.OAM_BIN;
-  if (override) return existsSync(override) ? override : null;
-
-  // 2. Installed locations, BEFORE PATH. Someone who develops oam itself
-  //    usually has oam/target/release on PATH, and a build directory is the
-  //    wrong thing for a user-facing launcher to bind to: cargo replaces the
-  //    binary underneath running processes, and the dev build is not the
-  //    release the user installed. Preferring the installed copy makes the
-  //    default path "what a normal user has", and OAM_BIN remains the way to
-  //    point deliberately at a dev build.
-  //
-  //    Both forms are checked on Windows: the installer defaults to
-  //    %LOCALAPPDATA%oamin there, but oam's docs name ~/.oam/bin first and
-  //    OAM_INSTALL_DIR can pick either, so checking one silently misses a real
-  //    install.
-  const installed = [join(homedir(), ".oam", "bin", exe)];
-  if (isWin) {
-    installed.unshift(join(process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "oam", "bin", exe));
-  }
-  for (const candidate of installed) {
-    if (existsSync(candidate)) return candidate;
-  }
-
-  // 3. PATH, resolved manually rather than by spawning `which`/`where`, which
-  //    would cost a subprocess on every launch just to decide whether to spawn.
-  const pathExt = isWin ? (process.env.PATHEXT ?? ".EXE").split(";").filter(Boolean) : [""];
-  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
-    if (!dir) continue;
-    for (const ext of isWin ? pathExt : [""]) {
-      const candidate = join(dir, isWin ? `oam${ext.toLowerCase()}` : "oam");
-      if (existsSync(candidate)) return candidate;
-    }
-  }
-
-  return null;
-}
-
+const OAM_MIN = [0, 9, 0];
+
+// Two forms, deliberately. `import()` on Windows REJECTS a bare `C:\...` path
+// with ERR_UNSUPPORTED_ESM_URL_SCHEME (it reads `c:` as a protocol), so the
+// in-process fallback must use the file:// URL. spawn() needs a real path.
+const SERVER_URL = new URL("../dist/index.js", import.meta.url);
+const SERVER_ENTRY = fileURLToPath(SERVER_URL);
+const isWin = process.platform === "win32";
+const exe = isWin ? "oam.exe" : "oam";
+
+/** Locate an oam binary, or null. Every branch is a stat, never a subprocess. */
+function findOam() {
+  // 1. Explicit override wins and is never second-guessed.
+  const override = process.env.OAM_BIN;
+  if (override) return existsSync(override) ? override : null;
+
+  // 2. Installed locations, BEFORE PATH. Someone who develops oam itself
+  //    usually has oam/target/release on PATH, and a build directory is the
+  //    wrong thing for a user-facing launcher to bind to: cargo replaces the
+  //    binary underneath running processes, and the dev build is not the
+  //    release the user installed. Preferring the installed copy makes the
+  //    default path "what a normal user has", and OAM_BIN remains the way to
+  //    point deliberately at a dev build.
+  //
+  //    Both forms are checked on Windows: the installer defaults to
+  //    %LOCALAPPDATA%\oam\bin there, but oam's docs name ~/.oam/bin first and
+  //    OAM_INSTALL_DIR can pick either, so checking one silently misses a real
+  //    install.
+  const installed = [join(homedir(), ".oam", "bin", exe)];
+  if (isWin) {
+    installed.unshift(join(process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "oam", "bin", exe));
+  }
+  for (const candidate of installed) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  // 3. PATH, resolved manually rather than by spawning `which`/`where`, which
+  //    would cost a subprocess on every launch just to decide whether to spawn.
+  // Windows: `.exe` ONLY -- deliberately narrower than PATHEXT. Node refuses to
+  // run a .cmd/.bat through execFile/spawn without `shell: true` (EINVAL, and
+  // for spawn it throws SYNCHRONOUSLY rather than emitting 'error'), so walking
+  // the full PATHEXT list would hand back a path this launcher cannot execute.
+  // Discovery has to agree with execution. A skipped shim is still reported --
+  // see findOamShim.
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join(dir, exe);
+    if (existsSync(candidate)) return candidate;
+  }
+
+  return null;
+}
+
 /**
  * `oam --version` -> [major, minor, patch], or null when it cannot be read.
  * A pre-release suffix (0.9.0-rc.1) truncates to its base version.
@@ -183,87 +186,243 @@ function sandboxFlags() {
   return flags;
 }
 
-/** Run the server in THIS process. The zero-overhead fallback. */
-async function runInProcess() {
-  // A server may gate its bootstrap on being the process ENTRY POINT --
-  // `import.meta.url === pathToFileURL(process.argv[1]).href` -- so that its own
-  // test file can import the module for unit tests without connecting a stdio
-  // transport. aws-mcp does exactly this. Importing the server here would leave
-  // argv[1] pointing at THIS launcher, the guard would read false, and the
-  // server would load but never serve: the MCP handshake just hangs.
-  //
-  // Point argv[1] at the server first, so the in-process path is
-  // indistinguishable from having executed the file directly. The spawn path
-  // needs no equivalent -- there argv[1] is already the server.
-  process.argv[1] = SERVER_ENTRY;
-  await import(SERVER_URL.href);
-}
-
-const mode = (process.env.CADDY_MCP_RUNTIME ?? "auto").toLowerCase();
-
-if (mode === "node") {
-  await runInProcess();
-} else {
-  const oam = findOam();
-
-  if (!oam) {
-    if (mode === "oam") {
-      // Explicitly demanded, so this is a real misconfiguration. writeSync
-      // because stderr is async for TTYs/pipes on Windows and process.exit
-      // truncates pending writes.
-      const { writeSync } = await import("node:fs");
-      writeSync(
-        2,
-        "caddy-mcp: CADDY_MCP_RUNTIME=oam but no oam binary was found.\n" +
-          "Install from https://oamjs.org, set OAM_BIN=/path/to/oam, or use CADDY_MCP_RUNTIME=node.\n",
-      );
-      process.exit(1);
-    }
-    await runInProcess();
-  } else {
-    // `--` separates oam's own flags from the script's argv, so `caddy-mcp
-    // --version` and any host-supplied flags survive the hop unchanged.
-    const child = spawn(oam, [...sandboxFlags(), "run", SERVER_ENTRY, "--", ...process.argv.slice(2)], {
-      // inherit keeps the SAME fds, so MCP's newline-delimited JSON framing on
-      // stdin/stdout is untouched and the host's stdin-close still reaches the
-      // server's shutdown path.
-      stdio: "inherit",
-      env: process.env,
-      windowsHide: true,
-    });
-
-    // If oam cannot be executed at all (deleted between the stat and the spawn,
-    // wrong arch, permission), fall back rather than failing the whole server.
-    // `spawned` prevents falling back AFTER the child started, which would
-    // double-start the server on the same stdio.
-    let spawned = false;
-    child.on("spawn", () => {
-      spawned = true;
-    });
-    child.on("error", (err) => {
-      if (spawned) return;
-      if (mode === "oam") {
-        process.stderr.write(`caddy-mcp: failed to launch oam (${err.message})\n`);
-        process.exit(1);
-      }
-      void runInProcess();
-    });
-
-    // Forward termination so the server's own shutdown path runs in the child
-    // rather than the child being orphaned. No-op on Windows, harmless to add.
-    for (const sig of ["SIGINT", "SIGTERM"]) {
-      process.on(sig, () => {
-        if (!child.killed) child.kill(sig);
-      });
-    }
-
-    child.on("exit", (code, signal) => {
-      // Mirror the child's fate: a signal death becomes 128+n so callers see a
-      // conventional shell exit status rather than a bare 0.
-      if (signal) {
-        process.exit(128 + (constants.signals[signal] ?? 15));
-      }
-      process.exit(code ?? 0);
-    });
-  }
-}
+/**
+ * Write a diagnostic to stderr synchronously, so a following process.exit
+ * cannot truncate it.
+ *
+ * Not a bare writeSync: that call can short-write (it returns a byte count) and
+ * on macOS it can throw EAGAIN, because Node makes a piped stderr non-blocking
+ * there rather than blocking the write. Loop over the remaining bytes, and if
+ * stderr turns out to be unusable give up quietly -- failing to print a
+ * diagnostic is not worth crashing a stdio server over.
+ */
+async function errSync(message) {
+  const { writeSync } = await import("node:fs");
+  const buf = Buffer.from(message);
+  let off = 0;
+  for (let attempts = 0; off < buf.length && attempts < 1000; attempts++) {
+    try {
+      off += writeSync(2, buf, off, buf.length - off);
+    } catch (err) {
+      if (err?.code !== "EAGAIN") return;
+      // Pipe is full and the reader has not drained yet -- retry.
+    }
+  }
+}
+
+/**
+ * An oam-named .cmd/.bat on PATH: a real install in a shape this launcher
+ * cannot spawn. Reported rather than ignored, because "no oam binary was found"
+ * reads as "install oam" -- the one thing that will not help. Windows only;
+ * there is no such shim concept on POSIX.
+ */
+function findOamShim() {
+  if (!isWin) return null;
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    for (const ext of [".cmd", ".bat"]) {
+      const candidate = join(dir, `oam${ext}`);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+/** Run the server in THIS process. The zero-overhead fallback. */
+async function runInProcess() {
+  // A server may gate its bootstrap on being the process ENTRY POINT --
+  // `import.meta.url === pathToFileURL(process.argv[1]).href` -- so that its own
+  // test file can import the module for unit tests without connecting a stdio
+  // transport. aws-mcp does exactly this. Importing the server here would leave
+  // argv[1] pointing at THIS launcher, the guard would read false, and the
+  // server would load but never serve: the MCP handshake just hangs.
+  //
+  // Point argv[1] at the server first, so the in-process path is
+  // indistinguishable from having executed the file directly. The spawn path
+  // needs no equivalent -- there argv[1] is already the server.
+  process.argv[1] = SERVER_ENTRY;
+  await import(SERVER_URL.href);
+}
+
+const mode = (process.env.CADDY_MCP_RUNTIME ?? "auto").toLowerCase();
+
+if (mode === "node") {
+  await runInProcess();
+} else {
+  const oam = findOam();
+  // Read the version ONCE, and only when discovery found something: the gate
+  // below has to tell "too old" apart from "could not be read at all", and
+  // re-probing inside the branch would cost a second subprocess.
+  //
+  // This is the first subprocess the launcher runs -- discovery itself is
+  // stat-only. Paid on every launch that finds an oam, including the ones
+  // that go on to fall back to Node.
+  const found = oam ? oamVersion(oam) : null;
+
+  if (!oam) {
+    // An oam-named .cmd/.bat on PATH is a real install in a shape this
+    // launcher cannot spawn. Naming it turns "no oam binary was found" --
+    // which reads as "install oam", the one thing that will not help --
+    // into something the user can act on.
+    const oamShim = findOamShim();
+    const shimNote = oamShim
+      ? `Found ${oamShim}, but Node cannot execute a .cmd/.bat directly.\n` +
+        "Install the native oam binary, or point OAM_BIN at one.\n"
+      : "";
+    if (mode === "oam") {
+      // Explicitly demanded, so this is a real misconfiguration. writeSync
+      // because stderr is async for TTYs/pipes on Windows and process.exit
+      // truncates pending writes.
+      const { writeSync } = await import("node:fs");
+      writeSync(
+        2,
+        "caddy-mcp: CADDY_MCP_RUNTIME=oam but no runnable oam binary was found.\n" + shimNote +
+          "Install from https://oamjs.org, set OAM_BIN=/path/to/oam, or use CADDY_MCP_RUNTIME=node.\n",
+      );
+      process.exit(1);
+    }
+    // auto: falling back is correct, but silence is how someone never learns
+    // their oam install is a shape this launcher skips.
+    if (oamShim) await errSync(`caddy-mcp: ${shimNote}Using Node instead.\n`);
+    await runInProcess();
+  } else if (!atLeast(found, OAM_MIN)) {
+    const min = OAM_MIN.join(".");
+    // Two different causes reach this branch and they need different
+    // remedies. `found === null` is NOT "old": oamVersion returns null when
+    // the binary could not be run at all (not executable, wrong arch, a
+    // .cmd/.bat Node refuses, deleted between the stat and the probe) or
+    // when its --version output did not parse. Telling that user to
+    // `oam self-update` sends them after the one cause it definitely is not.
+    const detail = found
+      ? `${oam} is oam ${found.join(".")}, older than ${min}`
+      : `${oam} could not be run, or did not report a version this launcher understands`;
+    const remedy = found
+      ? "Run `oam self-update`, or use CADDY_MCP_RUNTIME=node.\n"
+      : "Check that it is an executable oam binary for this platform, or use CADDY_MCP_RUNTIME=node.\n";
+    if (mode === "oam") {
+      await errSync(`caddy-mcp: CADDY_MCP_RUNTIME=oam but ${detail}.\n${remedy}`);
+      process.exit(1);
+    }
+    // auto: neither cause is worth failing over -- prefer Node. Say so,
+    // because a silent downgrade is how someone keeps running an oam they
+    // meant to update, or never learns their oam is unexecutable.
+    await errSync(`caddy-mcp: ${detail}; using Node instead.\n`);
+    await runInProcess();
+  } else {
+    // `--` separates oam's own flags from the script's argv, so `caddy-mcp
+    // --version` and any host-supplied flags survive the hop unchanged.
+    // Every "oam could not be executed" outcome lands here: the synchronous
+    // throw from spawn() and the async 'error' event mean the same thing and
+    // must degrade the same way, so the handling lives in one place.
+    // errSync rather than process.stderr.write because stderr is async for
+    // TTYs and pipes on Windows and the process.exit below truncates pending
+    // writes.
+    const launchFailed = async (err) => {
+      if (mode === "oam") {
+        await errSync(`caddy-mcp: failed to launch oam (${err?.message ?? err})\n`);
+        process.exit(1);
+      }
+      await runInProcess();
+    };
+
+    // ONE reporter shared by both launchFailed call sites, so the sync-throw
+    // path and the 'error'-event path cannot drift apart. Either can reject:
+    // runInProcess() is a bare import() that rejects when dist/index.js is
+    // missing, and at ESM top level an unhandled rejection is an uncaught
+    // exception -- the exact failure this handling exists to prevent.
+    const fallbackFailed = (e) => {
+      process.stderr.write(`caddy-mcp: fallback to Node failed (${e?.message ?? e})\n`);
+      process.exitCode = 1;
+    };
+
+    let child = null;
+    try {
+      child = spawn(oam, [...sandboxFlags(), "run", SERVER_ENTRY, "--", ...process.argv.slice(2)], {
+        // inherit keeps the SAME fds, so MCP's newline-delimited JSON framing on
+        // stdin/stdout is untouched and the host's stdin-close still reaches the
+        // server's shutdown path.
+        stdio: "inherit",
+        env: process.env,
+        windowsHide: true,
+      });
+    } catch (err) {
+      // spawn() THROWS for some failures instead of emitting 'error', and the
+      // 'error' listener is registered AFTER this call, so it can never observe
+      // one -- an uncaught throw here kills the launcher with a raw stack trace
+      // instead of falling back to Node.
+      await launchFailed(err).catch(fallbackFailed);
+    }
+
+    if (child) {
+
+      // If oam cannot be executed at all (deleted between the stat and the spawn,
+      // wrong arch, permission), fall back rather than failing the whole server.
+      // `spawned` prevents falling back AFTER the child started, which would
+      // double-start the server on the same stdio.
+      let spawned = false;
+      child.on("spawn", () => {
+        spawned = true;
+      });
+      child.on("error", (err) => {
+        if (spawned) return;
+        // Handle the rejection instead of discarding it: a failing in-process
+        // fallback would otherwise escape as an unhandled rejection, replacing
+        // this launcher's diagnostic with a raw stack trace.
+        launchFailed(err).catch(fallbackFailed);
+      });
+
+      // Forward termination so the server's own shutdown path runs in the child
+      // rather than the child being orphaned.
+      //
+      // Registering ANY handler for these suppresses Node's default
+      // terminate-on-signal, so the parent's exit has to be arranged explicitly.
+      // `child.killed` only records that kill() was CALLED, never that the child
+      // is gone, so gating on it swallows every signal after the first and wedges
+      // the launcher with no escape hatch.
+      //
+      // Escalation is driven by a TIMER, not by counting signals. Counting is
+      // ambiguous: a supervisor routinely sends SIGINT then SIGTERM milliseconds
+      // apart, and a terminal Ctrl-C reaches the whole process group, so reading
+      // "a second signal" as impatience hard-kills a child that is already
+      // shutting down cleanly. A timer makes the count irrelevant -- ONE press is
+      // enough, and a wedged child dies on schedule. setTimeout is monotonic, so
+      // a wall-clock step cannot mis-gate the window either.
+      //
+      // POSIX vs Windows, and why we do NOT forward on Windows.
+      // On POSIX child.kill(sig) delivers a real, catchable signal, so forwarding
+      // is what lets the child run its shutdown. On Windows there are no POSIX
+      // signals: child.kill IGNORES the name and calls TerminateProcess -- an
+      // immediate hard kill (verified: a child with a SIGTERM handler never runs
+      // it and dies with code=null, signal=SIGTERM). Forwarding there ABORTS the
+      // graceful shutdown the console's own Ctrl-C just started, skipping the
+      // child's process.on("exit") cleanup. The console has already notified the
+      // child, so on Windows the timer below is the only kill we issue.
+      const ESCALATE_AFTER_MS = 2000;
+      let escalation = null;
+      for (const sig of ["SIGINT", "SIGTERM"]) {
+        process.on(sig, () => {
+          // No try/catch: kill() on an already-exited child returns false, it does
+          // not throw. It throws only for a signal the platform does not know,
+          // which SIGINT/SIGTERM/SIGKILL never are.
+          if (!isWin) child.kill(sig);
+          if (escalation) return; // already counting down; further signals are noise
+          escalation = setTimeout(() => {
+            // Still here after its grace window. Stop waiting on it.
+            child.kill("SIGKILL");
+            process.exit(128 + (constants.signals[sig] ?? 15));
+          }, ESCALATE_AFTER_MS);
+        });
+      }
+
+      child.on("exit", (code, signal) => {
+        if (escalation) clearTimeout(escalation);
+        // Mirror the child's fate: a signal death becomes 128+n so callers see a
+        // conventional shell exit status rather than a bare 0.
+        if (signal) {
+          process.exit(128 + (constants.signals[signal] ?? 15));
+        }
+        process.exit(code ?? 0);
+      });
+    }
+  }
+}

package/package.json

@@ -1,82 +1,82 @@
-{
-  "name": "@yawlabs/caddy-mcp",
-  "version": "2.3.0",
-  "mcpName": "io.github.YawLabs/caddy-mcp",
-  "description": "MCP server for managing Caddy web servers via the admin API",
-  "license": "MIT",
-  "author": "Yaw Labs <contact@yaw.sh> (https://yaw.sh)",
-  "type": "module",
-  "exports": {
-    ".": {
-      "import": "./dist/server.js",
-      "types": "./dist/server.d.ts"
-    }
-  },
-  "main": "./dist/server.js",
-  "types": "./dist/server.d.ts",
-  "bin": {
-    "caddy-mcp": "bin/caddy-mcp.mjs"
-  },
-  "files": [
-    "bin/caddy-mcp.mjs",
-    "dist",
-    "!dist/**/*.test.*",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsup && tsc -p tsconfig.build.json",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "lint": "biome check src/",
-    "lint:fix": "biome check --write src/",
-    "typecheck": "node scripts/typecheck.mjs",
-    "typecheck:tsc": "tsc --noEmit",
-    "test:ci": "npm run build && npm test",
-    "prepublishOnly": "npm run build",
-    "prepare": "git config core.hooksPath .githooks 2>/dev/null || true",
-    "start": "node dist/index.js"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^4.3.6"
-  },
-  "overrides": {
-    "hono": "^4.12.21",
-    "@hono/node-server": "^1.19.13",
-    "postcss": "^8.5.10",
-    "ip-address": "^10.1.1",
-    "fast-uri": "^3.1.2",
-    "qs": "^6.15.2",
-    "esbuild": "^0.28.1"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "~2.4.11",
-    "@types/node": "^26.0.0",
-    "postject": "^1.0.0-alpha.6",
-    "tsup": "^8.4.0",
-    "typescript": "^7.0.2",
-    "vitest": "^4.1.4"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "caddy",
-    "reverse-proxy",
-    "web-server",
-    "mcp-server",
-    "devtools",
-    "ai"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/YawLabs/caddy-mcp.git"
-  },
-  "bugs": {
-    "url": "https://github.com/YawLabs/caddy-mcp/issues"
-  },
-  "homepage": "https://github.com/YawLabs/caddy-mcp"
-}
+{
+  "name": "@yawlabs/caddy-mcp",
+  "version": "2.3.1",
+  "mcpName": "io.github.YawLabs/caddy-mcp",
+  "description": "MCP server for managing Caddy web servers via the admin API",
+  "license": "MIT",
+  "author": "Yaw Labs <contact@yaw.sh> (https://yaw.sh)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/server.js",
+      "types": "./dist/server.d.ts"
+    }
+  },
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "bin": {
+    "caddy-mcp": "bin/caddy-mcp.mjs"
+  },
+  "files": [
+    "bin/caddy-mcp.mjs",
+    "dist",
+    "!dist/**/*.test.*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "typecheck": "node scripts/typecheck.mjs",
+    "typecheck:tsc": "tsc --noEmit",
+    "test:ci": "npm run build && npm test",
+    "prepublishOnly": "npm run build",
+    "prepare": "git config core.hooksPath .githooks 2>/dev/null || true",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.6"
+  },
+  "overrides": {
+    "hono": "^4.12.21",
+    "@hono/node-server": "^1.19.13",
+    "postcss": "^8.5.10",
+    "ip-address": "^10.1.1",
+    "fast-uri": "^3.1.2",
+    "qs": "^6.15.2",
+    "esbuild": "^0.28.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "~2.4.11",
+    "@types/node": "^26.0.0",
+    "postject": "^1.0.0-alpha.6",
+    "tsup": "^8.4.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.4"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "caddy",
+    "reverse-proxy",
+    "web-server",
+    "mcp-server",
+    "devtools",
+    "ai"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YawLabs/caddy-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/YawLabs/caddy-mcp/issues"
+  },
+  "homepage": "https://github.com/YawLabs/caddy-mcp"
+}