@yawlabs/caddy-mcp 1.3.1 → 2.0.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.0.0",
   "mcpName": "io.github.YawLabs/caddy-mcp",
   "description": "MCP server for managing Caddy web servers via the admin API",
   "license": "MIT",
@@ -24,12 +24,13 @@
     "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 +50,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",