@yawlabs/caddy-mcp 1.2.8 → 1.3.0

package/README.md

@@ -1,245 +1,246 @@
-# @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)](yaw://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. |
-| `CADDY_API_TOKEN` | (none) | Optional Bearer token for authenticated admin endpoints. Only needed if you've configured Caddy with auth. |
-| `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_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. |
-
-**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.
-- **caddy_config_by_id** — Get/set/delete config by `@id` tag — much easier than navigating deep paths.
-- **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.
-
-**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`)
-
-## 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 (188 unit tests; +8 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. |
+| `CADDY_API_TOKEN` | (none) | Optional Bearer token for authenticated admin endpoints. Only needed if you've configured Caddy with auth. |
+| `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. |
+
+**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.
+
+**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`)
+
+## 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 (230 unit tests; +8 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/dist/index.js

@@ -102,7 +102,7 @@ async function caddyRequest(method, path, body, contentType, timeout) {
 }
 async function attemptRequest(method, path, body, contentType, timeout) {
   const url = `${getBaseUrl()}${path}`;
-  const effectiveTimeout = timeout ?? TIMEOUT;
+  const effectiveTimeout = timeout ?? getRequestTimeout();
   try {
     const hasBody = body !== void 0;
     const headers = getHeaders(hasBody ? contentType || "application/json" : void 0);
@@ -138,7 +138,11 @@ async function attemptRequest(method, path, body, contentType, timeout) {
           error: "Config has been modified since it was last read (HTTP 412 Precondition Failed). Re-read the config and retry your change."
         };
       }
-      return { ok: false, status: res.status, error: text || `HTTP ${res.status}` };
+      if (!text) {
+        const hint = res.status === 401 || res.status === 403 ? " -- check CADDY_API_TOKEN" : "";
+        return { ok: false, status: res.status, error: `HTTP ${res.status}${hint}` };
+      }
+      return { ok: false, status: res.status, error: text };
     }
     if (!text) return { ok: true, status: res.status, etag };
     try {
@@ -197,6 +201,15 @@ function configDelete(path) {
   if (bad) return Promise.resolve(bad);
   return caddyRequest("DELETE", `/config/${normalized}`);
 }
+function getRequestTimeout() {
+  const raw = process.env.CADDY_TIMEOUT;
+  if (raw === void 0) return TIMEOUT;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return TIMEOUT;
+  const floored = Math.floor(n);
+  if (floored < 1) return TIMEOUT;
+  return floored;
+}
 function getLoadTimeout() {
   const raw = process.env.CADDY_LOAD_TIMEOUT;
   if (raw === void 0) return 6e4;
@@ -312,7 +325,7 @@ function applyMetricsControls(raw, filter, maxLines) {
   if (filtered.length <= maxLines) return filtered.join("\n");
   const dropped = filtered.length - maxLines;
   const kept = filtered.slice(0, maxLines);
-  kept.push(`# [truncated, ${dropped} lines omitted -- use filter to narrow]`);
+  kept.push(`# [truncated, ${dropped} lines omitted; max_lines=${maxLines} -- use filter or raise max_lines]`);
   const keptHasEof = kept.some((l) => l.trim() === "# EOF");
   if (!keptHasEof && filtered.slice(maxLines).some((l) => l.trim() === "# EOF")) {
     kept.push("# EOF");
@@ -441,7 +454,7 @@ function registerResources(server) {
         {
           uri: "caddy://config",
           mimeType: res.ok ? "application/json" : "text/plain",
-          text: res.ok ? JSON.stringify(res.data, null, 2) : `Error: ${res.error}`
+          text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : `Error: ${res.error}`
         }
       ]
     };
@@ -457,7 +470,7 @@ function registerResources(server) {
           {
             uri: "caddy://upstreams",
             mimeType: res.ok ? "application/json" : "text/plain",
-            text: res.ok ? JSON.stringify(res.data, null, 2) : `Error: ${res.error}`
+            text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : `Error: ${res.error}`
           }
         ]
       };
@@ -603,10 +616,26 @@ function registerConfigTools(server) {
   );
   server.tool(
     "caddy_config_delete",
-    "Delete config at a JSON path. Removes the config node at the specified path.",
-    { path: z3.string().describe("Config path to delete (e.g., 'apps/http/servers/srv0/routes/0')") },
+    "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.",
+    {
+      path: z3.string().describe("Config path to delete (e.g., 'apps/http/servers/srv0/routes/0')"),
+      confirm: z3.boolean().optional().default(false).describe("Must be true to actually delete the config node (safety)")
+    },
     { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
-    async ({ path }) => formatResult(await configDelete(path))
+    async ({ path, confirm }) => {
+      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.`
+            }
+          ]
+        };
+      }
+      return formatResult(await configDelete(path));
+    }
   );
   server.tool(
     "caddy_load",
@@ -705,7 +734,7 @@ ${lines.join("\n")}` }] };
   );
   server.tool(
     "caddy_config_by_id",
-    "Access config by @id tag. Any config object with an '@id' field can be read, updated, or deleted by its ID instead of needing its full path. This is the recommended way to manage individual routes and config objects.",
+    "Access config by @id tag. Any config object with an '@id' field can be read, updated, or deleted by its ID instead of needing its full path. This is the recommended way to manage individual routes and config objects. The 'delete' action requires confirm=true.",
     {
       id: z3.string().regex(/^[\w-]{1,128}$/).describe("The @id value of the config object"),
       action: z3.enum(["get", "set", "delete"]).optional().default("get").describe("Action to perform"),
@@ -713,10 +742,11 @@ ${lines.join("\n")}` }] };
       subpath: z3.string().optional().default("").describe("Optional sub-path within the identified object"),
       mode: z3.enum(["append", "overwrite", "insert"]).optional().default("overwrite").describe(
         "For 'set' action: 'overwrite' = PATCH (replace existing, default), 'append' = POST (add to arrays, create on objects), 'insert' = PUT (insert at array index)"
-      )
+      ),
+      confirm: z3.boolean().optional().default(false).describe("Must be true to actually delete (only enforced for action='delete')")
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    async ({ id, action, value, subpath, mode }) => {
+    async ({ id, action, value, subpath, mode, confirm }) => {
       if (action === "get") {
         return formatResult(await configByIdGet(id, subpath));
       }
@@ -731,6 +761,18 @@ ${lines.join("\n")}` }] };
         return formatResult(await configByIdSet(id, value, method, subpath));
       }
       if (action === "delete") {
+        if (!confirm) {
+          const target = subpath ? `@id="${id}" subpath "${subpath}"` : `@id="${id}"`;
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: `Refusing to delete ${target} without confirm=true. Re-run with confirm:true to proceed.`
+              }
+            ]
+          };
+        }
         return formatResult(await configByIdDelete(id, subpath));
       }
       return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
