@yawlabs/caddy-mcp 0.1.0 → 0.2.0

package/README.md

@@ -3,7 +3,7 @@
 [![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)
 
-**MCP server for managing Caddy web servers.** 13 tools for config management, reverse proxy setup, route operations, TLS, and server monitoring — all via Caddy's admin API.
+**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.
 
 Built and maintained by [Yaw Labs](https://yaw.sh).
 
@@ -60,6 +60,7 @@ Add to your MCP config file:
 - **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
 
 ### Route operations
@@ -76,7 +77,9 @@ Add to your MCP config file:
 ### Server operations
 
 - **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)
 

package/dist/index.js

@@ -8,36 +8,62 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // src/api.ts
 var DEFAULT_URL = "http://localhost:2019";
 var TIMEOUT = 1e4;
+var etagCache = /* @__PURE__ */ new Map();
 function getBaseUrl() {
   return (process.env.CADDY_ADMIN_URL || DEFAULT_URL).replace(/\/+$/, "");
 }
-function getHeaders(contentType = "application/json") {
-  const headers = { "Content-Type": contentType };
+function getHeaders(contentType) {
+  const headers = {};
+  if (contentType) headers["Content-Type"] = contentType;
   const token = process.env.CADDY_API_TOKEN;
   if (token) headers.Authorization = `Bearer ${token}`;
   return headers;
 }
 function normalizePath(path) {
-  return path.replace(/^\/?(config\/?)?/, "");
+  return path.replace(/^\/?(config(\/|$))?/, "");
 }
-async function caddyRequest(method, path, body, contentType) {
+async function caddyRequest(method, path, body, contentType, timeout) {
   const url = `${getBaseUrl()}${path}`;
+  const effectiveTimeout = timeout ?? TIMEOUT;
   try {
+    const hasBody = body !== void 0;
+    const headers = getHeaders(hasBody ? contentType || "application/json" : void 0);
+    const isConfigPath = path.startsWith("/config/") || path.startsWith("/id/");
+    const isWrite = method !== "GET";
+    if (isWrite && isConfigPath) {
+      const cachedEtag = etagCache.get(path);
+      if (cachedEtag) headers["If-Match"] = cachedEtag;
+    }
     const res = await fetch(url, {
       method,
-      headers: getHeaders(contentType),
-      body: body !== void 0 ? typeof body === "string" ? body : JSON.stringify(body) : void 0,
-      signal: AbortSignal.timeout(TIMEOUT)
+      headers,
+      body: hasBody ? typeof body === "string" ? body : JSON.stringify(body) : void 0,
+      signal: AbortSignal.timeout(effectiveTimeout)
     });
     const text = await res.text();
+    const etag = res.headers.get("ETag") || void 0;
+    if (method === "GET" && etag && isConfigPath) {
+      etagCache.set(path, etag);
+    }
+    if (isWrite && res.ok && isConfigPath) {
+      etagCache.delete(path);
+    }
     if (!res.ok) {
+      if (res.status === 412) {
+        etagCache.delete(path);
+        return {
+          ok: false,
+          status: 412,
+          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) return { ok: true, status: res.status };
+    if (!text) return { ok: true, status: res.status, etag };
     try {
-      return { ok: true, status: res.status, data: JSON.parse(text) };
+      return { ok: true, status: res.status, data: JSON.parse(text), etag };
     } catch {
-      return { ok: true, status: res.status, data: text };
+      return { ok: true, status: res.status, data: text, etag };
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -49,7 +75,7 @@ async function caddyRequest(method, path, body, contentType) {
       };
     }
     if (msg.includes("abort") || msg.includes("timeout")) {
-      return { ok: false, status: 0, error: `Request timed out after ${TIMEOUT}ms` };
+      return { ok: false, status: 0, error: `Request timed out after ${effectiveTimeout}ms` };
     }
     return { ok: false, status: 0, error: msg };
   }
@@ -62,6 +88,10 @@ function configPost(path, value) {
   const normalized = normalizePath(path);
   return caddyRequest("POST", `/config/${normalized}`, value);
 }
+function configPut(path, value) {
+  const normalized = normalizePath(path);
+  return caddyRequest("PUT", `/config/${normalized}`, value);
+}
 function configPatch(path, value) {
   const normalized = normalizePath(path);
   return caddyRequest("PATCH", `/config/${normalized}`, value);
@@ -70,8 +100,11 @@ function configDelete(path) {
   const normalized = normalizePath(path);
   return caddyRequest("DELETE", `/config/${normalized}`);
 }
-function loadConfig(config) {
-  return caddyRequest("POST", "/load", config);
+var LOAD_TIMEOUT = 6e4;
+async function loadConfig(config, contentType) {
+  const res = await caddyRequest("POST", "/load", config, contentType, LOAD_TIMEOUT);
+  if (res.ok) etagCache.clear();
+  return res;
 }
 function adapt(config, adapter = "caddyfile") {
   return caddyRequest("POST", "/adapt", config, `text/${adapter}`);
@@ -88,6 +121,21 @@ function getPki(ca = "local") {
 function getPkiCertificates(ca = "local") {
   return caddyRequest("GET", `/pki/ca/${ca}/certificates`);
 }
+function configByIdGet(id, subpath = "") {
+  const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
+  return caddyRequest("GET", path);
+}
+function configByIdSet(id, value, method = "PATCH", subpath = "") {
+  const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
+  return caddyRequest(method, path, value);
+}
+function configByIdDelete(id, subpath = "") {
+  const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
+  return caddyRequest("DELETE", path);
+}
+function getMetrics() {
+  return caddyRequest("GET", "/metrics");
+}
 
 // src/resources.ts
 function registerResources(server) {
@@ -133,7 +181,8 @@ function formatResult(res) {
       content: [{ type: "text", text: `Error: ${res.error || `HTTP ${res.status}`}` }]
     };
   }
-  const text = res.data !== void 0 ? typeof res.data === "string" ? res.data : JSON.stringify(res.data, null, 2) : "OK";
+  const raw = res.data !== void 0 ? typeof res.data === "string" ? res.data : JSON.stringify(res.data, null, 2) : "";
+  const text = raw || "OK";
   return { content: [{ type: "text", text }] };
 }
 
@@ -141,13 +190,31 @@ function formatResult(res) {
 function registerAdaptTools(server) {
   server.tool(
     "caddy_adapt",
-    "Convert a Caddyfile or other config format to Caddy JSON without loading it. Useful for previewing what a Caddyfile produces.",
+    "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')")
     },
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    async ({ config, adapter }) => formatResult(await adapt(config, adapter))
+    async ({ config, adapter }) => {
+      const res = await adapt(config, adapter);
+      if (!res.ok) return formatResult(res);
+      const warnings = res.data?.warnings || [];
+      const result = res.data?.result;
+      const content = [];
+      if (warnings.length > 0) {
+        const warnLines = warnings.map(
+          (w) => `  - ${w.directive || "unknown"}: ${w.message || JSON.stringify(w)}`
+        );
+        content.push({ type: "text", text: `Warnings:
+${warnLines.join("\n")}` });
+      }
+      content.push({
+        type: "text",
+        text: result !== void 0 ? JSON.stringify(result, null, 2) : "OK (no output)"
+      });
+      return { content };
+    }
   );
 }
 
@@ -163,15 +230,17 @@ function registerConfigTools(server) {
   );
   server.tool(
     "caddy_config_set",
-    "Create or replace config at a JSON path. Mode 'create' (default) appends to arrays or creates objects (POST). Mode 'replace' overwrites existing values (PATCH).",
+    "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.",
     {
       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(["create", "replace"]).optional().default("create").describe("'create' = POST (append), 'replace' = PATCH (overwrite)")
+      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)"
+      )
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     async ({ path, value, mode }) => {
-      const res = mode === "replace" ? await configPatch(path, value) : await configPost(path, value);
+      const res = mode === "overwrite" ? await configPatch(path, value) : mode === "insert" ? await configPut(path, value) : await configPost(path, value);
       return formatResult(res);
     }
   );
@@ -184,10 +253,49 @@ function registerConfigTools(server) {
   );
   server.tool(
     "caddy_load",
-    "Replace the entire Caddy configuration atomically. Accepts a full Caddy JSON config object. This is the safest way to make large config changes.",
-    { config: z2.record(z2.any()).describe("Full Caddy JSON configuration object") },
+    "Replace the entire Caddy configuration atomically. Accepts a JSON config object, or a Caddyfile string with format='caddyfile'. This is the safest way to make large config changes. Has a 60-second timeout to allow for TLS provisioning.",
+    {
+      config: z2.union([z2.record(z2.string(), z2.any()), z2.string()]).describe("Full config \u2014 JSON object or Caddyfile text string"),
+      format: z2.enum(["json", "caddyfile"]).optional().default("json").describe("Config format: 'json' (default) or 'caddyfile'")
+    },
     { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
-    async ({ config }) => formatResult(await loadConfig(config))
+    async ({ config, format }) => {
+      const contentType = format === "caddyfile" ? "text/caddyfile" : "application/json";
+      return formatResult(await loadConfig(config, contentType));
+    }
+  );
+  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.",
+    {
+      id: z2.string().regex(/^[\w-]+$/).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"),
+      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, mode }) => {
+      if (action === "get") {
+        return formatResult(await configByIdGet(id, subpath));
+      }
+      if (action === "set") {
+        if (value === void 0) {
+          return {
+            isError: true,
+            content: [{ type: "text", text: "Error: value is required for 'set' action" }]
+          };
+        }
+        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));
+      }
+      return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
+    }
   );
 }
 
@@ -214,7 +322,9 @@ function registerOperationalTools(server) {
           const srv = servers[name];
           const listen = srv.listen || [];
           const routes = srv.routes || [];
-          const tls = srv.tls_connection_policies ? "enabled" : "auto";
+          const hasExplicitTls = !!srv.tls_connection_policies;
+          const listensHttps = listen.some((l) => l.includes(":443"));
+          const tls = hasExplicitTls ? "enabled" : listensHttps ? "auto (HTTPS)" : "off (HTTP only)";
           lines.push(
             `Server "${name}": ${routes.length} route(s), listen: ${listen.join(", ") || "default"}, TLS: ${tls}`
           );
@@ -229,6 +339,35 @@ ACME email: ${email}`);
       return { content: [{ type: "text", text: lines.join("\n") }] };
     }
   );
+  server.tool(
+    "caddy_list_servers",
+    "List all configured HTTP servers with their names, listen addresses, route counts, and TLS status. Use this to discover server names before calling route tools.",
+    {},
+    { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async () => {
+      const res = await configGet("apps/http/servers");
+      if (!res.ok) return formatResult(res);
+      const servers = res.data || {};
+      const names = Object.keys(servers);
+      if (names.length === 0) {
+        return { content: [{ type: "text", text: "No HTTP servers configured" }] };
+      }
+      const lines = [];
+      for (const name of names) {
+        const srv = servers[name];
+        const listen = srv.listen || [];
+        const routes = srv.routes || [];
+        const hasExplicitTls = !!srv.tls_connection_policies;
+        const listensHttps = listen.some((l) => l.includes(":443"));
+        const tls = hasExplicitTls ? "enabled" : listensHttps ? "auto (HTTPS)" : "off (HTTP only)";
+        lines.push(`  ${name}: ${routes.length} route(s), listen: ${listen.join(", ") || "default"}, TLS: ${tls}`);
+      }
+      return {
+        content: [{ type: "text", text: `HTTP Servers:
+${lines.join("\n")}` }]
+      };
+    }
+  );
   server.tool(
     "caddy_upstreams",
     "Get the current health status of all reverse proxy upstreams. Shows address, active requests, and failure counts.",
@@ -240,7 +379,7 @@ ACME email: ${email}`);
     "caddy_pki",
     "Get PKI certificate authority info or the CA certificate chain.",
     {
-      ca: z3.string().optional().default("local").describe("CA ID (default: 'local')"),
+      ca: z3.string().regex(/^[\w-]+$/).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 },
@@ -249,6 +388,13 @@ ACME email: ${email}`);
       return formatResult(res);
     }
   );
+  server.tool(
+    "caddy_metrics",
+    "Get Prometheus metrics from Caddy. Shows request counts, durations, TLS handshake stats, active connections, and more.",
+    {},
+    { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async () => formatResult(await getMetrics())
+  );
   server.tool(
     "caddy_stop",
     "Gracefully shut down the Caddy server. Requires confirm=true to prevent accidental shutdown.",
@@ -269,18 +415,33 @@ ACME email: ${email}`);
 // src/tools/routes.ts
 import { z as z4 } from "zod";
 function parseFrom(from) {
+  const cleaned = from.replace(/^https?:\/\//, "");
   const match = {};
-  const slashIdx = from.indexOf("/");
+  const slashIdx = cleaned.indexOf("/");
   if (slashIdx > 0) {
-    match.host = [from.substring(0, slashIdx)];
-    match.path = [from.substring(slashIdx)];
-  } else if (from.startsWith("/")) {
-    match.path = [from];
+    match.host = [cleaned.substring(0, slashIdx)];
+    match.path = [cleaned.substring(slashIdx)];
+  } else if (cleaned.startsWith("/")) {
+    match.path = [cleaned];
   } else {
-    match.host = [from];
+    match.host = [cleaned];
   }
   return match;
 }
+function cleanUpstreamAddr(addr) {
+  return addr.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+}
+function serverNotFoundError(srv) {
+  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"] }`
+      }
+    ]
+  };
+}
 function registerRouteTools(server) {
   server.tool(
     "caddy_reverse_proxy",
@@ -288,24 +449,28 @@ 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().optional().default("srv0").describe("Caddy server name (default: srv0)")
+      server: z4.string().regex(/^[\w-]+$/).optional().default("srv0").describe("Caddy server name (default: srv0)")
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     async ({ from, to, server: srv }) => {
       const match = parseFrom(from);
+      const cleanedTo = to.map(cleanUpstreamAddr);
       const route = {
         match: [match],
         handle: [
           {
             handler: "reverse_proxy",
-            upstreams: to.map((addr) => ({ dial: addr }))
+            upstreams: cleanedTo.map((addr) => ({ dial: addr }))
           }
         ],
         terminal: true
       };
       const res = await configPost(`apps/http/servers/${srv}/routes`, route);
       if (res.ok) {
-        return { content: [{ type: "text", text: `Route added: ${from} \u2192 ${to.join(", ")}` }] };
+        return { content: [{ type: "text", text: `Route added: ${from} \u2192 ${cleanedTo.join(", ")}` }] };
+      }
+      if (!res.ok && res.error?.includes("key does not exist")) {
+        return serverNotFoundError(srv);
       }
       return formatResult(res);
     }
@@ -314,15 +479,18 @@ function registerRouteTools(server) {
     "caddy_add_route",
     "Add a route with full control over match conditions and handlers. Supports any Caddy handler (reverse_proxy, file_server, static_response, redirect, encode, headers, etc.).",
     {
-      match: z4.array(z4.record(z4.any())).describe("Array of match objects (e.g., [{ host: ['example.com'], path: ['/api/*'] }])"),
-      handle: z4.array(z4.record(z4.any())).describe("Array of handler objects (e.g., [{ handler: 'file_server', root: '/var/www' }])"),
-      server: z4.string().optional().default("srv0").describe("Caddy server name (default: srv0)"),
+      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)"),
       terminal: z4.boolean().optional().default(true).describe("Stop processing further routes after this one matches")
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     async ({ match, handle, server: srv, terminal }) => {
       const route = { match, handle, terminal };
       const res = await configPost(`apps/http/servers/${srv}/routes`, route);
+      if (!res.ok && res.error?.includes("key does not exist")) {
+        return serverNotFoundError(srv);
+      }
       return formatResult(res);
     }
   );
@@ -330,7 +498,7 @@ 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().optional().default("srv0").describe("Caddy server name (default: srv0)")
+      server: z4.string().regex(/^[\w-]+$/).optional().default("srv0").describe("Caddy server name (default: srv0)")
     },
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async ({ server: srv }) => {
@@ -352,12 +520,35 @@ function registerRouteTools(server) {
       const lines = [`Server: ${srv} (listen: ${listen.join(", ") || "default"})`, ""];
       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 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(",") || "..."}]`);
+          if (m.query) parts.push("query=...");
           if (m.header) parts.push("header=...");
+          if (m.expression) parts.push(`expr(${typeof m.expression === "string" ? m.expression : "..."})`);
+          if (m.not) parts.push("not(...)");
+          const known = /* @__PURE__ */ new Set([
+            "host",
+            "path",
+            "method",
+            "protocol",
+            "remote_ip",
+            "client_ip",
+            "query",
+            "header",
+            "expression",
+            "not"
+          ]);
+          for (const key of Object.keys(m)) {
+            if (!known.has(key)) parts.push(`${key}=...`);
+          }
           if (parts.length === 0) return "catch-all";
           return parts.join(" ");
         }).join(" | ");
@@ -368,11 +559,16 @@ function registerRouteTools(server) {
           }
           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 === "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";
         }).join(" \u2192 ");
-        lines.push(`  Route ${i}: ${matchers} \u2192 ${handlers}${route.terminal ? " [terminal]" : ""}`);
+        lines.push(`  Route ${i}:${id}${group} ${matchers} \u2192 ${handlers}${route.terminal ? " [terminal]" : ""}`);
       }
       return {
         content: [
@@ -386,10 +582,20 @@ function registerRouteTools(server) {
 
 // src/tools/tls.ts
 import { z as z5 } from "zod";
+function buildTlsConfig(fields) {
+  const issuer = { module: "acme" };
+  if (fields.email) issuer.email = fields.email;
+  if (fields.ca) issuer.ca = fields.ca;
+  return {
+    automation: {
+      policies: [{ issuers: [issuer] }]
+    }
+  };
+}
 function registerTlsTools(server) {
   server.tool(
     "caddy_tls",
-    "Get or configure TLS/HTTPS settings. Actions: 'status' shows current TLS config, 'set_email' sets the ACME email, 'set_acme_ca' sets the ACME CA URL.",
+    "Get or configure TLS/HTTPS settings. Actions: 'status' shows current TLS config, 'set_email' sets the ACME email, 'set_acme_ca' sets the ACME CA URL. Works on both fresh and existing Caddy instances.",
     {
       action: z5.enum(["status", "set_email", "set_acme_ca"]).describe("Action to perform"),
       email: z5.string().optional().describe("ACME email address (for 'set_email' action)"),
@@ -408,7 +614,9 @@ function registerTlsTools(server) {
           };
         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}` }] };
