@yawlabs/caddy-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yaw Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# @yawlabs/caddy-mcp
+
+[![npm version](https://img.shields.io/npm/v/@yawlabs/caddy-mcp)](https://www.npmjs.com/package/@yawlabs/caddy-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**MCP server for managing Caddy web servers.** 13 tools for config management, reverse proxy setup, route operations, TLS, and server monitoring — all via Caddy's admin API.
+
+Built and maintained by [Yaw Labs](https://yaw.sh).
+
+## Quick start
+
+```bash
+npx @yawlabs/caddy-mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g @yawlabs/caddy-mcp
+caddy-mcp
+```
+
+## MCP client configuration
+
+### Claude Code
+
+```bash
+claude mcp add caddy-mcp npx @yawlabs/caddy-mcp
+```
+
+### Claude Desktop / Cursor / Windsurf
+
+Add to your MCP config file:
+
+```json
+{
+  "mcpServers": {
+    "caddy-mcp": {
+      "command": "npx",
+      "args": ["@yawlabs/caddy-mcp"],
+      "env": {
+        "CADDY_ADMIN_URL": "http://localhost:2019"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---|---|---|
+| `CADDY_ADMIN_URL` | `http://localhost:2019` | Caddy admin API URL |
+| `CADDY_API_TOKEN` | (none) | Optional Bearer token for authenticated admin endpoints |
+
+## Tools
+
+### Config management
+
+- **caddy_config_get** — Read config at any JSON path (or full config)
+- **caddy_config_set** — Create or replace config at a path
+- **caddy_config_delete** — Delete config at a path
+- **caddy_load** — Replace entire config atomically
+
+### Route operations
+
+- **caddy_reverse_proxy** — Add a reverse proxy in one call: `from='api.local' to=['localhost:3000']`
+- **caddy_add_route** — Add a route with full match/handle control (any Caddy handler)
+- **caddy_list_routes** — Human-readable route summary
+
+### TLS & config conversion
+
+- **caddy_tls** — Check/configure TLS settings, ACME email, CA
+- **caddy_adapt** — Convert Caddyfile to JSON (preview before applying)
+
+### Server operations
+
+- **caddy_status** — Connectivity check + config summary
+- **caddy_upstreams** — Reverse proxy backend health
+- **caddy_pki** — CA info and certificate chains
+- **caddy_stop** — Graceful shutdown (requires confirmation)
+
+## Resources
+
+- `caddy://config` — Current Caddy JSON configuration
+- `caddy://upstreams` — Reverse proxy upstream health status
+
+## Examples
+
+```
+> "Proxy api.local to my dev server on port 3000"
+→ caddy_reverse_proxy(from: "api.local", to: ["localhost:3000"])
+
+> "What routes are configured?"
+→ caddy_list_routes()
+
+> "Show me the full Caddy config"
+→ caddy_config_get()
+
+> "Convert this Caddyfile to JSON"
+→ caddy_adapt(config: "example.com {\n  reverse_proxy localhost:8080\n}")
+
+> "Is Caddy running?"
+→ caddy_status()
+```
+
+## Requirements
+
+- Node.js 18+
+- Caddy server with admin API enabled (default: `localhost:2019`)
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,458 @@
+#!/usr/bin/env node
+
+// src/server.ts
+import { createRequire } from "module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/api.ts
+var DEFAULT_URL = "http://localhost:2019";
+var TIMEOUT = 1e4;
+function getBaseUrl() {
+  return (process.env.CADDY_ADMIN_URL || DEFAULT_URL).replace(/\/+$/, "");
+}
+function getHeaders(contentType = "application/json") {
+  const headers = { "Content-Type": contentType };
+  const token = process.env.CADDY_API_TOKEN;
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return headers;
+}
+function normalizePath(path) {
+  return path.replace(/^\/?(config\/?)?/, "");
+}
+async function caddyRequest(method, path, body, contentType) {
+  const url = `${getBaseUrl()}${path}`;
+  try {
+    const res = await fetch(url, {
+      method,
+      headers: getHeaders(contentType),
+      body: body !== void 0 ? typeof body === "string" ? body : JSON.stringify(body) : void 0,
+      signal: AbortSignal.timeout(TIMEOUT)
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      return { ok: false, status: res.status, error: text || `HTTP ${res.status}` };
+    }
+    if (!text) return { ok: true, status: res.status };
+    try {
+      return { ok: true, status: res.status, data: JSON.parse(text) };
+    } catch {
+      return { ok: true, status: res.status, data: text };
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+      return {
+        ok: false,
+        status: 0,
+        error: `Cannot connect to Caddy admin API at ${getBaseUrl()} \u2014 is Caddy running?`
+      };
+    }
+    if (msg.includes("abort") || msg.includes("timeout")) {
+      return { ok: false, status: 0, error: `Request timed out after ${TIMEOUT}ms` };
+    }
+    return { ok: false, status: 0, error: msg };
+  }
+}
+function configGet(path = "") {
+  const normalized = normalizePath(path);
+  return caddyRequest("GET", `/config/${normalized}`);
+}
+function configPost(path, value) {
+  const normalized = normalizePath(path);
+  return caddyRequest("POST", `/config/${normalized}`, value);
+}
+function configPatch(path, value) {
+  const normalized = normalizePath(path);
+  return caddyRequest("PATCH", `/config/${normalized}`, value);
+}
+function configDelete(path) {
+  const normalized = normalizePath(path);
+  return caddyRequest("DELETE", `/config/${normalized}`);
+}
+function loadConfig(config) {
+  return caddyRequest("POST", "/load", config);
+}
+function adapt(config, adapter = "caddyfile") {
+  return caddyRequest("POST", "/adapt", config, `text/${adapter}`);
+}
+function stop() {
+  return caddyRequest("POST", "/stop");
+}
+function getUpstreams() {
+  return caddyRequest("GET", "/reverse_proxy/upstreams");
+}
+function getPki(ca = "local") {
+  return caddyRequest("GET", `/pki/ca/${ca}`);
+}
+function getPkiCertificates(ca = "local") {
+  return caddyRequest("GET", `/pki/ca/${ca}/certificates`);
+}
+
+// src/resources.ts
+function registerResources(server) {
+  server.resource("caddy-config", "caddy://config", { description: "Current Caddy JSON configuration" }, async () => {
+    const res = await configGet();
+    return {
+      contents: [
+        {
+          uri: "caddy://config",
+          mimeType: "application/json",
+          text: res.ok ? JSON.stringify(res.data, null, 2) : `Error: ${res.error}`
+        }
+      ]
+    };
+  });
+  server.resource(
+    "caddy-upstreams",
+    "caddy://upstreams",
+    { description: "Reverse proxy upstream health status" },
+    async () => {
+      const res = await getUpstreams();
+      return {
+        contents: [
+          {
+            uri: "caddy://upstreams",
+            mimeType: "application/json",
+            text: res.ok ? JSON.stringify(res.data, null, 2) : `Error: ${res.error}`
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/adapt.ts
+import { z } from "zod";
+
+// src/format.ts
+function formatResult(res) {
+  if (!res.ok) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: `Error: ${res.error || `HTTP ${res.status}`}` }]
+    };
+  }
+  const text = res.data !== void 0 ? typeof res.data === "string" ? res.data : JSON.stringify(res.data, null, 2) : "OK";
+  return { content: [{ type: "text", text }] };
+}
+
+// src/tools/adapt.ts
+function registerAdaptTools(server) {
+  server.tool(
+    "caddy_adapt",
+    "Convert a Caddyfile or other config format to Caddy JSON without loading it. Useful for previewing what a Caddyfile produces.",
+    {
+      config: z.string().describe("The raw config text (e.g., Caddyfile contents)"),
+      adapter: z.string().optional().default("caddyfile").describe("Config format adapter (default: 'caddyfile')")
+    },
+    { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async ({ config, adapter }) => formatResult(await adapt(config, adapter))
+  );
+}
+
+// src/tools/config.ts
+import { z as z2 } from "zod";
+function registerConfigTools(server) {
+  server.tool(
+    "caddy_config_get",
+    "Read Caddy config at any JSON path. Returns the full config when path is empty, or a subtree at a specific path (e.g., 'apps/http/servers/srv0/routes').",
+    { path: z2.string().optional().default("").describe("Config path (e.g., 'apps/http/servers/srv0')") },
+    { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async ({ path }) => formatResult(await configGet(path))
+  );
+  server.tool(
+    "caddy_config_set",
+    "Create or replace config at a JSON path. Mode 'create' (default) appends to arrays or creates objects (POST). Mode 'replace' overwrites existing values (PATCH).",
+    {
+      path: z2.string().describe("Config path to write to (e.g., 'apps/http/servers/srv0/routes')"),
+      value: z2.any().describe("The JSON value to set at the path"),
+      mode: z2.enum(["create", "replace"]).optional().default("create").describe("'create' = POST (append), 'replace' = PATCH (overwrite)")
+    },
+    { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    async ({ path, value, mode }) => {
+      const res = mode === "replace" ? await configPatch(path, value) : await configPost(path, value);
+      return formatResult(res);
+    }
+  );
+  server.tool(
+    "caddy_config_delete",
+    "Delete config at a JSON path. Removes the config node at the specified path.",
+    { path: z2.string().describe("Config path to delete (e.g., 'apps/http/servers/srv0/routes/0')") },
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    async ({ path }) => formatResult(await configDelete(path))
+  );
+  server.tool(
+    "caddy_load",
+    "Replace the entire Caddy configuration atomically. Accepts a full Caddy JSON config object. This is the safest way to make large config changes.",
+    { config: z2.record(z2.any()).describe("Full Caddy JSON configuration object") },
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    async ({ config }) => formatResult(await loadConfig(config))
+  );
+}
+
+// src/tools/operational.ts
+import { z as z3 } from "zod";
+function registerOperationalTools(server) {
+  server.tool(
+    "caddy_status",
+    "Check Caddy connectivity and get a config summary: servers, routes, listen addresses, and TLS status.",
+    {},
+    { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async () => {
+      const res = await configGet();
+      if (!res.ok) return formatResult(res);
+      const config = res.data || {};
+      const httpApp = config?.apps?.http;
+      const servers = httpApp?.servers || {};
+      const serverNames = Object.keys(servers);
+      const lines = ["Caddy is running", ""];
+      if (serverNames.length === 0) {
+        lines.push("No HTTP servers configured");
+      } else {
+        for (const name of serverNames) {
+          const srv = servers[name];
+          const listen = srv.listen || [];
+          const routes = srv.routes || [];
+          const tls = srv.tls_connection_policies ? "enabled" : "auto";
+          lines.push(
+            `Server "${name}": ${routes.length} route(s), listen: ${listen.join(", ") || "default"}, TLS: ${tls}`
+          );
+        }
+      }
+      const tlsApp = config?.apps?.tls;
+      if (tlsApp?.automation?.policies) {
+        const email = tlsApp.automation.policies.find((p) => p.issuers)?.issuers?.[0]?.email;
+        if (email) lines.push(`
+ACME email: ${email}`);
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+  server.tool(
+    "caddy_upstreams",
+    "Get the current health status of all reverse proxy upstreams. Shows address, active requests, and failure counts.",
+    {},
+    { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async () => formatResult(await getUpstreams())
+  );
+  server.tool(
+    "caddy_pki",
+    "Get PKI certificate authority info or the CA certificate chain.",
+    {
+      ca: z3.string().optional().default("local").describe("CA ID (default: 'local')"),
+      certificates: z3.boolean().optional().default(false).describe("If true, return the full CA certificate chain")
+    },
+    { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async ({ ca, certificates }) => {
+      const res = certificates ? await getPkiCertificates(ca) : await getPki(ca);
+      return formatResult(res);
+    }
+  );
+  server.tool(
+    "caddy_stop",
+    "Gracefully shut down the Caddy server. Requires confirm=true to prevent accidental shutdown.",
+    { confirm: z3.boolean().describe("Must be true to confirm shutdown") },
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    async ({ confirm }) => {
+      if (!confirm) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: "Error: confirm must be true to shut down Caddy" }]
+        };
+      }
+      return formatResult(await stop());
+    }
+  );
+}
+
+// src/tools/routes.ts
+import { z as z4 } from "zod";
+function parseFrom(from) {
+  const match = {};
+  const slashIdx = from.indexOf("/");
+  if (slashIdx > 0) {
+    match.host = [from.substring(0, slashIdx)];
+    match.path = [from.substring(slashIdx)];
+  } else if (from.startsWith("/")) {
+    match.path = [from];
+  } else {
+    match.host = [from];
+  }
+  return match;
+}
+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'].",
+    {
+      from: z4.string().describe("Domain, path, or domain/path to match (e.g., 'api.local', '/api/*', 'app.local/ws')"),
+      to: z4.array(z4.string()).describe("Upstream addresses (e.g., ['localhost:3000', 'localhost:3001'])"),
+      server: z4.string().optional().default("srv0").describe("Caddy server name (default: srv0)")
+    },
+    { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    async ({ from, to, server: srv }) => {
+      const match = parseFrom(from);
+      const route = {
+        match: [match],
+        handle: [
+          {
+            handler: "reverse_proxy",
+            upstreams: to.map((addr) => ({ dial: addr }))
+          }
+        ],
+        terminal: true
+      };
+      const res = await configPost(`apps/http/servers/${srv}/routes`, route);
+      if (res.ok) {
+        return { content: [{ type: "text", text: `Route added: ${from} \u2192 ${to.join(", ")}` }] };
+      }
+      return formatResult(res);
+    }
+  );
+  server.tool(
+    "caddy_add_route",
+    "Add a route with full control over match conditions and handlers. Supports any Caddy handler (reverse_proxy, file_server, static_response, redirect, encode, headers, etc.).",
+    {
+      match: z4.array(z4.record(z4.any())).describe("Array of match objects (e.g., [{ host: ['example.com'], path: ['/api/*'] }])"),
+      handle: z4.array(z4.record(z4.any())).describe("Array of handler objects (e.g., [{ handler: 'file_server', root: '/var/www' }])"),
+      server: z4.string().optional().default("srv0").describe("Caddy server name (default: srv0)"),
+      terminal: z4.boolean().optional().default(true).describe("Stop processing further routes after this one matches")
+    },
+    { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    async ({ match, handle, server: srv, terminal }) => {
+      const route = { match, handle, terminal };
+      const res = await configPost(`apps/http/servers/${srv}/routes`, route);
+      return formatResult(res);
+    }
+  );
+  server.tool(
+    "caddy_list_routes",
+    "List all routes on a Caddy HTTP server with a human-readable summary of matchers and handlers.",
+    {
+      server: z4.string().optional().default("srv0").describe("Caddy server name (default: srv0)")
+    },
+    { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async ({ server: srv }) => {
+      const serverRes = await configGet(`apps/http/servers/${srv}`);
+      if (!serverRes.ok) return formatResult(serverRes);
+      const serverConfig = serverRes.data;
+      const routes = serverConfig?.routes || [];
+      const listen = serverConfig?.listen || [];
+      if (routes.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Server ${srv} (listen: ${listen.join(", ") || "default"}) \u2014 no routes configured`
+            }
+          ]
+        };
+      }
+      const lines = [`Server: ${srv} (listen: ${listen.join(", ") || "default"})`, ""];
+      for (let i = 0; i < routes.length; i++) {
+        const route = routes[i];
+        const matchers = (route.match || []).map((m) => {
+          const parts = [];
+          if (m.host) parts.push(`host=[${m.host.join(",")}]`);
+          if (m.path) parts.push(`path=[${m.path.join(",")}]`);
+          if (m.method) parts.push(`method=[${m.method.join(",")}]`);
+          if (m.header) parts.push("header=...");
+          if (parts.length === 0) return "catch-all";
+          return parts.join(" ");
+        }).join(" | ");
+        const handlers = (route.handle || []).map((h) => {
+          if (h.handler === "reverse_proxy") {
+            const upstreams = (h.upstreams || []).map((u) => u.dial).join(",");
+            return `reverse_proxy(${upstreams})`;
+          }
+          if (h.handler === "file_server") return `file_server(${h.root || "."})`;
+          if (h.handler === "static_response") return `static_response(${h.status_code || 200})`;
+          if (h.handler === "encode") return "encode";
+          if (h.handler === "headers") return "headers";
+          return h.handler || "unknown";
+        }).join(" \u2192 ");
+        lines.push(`  Route ${i}: ${matchers} \u2192 ${handlers}${route.terminal ? " [terminal]" : ""}`);
+      }
+      return {
+        content: [
+          { type: "text", text: lines.join("\n") },
+          { type: "text", text: JSON.stringify(routes, null, 2) }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/tls.ts
+import { z as z5 } from "zod";
+function registerTlsTools(server) {
+  server.tool(
+    "caddy_tls",
+    "Get or configure TLS/HTTPS settings. Actions: 'status' shows current TLS config, 'set_email' sets the ACME email, 'set_acme_ca' sets the ACME CA URL.",
+    {
+      action: z5.enum(["status", "set_email", "set_acme_ca"]).describe("Action to perform"),
+      email: z5.string().optional().describe("ACME email address (for 'set_email' action)"),
+      ca: z5.string().optional().describe("ACME CA URL (for 'set_acme_ca' action)")
+    },
+    { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async ({ action, email, ca }) => {
+      if (action === "status") {
+        return formatResult(await configGet("apps/tls"));
+      }
+      if (action === "set_email") {
+        if (!email)
+          return {
+            isError: true,
+            content: [{ type: "text", text: "Error: email is required for set_email action" }]
+          };
+        const res = await configPatch("apps/tls/automation/policies/0/issuers/0/email", email);
+        if (res.ok) return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
+        return formatResult(res);
+      }
+      if (action === "set_acme_ca") {
+        if (!ca)
+          return {
+            isError: true,
+            content: [{ type: "text", text: "Error: ca is required for set_acme_ca action" }]
+          };
+        const res = await configPatch("apps/tls/automation/policies/0/issuers/0/ca", ca);
+        if (res.ok) return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
+        return formatResult(res);
+      }
+      return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
+    }
+  );
+}
+
+// src/server.ts
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
+function createCaddyServer() {
+  const server = new McpServer({ name: "caddy-mcp", version });
+  registerConfigTools(server);
+  registerRouteTools(server);
+  registerAdaptTools(server);
+  registerTlsTools(server);
+  registerOperationalTools(server);
+  registerResources(server);
+  return server;
+}
+async function startServer() {
+  const server = createCaddyServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+var isDirectRun = process.argv[1]?.endsWith("server.js");
+if (isDirectRun) {
+  startServer().catch((err) => {
+    console.error("MCP server error:", err);
+    process.exit(1);
+  });
+}
+
+// src/index.ts
+startServer().catch((err) => {
+  console.error("caddy-mcp error:", err);
+  process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,6 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+declare function createCaddyServer(): McpServer;
+declare function startServer(): Promise<void>;
+
+export { createCaddyServer, startServer };

package/dist/server.js

@@ -0,0 +1,454 @@
+// src/server.ts
+import { createRequire } from "module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/api.ts
+var DEFAULT_URL = "http://localhost:2019";
+var TIMEOUT = 1e4;
+function getBaseUrl() {
+  return (process.env.CADDY_ADMIN_URL || DEFAULT_URL).replace(/\/+$/, "");
+}
+function getHeaders(contentType = "application/json") {
+  const headers = { "Content-Type": contentType };
+  const token = process.env.CADDY_API_TOKEN;
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return headers;
+}
+function normalizePath(path) {
+  return path.replace(/^\/?(config\/?)?/, "");
+}
+async function caddyRequest(method, path, body, contentType) {
+  const url = `${getBaseUrl()}${path}`;
+  try {
+    const res = await fetch(url, {
+      method,
+      headers: getHeaders(contentType),
+      body: body !== void 0 ? typeof body === "string" ? body : JSON.stringify(body) : void 0,
+      signal: AbortSignal.timeout(TIMEOUT)
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      return { ok: false, status: res.status, error: text || `HTTP ${res.status}` };
+    }
+    if (!text) return { ok: true, status: res.status };
+    try {
+      return { ok: true, status: res.status, data: JSON.parse(text) };
+    } catch {
+      return { ok: true, status: res.status, data: text };
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+      return {
+        ok: false,
+        status: 0,
+        error: `Cannot connect to Caddy admin API at ${getBaseUrl()} \u2014 is Caddy running?`
+      };
+    }
+    if (msg.includes("abort") || msg.includes("timeout")) {
+      return { ok: false, status: 0, error: `Request timed out after ${TIMEOUT}ms` };
+    }
+    return { ok: false, status: 0, error: msg };
+  }
+}
+function configGet(path = "") {
+  const normalized = normalizePath(path);
+  return caddyRequest("GET", `/config/${normalized}`);
+}
+function configPost(path, value) {
+  const normalized = normalizePath(path);
+  return caddyRequest("POST", `/config/${normalized}`, value);
+}
+function configPatch(path, value) {
+  const normalized = normalizePath(path);
+  return caddyRequest("PATCH", `/config/${normalized}`, value);
+}
+function configDelete(path) {
+  const normalized = normalizePath(path);
+  return caddyRequest("DELETE", `/config/${normalized}`);
+}
+function loadConfig(config) {
+  return caddyRequest("POST", "/load", config);
+}
+function adapt(config, adapter = "caddyfile") {
+  return caddyRequest("POST", "/adapt", config, `text/${adapter}`);
+}
+function stop() {
+  return caddyRequest("POST", "/stop");
+}
+function getUpstreams() {
+  return caddyRequest("GET", "/reverse_proxy/upstreams");
+}
+function getPki(ca = "local") {
+  return caddyRequest("GET", `/pki/ca/${ca}`);
+}
+function getPkiCertificates(ca = "local") {
+  return caddyRequest("GET", `/pki/ca/${ca}/certificates`);
+}
+
+// src/resources.ts
+function registerResources(server) {
+  server.resource("caddy-config", "caddy://config", { description: "Current Caddy JSON configuration" }, async () => {
+    const res = await configGet();
+    return {
+      contents: [
+        {
+          uri: "caddy://config",
+          mimeType: "application/json",
+          text: res.ok ? JSON.stringify(res.data, null, 2) : `Error: ${res.error}`
+        }
+      ]
+    };
+  });
+  server.resource(
+    "caddy-upstreams",
+    "caddy://upstreams",
+    { description: "Reverse proxy upstream health status" },
+    async () => {
+      const res = await getUpstreams();
+      return {
+        contents: [
+          {
+            uri: "caddy://upstreams",
+            mimeType: "application/json",
+            text: res.ok ? JSON.stringify(res.data, null, 2) : `Error: ${res.error}`
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/adapt.ts
+import { z } from "zod";
+
+// src/format.ts
+function formatResult(res) {
+  if (!res.ok) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: `Error: ${res.error || `HTTP ${res.status}`}` }]
+    };
+  }
+  const text = res.data !== void 0 ? typeof res.data === "string" ? res.data : JSON.stringify(res.data, null, 2) : "OK";
+  return { content: [{ type: "text", text }] };
+}
+
+// src/tools/adapt.ts
+function registerAdaptTools(server) {
+  server.tool(
+    "caddy_adapt",
+    "Convert a Caddyfile or other config format to Caddy JSON without loading it. Useful for previewing what a Caddyfile produces.",
+    {
+      config: z.string().describe("The raw config text (e.g., Caddyfile contents)"),
+      adapter: z.string().optional().default("caddyfile").describe("Config format adapter (default: 'caddyfile')")
+    },
+    { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async ({ config, adapter }) => formatResult(await adapt(config, adapter))
+  );
+}
+
+// src/tools/config.ts
+import { z as z2 } from "zod";
+function registerConfigTools(server) {
+  server.tool(
+    "caddy_config_get",
+    "Read Caddy config at any JSON path. Returns the full config when path is empty, or a subtree at a specific path (e.g., 'apps/http/servers/srv0/routes').",
+    { path: z2.string().optional().default("").describe("Config path (e.g., 'apps/http/servers/srv0')") },
+    { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async ({ path }) => formatResult(await configGet(path))
+  );
+  server.tool(
+    "caddy_config_set",
+    "Create or replace config at a JSON path. Mode 'create' (default) appends to arrays or creates objects (POST). Mode 'replace' overwrites existing values (PATCH).",
+    {
+      path: z2.string().describe("Config path to write to (e.g., 'apps/http/servers/srv0/routes')"),
+      value: z2.any().describe("The JSON value to set at the path"),
+      mode: z2.enum(["create", "replace"]).optional().default("create").describe("'create' = POST (append), 'replace' = PATCH (overwrite)")
+    },
+    { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    async ({ path, value, mode }) => {
+      const res = mode === "replace" ? await configPatch(path, value) : await configPost(path, value);
+      return formatResult(res);
+    }
+  );
+  server.tool(
+    "caddy_config_delete",
+    "Delete config at a JSON path. Removes the config node at the specified path.",
+    { path: z2.string().describe("Config path to delete (e.g., 'apps/http/servers/srv0/routes/0')") },
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    async ({ path }) => formatResult(await configDelete(path))
+  );
+  server.tool(
+    "caddy_load",
+    "Replace the entire Caddy configuration atomically. Accepts a full Caddy JSON config object. This is the safest way to make large config changes.",
+    { config: z2.record(z2.any()).describe("Full Caddy JSON configuration object") },
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    async ({ config }) => formatResult(await loadConfig(config))
+  );
+}
+
+// src/tools/operational.ts
+import { z as z3 } from "zod";
+function registerOperationalTools(server) {
+  server.tool(
+    "caddy_status",
+    "Check Caddy connectivity and get a config summary: servers, routes, listen addresses, and TLS status.",
+    {},
+    { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async () => {
+      const res = await configGet();
+      if (!res.ok) return formatResult(res);
+      const config = res.data || {};
+      const httpApp = config?.apps?.http;
+      const servers = httpApp?.servers || {};
+      const serverNames = Object.keys(servers);
+      const lines = ["Caddy is running", ""];
+      if (serverNames.length === 0) {
+        lines.push("No HTTP servers configured");
+      } else {
+        for (const name of serverNames) {
+          const srv = servers[name];
+          const listen = srv.listen || [];
+          const routes = srv.routes || [];
+          const tls = srv.tls_connection_policies ? "enabled" : "auto";
+          lines.push(
+            `Server "${name}": ${routes.length} route(s), listen: ${listen.join(", ") || "default"}, TLS: ${tls}`
+          );
+        }
+      }
+      const tlsApp = config?.apps?.tls;
+      if (tlsApp?.automation?.policies) {
+        const email = tlsApp.automation.policies.find((p) => p.issuers)?.issuers?.[0]?.email;
+        if (email) lines.push(`
+ACME email: ${email}`);
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+  server.tool(
+    "caddy_upstreams",
+    "Get the current health status of all reverse proxy upstreams. Shows address, active requests, and failure counts.",
+    {},
+    { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async () => formatResult(await getUpstreams())
+  );
+  server.tool(
+    "caddy_pki",
+    "Get PKI certificate authority info or the CA certificate chain.",
+    {
+      ca: z3.string().optional().default("local").describe("CA ID (default: 'local')"),
+      certificates: z3.boolean().optional().default(false).describe("If true, return the full CA certificate chain")
+    },
+    { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async ({ ca, certificates }) => {
+      const res = certificates ? await getPkiCertificates(ca) : await getPki(ca);
+      return formatResult(res);
+    }
+  );
+  server.tool(
+    "caddy_stop",
+    "Gracefully shut down the Caddy server. Requires confirm=true to prevent accidental shutdown.",
+    { confirm: z3.boolean().describe("Must be true to confirm shutdown") },
+    { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    async ({ confirm }) => {
+      if (!confirm) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: "Error: confirm must be true to shut down Caddy" }]
+        };
+      }
+      return formatResult(await stop());
+    }
+  );
+}
+
+// src/tools/routes.ts
+import { z as z4 } from "zod";
+function parseFrom(from) {
+  const match = {};
+  const slashIdx = from.indexOf("/");
+  if (slashIdx > 0) {
+    match.host = [from.substring(0, slashIdx)];
+    match.path = [from.substring(slashIdx)];
+  } else if (from.startsWith("/")) {
+    match.path = [from];
+  } else {
+    match.host = [from];
+  }
+  return match;
+}
+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'].",
+    {
+      from: z4.string().describe("Domain, path, or domain/path to match (e.g., 'api.local', '/api/*', 'app.local/ws')"),
+      to: z4.array(z4.string()).describe("Upstream addresses (e.g., ['localhost:3000', 'localhost:3001'])"),
+      server: z4.string().optional().default("srv0").describe("Caddy server name (default: srv0)")
+    },
+    { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    async ({ from, to, server: srv }) => {
+      const match = parseFrom(from);
+      const route = {
+        match: [match],
+        handle: [
+          {
+            handler: "reverse_proxy",
+            upstreams: to.map((addr) => ({ dial: addr }))
+          }
+        ],
+        terminal: true
+      };
+      const res = await configPost(`apps/http/servers/${srv}/routes`, route);
+      if (res.ok) {
+        return { content: [{ type: "text", text: `Route added: ${from} \u2192 ${to.join(", ")}` }] };
+      }
+      return formatResult(res);
+    }
+  );
+  server.tool(
+    "caddy_add_route",
+    "Add a route with full control over match conditions and handlers. Supports any Caddy handler (reverse_proxy, file_server, static_response, redirect, encode, headers, etc.).",
+    {
+      match: z4.array(z4.record(z4.any())).describe("Array of match objects (e.g., [{ host: ['example.com'], path: ['/api/*'] }])"),
+      handle: z4.array(z4.record(z4.any())).describe("Array of handler objects (e.g., [{ handler: 'file_server', root: '/var/www' }])"),
+      server: z4.string().optional().default("srv0").describe("Caddy server name (default: srv0)"),
+      terminal: z4.boolean().optional().default(true).describe("Stop processing further routes after this one matches")
+    },
+    { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    async ({ match, handle, server: srv, terminal }) => {
+      const route = { match, handle, terminal };
+      const res = await configPost(`apps/http/servers/${srv}/routes`, route);
+      return formatResult(res);
+    }
+  );
+  server.tool(
+    "caddy_list_routes",
+    "List all routes on a Caddy HTTP server with a human-readable summary of matchers and handlers.",
+    {
+      server: z4.string().optional().default("srv0").describe("Caddy server name (default: srv0)")
+    },
+    { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async ({ server: srv }) => {
+      const serverRes = await configGet(`apps/http/servers/${srv}`);
+      if (!serverRes.ok) return formatResult(serverRes);
+      const serverConfig = serverRes.data;
+      const routes = serverConfig?.routes || [];
+      const listen = serverConfig?.listen || [];
+      if (routes.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Server ${srv} (listen: ${listen.join(", ") || "default"}) \u2014 no routes configured`
+            }
+          ]
+        };
+      }
+      const lines = [`Server: ${srv} (listen: ${listen.join(", ") || "default"})`, ""];
+      for (let i = 0; i < routes.length; i++) {
+        const route = routes[i];
+        const matchers = (route.match || []).map((m) => {
+          const parts = [];
+          if (m.host) parts.push(`host=[${m.host.join(",")}]`);
+          if (m.path) parts.push(`path=[${m.path.join(",")}]`);
+          if (m.method) parts.push(`method=[${m.method.join(",")}]`);
+          if (m.header) parts.push("header=...");
+          if (parts.length === 0) return "catch-all";
+          return parts.join(" ");
+        }).join(" | ");
+        const handlers = (route.handle || []).map((h) => {
+          if (h.handler === "reverse_proxy") {
+            const upstreams = (h.upstreams || []).map((u) => u.dial).join(",");
+            return `reverse_proxy(${upstreams})`;
+          }
+          if (h.handler === "file_server") return `file_server(${h.root || "."})`;
+          if (h.handler === "static_response") return `static_response(${h.status_code || 200})`;
+          if (h.handler === "encode") return "encode";
+          if (h.handler === "headers") return "headers";
+          return h.handler || "unknown";
+        }).join(" \u2192 ");
+        lines.push(`  Route ${i}: ${matchers} \u2192 ${handlers}${route.terminal ? " [terminal]" : ""}`);
+      }
+      return {
+        content: [
+          { type: "text", text: lines.join("\n") },
+          { type: "text", text: JSON.stringify(routes, null, 2) }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/tls.ts
+import { z as z5 } from "zod";
+function registerTlsTools(server) {
+  server.tool(
+    "caddy_tls",
+    "Get or configure TLS/HTTPS settings. Actions: 'status' shows current TLS config, 'set_email' sets the ACME email, 'set_acme_ca' sets the ACME CA URL.",
+    {
+      action: z5.enum(["status", "set_email", "set_acme_ca"]).describe("Action to perform"),
+      email: z5.string().optional().describe("ACME email address (for 'set_email' action)"),
+      ca: z5.string().optional().describe("ACME CA URL (for 'set_acme_ca' action)")
+    },
+    { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async ({ action, email, ca }) => {
+      if (action === "status") {
+        return formatResult(await configGet("apps/tls"));
+      }
+      if (action === "set_email") {
+        if (!email)
+          return {
+            isError: true,
+            content: [{ type: "text", text: "Error: email is required for set_email action" }]
+          };
+        const res = await configPatch("apps/tls/automation/policies/0/issuers/0/email", email);
+        if (res.ok) return { content: [{ type: "text", text: `ACME email set to: ${email}` }] };
+        return formatResult(res);
+      }
+      if (action === "set_acme_ca") {
+        if (!ca)
+          return {
+            isError: true,
+            content: [{ type: "text", text: "Error: ca is required for set_acme_ca action" }]
+          };
+        const res = await configPatch("apps/tls/automation/policies/0/issuers/0/ca", ca);
+        if (res.ok) return { content: [{ type: "text", text: `ACME CA set to: ${ca}` }] };
+        return formatResult(res);
+      }
+      return { isError: true, content: [{ type: "text", text: `Unknown action: ${action}` }] };
+    }
+  );
+}
+
+// src/server.ts
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
+function createCaddyServer() {
+  const server = new McpServer({ name: "caddy-mcp", version });
+  registerConfigTools(server);
+  registerRouteTools(server);
+  registerAdaptTools(server);
+  registerTlsTools(server);
+  registerOperationalTools(server);
+  registerResources(server);
+  return server;
+}
+async function startServer() {
+  const server = createCaddyServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+var isDirectRun = process.argv[1]?.endsWith("server.js");
+if (isDirectRun) {
+  startServer().catch((err) => {
+    console.error("MCP server error:", err);
+    process.exit(1);
+  });
+}
+export {
+  createCaddyServer,
+  startServer
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@yawlabs/caddy-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for managing Caddy web servers via the admin API",
+  "license": "MIT",
+  "author": "Yaw Labs <contact@yaw.sh> (https://yaw.sh)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/server.js",
+      "types": "./dist/server.d.ts"
+    }
+  },
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "bin": {
+    "caddy-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "typecheck": "tsc --noEmit",
+    "test:ci": "npm run build && npm test",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^25.5.2",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "caddy",
+    "reverse-proxy",
+    "web-server",
+    "mcp-server",
+    "devtools",
+    "ai"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YawLabs/caddy-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/YawLabs/caddy-mcp/issues"
+  },
+  "homepage": "https://github.com/YawLabs/caddy-mcp"
+}