@yawlabs/caddy-mcp 1.1.0 → 1.2.0

package/README.md

@@ -107,14 +107,14 @@ Use the same JSON block shown above in any of these.
 
 ### Route operations (4)
 
-- **caddy_reverse_proxy** — Add a reverse proxy in one call: `from='api.local' to=['localhost:3000']`.
+- **caddy_reverse_proxy** — Add a reverse proxy in one call: `from='api.local' to=['localhost:3000']`. Pass an optional `id` for idempotent writes — repeat calls replace the route in place instead of duplicating.
 - **caddy_add_route** — Add a route with full match/handle control (any Caddy handler).
 - **caddy_remove_route** — Remove a route by `@id` (preferred) or by index. Requires `confirm=true`.
 - **caddy_list_routes** — Human-readable route summary. Defensive: never crashes on weird config.
 
 ### TLS & config conversion (2)
 
-- **caddy_tls** — Check or set TLS settings: ACME email, ACME CA URL. Falls back gracefully when paths don't yet exist.
+- **caddy_tls** — Check or set TLS settings: ACME email, ACME CA URL. PATCH first; on a fresh install, POSTs a minimal config. On an existing config it deep-merges into the issuer path and PUTs the result back, preserving siblings (custom certs, `on_demand`, additional policies). Refuses with a shape-specific error if the existing structure is unexpected — never clobbers.
 - **caddy_adapt** — Convert a Caddyfile (or nginx config) to Caddy JSON without applying it. Great for previewing.
 
 ### Server operations (6)
@@ -122,7 +122,7 @@ Use the same JSON block shown above in any of these.
 - **caddy_status** — Connectivity check + config summary (server count, routes, TLS mode).
 - **caddy_list_servers** — List all HTTP servers with names, addresses, route counts, and TLS status.
 - **caddy_upstreams** — Reverse proxy backend health.
-- **caddy_metrics** — Prometheus metrics (request counts, durations, connections, TLS handshakes).
+- **caddy_metrics** — Prometheus metrics (request counts, durations, connections, TLS handshakes). Optional `filter` (substring match on metric name, keeps `# HELP` / `# TYPE` lines for retained metrics) and `max_lines` (default 500) keep responses compact on busy servers.
 - **caddy_pki** — CA info and certificate chains (default CA: `local`).
 - **caddy_stop** — Graceful shutdown. Requires `confirm=true` to prevent accidents.
 
@@ -144,6 +144,26 @@ Browsable read-only data — MCP clients can fetch these directly without a tool
 → caddy_reverse_proxy({ from: "api.example.com", to: ["localhost:3000"] })
 ```
 
+### Idempotent reverse proxy (safe to re-run from automation)
+
+```
+> "Make sure api.example.com points at localhost:3000, with a stable id"
+→ caddy_reverse_proxy({ from: "api.example.com", to: ["localhost:3000"], id: "api-prod" })
+  # First call creates the route under @id="api-prod".
+  # Subsequent calls with the same id REPLACE in place — no duplicate routes.
+  # Refuses with a clear error if "api-prod" is already in use by a non-route
+  # config object (TLS issuer, server, etc.) — @ids are config-global in Caddy.
+```
+
+### Filter Prometheus metrics
+
+```
+> "Just the HTTP request metrics, please"
+→ caddy_metrics({ filter: "http_requests" })
+  # Keeps sample lines whose metric name contains "http_requests",
+  # plus their `# HELP` / `# TYPE` lines. Drops the rest.
+```
+
 ### Preview a Caddyfile before applying it
 
 ```
@@ -213,7 +233,7 @@ npm install
 npm run lint       # Biome check
 npm run lint:fix   # Auto-fix
 npm run build      # tsup bundle