-        return formatResult(res);
+        const fallback = await configPost("apps/tls", buildTlsConfig({ email }));
+        if (fallback.ok) return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
+        return formatResult(fallback);
       }
       if (action === "set_acme_ca") {
         if (!ca)
@@ -418,7 +626,9 @@ function registerTlsTools(server) {
           };
         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}` }] };
-        return formatResult(res);
+        const fallback = await configPost("apps/tls", buildTlsConfig({ ca }));
+        if (fallback.ok) return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
+        return formatResult(fallback);
       }
       return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
     }
@@ -443,13 +653,6 @@ async function startServer() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
-var isDirectRun = process.argv[1]?.endsWith("server.js");
-if (isDirectRun) {
-  startServer().catch((err) => {
-    console.error("MCP server error:", err);
-    process.exit(1);
-  });
-}
 
 // src/index.ts
 startServer().catch((err) => {

package/dist/server.js

@@ -6,36 +6,62 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // src/api.ts
 var DEFAULT_URL = "http://localhost:2019";
 var TIMEOUT = 1e4;
+var etagCache = /* @__PURE__ */ new Map();
 function getBaseUrl() {
   return (process.env.CADDY_ADMIN_URL || DEFAULT_URL).replace(/\/+$/, "");
 }
-function getHeaders(contentType = "application/json") {
-  const headers = { "Content-Type": contentType };
+function getHeaders(contentType) {
+  const headers = {};
+  if (contentType) headers["Content-Type"] = contentType;
   const token = process.env.CADDY_API_TOKEN;
   if (token) headers.Authorization = `Bearer ${token}`;
   return headers;
 }
 function normalizePath(path) {
-  return path.replace(/^\/?(config\/?)?/, "");
+  return path.replace(/^\/?(config(\/|$))?/, "");
 }
-async function caddyRequest(method, path, body, contentType) {
+async function caddyRequest(method, path, body, contentType, timeout) {
   const url = `${getBaseUrl()}${path}`;
+  const effectiveTimeout = timeout ?? TIMEOUT;
   try {
+    const hasBody = body !== void 0;
+    const headers = getHeaders(hasBody ? contentType || "application/json" : void 0);
+    const isConfigPath = path.startsWith("/config/") || path.startsWith("/id/");
+    const isWrite = method !== "GET";
+    if (isWrite && isConfigPath) {
+      const cachedEtag = etagCache.get(path);
+      if (cachedEtag) headers["If-Match"] = cachedEtag;
+    }
     const res = await fetch(url, {
       method,
-      headers: getHeaders(contentType),
-      body: body !== void 0 ? typeof body === "string" ? body : JSON.stringify(body) : void 0,
-      signal: AbortSignal.timeout(TIMEOUT)
+      headers,
+      body: hasBody ? typeof body === "string" ? body : JSON.stringify(body) : void 0,
+      signal: AbortSignal.timeout(effectiveTimeout)
     });
     const text = await res.text();
+    const etag = res.headers.get("ETag") || void 0;
+    if (method === "GET" && etag && isConfigPath) {
+      etagCache.set(path, etag);
+    }
+    if (isWrite && res.ok && isConfigPath) {
+      etagCache.delete(path);
+    }
     if (!res.ok) {
+      if (res.status === 412) {
+        etagCache.delete(path);
+        return {
+          ok: false,
+          status: 412,
+          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) return { ok: true, status: res.status };
+    if (!text) return { ok: true, status: res.status, etag };
     try {
-      return { ok: true, status: res.status, data: JSON.parse(text) };
+      return { ok: true, status: res.status, data: JSON.parse(text), etag };
     } catch {
-      return { ok: true, status: res.status, data: text };
+      return { ok: true, status: res.status, data: text, etag };
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -47,7 +73,7 @@ async function caddyRequest(method, path, body, contentType) {
       };
     }
     if (msg.includes("abort") || msg.includes("timeout")) {
-      return { ok: false, status: 0, error: `Request timed out after ${TIMEOUT}ms` };
+      return { ok: false, status: 0, error: `Request timed out after ${effectiveTimeout}ms` };
     }
     return { ok: false, status: 0, error: msg };
   }
@@ -60,6 +86,10 @@ function configPost(path, value) {
   const normalized = normalizePath(path);
   return caddyRequest("POST", `/config/${normalized}`, value);
 }
+function configPut(path, value) {
+  const normalized = normalizePath(path);
+  return caddyRequest("PUT", `/config/${normalized}`, value);
+}
 function configPatch(path, value) {
   const normalized = normalizePath(path);
   return caddyRequest("PATCH", `/config/${normalized}`, value);
@@ -68,8 +98,11 @@ function configDelete(path) {
   const normalized = normalizePath(path);
   return caddyRequest("DELETE", `/config/${normalized}`);
 }
-function loadConfig(config) {
-  return caddyRequest("POST", "/load", config);
+var LOAD_TIMEOUT = 6e4;
+async function loadConfig(config, contentType) {
+  const res = await caddyRequest("POST", "/load", config, contentType, LOAD_TIMEOUT);
+  if (res.ok) etagCache.clear();
+  return res;
 }
 function adapt(config, adapter = "caddyfile") {
   return caddyRequest("POST", "/adapt", config, `text/${adapter}`);
@@ -86,6 +119,21 @@ function getPki(ca = "local") {
 function getPkiCertificates(ca = "local") {
   return caddyRequest("GET", `/pki/ca/${ca}/certificates`);
 }
+function configByIdGet(id, subpath = "") {
+  const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
+  return caddyRequest("GET", path);
+}
+function configByIdSet(id, value, method = "PATCH", subpath = "") {
+  const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
+  return caddyRequest(method, path, value);
+}
+function configByIdDelete(id, subpath = "") {
+  const path = subpath ? `/id/${id}/${subpath}` : `/id/${id}`;
+  return caddyRequest("DELETE", path);
+}
+function getMetrics() {
+  return caddyRequest("GET", "/metrics");
+}
 
 // src/resources.ts
 function registerResources(server) {
@@ -131,7 +179,8 @@ function formatResult(res) {
       content: [{ type: "text", text: `Error: ${res.error || `HTTP ${res.status}`}` }]
     };
   }
-  const text = res.data !== void 0 ? typeof res.data === "string" ? res.data : JSON.stringify(res.data, null, 2) : "OK";
+  const raw = res.data !== void 0 ? typeof res.data === "string" ? res.data : JSON.stringify(res.data, null, 2) : "";
+  const text = raw || "OK";
   return { content: [{ type: "text", text }] };
 }
 
@@ -139,13 +188,31 @@ function formatResult(res) {
 function registerAdaptTools(server) {
   server.tool(
     "caddy_adapt",
-    "Convert a Caddyfile or other config format to Caddy JSON without loading it. Useful for previewing what a Caddyfile produces.",
+    "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')")
     },
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    async ({ config, adapter }) => formatResult(await adapt(config, adapter))
+    async ({ config, adapter }) => {
+      const res = await adapt(config, adapter);
+      if (!res.ok) return formatResult(res);
+      const warnings = res.data?.warnings || [];
+      const result = res.data?.result;
+      const content = [];
+      if (warnings.length > 0) {
+        const warnLines = warnings.map(
+          (w) => `  - ${w.directive || "unknown"}: ${w.message || JSON.stringify(w)}`
+        );
+        content.push({ type: "text", text: `Warnings:
+${warnLines.join("\n")}` });
+      }
+      content.push({
+        type: "text",
+        text: result !== void 0 ? JSON.stringify(result, null, 2) : "OK (no output)"
+      });
+      return { content };
+    }
   );
 }
 
@@ -161,15 +228,17 @@ function registerConfigTools(server) {
   );
   server.tool(
     "caddy_config_set",
-    "Create or replace config at a JSON path. Mode 'create' (default) appends to arrays or creates objects (POST). Mode 'replace' overwrites existing values (PATCH).",
+    "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.",
     {
       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(["create", "replace"]).optional().default("create").describe("'create' = POST (append), 'replace' = PATCH (overwrite)")
+      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)"
+      )
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     async ({ path, value, mode }) => {
-      const res = mode === "replace" ? await configPatch(path, value) : await configPost(path, value);
+      const res = mode === "overwrite" ? await configPatch(path, value) : mode === "insert" ? await configPut(path, value) : await configPost(path, value);
       return formatResult(res);
     }
   );
@@ -182,10 +251,49 @@ function registerConfigTools(server) {
   );
   server.tool(
     "caddy_load",
-    "Replace the entire Caddy configuration atomically. Accepts a full Caddy JSON config object. This is the safest way to make large config changes.",
-    { config: z2.record(z2.any()).describe("Full Caddy JSON configuration object") },
+    "Replace the entire Caddy configuration atomically. Accepts a JSON config object, or a Caddyfile string with format='caddyfile'. This is the safest way to make large config changes. Has a 60-second timeout to allow for TLS provisioning.",
+    {
+      config: z2.union([z2.record(z2.string(), z2.any()), z2.string()]).describe("Full config \u2014 JSON object or Caddyfile text string"),
+      format: z2.enum(["json", "caddyfile"]).optional().default("json").describe("Config format: 'json' (default) or 'caddyfile'")
+    },
     { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
-    async ({ config }) => formatResult(await loadConfig(config))
+    async ({ config, format }) => {
+      const contentType = format === "caddyfile" ? "text/caddyfile" : "application/json";
+      return formatResult(await loadConfig(config, contentType));
+    }
+  );
+  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.",
+    {
+      id: z2.string().regex(/^[\w-]+$/).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"),
+      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, mode }) => {
+      if (action === "get") {
+        return formatResult(await configByIdGet(id, subpath));
+      }
+      if (action === "set") {
+        if (value === void 0) {
+          return {
+            isError: true,
+            content: [{ type: "text", text: "Error: value is required for 'set' action" }]
+          };
+        }
+        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));
+      }
+      return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
+    }
   );
 }
 
@@ -212,7 +320,9 @@ function registerOperationalTools(server) {
           const srv = servers[name];
           const listen = srv.listen || [];
           const routes = srv.routes || [];
-          const tls = srv.tls_connection_policies ? "enabled" : "auto";
+          const hasExplicitTls = !!srv.tls_connection_policies;
+          const listensHttps = listen.some((l) => l.includes(":443"));
+          const tls = hasExplicitTls ? "enabled" : listensHttps ? "auto (HTTPS)" : "off (HTTP only)";
           lines.push(
             `Server "${name}": ${routes.length} route(s), listen: ${listen.join(", ") || "default"}, TLS: ${tls}`
           );
@@ -227,6 +337,35 @@ ACME email: ${email}`);
       return { content: [{ type: "text", text: lines.join("\n") }] };
     }
   );