@@ -791,13 +833,13 @@ function isRouteShape(obj) {
   if (!obj || typeof obj !== "object") return false;
   return Array.isArray(obj.handle);
 }
-function serverNotFoundError(srv) {
+function serverNotFoundError(srv, op = "operation") {
   return {
     isError: true,
     content: [
       {
         type: "text",
-        text: `Error: Server "${srv}" does not exist. Use caddy_list_servers to see available servers, or create one with caddy_load or caddy_config_set at path 'apps/http/servers/${srv}' with at minimum: { "listen": [":443"] }`
+        text: `Error: Server "${srv}" does not exist (${op}). Use caddy_list_servers to see available servers, or create one with caddy_load or caddy_config_set at path 'apps/http/servers/${srv}' with at minimum: { "listen": [":443"] }`
       }
     ]
   };
@@ -871,7 +913,7 @@ function registerRouteTools(server) {
           };
         }
         if (isParentMissing(postRes)) {
-          return serverNotFoundError(srv);
+          return serverNotFoundError(srv, "caddy_reverse_proxy");
         }
         return formatResult(postRes);
       }
@@ -880,7 +922,7 @@ function registerRouteTools(server) {
         return { content: [{ type: "text", text: `Route added: ${from} \u2192 ${cleanedTo.join(", ")}` }] };
       }
       if (isParentMissing(res)) {
-        return serverNotFoundError(srv);
+        return serverNotFoundError(srv, "caddy_reverse_proxy");
       }
       return formatResult(res);
     }
@@ -899,7 +941,7 @@ function registerRouteTools(server) {
       const route = { match, handle, terminal };
       const res = await configPost(`apps/http/servers/${srv}/routes`, route);
       if (isParentMissing(res)) {
-        return serverNotFoundError(srv);
+        return serverNotFoundError(srv, "caddy_add_route");
       }
       return formatResult(res);
     }
@@ -1070,13 +1112,25 @@ function registerRouteTools(server) {
         if (res2.ok) return { content: [{ type: "text", text: `Route @id="${id}" removed.` }] };
         return formatResult(res2);
       }
+      if (index === void 0) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: "Error: must provide either id or index" }]
+        };
+      }
       const readRes = await configGet(`apps/http/servers/${srv}/routes`);
       if (!readRes.ok) return formatResult(readRes);
       const routes = readRes.data;