-npm test           # Vitest (106 unit tests; +7 live-Caddy integration tests gated by CADDY_MCP_INTEGRATION=1)
+npm test           # Vitest (150 unit tests; +8 live-Caddy integration tests gated by CADDY_MCP_INTEGRATION=1)
 npm run typecheck  # tsc --noEmit
 ```
 

package/dist/index.js

@@ -175,9 +175,17 @@ function configDelete(path) {
   if (bad) return Promise.resolve(bad);
   return caddyRequest("DELETE", `/config/${normalized}`);
 }
-var LOAD_TIMEOUT = 6e4;
+function getLoadTimeout() {
+  const raw = process.env.CADDY_LOAD_TIMEOUT;
+  if (raw === void 0) return 6e4;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return 6e4;
+  const floored = Math.floor(n);
+  if (floored < 1) return 6e4;
+  return floored;
+}
 async function loadConfig(config, contentType) {
-  const res = await caddyRequest("POST", "/load", config, contentType, LOAD_TIMEOUT);
+  const res = await caddyRequest("POST", "/load", config, contentType, getLoadTimeout());
   if (res.ok) etagCache.clear();
   return res;
 }
@@ -369,6 +377,9 @@ function getSnapshot(index) {
 }
 
 // src/tools/config.ts
+function isSnapshotableConfig(data) {
+  return data !== null && typeof data === "object" && !Array.isArray(data);
+}
 function registerConfigTools(server) {
   server.tool(
     "caddy_config_get",
@@ -411,7 +422,7 @@ function registerConfigTools(server) {
     async ({ config, format }) => {
       const contentType = format === "caddyfile" ? "text/caddyfile" : "application/json";
       const current = await configGet();
-      if (current.ok && current.data !== void 0) {
+      if (current.ok && isSnapshotableConfig(current.data)) {
         saveSnapshot(current.data, "caddy_load");
       }
       return formatResult(await loadConfig(config, contentType));
@@ -443,10 +454,15 @@ ${lines.join("\n")}` }] };
       if (action === "save") {
         const current2 = await configGet();
         if (!current2.ok) return formatResult(current2);
-        if (current2.data === void 0) {
+        if (!isSnapshotableConfig(current2.data)) {
           return {
             isError: true,
-            content: [{ type: "text", text: "Error: no config loaded to snapshot" }]
+            content: [
+              {
+                type: "text",
+                text: "Error: cannot snapshot -- config response is empty or not a JSON object"
+              }
+            ]
           };
         }
         saveSnapshot(current2.data, "manual");
@@ -476,11 +492,11 @@ ${lines.join("\n")}` }] };
         };
       }
       const current = await configGet();
-      if (current.ok && current.data !== void 0) {
-        saveSnapshot(current.data, "caddy_revert");
-      }
       const res = await loadConfig(snap.config, "application/json");
       if (!res.ok) return formatResult(res);
+      if (current.ok && isSnapshotableConfig(current.data)) {
+        saveSnapshot(current.data, "caddy_revert");
+      }
       const when = new Date(snap.timestamp).toISOString();
       return {
         content: [
@@ -552,6 +568,7 @@ function applyMetricsControls(raw, filter, maxLines) {
   let filtered;
   if (filter && filter.length > 0) {
     filtered = lines.filter((line) => {
+      if (line.trim() === "# EOF") return true;
       const name = metricNameFromLine(line);
       return name?.includes(filter) ?? false;
     });
@@ -565,18 +582,15 @@ function applyMetricsControls(raw, filter, maxLines) {
   return kept.join("\n");
 }
 function findAcmeEmail(policies) {
-  if (!Array.isArray(policies)) return void 0;
-  for (const rawPolicy of policies) {
-    if (!rawPolicy || typeof rawPolicy !== "object") continue;
-    const policy = rawPolicy;
-    if (!Array.isArray(policy.issuers)) continue;
-    for (const rawIssuer of policy.issuers) {
-      if (!rawIssuer || typeof rawIssuer !== "object") continue;
-      const issuer = rawIssuer;
-      if (typeof issuer.email === "string") return issuer.email;
-    }
-  }
-  return void 0;
+  if (!Array.isArray(policies) || policies.length === 0) return void 0;
+  const rawPolicy = policies[0];
+  if (!rawPolicy || typeof rawPolicy !== "object" || Array.isArray(rawPolicy)) return void 0;
+  const policy = rawPolicy;
+  if (!Array.isArray(policy.issuers) || policy.issuers.length === 0) return void 0;
+  const rawIssuer = policy.issuers[0];
+  if (!rawIssuer || typeof rawIssuer !== "object" || Array.isArray(rawIssuer)) return void 0;
+  const issuer = rawIssuer;
+  return typeof issuer.email === "string" ? issuer.email : void 0;
 }
 function registerOperationalTools(server) {
   server.tool(
@@ -649,7 +663,7 @@ ${lines.join("\n")}` }]
     "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.",
     {
       filter: z3.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."
+        "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."
       ),
       max_lines: z3.number().int().positive().optional().describe("Maximum number of output lines (default 500). Excess lines are dropped and a summary is appended.")
     },

package/dist/server.js

@@ -173,9 +173,17 @@ function configDelete(path) {
   if (bad) return Promise.resolve(bad);
   return caddyRequest("DELETE", `/config/${normalized}`);
 }
