@yawlabs/caddy-mcp 1.3.1 → 2.1.0

package/bin/caddy-mcp.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * Runtime launcher for @yawlabs/caddy-mcp.
+ *
+ * Prefers the oam runtime (https://oamjs.org) and falls back to the Node
+ * process already running this file.
+ *
+ * Unlike npmjs-mcp, this server is NOT a zero-dependency bundle -- dist/
+ * imports @modelcontextprotocol/sdk and zod from node_modules at runtime. That
+ * is fine on both paths: oam does npm resolution against an existing
+ * node_modules with CommonJS interop, and it was verified here before this
+ * launcher was written (`oam run dist/index.js -- --version` prints the same
+ * version Node does).
+ *
+ * WHY THE FALLBACK COSTS NOTHING
+ * npm has already started Node to run this launcher, so falling back is a
+ * plain `import()` of the server into THIS process: no extra spawn, no extra
+ * startup, byte-identical to invoking dist/index.js directly. Discovery is
+ * stat-only -- never a subprocess -- so the miss case stays sub-millisecond.
+ *
+ * WHAT THE OAM PATH COSTS
+ * Reaching oam through an npm `bin` means Node boots first and oam boots
+ * second, so the launcher is slower than either runtime alone. Measured on
+ * npmjs-mcp (windows-arm64, n=12 medians, spawn to first MCP initialize):
+ * oam 116ms, node 172ms, launcher 243ms. oam is the fastest runtime and the
+ * launcher is the slowest path -- it exists for `npx` convenience.
+ *
+ * For an MCP host config, point straight at oam and skip this file:
+ *   { "command": "oam", "args": ["run", "<abs>/dist/index.js"] }
+ *
+ * SELECTION
+ *   CADDY_MCP_RUNTIME=oam    require oam; fail loudly if it is missing
+ *   CADDY_MCP_RUNTIME=node   never use oam
+ *   CADDY_MCP_RUNTIME=auto   prefer oam, silently fall back (default)
+ *   OAM_BIN=/path/to/oam     explicit binary, checked before any discovery
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { constants, homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Two forms, deliberately. `import()` on Windows REJECTS a bare `C:\...` path
+// with ERR_UNSUPPORTED_ESM_URL_SCHEME (it reads `c:` as a protocol), so the
+// in-process fallback must use the file:// URL. spawn() needs a real path.
+const SERVER_URL = new URL("../dist/index.js", import.meta.url);
+const SERVER_ENTRY = fileURLToPath(SERVER_URL);
+const isWin = process.platform === "win32";
+const exe = isWin ? "oam.exe" : "oam";
+
+/** Locate an oam binary, or null. Every branch is a stat, never a subprocess. */
+function findOam() {
+  // 1. Explicit override wins and is never second-guessed.
+  const override = process.env.OAM_BIN;
+  if (override) return existsSync(override) ? override : null;
+
+  // 2. Installed locations, BEFORE PATH. Someone who develops oam itself
+  //    usually has oam/target/release on PATH, and a build directory is the
+  //    wrong thing for a user-facing launcher to bind to: cargo replaces the
+  //    binary underneath running processes, and the dev build is not the
+  //    release the user installed. Preferring the installed copy makes the
+  //    default path "what a normal user has", and OAM_BIN remains the way to
+  //    point deliberately at a dev build.
+  //
+  //    Both forms are checked on Windows: the installer defaults to
+  //    %LOCALAPPDATA%oamin there, but oam's docs name ~/.oam/bin first and
+  //    OAM_INSTALL_DIR can pick either, so checking one silently misses a real
+  //    install.
+  const installed = [join(homedir(), ".oam", "bin", exe)];
+  if (isWin) {
+    installed.unshift(join(process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "oam", "bin", exe));
+  }
+  for (const candidate of installed) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  // 3. PATH, resolved manually rather than by spawning `which`/`where`, which
+  //    would cost a subprocess on every launch just to decide whether to spawn.
+  const pathExt = isWin ? (process.env.PATHEXT ?? ".EXE").split(";").filter(Boolean) : [""];
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    for (const ext of isWin ? pathExt : [""]) {
+      const candidate = join(dir, isWin ? `oam${ext.toLowerCase()}` : "oam");
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+
+  return null;
+}
+
+/** Run the server in THIS process. The zero-overhead fallback. */
+async function runInProcess() {
+  // A server may gate its bootstrap on being the process ENTRY POINT --
+  // `import.meta.url === pathToFileURL(process.argv[1]).href` -- so that its own
+  // test file can import the module for unit tests without connecting a stdio
+  // transport. aws-mcp does exactly this. Importing the server here would leave
+  // argv[1] pointing at THIS launcher, the guard would read false, and the
+  // server would load but never serve: the MCP handshake just hangs.
+  //
+  // Point argv[1] at the server first, so the in-process path is
+  // indistinguishable from having executed the file directly. The spawn path
+  // needs no equivalent -- there argv[1] is already the server.
+  process.argv[1] = SERVER_ENTRY;
+  await import(SERVER_URL.href);
+}
+
+const mode = (process.env.CADDY_MCP_RUNTIME ?? "auto").toLowerCase();
+
+if (mode === "node") {
+  await runInProcess();
+} else {
+  const oam = findOam();
+
+  if (!oam) {
+    if (mode === "oam") {
+      // Explicitly demanded, so this is a real misconfiguration. writeSync
+      // because stderr is async for TTYs/pipes on Windows and process.exit
+      // truncates pending writes.
+      const { writeSync } = await import("node:fs");
+      writeSync(
+        2,
+        "caddy-mcp: CADDY_MCP_RUNTIME=oam but no oam binary was found.\n" +
+          "Install from https://oamjs.org, set OAM_BIN=/path/to/oam, or use CADDY_MCP_RUNTIME=node.\n",
+      );
+      process.exit(1);
+    }
+    await runInProcess();
+  } else {
+    // `--` separates oam's own flags from the script's argv, so `caddy-mcp
+    // --version` and any host-supplied flags survive the hop unchanged.
+    const child = spawn(oam, ["run", SERVER_ENTRY, "--", ...process.argv.slice(2)], {
+      // inherit keeps the SAME fds, so MCP's newline-delimited JSON framing on
+      // stdin/stdout is untouched and the host's stdin-close still reaches the
+      // server's shutdown path.
+      stdio: "inherit",
+      env: process.env,
+      windowsHide: true,
+    });
+
+    // If oam cannot be executed at all (deleted between the stat and the spawn,
+    // wrong arch, permission), fall back rather than failing the whole server.
+    // `spawned` prevents falling back AFTER the child started, which would
+    // double-start the server on the same stdio.
+    let spawned = false;
+    child.on("spawn", () => {
+      spawned = true;
+    });
+    child.on("error", (err) => {
+      if (spawned) return;
+      if (mode === "oam") {
+        process.stderr.write(`caddy-mcp: failed to launch oam (${err.message})\n`);
+        process.exit(1);
+      }
+      void runInProcess();
+    });
+
+    // Forward termination so the server's own shutdown path runs in the child
+    // rather than the child being orphaned. No-op on Windows, harmless to add.
+    for (const sig of ["SIGINT", "SIGTERM"]) {
+      process.on(sig, () => {
+        if (!child.killed) child.kill(sig);
+      });
+    }
+
+    child.on("exit", (code, signal) => {
+      // Mirror the child's fate: a signal death becomes 128+n so callers see a
+      // conventional shell exit status rather than a bare 0.
+      if (signal) {
+        process.exit(128 + (constants.signals[signal] ?? 15));
+      }
+      process.exit(code ?? 0);
+    });
+  }
+}

package/dist/api.d.ts

@@ -0,0 +1,22 @@
+export interface ApiResponse<T = any> {
+    ok: boolean;
+    status: number;
+    data?: T;
+    error?: string;
+    etag?: string;
+}
+export declare function configGet<T = any>(path?: string): Promise<ApiResponse<T>>;
+export declare function configPost<T = any>(path: string, value: unknown): Promise<ApiResponse<T>>;
+export declare function configPut<T = any>(path: string, value: unknown): Promise<ApiResponse<T>>;
+export declare function configPatch<T = any>(path: string, value: unknown): Promise<ApiResponse<T>>;
+export declare function configDelete<T = any>(path: string): Promise<ApiResponse<T>>;
+export declare function loadConfig(config: unknown, contentType?: string): Promise<ApiResponse>;
+export declare function adapt<T = any>(config: string, adapter?: string): Promise<ApiResponse<T>>;
+export declare function stop(): Promise<ApiResponse>;
+export declare function getUpstreams(): Promise<ApiResponse>;
+export declare function getPki(ca?: string): Promise<ApiResponse>;
+export declare function getPkiCertificates(ca?: string): Promise<ApiResponse>;
+export declare function configByIdGet<T = any>(id: string, subpath?: string): Promise<ApiResponse<T>>;
+export declare function configByIdSet<T = any>(id: string, value: unknown, method?: "POST" | "PATCH" | "PUT", subpath?: string): Promise<ApiResponse<T>>;
+export declare function configByIdDelete<T = any>(id: string, subpath?: string): Promise<ApiResponse<T>>;
+export declare function getMetrics(): Promise<ApiResponse>;

package/dist/format.d.ts

@@ -0,0 +1,15 @@
+import type { ApiResponse } from "./api.js";
+/** Convert an API response to MCP tool result format */
+export declare function formatResult(res: ApiResponse): {
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+} | {
+    isError?: undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -21,11 +21,15 @@ function setEtag(path, etag) {
   }
   etagCache.set(path, etag);
 }
+function isAncestorOf(ancestor, descendant) {
+  const base = ancestor.endsWith("/") ? ancestor.slice(0, -1) : ancestor;
+  return descendant.startsWith(`${base}/`);
+}
 function invalidateRelated(path) {
   etagCache.delete(path);
   for (const key of Array.from(etagCache.keys())) {
     if (key === path) continue;
-    if (path.startsWith(`${key}/`) || key.startsWith(`${path}/`)) {
+    if (isAncestorOf(key, path) || isAncestorOf(path, key)) {
       etagCache.delete(key);
     }
   }
@@ -54,11 +58,20 @@ function getMaxRetries() {
   }
   return Math.min(floored, RETRY_HARD_CAP);
 }
+function getAdminOrigin() {
+  try {
+    return new URL(getBaseUrl()).origin;
+  } catch {
+    return void 0;
+  }
+}
 function getHeaders(contentType) {
   const headers = {};
   if (contentType) headers["Content-Type"] = contentType;
   const token = process.env.CADDY_API_TOKEN;
   if (token) headers.Authorization = `Bearer ${token}`;
+  const origin = getAdminOrigin();
+  if (origin) headers.Origin = origin;
   return headers;
 }
 function normalizePath(path) {
@@ -83,7 +96,9 @@ function isTransientFailure(res) {
   if (res.status >= 500 && res.status <= 599) return true;
   return false;
 }
+var ARRAY_INDEX_TAIL_RE = /\/\d+$/;
 function isRetryableMethod(method, path) {
+  if (method === "PUT") return !ARRAY_INDEX_TAIL_RE.test(path);
   if (method !== "POST") return true;
   return !path.startsWith("/config/") && !path.startsWith("/id/");
 }
@@ -142,6 +157,13 @@ async function attemptRequest(method, path, body, contentType, timeout) {
         const hint = res.status === 401 || res.status === 403 ? " -- check CADDY_API_TOKEN" : "";
         return { ok: false, status: res.status, error: `HTTP ${res.status}${hint}` };
       }
+      if (res.status === 403 && /origin/i.test(text)) {
+        return {
+          ok: false,
+          status: 403,
+          error: `${text.trim()} -- Caddy's admin API rejected this client's Origin. Set CADDY_ADMIN_URL to the exact origin Caddy allows (default http://localhost:2019), or add this origin to the admin.origins list in Caddy's config.`
+        };
+      }
       return { ok: false, status: res.status, error: text };
     }
     if (!text) return { ok: true, status: res.status, etag };
@@ -289,7 +311,8 @@ function formatResult(res) {
 
 // src/tools/operational.ts
 var HTTPS_PORT_RE = /:443(?:\D|$)/;
-function describeServer(raw) {
+function describeServer(rawValue) {
+  const raw = rawValue !== null && typeof rawValue === "object" && !Array.isArray(rawValue) ? rawValue : {};
   const listen = Array.isArray(raw.listen) ? raw.listen : [];
   const routes = Array.isArray(raw.routes) ? raw.routes : [];
   const hasExplicitTls = !!raw.tls_connection_policies;
@@ -411,7 +434,7 @@ ${lines.join("\n")}` }]
   );
   server.tool(
     "caddy_metrics",
-    "Get Prometheus metrics from Caddy. Shows request counts, durations, TLS handshake stats, active connections, and more. Output can be megabytes on busy servers -- use `filter` to keep only metrics whose name contains a substring (e.g. 'http_requests' or 'tls'); HELP/TYPE comment lines for retained metrics are kept. Filter-mode drops blank lines and free-form '# comment' lines (including '# EOF'); only '# HELP'/'# TYPE' lines for matching metrics are kept. Use `max_lines` to cap the response (default 500); a trailing comment reports how many lines were dropped.",
+    "Get Prometheus metrics from Caddy. Shows request counts, durations, TLS handshake stats, active connections, and more. Output can be megabytes on busy servers -- use `filter` to keep only metrics whose name contains a substring (e.g. 'http_requests' or 'tls'); HELP/TYPE comment lines for retained metrics are kept. Filter-mode drops blank lines and free-form '# comment' lines, keeping only '# HELP'/'# TYPE' lines for matching metrics; the '# EOF' end-of-file marker is always preserved. Use `max_lines` to cap the response (default 500); a trailing comment reports how many lines were dropped.",
     {
       filter: z.string().optional().describe(
         "Substring to match against metric names. Keeps sample lines whose metric name contains this substring, plus their `# HELP` and `# TYPE` comment lines. Empty/absent = no filtering. Label values are NOT matched -- use a Prometheus-aware client for label filtering."
@@ -639,13 +662,25 @@ function registerConfigTools(server) {
   );
   server.tool(
     "caddy_load",
-    "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.",
+    "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. Requires confirm=true: this DISCARDS the entire running config, including servers and routes not present in the supplied config. The prior config is snapshotted first and can be restored with caddy_revert.",
     {
       config: z3.union([z3.record(z3.string(), z3.any()), z3.string()]).describe("Full config \u2014 JSON object or Caddyfile text string"),
-      format: z3.enum(["json", "caddyfile"]).optional().default("json").describe("Config format: 'json' (default) or 'caddyfile'")
+      format: z3.enum(["json", "caddyfile"]).optional().default("json").describe("Config format: 'json' (default) or 'caddyfile'"),
+      confirm: z3.boolean().optional().default(false).describe("Must be true to replace the running configuration (safety)")
     },
     { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
-    async ({ config, format }) => {
+    async ({ config, format, confirm }) => {
+      if (!confirm) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: "Refusing to replace the running configuration without confirm=true. caddy_load discards every server and route not present in the supplied config. Re-run with confirm:true to proceed (the prior config is snapshotted and restorable via caddy_revert)."
+            }
+          ]
+        };
+      }
       const contentType = format === "caddyfile" ? "text/caddyfile" : "application/json";
       const current = await configGet();
       const res = await loadConfig(config, contentType);
@@ -782,6 +817,23 @@ ${lines.join("\n")}` }] };
 
 // src/tools/routes.ts
 import { z as z4 } from "zod";
+var ROUTES_JSON_MAX_CHARS = 2e4;
+var ROUTES_SUMMARY_MAX = 500;
+function serializeRoutesCapped(routes) {
+  const parts = [];
+  let used = 2;
+  for (const route of routes) {
+    const entry = JSON.stringify(route, null, 2).split("\n").map((line) => `  ${line}`).join("\n");
+    const cost = entry.length + (parts.length > 0 ? 2 : 1);
+    if (parts.length > 0 && used + cost > ROUTES_JSON_MAX_CHARS) break;
+    parts.push(entry);
+    used += cost;
+  }
+  if (parts.length === 0) return { json: "[]", shown: 0 };
+  return { json: `[
+${parts.join(",\n")}
+]`, shown: parts.length };
+}
 function safeJoin(value) {
   if (!Array.isArray(value)) return "";
   return value.filter((v) => v !== null && v !== void 0).map(String).join(",");
@@ -794,6 +846,7 @@ function stripPort(host) {
   }
   const colonIdx = host.lastIndexOf(":");
   if (colonIdx === -1) return host;
+  if (host.indexOf(":") !== colonIdx) return host;
   const portCandidate = host.substring(colonIdx + 1);
   if (portCandidate.length === 0 || !/^\d+$/.test(portCandidate)) return host;
   return host.substring(0, colonIdx);
@@ -847,9 +900,9 @@ function serverNotFoundError(srv, op = "operation") {
 function registerRouteTools(server) {
   server.tool(
     "caddy_reverse_proxy",
-    "Add a reverse proxy route. The most common operation \u2014 just specify where traffic comes from and where it goes. Example: from='api.local' to=['localhost:3000']. When `id` is OMITTED the route is appended to the server's routes array \u2014 calling the tool twice with the same args produces TWO duplicate routes (non-idempotent). When `id` is SUPPLIED the route is written via PUT under that @id, so repeat calls REPLACE in place (idempotent). Strongly recommended: supply a stable `id` for any route managed from automation or production tooling. Note: @ids are config-global in Caddy (NOT route-scoped). If `id` collides with an @id used by a non-route object (TLS issuer, server, etc.) the call refuses with an error rather than clobbering it. Once an @id is registered to a route under one server, subsequent calls update that route in place regardless of the `server` argument.",
+    "Add a reverse proxy route. The most common operation \u2014 just specify where traffic comes from and where it goes. Example: from='api.local' to=['localhost:3000']. When `id` is OMITTED the route is appended to the server's routes array \u2014 calling the tool twice with the same args produces TWO duplicate routes (non-idempotent). When `id` is SUPPLIED the route is written via PATCH under that @id, so repeat calls REPLACE in place (idempotent). Strongly recommended: supply a stable `id` for any route managed from automation or production tooling. Note: @ids are config-global in Caddy (NOT route-scoped). If `id` collides with an @id used by a non-route object (TLS issuer, server, etc.) the call refuses with an error rather than clobbering it. Once an @id is registered to a route under one server, subsequent calls update that route in place regardless of the `server` argument.",
     {
-      from: z4.string().describe("Domain, path, or domain/path to match (e.g., 'api.local', '/api/*', 'app.local/ws')"),
+      from: z4.string().min(1).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-]{1,128}$/).optional().default("srv0").describe("Caddy server name (default: srv0)"),
       id: z4.string().regex(/^[\w-]{1,128}$/).optional().describe(
@@ -858,7 +911,18 @@ function registerRouteTools(server) {
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     async ({ from, to, server: srv, id }) => {
-      const match = parseFrom(from);
+      const match = parseFrom(from.trim());
+      if (match.host?.[0]?.trim() === "" || match.host === void 0 && match.path === void 0) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Error: "from" value ${JSON.stringify(from)} has no host or path to match on. Supply a domain ('api.local'), a path ('/api/*'), or both ('app.local/ws').`
+            }
+          ]
+        };
+      }
       const cleanedTo = to.map(cleanUpstreamAddr);
       const route = {
         match: [match],
@@ -885,7 +949,7 @@ function registerRouteTools(server) {
               ]
             };
           }
-          const putRes = await configByIdSet(id, route, "PUT");
+          const putRes = await configByIdSet(id, route, "PATCH");
           if (putRes.ok) {
             return {
               content: [
@@ -948,7 +1012,7 @@ function registerRouteTools(server) {
   );
   server.tool(
     "caddy_list_routes",
-    "List all routes on a Caddy HTTP server with a human-readable summary of matchers and handlers.",
+    "List all routes on a Caddy HTTP server with a human-readable summary of matchers and handlers, followed by the raw route JSON. Both halves are capped on large servers: the summary at 500 routes, the JSON at 20000 characters (truncated on whole-route boundaries, so it always parses). When either cap trims output, a note says how many routes were omitted -- read the rest with caddy_config_get at 'apps/http/servers/<server>/routes'.",
     {
       server: z4.string().regex(/^[\w-]{1,128}$/).optional().default("srv0").describe("Caddy server name (default: srv0)")
     },
@@ -971,7 +1035,8 @@ function registerRouteTools(server) {
         };
       }
       const lines = [`Server: ${srv} (listen: ${listenStr})`, ""];
-      for (let i = 0; i < routes.length; i++) {
+      const summarized = Math.min(routes.length, ROUTES_SUMMARY_MAX);
+      for (let i = 0; i < summarized; i++) {
         const rawRoute = routes[i];
         if (!rawRoute || typeof rawRoute !== "object") {
           lines.push(`  Route ${i}: <invalid>`);
@@ -1070,12 +1135,23 @@ function registerRouteTools(server) {
         const terminal = route.terminal === true ? " [terminal]" : "";
         lines.push(`  Route ${i}:${id}${group} ${matchers} \u2192 ${handlers}${terminal}`);
       }
-      return {
-        content: [
-          { type: "text", text: lines.join("\n") },
-          { type: "text", text: JSON.stringify(routes, null, 2) }
-        ]
-      };
+      if (summarized < routes.length) {
+        lines.push(
+          `  ... ${routes.length - summarized} more route(s) not shown (summary caps at ${ROUTES_SUMMARY_MAX}).`
+        );
+      }
+      const { json, shown } = serializeRoutesCapped(routes);
+      const content = [
+        { type: "text", text: lines.join("\n") },
+        { type: "text", text: json }
+      ];
+      if (shown < routes.length) {
+        content.push({
+          type: "text",
+          text: `[JSON block truncated: showing ${shown} of ${routes.length} routes to stay under ${ROUTES_JSON_MAX_CHARS} characters. Read the rest with caddy_config_get at path 'apps/http/servers/${srv}/routes', or one route at a time with caddy_config_by_id.]`
+        });
+      }
+      return { content };
     }
   );
   server.tool(

package/dist/resources.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerResources(server: McpServer): void;

package/dist/server.d.ts

@@ -1,7 +1,4 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-
-declare const version: string;
-declare function createCaddyServer(): McpServer;
-declare function startServer(): Promise<void>;
-
-export { createCaddyServer, startServer, version };
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const version: string;
+export declare function createCaddyServer(): McpServer;
+export declare function startServer(): Promise<void>;

package/dist/server.js

@@ -19,11 +19,15 @@ function setEtag(path, etag) {
   }
   etagCache.set(path, etag);
 }
+function isAncestorOf(ancestor, descendant) {
+  const base = ancestor.endsWith("/") ? ancestor.slice(0, -1) : ancestor;
+  return descendant.startsWith(`${base}/`);
+}
 function invalidateRelated(path) {
   etagCache.delete(path);
   for (const key of Array.from(etagCache.keys())) {
     if (key === path) continue;
-    if (path.startsWith(`${key}/`) || key.startsWith(`${path}/`)) {
+    if (isAncestorOf(key, path) || isAncestorOf(path, key)) {
       etagCache.delete(key);
     }
   }
@@ -52,11 +56,20 @@ function getMaxRetries() {
   }
   return Math.min(floored, RETRY_HARD_CAP);
 }
+function getAdminOrigin() {
+  try {
+    return new URL(getBaseUrl()).origin;
+  } catch {
+    return void 0;
+  }
+}
 function getHeaders(contentType) {
   const headers = {};
   if (contentType) headers["Content-Type"] = contentType;
   const token = process.env.CADDY_API_TOKEN;
   if (token) headers.Authorization = `Bearer ${token}`;
+  const origin = getAdminOrigin();
+  if (origin) headers.Origin = origin;
   return headers;
 }
 function normalizePath(path) {
@@ -81,7 +94,9 @@ function isTransientFailure(res) {
   if (res.status >= 500 && res.status <= 599) return true;
   return false;
 }
+var ARRAY_INDEX_TAIL_RE = /\/\d+$/;
 function isRetryableMethod(method, path) {
+  if (method === "PUT") return !ARRAY_INDEX_TAIL_RE.test(path);
   if (method !== "POST") return true;
   return !path.startsWith("/config/") && !path.startsWith("/id/");
 }
@@ -140,6 +155,13 @@ async function attemptRequest(method, path, body, contentType, timeout) {
         const hint = res.status === 401 || res.status === 403 ? " -- check CADDY_API_TOKEN" : "";
         return { ok: false, status: res.status, error: `HTTP ${res.status}${hint}` };
       }
+      if (res.status === 403 && /origin/i.test(text)) {
+        return {
+          ok: false,
+          status: 403,
+          error: `${text.trim()} -- Caddy's admin API rejected this client's Origin. Set CADDY_ADMIN_URL to the exact origin Caddy allows (default http://localhost:2019), or add this origin to the admin.origins list in Caddy's config.`
+        };
+      }
       return { ok: false, status: res.status, error: text };
     }
     if (!text) return { ok: true, status: res.status, etag };
@@ -287,7 +309,8 @@ function formatResult(res) {
 
 // src/tools/operational.ts
 var HTTPS_PORT_RE = /:443(?:\D|$)/;
-function describeServer(raw) {
+function describeServer(rawValue) {
+  const raw = rawValue !== null && typeof rawValue === "object" && !Array.isArray(rawValue) ? rawValue : {};
   const listen = Array.isArray(raw.listen) ? raw.listen : [];
   const routes = Array.isArray(raw.routes) ? raw.routes : [];
   const hasExplicitTls = !!raw.tls_connection_policies;
@@ -409,7 +432,7 @@ ${lines.join("\n")}` }]
   );
   server.tool(
     "caddy_metrics",
-    "Get Prometheus metrics from Caddy. Shows request counts, durations, TLS handshake stats, active connections, and more. Output can be megabytes on busy servers -- use `filter` to keep only metrics whose name contains a substring (e.g. 'http_requests' or 'tls'); HELP/TYPE comment lines for retained metrics are kept. Filter-mode drops blank lines and free-form '# comment' lines (including '# EOF'); only '# HELP'/'# TYPE' lines for matching metrics are kept. Use `max_lines` to cap the response (default 500); a trailing comment reports how many lines were dropped.",
+    "Get Prometheus metrics from Caddy. Shows request counts, durations, TLS handshake stats, active connections, and more. Output can be megabytes on busy servers -- use `filter` to keep only metrics whose name contains a substring (e.g. 'http_requests' or 'tls'); HELP/TYPE comment lines for retained metrics are kept. Filter-mode drops blank lines and free-form '# comment' lines, keeping only '# HELP'/'# TYPE' lines for matching metrics; the '# EOF' end-of-file marker is always preserved. Use `max_lines` to cap the response (default 500); a trailing comment reports how many lines were dropped.",
     {
       filter: z.string().optional().describe(
         "Substring to match against metric names. Keeps sample lines whose metric name contains this substring, plus their `# HELP` and `# TYPE` comment lines. Empty/absent = no filtering. Label values are NOT matched -- use a Prometheus-aware client for label filtering."
@@ -637,13 +660,25 @@ function registerConfigTools(server) {
   );
   server.tool(
     "caddy_load",
-    "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.",
+    "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. Requires confirm=true: this DISCARDS the entire running config, including servers and routes not present in the supplied config. The prior config is snapshotted first and can be restored with caddy_revert.",
     {
       config: z3.union([z3.record(z3.string(), z3.any()), z3.string()]).describe("Full config \u2014 JSON object or Caddyfile text string"),
-      format: z3.enum(["json", "caddyfile"]).optional().default("json").describe("Config format: 'json' (default) or 'caddyfile'")
+      format: z3.enum(["json", "caddyfile"]).optional().default("json").describe("Config format: 'json' (default) or 'caddyfile'"),
+      confirm: z3.boolean().optional().default(false).describe("Must be true to replace the running configuration (safety)")
     },
     { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
-    async ({ config, format }) => {
+    async ({ config, format, confirm }) => {
+      if (!confirm) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: "Refusing to replace the running configuration without confirm=true. caddy_load discards every server and route not present in the supplied config. Re-run with confirm:true to proceed (the prior config is snapshotted and restorable via caddy_revert)."
+            }
+          ]
+        };
+      }
       const contentType = format === "caddyfile" ? "text/caddyfile" : "application/json";
       const current = await configGet();
       const res = await loadConfig(config, contentType);
@@ -780,6 +815,23 @@ ${lines.join("\n")}` }] };
 
 // src/tools/routes.ts
 import { z as z4 } from "zod";
+var ROUTES_JSON_MAX_CHARS = 2e4;
+var ROUTES_SUMMARY_MAX = 500;
+function serializeRoutesCapped(routes) {
+  const parts = [];
+  let used = 2;
+  for (const route of routes) {
+    const entry = JSON.stringify(route, null, 2).split("\n").map((line) => `  ${line}`).join("\n");
+    const cost = entry.length + (parts.length > 0 ? 2 : 1);
+    if (parts.length > 0 && used + cost > ROUTES_JSON_MAX_CHARS) break;
+    parts.push(entry);
+    used += cost;
+  }
+  if (parts.length === 0) return { json: "[]", shown: 0 };
+  return { json: `[
+${parts.join(",\n")}
+]`, shown: parts.length };
+}
 function safeJoin(value) {
   if (!Array.isArray(value)) return "";
   return value.filter((v) => v !== null && v !== void 0).map(String).join(",");
@@ -792,6 +844,7 @@ function stripPort(host) {
   }
   const colonIdx = host.lastIndexOf(":");
   if (colonIdx === -1) return host;
+  if (host.indexOf(":") !== colonIdx) return host;
   const portCandidate = host.substring(colonIdx + 1);
   if (portCandidate.length === 0 || !/^\d+$/.test(portCandidate)) return host;
   return host.substring(0, colonIdx);
@@ -845,9 +898,9 @@ function serverNotFoundError(srv, op = "operation") {
 function registerRouteTools(server) {
   server.tool(
     "caddy_reverse_proxy",
-    "Add a reverse proxy route. The most common operation \u2014 just specify where traffic comes from and where it goes. Example: from='api.local' to=['localhost:3000']. When `id` is OMITTED the route is appended to the server's routes array \u2014 calling the tool twice with the same args produces TWO duplicate routes (non-idempotent). When `id` is SUPPLIED the route is written via PUT under that @id, so repeat calls REPLACE in place (idempotent). Strongly recommended: supply a stable `id` for any route managed from automation or production tooling. Note: @ids are config-global in Caddy (NOT route-scoped). If `id` collides with an @id used by a non-route object (TLS issuer, server, etc.) the call refuses with an error rather than clobbering it. Once an @id is registered to a route under one server, subsequent calls update that route in place regardless of the `server` argument.",
+    "Add a reverse proxy route. The most common operation \u2014 just specify where traffic comes from and where it goes. Example: from='api.local' to=['localhost:3000']. When `id` is OMITTED the route is appended to the server's routes array \u2014 calling the tool twice with the same args produces TWO duplicate routes (non-idempotent). When `id` is SUPPLIED the route is written via PATCH under that @id, so repeat calls REPLACE in place (idempotent). Strongly recommended: supply a stable `id` for any route managed from automation or production tooling. Note: @ids are config-global in Caddy (NOT route-scoped). If `id` collides with an @id used by a non-route object (TLS issuer, server, etc.) the call refuses with an error rather than clobbering it. Once an @id is registered to a route under one server, subsequent calls update that route in place regardless of the `server` argument.",
     {
-      from: z4.string().describe("Domain, path, or domain/path to match (e.g., 'api.local', '/api/*', 'app.local/ws')"),
+      from: z4.string().min(1).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-]{1,128}$/).optional().default("srv0").describe("Caddy server name (default: srv0)"),
       id: z4.string().regex(/^[\w-]{1,128}$/).optional().describe(
@@ -856,7 +909,18 @@ function registerRouteTools(server) {
     },
     { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     async ({ from, to, server: srv, id }) => {
-      const match = parseFrom(from);
+      const match = parseFrom(from.trim());
+      if (match.host?.[0]?.trim() === "" || match.host === void 0 && match.path === void 0) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Error: "from" value ${JSON.stringify(from)} has no host or path to match on. Supply a domain ('api.local'), a path ('/api/*'), or both ('app.local/ws').`
+            }
+          ]
+        };
+      }
       const cleanedTo = to.map(cleanUpstreamAddr);
       const route = {
         match: [match],
@@ -883,7 +947,7 @@ function registerRouteTools(server) {
               ]
             };
           }
-          const putRes = await configByIdSet(id, route, "PUT");
+          const putRes = await configByIdSet(id, route, "PATCH");
           if (putRes.ok) {
             return {
               content: [
@@ -946,7 +1010,7 @@ function registerRouteTools(server) {
   );
   server.tool(
     "caddy_list_routes",
-    "List all routes on a Caddy HTTP server with a human-readable summary of matchers and handlers.",
+    "List all routes on a Caddy HTTP server with a human-readable summary of matchers and handlers, followed by the raw route JSON. Both halves are capped on large servers: the summary at 500 routes, the JSON at 20000 characters (truncated on whole-route boundaries, so it always parses). When either cap trims output, a note says how many routes were omitted -- read the rest with caddy_config_get at 'apps/http/servers/<server>/routes'.",
     {
       server: z4.string().regex(/^[\w-]{1,128}$/).optional().default("srv0").describe("Caddy server name (default: srv0)")
     },
@@ -969,7 +1033,8 @@ function registerRouteTools(server) {
         };
       }
       const lines = [`Server: ${srv} (listen: ${listenStr})`, ""];
-      for (let i = 0; i < routes.length; i++) {
+      const summarized = Math.min(routes.length, ROUTES_SUMMARY_MAX);
+      for (let i = 0; i < summarized; i++) {
         const rawRoute = routes[i];
         if (!rawRoute || typeof rawRoute !== "object") {
           lines.push(`  Route ${i}: <invalid>`);
@@ -1068,12 +1133,23 @@ function registerRouteTools(server) {
         const terminal = route.terminal === true ? " [terminal]" : "";
         lines.push(`  Route ${i}:${id}${group} ${matchers} \u2192 ${handlers}${terminal}`);
       }
-      return {
-        content: [
-          { type: "text", text: lines.join("\n") },
-          { type: "text", text: JSON.stringify(routes, null, 2) }
-        ]
-      };
+      if (summarized < routes.length) {
+        lines.push(
+          `  ... ${routes.length - summarized} more route(s) not shown (summary caps at ${ROUTES_SUMMARY_MAX}).`
+        );
+      }
+      const { json, shown } = serializeRoutesCapped(routes);
+      const content = [
+        { type: "text", text: lines.join("\n") },
+        { type: "text", text: json }
+      ];
+      if (shown < routes.length) {
+        content.push({
+          type: "text",
+          text: `[JSON block truncated: showing ${shown} of ${routes.length} routes to stay under ${ROUTES_JSON_MAX_CHARS} characters. Read the rest with caddy_config_get at path 'apps/http/servers/${srv}/routes', or one route at a time with caddy_config_by_id.]`
+        });
+      }
+      return { content };
     }
   );
   server.tool(

package/dist/snapshots.d.ts

@@ -0,0 +1,9 @@
+export interface Snapshot {
+    config: unknown;
+    timestamp: number;
+    trigger: string;
+}
+export declare function saveSnapshot(config: unknown, trigger: string): void;
+export declare function listSnapshots(): readonly Snapshot[];
+export declare function getSnapshot(index: number): Snapshot | undefined;
+export declare function clearSnapshots(): void;

package/dist/tools/adapt.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAdaptTools(server: McpServer): void;

package/dist/tools/config.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerConfigTools(server: McpServer): void;

package/dist/tools/operational.d.ts

@@ -0,0 +1,19 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/** Default max_lines for caddy_metrics. Prometheus output on busy servers can be megabytes; 500 lines is enough to skim. */
+export declare const METRICS_DEFAULT_MAX_LINES = 500;
+/**
+ * Apply the optional substring filter and max_lines truncation to raw Prometheus exposition text.
+ *
+ * Filter rule: a line is kept if the metric name on that line contains the filter substring.
+ * Both `# HELP` / `# TYPE` comment lines and sample lines are matched on their metric name, so any
+ * retained metric keeps its descriptive comments alongside its samples. Lines with no parseable
+ * metric name (blank lines, free-form `#` comments) are dropped when filtering.
+ *
+ * Truncation: if the resulting line count exceeds `maxLines`, output is cut at `maxLines` and a
+ * trailing `# [truncated, N lines omitted -- use filter to narrow]` comment is appended. If the
+ * input contained a `# EOF` end-of-file marker that would have been dropped by the cut, it is
+ * re-appended after the truncation comment so strict downstream parsers still see a terminated
+ * stream.
+ */
+export declare function applyMetricsControls(raw: string, filter: string | undefined, maxLines: number): string;
+export declare function registerOperationalTools(server: McpServer): void;

package/dist/tools/routes.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/** Parse a "from" string like "api.example.com" or "example.com/api/*" into match object */
+export declare function parseFrom(from: string): {
+    host?: string[];
+    path?: string[];
+};
+export declare function registerRouteTools(server: McpServer): void;

package/dist/tools/tls.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerTlsTools(server: McpServer): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/caddy-mcp",
-  "version": "1.3.1",
+  "version": "2.1.0",
   "mcpName": "io.github.YawLabs/caddy-mcp",
   "description": "MCP server for managing Caddy web servers via the admin API",
   "license": "MIT",
@@ -15,21 +15,23 @@
   "main": "./dist/server.js",
   "types": "./dist/server.d.ts",
   "bin": {
-    "caddy-mcp": "dist/index.js"
+    "caddy-mcp": "bin/caddy-mcp.mjs"
   },
   "files": [
+    "bin/caddy-mcp.mjs",
     "dist",
     "!dist/**/*.test.*",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsc -p tsconfig.build.json",
     "dev": "tsup --watch",
     "test": "vitest run",
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "node scripts/typecheck.mjs",
+    "typecheck:tsc": "tsc --noEmit",
     "test:ci": "npm run build && npm test",
     "prepublishOnly": "npm run build",
     "prepare": "git config core.hooksPath .githooks 2>/dev/null || true",
@@ -49,7 +51,7 @@
     "esbuild": "^0.28.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.11",
+    "@biomejs/biome": "~2.4.11",
     "@types/node": "^26.0.0",
     "postject": "^1.0.0-alpha.6",
     "tsup": "^8.4.0",