@yawlabs/caddy-mcp 0.1.1 → 0.3.0

package/README.md

@@ -2,115 +2,221 @@
 
 [![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)
+[![CI](https://github.com/YawLabs/caddy-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/YawLabs/caddy-mcp/actions/workflows/ci.yml) [![Release](https://github.com/YawLabs/caddy-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/YawLabs/caddy-mcp/actions/workflows/release.yml)
 
-**MCP server for managing Caddy web servers.** 16 tools for config management, reverse proxy setup, route operations, TLS, and server monitoring — all via Caddy's admin API.
+**Manage Caddy web servers from Claude Code, Cursor, and any MCP client.** 17 tools + 4 resources covering every endpoint of Caddy's admin API — config, routes, reverse proxies, TLS, PKI, metrics.
 
 Built and maintained by [Yaw Labs](https://yaw.sh).
 
-## Quick start
+[![Add to mcp.hosting](https://mcp.hosting/install-button.svg)](https://mcp.hosting/install?name=Caddy&command=npx&args=-y%2C%40yawlabs%2Fcaddy-mcp&env=CADDY_ADMIN_URL%2CCADDY_API_TOKEN&description=Manage%20Caddy%20web%20servers%20-%20config%2C%20routes%2C%20TLS%2C%20PKI&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Fcaddy-mcp)
 
-```bash
-npx @yawlabs/caddy-mcp
-```
+One click adds this to your [mcp.hosting](https://mcp.hosting) account so it syncs to every MCP client you use. Or install manually below.
 
-Or install globally:
+## Why this one?
 
-```bash
-npm install -g @yawlabs/caddy-mcp
-caddy-mcp
-```
+Other Caddy MCP servers wrap half the admin API and silently swallow errors. This one doesn't.
 
-## MCP client configuration
+- **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.
 
-### Claude Code
+## Quick start
 
-```bash
-claude mcp add caddy-mcp npx @yawlabs/caddy-mcp
-```
+**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`.
 
-### Claude Desktop / Cursor / Windsurf
+**2. Create `.mcp.json` in your project root**
 
-Add to your MCP config file:
+macOS / Linux / WSL:
 
 ```json
 {
   "mcpServers": {
-    "caddy-mcp": {
+    "caddy": {
       "command": "npx",
-      "args": ["@yawlabs/caddy-mcp"],
-      "env": {
-        "CADDY_ADMIN_URL": "http://localhost:2019"
-      }
+      "args": ["-y", "@yawlabs/caddy-mcp"]
     }
   }
 }
 ```
 
+Windows:
+
+```json
+{
+  "mcpServers": {
+    "caddy": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@yawlabs/caddy-mcp"]
+    }
+  }
+}
+```
+
+> **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 |
+| Environment variable | Default | Description |
 |---|---|---|
-| `CADDY_ADMIN_URL` | `http://localhost:2019` | Caddy admin API URL |
-| `CADDY_API_TOKEN` | (none) | Optional Bearer token for authenticated admin endpoints |
+| `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. |
+
+**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
+### Config management (5)
 
-- **caddy_config_get** — Read config at any JSON path (or full config)
-- **caddy_config_set** — Create or replace config at a path
-- **caddy_config_delete** — Delete config at a path
-- **caddy_config_by_id** — Read, update, or delete config by `@id` tag
-- **caddy_load** — Replace entire config atomically
+- **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.
 
-### Route operations
+### Route operations (4)
 
-- **caddy_reverse_proxy** — Add a reverse proxy in one call: `from='api.local' to=['localhost:3000']`
-- **caddy_add_route** — Add a route with full match/handle control (any Caddy handler)
-- **caddy_list_routes** — Human-readable route summary
+- **caddy_reverse_proxy** — Add a reverse proxy in one call: `from='api.local' to=['localhost:3000']`.
+- **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
+### TLS & config conversion (2)
 
-- **caddy_tls** — Check/configure TLS settings, ACME email, CA
-- **caddy_adapt** — Convert Caddyfile to JSON (preview before applying)
+- **caddy_tls** — Check or set TLS settings: ACME email, ACME CA URL. Falls back gracefully when paths don't yet exist.
+- **caddy_adapt** — Convert a Caddyfile (or nginx config) to Caddy JSON without applying it. Great for previewing.
 
-### Server operations
+### Server operations (6)
 
-- **caddy_status** — Connectivity check + config summary
-- **caddy_list_servers** — List all HTTP servers with names, addresses, and TLS status
-- **caddy_upstreams** — Reverse proxy backend health
-- **caddy_metrics** — Prometheus metrics (request counts, durations, connections)
-- **caddy_pki** — CA info and certificate chains
-- **caddy_stop** — Graceful shutdown (requires confirmation)
+- **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).
+- **caddy_pki** — CA info and certificate chains (default CA: `local`).
+- **caddy_stop** — Graceful shutdown. Requires `confirm=true` to prevent accidents.
 
 ## Resources
 
-- `caddy://config` — Current Caddy JSON configuration
-- `caddy://upstreams` — Reverse proxy upstream health status
+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).
 
 ## 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"] })
+```
+
+### 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()
 ```
-> "Proxy api.local to my dev server on port 3000"
-→ caddy_reverse_proxy(from: "api.local", to: ["localhost:3000"])
 
-> "What routes are configured?"
-→ caddy_list_routes()
+### Safely update a route by @id
 
-> "Show me the full Caddy config"
-→ caddy_config_get()
+```
+> "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
+```
 
-> "Convert this Caddyfile to JSON"
-→ caddy_adapt(config: "example.com {\n  reverse_proxy localhost:8080\n}")
+### Atomic deploy
 
-> "Is Caddy running?"
-→ caddy_status()
 ```
+> "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 18+
-- Caddy server with admin API enabled (default: `localhost:2019`)
+- 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 (83 tests)
+npm run typecheck  # tsc --noEmit
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow, including release process.
 
 ## License
 

package/dist/index.js

@@ -9,6 +9,14 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 var DEFAULT_URL = "http://localhost:2019";
 var TIMEOUT = 1e4;
 var etagCache = /* @__PURE__ */ new Map();
+var MAX_ETAG_CACHE = 256;
+function setEtag(path, etag) {
+  if (etagCache.size >= MAX_ETAG_CACHE && !etagCache.has(path)) {
+    const oldest = etagCache.keys().next().value;
+    if (oldest !== void 0) etagCache.delete(oldest);
+  }
+  etagCache.set(path, etag);
+}
 function getBaseUrl() {
   return (process.env.CADDY_ADMIN_URL || DEFAULT_URL).replace(/\/+$/, "");
 }
@@ -43,7 +51,7 @@ async function caddyRequest(method, path, body, contentType, timeout) {
     const text = await res.text();
     const etag = res.headers.get("ETag") || void 0;
     if (method === "GET" && etag && isConfigPath) {
-      etagCache.set(path, etag);
+      setEtag(path, etag);
     }
     if (isWrite && res.ok && isConfigPath) {
       etagCache.delete(path);
@@ -68,10 +76,16 @@ async function caddyRequest(method, path, body, contentType, timeout) {
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+      const baseUrl = getBaseUrl();
+      let origin = baseUrl;
+      try {
+        origin = new URL(baseUrl).origin;
+      } catch {
+      }
       return {
         ok: false,
         status: 0,
-        error: `Cannot connect to Caddy admin API at ${getBaseUrl()} \u2014 is Caddy running?`
+        error: `Cannot connect to Caddy admin API at ${origin} \u2014 is Caddy running?`
       };
     }
     if (msg.includes("abort") || msg.includes("timeout")) {
@@ -168,6 +182,40 @@ function registerResources(server) {
       };
     }
   );
+  server.resource(
+    "caddy-metrics",
+    "caddy://metrics",
+    { description: "Prometheus metrics (text exposition format)" },
+    async () => {
+      const res = await getMetrics();
+      return {
+        contents: [
+          {
+            uri: "caddy://metrics",
+            mimeType: "text/plain",
+            text: res.ok ? String(res.data ?? "") : `Error: ${res.error}`
+          }
+        ]
+      };
+    }
+  );
+  server.resource(
+    "caddy-servers",
+    "caddy://servers",
+    { description: "Summary of all configured HTTP servers" },
+    async () => {
+      const res = await configGet("apps/http/servers");
+      return {
+        contents: [
+          {
+            uri: "caddy://servers",
+            mimeType: "application/json",
+            text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : `Error: ${res.error}`
+          }
+        ]
+      };
+    }
+  );
 }
 
 // src/tools/adapt.ts
@@ -193,7 +241,7 @@ function registerAdaptTools(server) {
     "Convert a Caddyfile or other config format to Caddy JSON without loading it. Useful for previewing what a Caddyfile produces. Returns the adapted JSON and any warnings separately.",
     {
       config: z.string().describe("The raw config text (e.g., Caddyfile contents)"),
-      adapter: z.string().optional().default("caddyfile").describe("Config format adapter (default: 'caddyfile')")
+      adapter: z.string().regex(/^[a-z0-9_-]+$/i, "Adapter must be alphanumeric, hyphens, or underscores").max(64).optional().default("caddyfile").describe("Config format adapter (default: 'caddyfile')")
     },
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async ({ config, adapter }) => {
@@ -230,12 +278,12 @@ function registerConfigTools(server) {
   );
   server.tool(
     "caddy_config_set",
-    "Write config at a JSON path. Mode 'append' (default) adds to arrays or creates keys (POST). Mode 'overwrite' replaces existing values (PATCH). Mode 'insert' places at a specific array index (PUT) \u2014 useful for route ordering.",
+    "Write config at a JSON path. Mode 'overwrite' (default) replaces existing values (PATCH) \u2014 safe and idempotent. Mode 'append' adds to arrays or creates keys (POST) \u2014 NOT idempotent: calling twice with the same route duplicates it. Mode 'insert' places at a specific array index (PUT) \u2014 useful for route ordering.",
     {
       path: z2.string().describe("Config path to write to (e.g., 'apps/http/servers/srv0/routes')"),
       value: z2.any().describe("The JSON value to set at the path"),
-      mode: z2.enum(["append", "overwrite", "insert"]).optional().default("append").describe(
-        "'append' = POST (add to arrays, create on objects), 'overwrite' = PATCH (replace existing), 'insert' = PUT (insert at array index)"
+      mode: z2.enum(["append", "overwrite", "insert"]).optional().default("overwrite").describe(
+        "'overwrite' = PATCH (replace existing, default, idempotent), 'append' = POST (add to arrays / create keys, NOT idempotent), 'insert' = PUT (insert at array index)"
       )
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
@@ -268,13 +316,16 @@ function registerConfigTools(server) {
     "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.",
     {
-      id: z2.string().regex(/^[\w-]+$/).describe("The @id value of the config object"),
+      id: z2.string().regex(/^[\w-]{1,128}$/).describe("The @id value of the config object"),
       action: z2.enum(["get", "set", "delete"]).optional().default("get").describe("Action to perform"),
       value: z2.any().optional().describe("New value (required for 'set' action)"),
-      subpath: z2.string().optional().default("").describe("Optional sub-path within the identified object")
+      subpath: z2.string().optional().default("").describe("Optional sub-path within the identified object"),
+      mode: z2.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)"
+      )
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    async ({ id, action, value, subpath }) => {
+    async ({ id, action, value, subpath, mode }) => {
       if (action === "get") {
         return formatResult(await configByIdGet(id, subpath));
       }
@@ -285,7 +336,8 @@ function registerConfigTools(server) {
             content: [{ type: "text", text: "Error: value is required for 'set' action" }]
           };
         }
-        return formatResult(await configByIdSet(id, value, "PATCH", subpath));
+        const method = mode === "append" ? "POST" : mode === "insert" ? "PUT" : "PATCH";
+        return formatResult(await configByIdSet(id, value, method, subpath));
       }
       if (action === "delete") {
         return formatResult(await configByIdDelete(id, subpath));
@@ -375,7 +427,7 @@ ${lines.join("\n")}` }]
     "caddy_pki",
     "Get PKI certificate authority info or the CA certificate chain.",
     {
-      ca: z3.string().regex(/^[\w-]+$/).optional().default("local").describe("CA ID (default: 'local')"),
+      ca: z3.string().regex(/^[\w-]{1,128}$/).optional().default("local").describe("CA ID (default: 'local')"),
       certificates: z3.boolean().optional().default(false).describe("If true, return the full CA certificate chain")
     },
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
@@ -410,6 +462,10 @@ ${lines.join("\n")}` }]
 
 // src/tools/routes.ts
 import { z as z4 } from "zod";
+function safeJoin(value) {
+  if (!Array.isArray(value)) return "";
+  return value.filter((v) => v !== null && v !== void 0).map(String).join(",");
+}
 function parseFrom(from) {
   const cleaned = from.replace(/^https?:\/\//, "");
   const match = {};
@@ -445,7 +501,7 @@ function registerRouteTools(server) {
     {
       from: z4.string().describe("Domain, path, or domain/path to match (e.g., 'api.local', '/api/*', 'app.local/ws')"),
       to: z4.array(z4.string()).describe("Upstream addresses (e.g., ['localhost:3000', 'localhost:3001'])"),
-      server: z4.string().regex(/^[\w-]+$/).optional().default("srv0").describe("Caddy server name (default: srv0)")
+      server: z4.string().regex(/^[\w-]{1,128}$/).optional().default("srv0").describe("Caddy server name (default: srv0)")
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     async ({ from, to, server: srv }) => {
@@ -477,7 +533,7 @@ function registerRouteTools(server) {
     {
       match: z4.array(z4.record(z4.string(), z4.any())).describe("Array of match objects (e.g., [{ host: ['example.com'], path: ['/api/*'] }])"),
       handle: z4.array(z4.record(z4.string(), z4.any())).describe("Array of handler objects (e.g., [{ handler: 'file_server', root: '/var/www' }])"),
-      server: z4.string().regex(/^[\w-]+$/).optional().default("srv0").describe("Caddy server name (default: srv0)"),
+      server: z4.string().regex(/^[\w-]{1,128}$/).optional().default("srv0").describe("Caddy server name (default: srv0)"),
       terminal: z4.boolean().optional().default(true).describe("Stop processing further routes after this one matches")
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
@@ -494,38 +550,58 @@ function registerRouteTools(server) {
     "caddy_list_routes",
     "List all routes on a Caddy HTTP server with a human-readable summary of matchers and handlers.",
     {
-      server: z4.string().regex(/^[\w-]+$/).optional().default("srv0").describe("Caddy server name (default: srv0)")
+      server: z4.string().regex(/^[\w-]{1,128}$/).optional().default("srv0").describe("Caddy server name (default: srv0)")
     },
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async ({ server: srv }) => {
       const serverRes = await configGet(`apps/http/servers/${srv}`);
       if (!serverRes.ok) return formatResult(serverRes);
-      const serverConfig = serverRes.data;
-      const routes = serverConfig?.routes || [];
-      const listen = serverConfig?.listen || [];
+      const serverConfig = serverRes.data || {};
+      const routes = Array.isArray(serverConfig.routes) ? serverConfig.routes : [];
+      const listen = Array.isArray(serverConfig.listen) ? serverConfig.listen : [];
+      const listenStr = listen.map(String).join(", ") || "default";
       if (routes.length === 0) {
         return {
           content: [
             {
               type: "text",
-              text: `Server ${srv} (listen: ${listen.join(", ") || "default"}) \u2014 no routes configured`
+              text: `Server ${srv} (listen: ${listenStr}) \u2014 no routes configured`
             }
           ]
         };
       }
-      const lines = [`Server: ${srv} (listen: ${listen.join(", ") || "default"})`, ""];
+      const lines = [`Server: ${srv} (listen: ${listenStr})`, ""];
       for (let i = 0; i < routes.length; i++) {
-        const route = routes[i];
-        const id = route["@id"] ? ` @id="${route["@id"]}"` : "";
-        const group = route.group ? ` group="${route.group}"` : "";
-        const matchers = (route.match || []).map((m) => {
+        const rawRoute = routes[i];
+        if (!rawRoute || typeof rawRoute !== "object") {
+          lines.push(`  Route ${i}: <invalid>`);
+          continue;
+        }
+        const route = rawRoute;
+        const idVal = typeof route["@id"] === "string" ? route["@id"] : void 0;
+        const groupVal = typeof route.group === "string" ? route.group : void 0;
+        const id = idVal ? ` @id="${idVal}"` : "";
+        const group = groupVal ? ` group="${groupVal}"` : "";
+        const matchList = Array.isArray(route.match) ? route.match : [];
+        const matchers = matchList.map((rawMatcher) => {
+          if (!rawMatcher || typeof rawMatcher !== "object") return "catch-all";
+          const m = rawMatcher;
           const parts = [];
-          if (m.host) parts.push(`host=[${m.host.join(",")}]`);
-          if (m.path) parts.push(`path=[${m.path.join(",")}]`);
-          if (m.method) parts.push(`method=[${m.method.join(",")}]`);
-          if (m.protocol) parts.push(`protocol=${m.protocol}`);
-          if (m.remote_ip) parts.push(`remote_ip=[${m.remote_ip.ranges?.join(",") || "..."}]`);
-          if (m.client_ip) parts.push(`client_ip=[${m.client_ip.ranges?.join(",") || "..."}]`);
+          const host = safeJoin(m.host);
+          if (host) parts.push(`host=[${host}]`);
+          const path = safeJoin(m.path);
+          if (path) parts.push(`path=[${path}]`);
+          const method = safeJoin(m.method);
+          if (method) parts.push(`method=[${method}]`);
+          if (typeof m.protocol === "string") parts.push(`protocol=${m.protocol}`);
+          if (m.remote_ip && typeof m.remote_ip === "object") {
+            const ranges = safeJoin(m.remote_ip.ranges);
+            parts.push(`remote_ip=[${ranges || "..."}]`);
+          }
+          if (m.client_ip && typeof m.client_ip === "object") {
+            const ranges = safeJoin(m.client_ip.ranges);
+            parts.push(`client_ip=[${ranges || "..."}]`);
+          }
           if (m.query) parts.push("query=...");
           if (m.header) parts.push("header=...");
           if (m.expression) parts.push(`expr(${typeof m.expression === "string" ? m.expression : "..."})`);
@@ -548,23 +624,51 @@ function registerRouteTools(server) {
           if (parts.length === 0) return "catch-all";
           return parts.join(" ");
         }).join(" | ");
-        const handlers = (route.handle || []).map((h) => {
+        const handleList = Array.isArray(route.handle) ? route.handle : [];
+        const handlers = handleList.map((rawHandler) => {
+          if (!rawHandler || typeof rawHandler !== "object") return "unknown";
+          const h = rawHandler;
           if (h.handler === "reverse_proxy") {
-            const upstreams = (h.upstreams || []).map((u) => u.dial).join(",");
+            const upstreamsArr = Array.isArray(h.upstreams) ? h.upstreams : [];
+            const upstreams = upstreamsArr.map((u) => {
+              if (u && typeof u === "object") {
+                const dial = u.dial;
+                if (typeof dial === "string") return dial;
+              }
+              return "?";
+            }).join(",");
             return `reverse_proxy(${upstreams})`;
           }
-          if (h.handler === "file_server") return `file_server(${h.root || "."})`;
-          if (h.handler === "static_response") return `static_response(${h.status_code || 200})`;
-          if (h.handler === "rewrite") return `rewrite(${h.uri || "..."})`;
-          if (h.handler === "subroute") return `subroute(${h.routes?.length || 0} routes)`;
+          if (h.handler === "file_server") {
+            const root = typeof h.root === "string" ? h.root : ".";
+            return `file_server(${root})`;
+          }
+          if (h.handler === "static_response") {
+            const status = typeof h.status_code === "number" ? h.status_code : 200;
+            return `static_response(${status})`;
+          }
+          if (h.handler === "rewrite") {
+            const uri = typeof h.uri === "string" ? h.uri : "...";
+            return `rewrite(${uri})`;
+          }
+          if (h.handler === "subroute") {
+            const count = Array.isArray(h.routes) ? h.routes.length : 0;
+            return `subroute(${count} routes)`;
+          }
           if (h.handler === "encode") return "encode";
           if (h.handler === "headers") return "headers";
-          if (h.handler === "authentication")
-            return `auth(${h.providers ? Object.keys(h.providers).join(",") : "..."})`;
-          if (h.handler === "error") return `error(${h.status_code || "..."})`;
-          return h.handler || "unknown";
+          if (h.handler === "authentication") {
+            const providers = h.providers && typeof h.providers === "object" ? Object.keys(h.providers).join(",") : "...";
+            return `auth(${providers})`;
+          }
+          if (h.handler === "error") {
+            const status = typeof h.status_code === "number" ? h.status_code : "...";
+            return `error(${status})`;
+          }
+          return typeof h.handler === "string" ? h.handler : "unknown";
         }).join(" \u2192 ");
-        lines.push(`  Route ${i}:${id}${group} ${matchers} \u2192 ${handlers}${route.terminal ? " [terminal]" : ""}`);
+        const terminal = route.terminal === true ? " [terminal]" : "";
+        lines.push(`  Route ${i}:${id}${group} ${matchers} \u2192 ${handlers}${terminal}`);
       }
       return {
         content: [
@@ -574,6 +678,67 @@ function registerRouteTools(server) {
       };
     }
   );
+  server.tool(
+    "caddy_remove_route",
+    "Remove a route. Target by @id (preferred \u2014 stable across reorderings) or by array index on a specific server. Uses ETags to prevent concurrent overwrites.",
+    {
+      id: z4.string().regex(/^[\w-]{1,128}$/).optional().describe("The @id of the route to remove (preferred \u2014 stable even if routes get reordered)"),
+      index: z4.number().int().nonnegative().optional().describe("Zero-based index of the route in the server's routes array (only used if id is not provided)"),
+      server: z4.string().regex(/^[\w-]{1,128}$/).optional().default("srv0").describe("Caddy server name when using index (default: srv0). Ignored when id is provided."),
+      confirm: z4.boolean().optional().default(false).describe("Must be true to actually remove the route (safety)")
+    },
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    async ({ id, index, server: srv, confirm }) => {
+      if (!id && index === void 0) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: "Error: must provide either id or index" }]
+        };
+      }
+      if (!confirm) {
+        const target = id ? `@id="${id}"` : `route ${index} on server "${srv}"`;
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Refusing to remove ${target} without confirm=true. Re-run with confirm:true to proceed.`
+            }
+          ]
+        };
+      }
+      if (id) {
+        const res2 = await configByIdDelete(id);
+        if (res2.ok) return { content: [{ type: "text", text: `Route @id="${id}" removed.` }] };
+        return formatResult(res2);
+      }
+      const readRes = await configGet(`apps/http/servers/${srv}/routes`);
+      if (!readRes.ok) return formatResult(readRes);
+      const routes = readRes.data;
+      if (!Array.isArray(routes)) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: `Error: server "${srv}" has no routes array (or it is malformed)` }]
+        };
+      }
+      if (index >= routes.length) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Error: index ${index} out of range \u2014 server "${srv}" has ${routes.length} route(s)`
+            }
+          ]
+        };
+      }
+      const res = await configDelete(`apps/http/servers/${srv}/routes/${index}`);
+      if (res.ok) {
+        return { content: [{ type: "text", text: `Route ${index} removed from server "${srv}".` }] };
+      }
+      return formatResult(res);
+    }
+  );
 }
 
 // src/tools/tls.ts
@@ -588,6 +753,21 @@ function buildTlsConfig(fields) {
     }
   };
 }
+function bothErrors(label, patchRes, postRes) {
+  const patchErr = patchRes.error || `HTTP ${patchRes.status}`;
+  const postErr = postRes.error || `HTTP ${postRes.status}`;
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: `Error: Failed to set ${label}.
+  PATCH attempt: ${patchErr}
+  POST fallback: ${postErr}`
+      }
+    ]
+  };
+}
 function registerTlsTools(server) {
   server.tool(
     "caddy_tls",
@@ -608,11 +788,11 @@ function registerTlsTools(server) {
             isError: true,
             content: [{ type: "text", text: "Error: email is required for set_email action" }]
           };
-        const res = await configPatch("apps/tls/automation/policies/0/issuers/0/email", email);
-        if (res.ok) return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
-        const fallback = await configPost("apps/tls", buildTlsConfig({ email }));
-        if (fallback.ok) return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
-        return formatResult(fallback);
+        const patchRes = await configPatch("apps/tls/automation/policies/0/issuers/0/email", email);
+        if (patchRes.ok) return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
+        const postRes = await configPost("apps/tls", buildTlsConfig({ email }));
+        if (postRes.ok) return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
+        return bothErrors("ACME email", patchRes, postRes);
       }
       if (action === "set_acme_ca") {
         if (!ca)
@@ -620,11 +800,11 @@ function registerTlsTools(server) {
             isError: true,
             content: [{ type: "text", text: "Error: ca is required for set_acme_ca action" }]
           };
-        const res = await configPatch("apps/tls/automation/policies/0/issuers/0/ca", ca);
-        if (res.ok) return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
-        const fallback = await configPost("apps/tls", buildTlsConfig({ ca }));
-        if (fallback.ok) return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
-        return formatResult(fallback);
+        const patchRes = await configPatch("apps/tls/automation/policies/0/issuers/0/ca", ca);
+        if (patchRes.ok) return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
+        const postRes = await configPost("apps/tls", buildTlsConfig({ ca }));
+        if (postRes.ok) return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
+        return bothErrors("ACME CA", patchRes, postRes);
       }
       return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
     }

package/dist/server.js

@@ -7,6 +7,14 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 var DEFAULT_URL = "http://localhost:2019";
 var TIMEOUT = 1e4;
 var etagCache = /* @__PURE__ */ new Map();
+var MAX_ETAG_CACHE = 256;
+function setEtag(path, etag) {
+  if (etagCache.size >= MAX_ETAG_CACHE && !etagCache.has(path)) {
+    const oldest = etagCache.keys().next().value;
+    if (oldest !== void 0) etagCache.delete(oldest);
+  }
+  etagCache.set(path, etag);
+}
 function getBaseUrl() {
   return (process.env.CADDY_ADMIN_URL || DEFAULT_URL).replace(/\/+$/, "");
 }
@@ -41,7 +49,7 @@ async function caddyRequest(method, path, body, contentType, timeout) {
     const text = await res.text();
     const etag = res.headers.get("ETag") || void 0;
     if (method === "GET" && etag && isConfigPath) {
-      etagCache.set(path, etag);
+      setEtag(path, etag);
     }
     if (isWrite && res.ok && isConfigPath) {
       etagCache.delete(path);
@@ -66,10 +74,16 @@ async function caddyRequest(method, path, body, contentType, timeout) {
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+      const baseUrl = getBaseUrl();
+      let origin = baseUrl;
+      try {
+        origin = new URL(baseUrl).origin;
+      } catch {
+      }
       return {
         ok: false,
         status: 0,
-        error: `Cannot connect to Caddy admin API at ${getBaseUrl()} \u2014 is Caddy running?`
+        error: `Cannot connect to Caddy admin API at ${origin} \u2014 is Caddy running?`
       };
     }
     if (msg.includes("abort") || msg.includes("timeout")) {
@@ -166,6 +180,40 @@ function registerResources(server) {
       };
     }
   );
+  server.resource(
+    "caddy-metrics",
+    "caddy://metrics",
+    { description: "Prometheus metrics (text exposition format)" },
+    async () => {
+      const res = await getMetrics();
+      return {
+        contents: [
+          {
+            uri: "caddy://metrics",
+            mimeType: "text/plain",
+            text: res.ok ? String(res.data ?? "") : `Error: ${res.error}`
+          }
+        ]
+      };
+    }
+  );
+  server.resource(
+    "caddy-servers",
+    "caddy://servers",
+    { description: "Summary of all configured HTTP servers" },
+    async () => {
+      const res = await configGet("apps/http/servers");
+      return {
+        contents: [
+          {
+            uri: "caddy://servers",
+            mimeType: "application/json",
+            text: res.ok ? JSON.stringify(res.data ?? {}, null, 2) : `Error: ${res.error}`
+          }
+        ]
+      };
+    }
+  );
 }
 
 // src/tools/adapt.ts
@@ -191,7 +239,7 @@ function registerAdaptTools(server) {
     "Convert a Caddyfile or other config format to Caddy JSON without loading it. Useful for previewing what a Caddyfile produces. Returns the adapted JSON and any warnings separately.",
     {
       config: z.string().describe("The raw config text (e.g., Caddyfile contents)"),
-      adapter: z.string().optional().default("caddyfile").describe("Config format adapter (default: 'caddyfile')")
+      adapter: z.string().regex(/^[a-z0-9_-]+$/i, "Adapter must be alphanumeric, hyphens, or underscores").max(64).optional().default("caddyfile").describe("Config format adapter (default: 'caddyfile')")
     },
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async ({ config, adapter }) => {
@@ -228,12 +276,12 @@ function registerConfigTools(server) {
   );
   server.tool(
     "caddy_config_set",
-    "Write config at a JSON path. Mode 'append' (default) adds to arrays or creates keys (POST). Mode 'overwrite' replaces existing values (PATCH). Mode 'insert' places at a specific array index (PUT) \u2014 useful for route ordering.",
+    "Write config at a JSON path. Mode 'overwrite' (default) replaces existing values (PATCH) \u2014 safe and idempotent. Mode 'append' adds to arrays or creates keys (POST) \u2014 NOT idempotent: calling twice with the same route duplicates it. Mode 'insert' places at a specific array index (PUT) \u2014 useful for route ordering.",
     {
       path: z2.string().describe("Config path to write to (e.g., 'apps/http/servers/srv0/routes')"),
       value: z2.any().describe("The JSON value to set at the path"),
-      mode: z2.enum(["append", "overwrite", "insert"]).optional().default("append").describe(
-        "'append' = POST (add to arrays, create on objects), 'overwrite' = PATCH (replace existing), 'insert' = PUT (insert at array index)"
+      mode: z2.enum(["append", "overwrite", "insert"]).optional().default("overwrite").describe(
+        "'overwrite' = PATCH (replace existing, default, idempotent), 'append' = POST (add to arrays / create keys, NOT idempotent), 'insert' = PUT (insert at array index)"
       )
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
@@ -266,13 +314,16 @@ function registerConfigTools(server) {
     "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.",
     {
-      id: z2.string().regex(/^[\w-]+$/).describe("The @id value of the config object"),
+      id: z2.string().regex(/^[\w-]{1,128}$/).describe("The @id value of the config object"),
       action: z2.enum(["get", "set", "delete"]).optional().default("get").describe("Action to perform"),
       value: z2.any().optional().describe("New value (required for 'set' action)"),
-      subpath: z2.string().optional().default("").describe("Optional sub-path within the identified object")
+      subpath: z2.string().optional().default("").describe("Optional sub-path within the identified object"),
+      mode: z2.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)"
+      )
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    async ({ id, action, value, subpath }) => {
+    async ({ id, action, value, subpath, mode }) => {
       if (action === "get") {
         return formatResult(await configByIdGet(id, subpath));
       }
@@ -283,7 +334,8 @@ function registerConfigTools(server) {
             content: [{ type: "text", text: "Error: value is required for 'set' action" }]
           };
         }
-        return formatResult(await configByIdSet(id, value, "PATCH", subpath));
+        const method = mode === "append" ? "POST" : mode === "insert" ? "PUT" : "PATCH";
+        return formatResult(await configByIdSet(id, value, method, subpath));
       }
       if (action === "delete") {
         return formatResult(await configByIdDelete(id, subpath));
@@ -373,7 +425,7 @@ ${lines.join("\n")}` }]
     "caddy_pki",
     "Get PKI certificate authority info or the CA certificate chain.",
     {
-      ca: z3.string().regex(/^[\w-]+$/).optional().default("local").describe("CA ID (default: 'local')"),
+      ca: z3.string().regex(/^[\w-]{1,128}$/).optional().default("local").describe("CA ID (default: 'local')"),
       certificates: z3.boolean().optional().default(false).describe("If true, return the full CA certificate chain")
     },
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
@@ -408,6 +460,10 @@ ${lines.join("\n")}` }]
 
 // src/tools/routes.ts
 import { z as z4 } from "zod";
+function safeJoin(value) {
+  if (!Array.isArray(value)) return "";
+  return value.filter((v) => v !== null && v !== void 0).map(String).join(",");
+}
 function parseFrom(from) {
   const cleaned = from.replace(/^https?:\/\//, "");
   const match = {};
@@ -443,7 +499,7 @@ function registerRouteTools(server) {
     {
       from: z4.string().describe("Domain, path, or domain/path to match (e.g., 'api.local', '/api/*', 'app.local/ws')"),
       to: z4.array(z4.string()).describe("Upstream addresses (e.g., ['localhost:3000', 'localhost:3001'])"),
-      server: z4.string().regex(/^[\w-]+$/).optional().default("srv0").describe("Caddy server name (default: srv0)")
+      server: z4.string().regex(/^[\w-]{1,128}$/).optional().default("srv0").describe("Caddy server name (default: srv0)")
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     async ({ from, to, server: srv }) => {
@@ -475,7 +531,7 @@ function registerRouteTools(server) {
     {
       match: z4.array(z4.record(z4.string(), z4.any())).describe("Array of match objects (e.g., [{ host: ['example.com'], path: ['/api/*'] }])"),
       handle: z4.array(z4.record(z4.string(), z4.any())).describe("Array of handler objects (e.g., [{ handler: 'file_server', root: '/var/www' }])"),
-      server: z4.string().regex(/^[\w-]+$/).optional().default("srv0").describe("Caddy server name (default: srv0)"),
+      server: z4.string().regex(/^[\w-]{1,128}$/).optional().default("srv0").describe("Caddy server name (default: srv0)"),
       terminal: z4.boolean().optional().default(true).describe("Stop processing further routes after this one matches")
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
@@ -492,38 +548,58 @@ function registerRouteTools(server) {
     "caddy_list_routes",
     "List all routes on a Caddy HTTP server with a human-readable summary of matchers and handlers.",
     {
-      server: z4.string().regex(/^[\w-]+$/).optional().default("srv0").describe("Caddy server name (default: srv0)")
+      server: z4.string().regex(/^[\w-]{1,128}$/).optional().default("srv0").describe("Caddy server name (default: srv0)")
     },
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async ({ server: srv }) => {
       const serverRes = await configGet(`apps/http/servers/${srv}`);
       if (!serverRes.ok) return formatResult(serverRes);
-      const serverConfig = serverRes.data;
-      const routes = serverConfig?.routes || [];
-      const listen = serverConfig?.listen || [];
+      const serverConfig = serverRes.data || {};
+      const routes = Array.isArray(serverConfig.routes) ? serverConfig.routes : [];
+      const listen = Array.isArray(serverConfig.listen) ? serverConfig.listen : [];
+      const listenStr = listen.map(String).join(", ") || "default";
       if (routes.length === 0) {
         return {
           content: [
             {
               type: "text",
-              text: `Server ${srv} (listen: ${listen.join(", ") || "default"}) \u2014 no routes configured`
+              text: `Server ${srv} (listen: ${listenStr}) \u2014 no routes configured`
             }
           ]
         };
       }
-      const lines = [`Server: ${srv} (listen: ${listen.join(", ") || "default"})`, ""];
+      const lines = [`Server: ${srv} (listen: ${listenStr})`, ""];
       for (let i = 0; i < routes.length; i++) {
-        const route = routes[i];
-        const id = route["@id"] ? ` @id="${route["@id"]}"` : "";
-        const group = route.group ? ` group="${route.group}"` : "";
-        const matchers = (route.match || []).map((m) => {
+        const rawRoute = routes[i];
+        if (!rawRoute || typeof rawRoute !== "object") {
+          lines.push(`  Route ${i}: <invalid>`);
+          continue;
+        }
+        const route = rawRoute;
+        const idVal = typeof route["@id"] === "string" ? route["@id"] : void 0;
+        const groupVal = typeof route.group === "string" ? route.group : void 0;
+        const id = idVal ? ` @id="${idVal}"` : "";
+        const group = groupVal ? ` group="${groupVal}"` : "";
+        const matchList = Array.isArray(route.match) ? route.match : [];
+        const matchers = matchList.map((rawMatcher) => {
+          if (!rawMatcher || typeof rawMatcher !== "object") return "catch-all";
+          const m = rawMatcher;
           const parts = [];
-          if (m.host) parts.push(`host=[${m.host.join(",")}]`);
-          if (m.path) parts.push(`path=[${m.path.join(",")}]`);
-          if (m.method) parts.push(`method=[${m.method.join(",")}]`);
-          if (m.protocol) parts.push(`protocol=${m.protocol}`);
-          if (m.remote_ip) parts.push(`remote_ip=[${m.remote_ip.ranges?.join(",") || "..."}]`);
-          if (m.client_ip) parts.push(`client_ip=[${m.client_ip.ranges?.join(",") || "..."}]`);
+          const host = safeJoin(m.host);
+          if (host) parts.push(`host=[${host}]`);
+          const path = safeJoin(m.path);
+          if (path) parts.push(`path=[${path}]`);
+          const method = safeJoin(m.method);
+          if (method) parts.push(`method=[${method}]`);
+          if (typeof m.protocol === "string") parts.push(`protocol=${m.protocol}`);
+          if (m.remote_ip && typeof m.remote_ip === "object") {
+            const ranges = safeJoin(m.remote_ip.ranges);
+            parts.push(`remote_ip=[${ranges || "..."}]`);
+          }
+          if (m.client_ip && typeof m.client_ip === "object") {
+            const ranges = safeJoin(m.client_ip.ranges);
+            parts.push(`client_ip=[${ranges || "..."}]`);
+          }
           if (m.query) parts.push("query=...");
           if (m.header) parts.push("header=...");
           if (m.expression) parts.push(`expr(${typeof m.expression === "string" ? m.expression : "..."})`);
@@ -546,23 +622,51 @@ function registerRouteTools(server) {
           if (parts.length === 0) return "catch-all";
           return parts.join(" ");
         }).join(" | ");
-        const handlers = (route.handle || []).map((h) => {
+        const handleList = Array.isArray(route.handle) ? route.handle : [];
+        const handlers = handleList.map((rawHandler) => {
+          if (!rawHandler || typeof rawHandler !== "object") return "unknown";
+          const h = rawHandler;
           if (h.handler === "reverse_proxy") {
-            const upstreams = (h.upstreams || []).map((u) => u.dial).join(",");
+            const upstreamsArr = Array.isArray(h.upstreams) ? h.upstreams : [];
+            const upstreams = upstreamsArr.map((u) => {
+              if (u && typeof u === "object") {
+                const dial = u.dial;
+                if (typeof dial === "string") return dial;
+              }
+              return "?";
+            }).join(",");
             return `reverse_proxy(${upstreams})`;
           }
-          if (h.handler === "file_server") return `file_server(${h.root || "."})`;
-          if (h.handler === "static_response") return `static_response(${h.status_code || 200})`;
-          if (h.handler === "rewrite") return `rewrite(${h.uri || "..."})`;
-          if (h.handler === "subroute") return `subroute(${h.routes?.length || 0} routes)`;
+          if (h.handler === "file_server") {
+            const root = typeof h.root === "string" ? h.root : ".";
+            return `file_server(${root})`;
+          }
+          if (h.handler === "static_response") {
+            const status = typeof h.status_code === "number" ? h.status_code : 200;
+            return `static_response(${status})`;
+          }
+          if (h.handler === "rewrite") {
+            const uri = typeof h.uri === "string" ? h.uri : "...";
+            return `rewrite(${uri})`;
+          }
+          if (h.handler === "subroute") {
+            const count = Array.isArray(h.routes) ? h.routes.length : 0;
+            return `subroute(${count} routes)`;
+          }
           if (h.handler === "encode") return "encode";
           if (h.handler === "headers") return "headers";
-          if (h.handler === "authentication")
-            return `auth(${h.providers ? Object.keys(h.providers).join(",") : "..."})`;
-          if (h.handler === "error") return `error(${h.status_code || "..."})`;
-          return h.handler || "unknown";
+          if (h.handler === "authentication") {
+            const providers = h.providers && typeof h.providers === "object" ? Object.keys(h.providers).join(",") : "...";
+            return `auth(${providers})`;
+          }
+          if (h.handler === "error") {
+            const status = typeof h.status_code === "number" ? h.status_code : "...";
+            return `error(${status})`;
+          }
+          return typeof h.handler === "string" ? h.handler : "unknown";
         }).join(" \u2192 ");
-        lines.push(`  Route ${i}:${id}${group} ${matchers} \u2192 ${handlers}${route.terminal ? " [terminal]" : ""}`);
+        const terminal = route.terminal === true ? " [terminal]" : "";
+        lines.push(`  Route ${i}:${id}${group} ${matchers} \u2192 ${handlers}${terminal}`);
       }
       return {
         content: [
@@ -572,6 +676,67 @@ function registerRouteTools(server) {
       };
     }
   );
+  server.tool(
+    "caddy_remove_route",
+    "Remove a route. Target by @id (preferred \u2014 stable across reorderings) or by array index on a specific server. Uses ETags to prevent concurrent overwrites.",
+    {
+      id: z4.string().regex(/^[\w-]{1,128}$/).optional().describe("The @id of the route to remove (preferred \u2014 stable even if routes get reordered)"),
+      index: z4.number().int().nonnegative().optional().describe("Zero-based index of the route in the server's routes array (only used if id is not provided)"),
+      server: z4.string().regex(/^[\w-]{1,128}$/).optional().default("srv0").describe("Caddy server name when using index (default: srv0). Ignored when id is provided."),
+      confirm: z4.boolean().optional().default(false).describe("Must be true to actually remove the route (safety)")
+    },
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    async ({ id, index, server: srv, confirm }) => {
+      if (!id && index === void 0) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: "Error: must provide either id or index" }]
+        };
+      }
+      if (!confirm) {
+        const target = id ? `@id="${id}"` : `route ${index} on server "${srv}"`;
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Refusing to remove ${target} without confirm=true. Re-run with confirm:true to proceed.`
+            }
+          ]
+        };
+      }
+      if (id) {
+        const res2 = await configByIdDelete(id);
+        if (res2.ok) return { content: [{ type: "text", text: `Route @id="${id}" removed.` }] };
+        return formatResult(res2);
+      }
+      const readRes = await configGet(`apps/http/servers/${srv}/routes`);
+      if (!readRes.ok) return formatResult(readRes);
+      const routes = readRes.data;
+      if (!Array.isArray(routes)) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: `Error: server "${srv}" has no routes array (or it is malformed)` }]
+        };
+      }
+      if (index >= routes.length) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Error: index ${index} out of range \u2014 server "${srv}" has ${routes.length} route(s)`
+            }
+          ]
+        };
+      }
+      const res = await configDelete(`apps/http/servers/${srv}/routes/${index}`);
+      if (res.ok) {
+        return { content: [{ type: "text", text: `Route ${index} removed from server "${srv}".` }] };
+      }
+      return formatResult(res);
+    }
+  );
 }
 
 // src/tools/tls.ts
@@ -586,6 +751,21 @@ function buildTlsConfig(fields) {
     }
   };
 }
+function bothErrors(label, patchRes, postRes) {
+  const patchErr = patchRes.error || `HTTP ${patchRes.status}`;
+  const postErr = postRes.error || `HTTP ${postRes.status}`;
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: `Error: Failed to set ${label}.
+  PATCH attempt: ${patchErr}
+  POST fallback: ${postErr}`
+      }
+    ]
+  };
+}
 function registerTlsTools(server) {
   server.tool(
     "caddy_tls",
@@ -606,11 +786,11 @@ function registerTlsTools(server) {
             isError: true,
             content: [{ type: "text", text: "Error: email is required for set_email action" }]
           };
-        const res = await configPatch("apps/tls/automation/policies/0/issuers/0/email", email);
-        if (res.ok) return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
-        const fallback = await configPost("apps/tls", buildTlsConfig({ email }));
-        if (fallback.ok) return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
-        return formatResult(fallback);
+        const patchRes = await configPatch("apps/tls/automation/policies/0/issuers/0/email", email);
+        if (patchRes.ok) return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
+        const postRes = await configPost("apps/tls", buildTlsConfig({ email }));
+        if (postRes.ok) return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
+        return bothErrors("ACME email", patchRes, postRes);
       }
       if (action === "set_acme_ca") {
         if (!ca)
@@ -618,11 +798,11 @@ function registerTlsTools(server) {
             isError: true,
             content: [{ type: "text", text: "Error: ca is required for set_acme_ca action" }]
           };
-        const res = await configPatch("apps/tls/automation/policies/0/issuers/0/ca", ca);
-        if (res.ok) return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
-        const fallback = await configPost("apps/tls", buildTlsConfig({ ca }));
-        if (fallback.ok) return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
-        return formatResult(fallback);
+        const patchRes = await configPatch("apps/tls/automation/policies/0/issuers/0/ca", ca);
+        if (patchRes.ok) return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
+        const postRes = await configPost("apps/tls", buildTlsConfig({ ca }));
+        if (postRes.ok) return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
+        return bothErrors("ACME CA", patchRes, postRes);
       }
       return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/caddy-mcp",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "MCP server for managing Caddy web servers via the admin API",
   "license": "MIT",
   "author": "Yaw Labs <contact@yaw.sh> (https://yaw.sh)",
@@ -31,6 +31,7 @@
     "typecheck": "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": {