+  server.tool(
+    "caddy_list_servers",
+    "List all configured HTTP servers with their names, listen addresses, route counts, and TLS status. Use this to discover server names before calling route tools.",
+    {},
+    { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async () => {
+      const res = await configGet("apps/http/servers");
+      if (!res.ok) return formatResult(res);
+      const servers = res.data || {};
+      const names = Object.keys(servers);
+      if (names.length === 0) {
+        return { content: [{ type: "text", text: "No HTTP servers configured" }] };
+      }
+      const lines = [];
+      for (const name of names) {
+        const srv = servers[name];
+        const listen = srv.listen || [];
+        const routes = srv.routes || [];
+        const hasExplicitTls = !!srv.tls_connection_policies;
+        const listensHttps = listen.some((l) => l.includes(":443"));
+        const tls = hasExplicitTls ? "enabled" : listensHttps ? "auto (HTTPS)" : "off (HTTP only)";
+        lines.push(`  ${name}: ${routes.length} route(s), listen: ${listen.join(", ") || "default"}, TLS: ${tls}`);
+      }
+      return {
+        content: [{ type: "text", text: `HTTP Servers:
+${lines.join("\n")}` }]
+      };
+    }
+  );
   server.tool(
     "caddy_upstreams",
     "Get the current health status of all reverse proxy upstreams. Shows address, active requests, and failure counts.",
@@ -238,7 +377,7 @@ ACME email: ${email}`);
     "caddy_pki",
     "Get PKI certificate authority info or the CA certificate chain.",
     {
-      ca: z3.string().optional().default("local").describe("CA ID (default: 'local')"),
+      ca: z3.string().regex(/^[\w-]+$/).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 },
@@ -247,6 +386,13 @@ ACME email: ${email}`);
       return formatResult(res);
     }
   );