-var LOAD_TIMEOUT = 6e4;
+function getLoadTimeout() {
+  const raw = process.env.CADDY_LOAD_TIMEOUT;
+  if (raw === void 0) return 6e4;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return 6e4;
+  const floored = Math.floor(n);
+  if (floored < 1) return 6e4;
+  return floored;
+}
 async function loadConfig(config, contentType) {
-  const res = await caddyRequest("POST", "/load", config, contentType, LOAD_TIMEOUT);
+  const res = await caddyRequest("POST", "/load", config, contentType, getLoadTimeout());
   if (res.ok) etagCache.clear();
   return res;
 }
@@ -367,6 +375,9 @@ function getSnapshot(index) {
 }
 
 // src/tools/config.ts
+function isSnapshotableConfig(data) {
+  return data !== null && typeof data === "object" && !Array.isArray(data);
+}
 function registerConfigTools(server) {
   server.tool(
     "caddy_config_get",
@@ -409,7 +420,7 @@ function registerConfigTools(server) {
     async ({ config, format }) => {
       const contentType = format === "caddyfile" ? "text/caddyfile" : "application/json";
       const current = await configGet();
-      if (current.ok && current.data !== void 0) {
+      if (current.ok && isSnapshotableConfig(current.data)) {
         saveSnapshot(current.data, "caddy_load");
       }
       return formatResult(await loadConfig(config, contentType));
@@ -441,10 +452,15 @@ ${lines.join("\n")}` }] };
       if (action === "save") {
         const current2 = await configGet();
         if (!current2.ok) return formatResult(current2);
-        if (current2.data === void 0) {
+        if (!isSnapshotableConfig(current2.data)) {
           return {
             isError: true,
-            content: [{ type: "text", text: "Error: no config loaded to snapshot" }]
+            content: [
+              {
+                type: "text",
+                text: "Error: cannot snapshot -- config response is empty or not a JSON object"
+              }
+            ]
           };
         }
         saveSnapshot(current2.data, "manual");
@@ -474,11 +490,11 @@ ${lines.join("\n")}` }] };
         };
       }
       const current = await configGet();
-      if (current.ok && current.data !== void 0) {
-        saveSnapshot(current.data, "caddy_revert");
-      }
       const res = await loadConfig(snap.config, "application/json");
       if (!res.ok) return formatResult(res);
+      if (current.ok && isSnapshotableConfig(current.data)) {
+        saveSnapshot(current.data, "caddy_revert");
+      }
       const when = new Date(snap.timestamp).toISOString();
       return {
         content: [
@@ -550,6 +566,7 @@ function applyMetricsControls(raw, filter, maxLines) {
   let filtered;
   if (filter && filter.length > 0) {
     filtered = lines.filter((line) => {
+      if (line.trim() === "# EOF") return true;
       const name = metricNameFromLine(line);
       return name?.includes(filter) ?? false;
     });
@@ -563,18 +580,15 @@ function applyMetricsControls(raw, filter, maxLines) {
   return kept.join("\n");
 }
 function findAcmeEmail(policies) {
-  if (!Array.isArray(policies)) return void 0;
-  for (const rawPolicy of policies) {
-    if (!rawPolicy || typeof rawPolicy !== "object") continue;
-    const policy = rawPolicy;
-    if (!Array.isArray(policy.issuers)) continue;
-    for (const rawIssuer of policy.issuers) {
-      if (!rawIssuer || typeof rawIssuer !== "object") continue;
-      const issuer = rawIssuer;
-      if (typeof issuer.email === "string") return issuer.email;
-    }
-  }
-  return void 0;
+  if (!Array.isArray(policies) || policies.length === 0) return void 0;
+  const rawPolicy = policies[0];
+  if (!rawPolicy || typeof rawPolicy !== "object" || Array.isArray(rawPolicy)) return void 0;
+  const policy = rawPolicy;
+  if (!Array.isArray(policy.issuers) || policy.issuers.length === 0) return void 0;
+  const rawIssuer = policy.issuers[0];
+  if (!rawIssuer || typeof rawIssuer !== "object" || Array.isArray(rawIssuer)) return void 0;
+  const issuer = rawIssuer;
+  return typeof issuer.email === "string" ? issuer.email : void 0;
 }
 function registerOperationalTools(server) {
   server.tool(
@@ -647,7 +661,7 @@ ${lines.join("\n")}` }]
     "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.",
     {
       filter: z3.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."
+        "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."
       ),
       max_lines: z3.number().int().positive().optional().describe("Maximum number of output lines (default 500). Excess lines are dropped and a summary is appended.")
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/caddy-mcp",
-  "version": "1.1.0",
+  "version": "1.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)",
@@ -41,7 +41,8 @@
   "overrides": {
     "hono": "^4.12.14",
     "@hono/node-server": "^1.19.13",
-    "postcss": "^8.5.10"
+    "postcss": "^8.5.10",
+    "ip-address": "^10.1.1"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",