+      if (routes === void 0 || routes === null) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: `Error: server "${srv}" has no routes configured` }]
+        };
+      }
       if (!Array.isArray(routes)) {
         return {
           isError: true,
-          content: [{ type: "text", text: `Error: server "${srv}" has no routes array (or it is malformed)` }]
+          content: [{ type: "text", text: `Error: server "${srv}" routes value is malformed (not an array)` }]
         };
       }
       if (index >= routes.length) {

package/dist/server.js

@@ -100,7 +100,7 @@ async function caddyRequest(method, path, body, contentType, timeout) {
 }
 async function attemptRequest(method, path, body, contentType, timeout) {
   const url = `${getBaseUrl()}${path}`;
-  const effectiveTimeout = timeout ?? TIMEOUT;
+  const effectiveTimeout = timeout ?? getRequestTimeout();
   try {
     const hasBody = body !== void 0;
     const headers = getHeaders(hasBody ? contentType || "application/json" : void 0);
@@ -136,7 +136,11 @@ async function attemptRequest(method, path, body, contentType, timeout) {
           error: "Config has been modified since it was last read (HTTP 412 Precondition Failed). Re-read the config and retry your change."
         };
       }
-      return { ok: false, status: res.status, error: text || `HTTP ${res.status}` };
+      if (!text) {
+        const hint = res.status === 401 || res.status === 403 ? " -- check CADDY_API_TOKEN" : "";
+        return { ok: false, status: res.status, error: `HTTP ${res.status}${hint}` };
+      }
+      return { ok: false, status: res.status, error: text };
     }
     if (!text) return { ok: true, status: res.status, etag };
     try {
@@ -195,6 +199,15 @@ function configDelete(path) {
   if (bad) return Promise.resolve(bad);
   return caddyRequest("DELETE", `/config/${normalized}`);
 }
+function getRequestTimeout() {
+  const raw = process.env.CADDY_TIMEOUT;
+  if (raw === void 0) return TIMEOUT;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return TIMEOUT;
+  const floored = Math.floor(n);
+  if (floored < 1) return TIMEOUT;
+  return floored;
+}
 function getLoadTimeout() {
   const raw = process.env.CADDY_LOAD_TIMEOUT;
   if (raw === void 0) return 6e4;
@@ -310,7 +323,7 @@ function applyMetricsControls(raw, filter, maxLines) {
   if (filtered.length <= maxLines) return filtered.join("\n");
   const dropped = filtered.length - maxLines;
   const kept = filtered.slice(0, maxLines);
-  kept.push(`# [truncated, ${dropped} lines omitted -- use filter to narrow]`);
+  kept.push(`# [truncated, ${dropped} lines omitted; max_lines=${maxLines} -- use filter or raise max_lines]`);
   const keptHasEof = kept.some((l) => l.trim() === "# EOF");
   if (!keptHasEof && filtered.slice(maxLines).some((l) => l.trim() === "# EOF")) {
     kept.push("# EOF");
@@ -439,7 +452,7 @@ function registerResources(server) {
         {
           uri: "caddy://config",
           mimeType: res.ok ? "application/json" : "text/plain",
-          text: res.ok ? JSON.stringify(res.data, null, 2) : `Error: ${res.error}`
+          text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : `Error: ${res.error}`
         }
       ]
     };
@@ -455,7 +468,7 @@ function registerResources(server) {
           {
             uri: "caddy://upstreams",
             mimeType: res.ok ? "application/json" : "text/plain",
-            text: res.ok ? JSON.stringify(res.data, null, 2) : `Error: ${res.error}`
+            text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : `Error: ${res.error}`
           }
         ]
       };
@@ -601,10 +614,26 @@ function registerConfigTools(server) {
   );
   server.tool(
     "caddy_config_delete",
-    "Delete config at a JSON path. Removes the config node at the specified path.",
-    { path: z3.string().describe("Config path to delete (e.g., 'apps/http/servers/srv0/routes/0')") },
+    "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.",
+    {
+      path: z3.string().describe("Config path to delete (e.g., 'apps/http/servers/srv0/routes/0')"),
+      confirm: z3.boolean().optional().default(false).describe("Must be true to actually delete the config node (safety)")
+    },
     { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
-    async ({ path }) => formatResult(await configDelete(path))
+    async ({ path, confirm }) => {
+      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.`
+            }
+          ]
+        };
+      }
+      return formatResult(await configDelete(path));
+    }
   );
   server.tool(
     "caddy_load",
@@ -703,7 +732,7 @@ ${lines.join("\n")}` }] };
   );
   server.tool(
     "caddy_config_by_id",
-    "Access config by @id tag. Any config object with an '@id' field can be read, updated, or deleted by its ID instead of needing its full path. This is the recommended way to manage individual routes and config objects.",
+    "Access config by @id tag. Any config object with an '@id' field can be read, updated, or deleted by its ID instead of needing its full path. This is the recommended way to manage individual routes and config objects. The 'delete' action requires confirm=true.",
     {
       id: z3.string().regex(/^[\w-]{1,128}$/).describe("The @id value of the config object"),
       action: z3.enum(["get", "set", "delete"]).optional().default("get").describe("Action to perform"),
@@ -711,10 +740,11 @@ ${lines.join("\n")}` }] };
       subpath: z3.string().optional().default("").describe("Optional sub-path within the identified object"),
       mode: z3.enum(["append", "overwrite", "insert"]).optional().default("overwrite").describe(
         "For 'set' action: 'overwrite' = PATCH (replace existing, default), 'append' = POST (add to arrays, create on objects), 'insert' = PUT (insert at array index)"
-      )
+      ),
+      confirm: z3.boolean().optional().default(false).describe("Must be true to actually delete (only enforced for action='delete')")
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    async ({ id, action, value, subpath, mode }) => {
+    async ({ id, action, value, subpath, mode, confirm }) => {
       if (action === "get") {
         return formatResult(await configByIdGet(id, subpath));
       }
@@ -729,6 +759,18 @@ ${lines.join("\n")}` }] };
         return formatResult(await configByIdSet(id, value, method, subpath));
       }
       if (action === "delete") {
+        if (!confirm) {
+          const target = subpath ? `@id="${id}" subpath "${subpath}"` : `@id="${id}"`;
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: `Refusing to delete ${target} without confirm=true. Re-run with confirm:true to proceed.`
+              }
+            ]
+          };
+        }
         return formatResult(await configByIdDelete(id, subpath));
       }
       return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