+  server.tool(
+    "caddy_metrics",
+    "Get Prometheus metrics from Caddy. Shows request counts, durations, TLS handshake stats, active connections, and more.",
+    {},
+    { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async () => formatResult(await getMetrics())
+  );
   server.tool(
     "caddy_stop",
     "Gracefully shut down the Caddy server. Requires confirm=true to prevent accidental shutdown.",
@@ -267,18 +413,33 @@ ACME email: ${email}`);
 // src/tools/routes.ts
 import { z as z4 } from "zod";
 function parseFrom(from) {
+  const cleaned = from.replace(/^https?:\/\//, "");
   const match = {};
-  const slashIdx = from.indexOf("/");
+  const slashIdx = cleaned.indexOf("/");
   if (slashIdx > 0) {
-    match.host = [from.substring(0, slashIdx)];
-    match.path = [from.substring(slashIdx)];
-  } else if (from.startsWith("/")) {
-    match.path = [from];
+    match.host = [cleaned.substring(0, slashIdx)];
+    match.path = [cleaned.substring(slashIdx)];
+  } else if (cleaned.startsWith("/")) {
+    match.path = [cleaned];
   } else {
-    match.host = [from];
+    match.host = [cleaned];
   }
   return match;
 }
+function cleanUpstreamAddr(addr) {
+  return addr.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+}
+function serverNotFoundError(srv) {
+  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"] }`
+      }
+    ]
+  };
+}
 function registerRouteTools(server) {
   server.tool(
     "caddy_reverse_proxy",
@@ -286,24 +447,28 @@ 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().optional().default("srv0").describe("Caddy server name (default: srv0)")
+      server: z4.string().regex(/^[\w-]+$/).optional().default("srv0").describe("Caddy server name (default: srv0)")
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     async ({ from, to, server: srv }) => {
       const match = parseFrom(from);
+      const cleanedTo = to.map(cleanUpstreamAddr);
       const route = {
         match: [match],
         handle: [
           {
             handler: "reverse_proxy",
-            upstreams: to.map((addr) => ({ dial: addr }))
+            upstreams: cleanedTo.map((addr) => ({ dial: addr }))
           }
         ],
         terminal: true
       };
       const res = await configPost(`apps/http/servers/${srv}/routes`, route);
       if (res.ok) {
-        return { content: [{ type: "text", text: `Route added: ${from} \u2192 ${to.join(", ")}` }] };
+        return { content: [{ type: "text", text: `Route added: ${from} \u2192 ${cleanedTo.join(", ")}` }] };
+      }
+      if (!res.ok && res.error?.includes("key does not exist")) {
+        return serverNotFoundError(srv);
       }
       return formatResult(res);
     }
@@ -312,15 +477,18 @@ function registerRouteTools(server) {
     "caddy_add_route",
     "Add a route with full control over match conditions and handlers. Supports any Caddy handler (reverse_proxy, file_server, static_response, redirect, encode, headers, etc.).",
     {
-      match: z4.array(z4.record(z4.any())).describe("Array of match objects (e.g., [{ host: ['example.com'], path: ['/api/*'] }])"),
-      handle: z4.array(z4.record(z4.any())).describe("Array of handler objects (e.g., [{ handler: 'file_server', root: '/var/www' }])"),
-      server: z4.string().optional().default("srv0").describe("Caddy server name (default: srv0)"),
+      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)"),
       terminal: z4.boolean().optional().default(true).describe("Stop processing further routes after this one matches")
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     async ({ match, handle, server: srv, terminal }) => {
       const route = { match, handle, terminal };
       const res = await configPost(`apps/http/servers/${srv}/routes`, route);
+      if (!res.ok && res.error?.includes("key does not exist")) {
+        return serverNotFoundError(srv);
+      }
       return formatResult(res);
     }
   );
@@ -328,7 +496,7 @@ 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().optional().default("srv0").describe("Caddy server name (default: srv0)")
+      server: z4.string().regex(/^[\w-]+$/).optional().default("srv0").describe("Caddy server name (default: srv0)")
     },
     { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async ({ server: srv }) => {
@@ -350,12 +518,35 @@ function registerRouteTools(server) {
       const lines = [`Server: ${srv} (listen: ${listen.join(", ") || "default"})`, ""];
       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 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(",") || "..."}]`);
+          if (m.query) parts.push("query=...");
           if (m.header) parts.push("header=...");
+          if (m.expression) parts.push(`expr(${typeof m.expression === "string" ? m.expression : "..."})`);
+          if (m.not) parts.push("not(...)");
+          const known = /* @__PURE__ */ new Set([
+            "host",
+            "path",
+            "method",
+            "protocol",
+            "remote_ip",
+            "client_ip",
+            "query",
+            "header",
+            "expression",
+            "not"
+          ]);
+          for (const key of Object.keys(m)) {
+            if (!known.has(key)) parts.push(`${key}=...`);
+          }
           if (parts.length === 0) return "catch-all";
           return parts.join(" ");
         }).join(" | ");
@@ -366,11 +557,16 @@ function registerRouteTools(server) {
           }
           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 === "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";
         }).join(" \u2192 ");
-        lines.push(`  Route ${i}: ${matchers} \u2192 ${handlers}${route.terminal ? " [terminal]" : ""}`);
+        lines.push(`  Route ${i}:${id}${group} ${matchers} \u2192 ${handlers}${route.terminal ? " [terminal]" : ""}`);
       }
       return {
         content: [
@@ -384,10 +580,20 @@ function registerRouteTools(server) {
 
 // src/tools/tls.ts
 import { z as z5 } from "zod";
+function buildTlsConfig(fields) {
+  const issuer = { module: "acme" };
+  if (fields.email) issuer.email = fields.email;
+  if (fields.ca) issuer.ca = fields.ca;
+  return {
+    automation: {
+      policies: [{ issuers: [issuer] }]
+    }
+  };
+}
 function registerTlsTools(server) {
   server.tool(
     "caddy_tls",
-    "Get or configure TLS/HTTPS settings. Actions: 'status' shows current TLS config, 'set_email' sets the ACME email, 'set_acme_ca' sets the ACME CA URL.",
+    "Get or configure TLS/HTTPS settings. Actions: 'status' shows current TLS config, 'set_email' sets the ACME email, 'set_acme_ca' sets the ACME CA URL. Works on both fresh and existing Caddy instances.",
     {
       action: z5.enum(["status", "set_email", "set_acme_ca"]).describe("Action to perform"),
       email: z5.string().optional().describe("ACME email address (for 'set_email' action)"),
@@ -406,7 +612,9 @@ function registerTlsTools(server) {
           };
         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}` }] };
-        return formatResult(res);
+        const fallback = await configPost("apps/tls", buildTlsConfig({ email }));
+        if (fallback.ok) return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
+        return formatResult(fallback);
       }
       if (action === "set_acme_ca") {
         if (!ca)
@@ -416,7 +624,9 @@ function registerTlsTools(server) {
           };
         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}` }] };
-        return formatResult(res);
+        const fallback = await configPost("apps/tls", buildTlsConfig({ ca }));
+        if (fallback.ok) return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
+        return formatResult(fallback);
       }
       return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
     }
@@ -441,13 +651,6 @@ async function startServer() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
-var isDirectRun = process.argv[1]?.endsWith("server.js");
-if (isDirectRun) {
-  startServer().catch((err) => {
-    console.error("MCP server error:", err);
-    process.exit(1);
-  });
-}
 export {
   createCaddyServer,
   startServer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/caddy-mcp",
-  "version": "0.1.0",
+  "version": "0.2.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,18 +31,19 @@
     "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": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^3.24.4"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
-    "@types/node": "^25.5.2",
+    "@biomejs/biome": "^2.4.11",
+    "@types/node": "^25.6.0",
     "tsup": "^8.4.0",
-    "typescript": "^5.8.3",
-    "vitest": "^3.1.1"
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
   },
   "engines": {
     "node": ">=18"