@@ -789,13 +831,13 @@ function isRouteShape(obj) {
   if (!obj || typeof obj !== "object") return false;
   return Array.isArray(obj.handle);
 }
-function serverNotFoundError(srv) {
+function serverNotFoundError(srv, op = "operation") {
   return {
     isError: true,
     content: [
       {
         type: "text",
-        text: `Error: Server "${srv}" does not exist. Use caddy_list_servers to see available servers, or create one with caddy_load or caddy_config_set at path 'apps/http/servers/${srv}' with at minimum: { "listen": [":443"] }`
+        text: `Error: Server "${srv}" does not exist (${op}). Use caddy_list_servers to see available servers, or create one with caddy_load or caddy_config_set at path 'apps/http/servers/${srv}' with at minimum: { "listen": [":443"] }`
       }
     ]
   };
@@ -869,7 +911,7 @@ function registerRouteTools(server) {
           };
         }
         if (isParentMissing(postRes)) {
-          return serverNotFoundError(srv);
+          return serverNotFoundError(srv, "caddy_reverse_proxy");
         }
         return formatResult(postRes);
       }
@@ -878,7 +920,7 @@ function registerRouteTools(server) {
         return { content: [{ type: "text", text: `Route added: ${from} \u2192 ${cleanedTo.join(", ")}` }] };
       }
       if (isParentMissing(res)) {
-        return serverNotFoundError(srv);
+        return serverNotFoundError(srv, "caddy_reverse_proxy");
       }
       return formatResult(res);
     }
@@ -897,7 +939,7 @@ function registerRouteTools(server) {
       const route = { match, handle, terminal };
       const res = await configPost(`apps/http/servers/${srv}/routes`, route);
       if (isParentMissing(res)) {
-        return serverNotFoundError(srv);
+        return serverNotFoundError(srv, "caddy_add_route");
       }
       return formatResult(res);
     }
@@ -1068,13 +1110,25 @@ function registerRouteTools(server) {
         if (res2.ok) return { content: [{ type: "text", text: `Route @id="${id}" removed.` }] };
         return formatResult(res2);
       }
+      if (index === void 0) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: "Error: must provide either id or index" }]
+        };
+      }
       const readRes = await configGet(`apps/http/servers/${srv}/routes`);
       if (!readRes.ok) return formatResult(readRes);
       const routes = readRes.data;
+      if (routes === void 0 || routes === null) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: `Error: server "${srv}" has no routes configured` }]
+        };
+      }
       if (!Array.isArray(routes)) {
         return {
           isError: true,
-          content: [{ type: "text", text: `Error: server "${srv}" has no routes array (or it is malformed)` }]
+          content: [{ type: "text", text: `Error: server "${srv}" routes value is malformed (not an array)` }]
         };
       }
       if (index >= routes.length) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/caddy-mcp",
-  "version": "1.2.8",
+  "version": "1.3.0",
   "mcpName": "io.github.YawLabs/caddy-mcp",
   "description": "MCP server for managing Caddy web servers via the admin API",
   "license": "MIT",
@@ -40,11 +40,12 @@
     "zod": "^4.3.6"
   },
   "overrides": {
-    "hono": "^4.12.18",
+    "hono": "^4.12.21",
     "@hono/node-server": "^1.19.13",
     "postcss": "^8.5.10",
     "ip-address": "^10.1.1",
-    "fast-uri": "^3.1.2"
+    "fast-uri": "^3.1.2",
+    "qs": "^6.15.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",