@mks2508/coolify-mks-cli-mcp 0.8.0 → 0.9.0

package/src/coolify/types.ts

@@ -44,6 +44,8 @@ export interface ICoolifyAppOptions {
   projectUuid: string;
   /** Environment UUID */
   environmentUuid: string;
+  /** Environment name (required by API alongside environment_uuid) */
+  environmentName?: string;
   /** Server UUID */
   serverUuid: string;
   /** Destination UUID (optional, for specific destination targeting) */
@@ -52,7 +54,7 @@ export interface ICoolifyAppOptions {
   type?: TCoolifyApplicationType;
   /** GitHub App UUID (required for private-github-app type — get from listGithubApps) */
   githubAppUuid?: string;
-  /** GitHub repository URL (for git-based apps) */
+  /** Git repository URL (for git-based apps) */
   githubRepoUrl?: string;
   /** Git branch */
   branch?: string;
@@ -72,6 +74,8 @@ export interface ICoolifyAppOptions {
   dockerfileLocation?: string;
   /** Base directory for build context (default: "/") */
   baseDirectory?: string;
+  /** Private key UUID (required for private-deploy-key type) */
+  privateKeyUuid?: string;
 }
 
 /**
@@ -102,10 +106,15 @@ export interface ICoolifyUpdateOptions {
   domains?: string;
   /** Docker Compose domains - JSON object: { "service-name": { "domain": "https://..." } } — for dockercompose apps */
   dockerComposeDomains?: string;
+  /** Raw docker-compose YAML content — for dockercompose buildPack only.
+   *  Pass the full compose string; Coolify will replace the existing one. */
+  dockerComposeRaw?: string;
   /** Force HTTPS redirect */
   isForceHttpsEnabled?: boolean;
   /** Enable auto deploy on git push */
   isAutoDeployEnabled?: boolean;
+  /** Watch paths for selective auto-deploy (newline-separated globs, e.g. "src/**\npackages/**") */
+  watchPaths?: string | null;
   /** Enable health check for the application */
   healthCheckEnabled?: boolean;
   /** Health check endpoint path (e.g., "/health") */
@@ -240,6 +249,17 @@ export interface ICoolifyApplication {
   dockerfile_location?: string | null;
   /** Base directory */
   base_directory?: string | null;
+  /** Watch paths for selective auto-deploy (newline-separated globs) */
+  watch_paths?: string | null;
+  /** Raw docker-compose YAML content (dockercompose buildPack only) */
+  docker_compose_raw?: string | null;
+  /** Application settings (returned from GET /applications/{uuid}) */
+  settings?: {
+    is_auto_deploy_enabled?: boolean;
+    is_force_https_enabled?: boolean;
+    is_preview_deployments_enabled?: boolean;
+    [key: string]: unknown;
+  } | null;
   /** Server status (boolean) */
   server_status?: boolean;
   /** Environment ID (numeric) */
@@ -541,3 +561,44 @@ export interface ICoolifyInfrastructureTree {
     unhealthy: number;
   };
 }
+
+/**
+ * GitHub App configuration from Coolify API (snake_case).
+ * OpenAPI schema: GET /github-apps returns ~16 fields.
+ *
+ * @see https://docs.coolify.io/api-reference/github-apps
+ */
+export interface ICoolifyGithubApp {
+  /** Coolify internal ID */
+  id: number;
+  /** Coolify UUID */
+  uuid: string;
+  /** App display name */
+  name: string;
+  /** GitHub organization or null for personal apps */
+  organization: string | null;
+  /** GitHub API URL (e.g., https://api.github.com) */
+  api_url: string;
+  /** GitHub App web URL (e.g., https://github.com/apps/my-app) */
+  html_url: string;
+  /** Custom SSH user for git operations (default: "git") */
+  custom_user: string;
+  /** Custom SSH port (default: 22) */
+  custom_port: number;
+  /** GitHub App ID (different from Coolify's internal id) */
+  app_id: number;
+  /** GitHub Installation ID */
+  installation_id: number;
+  /** GitHub OAuth App Client ID */
+  client_id: string;
+  /** GitHub private key ID on the Coolify server */
+  private_key_id: number;
+  /** Whether app is installed across all org repos (not just selected ones) */
+  is_system_wide: boolean;
+  /** Whether this is a public GitHub App (public installer) vs private */
+  is_public: boolean;
+  /** Coolify team ID that owns this app */
+  team_id: number;
+  /** App type string */
+  type: string;
+}

package/src/sdk.ts

@@ -32,6 +32,7 @@ import type {
   IProgressCallback,
 } from "./coolify/types.js";
 import type { ICoolifyEnvVar } from "./coolify/index.js";
+import { parseEnvContent } from "./utils/env-parser.js";
 
 /** SDK configuration options. */
 export interface ICoolifyOptions {
@@ -83,6 +84,11 @@ class ApplicationsResource {
     return unwrap(await this.svc.listApplicationSummaries());
   }
 
+  /** Get a single application by UUID with full details (including settings and watch_paths). */
+  async get(uuid: string): Promise<ICoolifyApplication> {
+    return unwrap(await this.svc.getApplication(uuid));
+  }
+
   /** Resolve application by name, domain, or UUID. */
   async resolve(query: string): Promise<ICoolifyApplication> {
     return unwrap(await this.svc.resolveApplication(query));
@@ -212,15 +218,19 @@ class ApplicationsResource {
   }> {
     const { filePath, dryRun = false, prune = false, onProgress } = options;
 
-    // 1. Read and parse .env file
+    // 1. Read and parse .env file (absolute path resolution + Node fs fallback)
     let envContent: string;
+    const { readFileSync } = await import('node:fs');
+    const { resolve, isAbsolute } = await import('node:path');
+    const target = filePath || '.env';
+    const absoluteTarget = isAbsolute(target) ? target : resolve(process.cwd(), target);
     try {
-      envContent = await Bun.file(filePath || '.env').text();
-    } catch {
+      // Prefer Node fs (more portable across Bun versions + clearer errors than Bun.file()).
+      envContent = readFileSync(absoluteTarget, 'utf-8');
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
       throw new Error(
-        filePath
-          ? `Cannot read file: ${filePath}`
-          : 'No .env file found in current directory',
+        `Cannot read env file at ${absoluteTarget} (resolved from ${target}): ${msg}`,
       );
     }
 
@@ -304,43 +314,14 @@ class ApplicationsResource {
 
   /**
    * Parse .env file content into a Map.
-   * Handles comments, empty lines, and quoted values.
+   * Delegates to the shared utility in `./utils/env-parser.js` so the SDK
+   * and CLI use a single implementation.
    *
    * @param content - The .env file content
    * @returns Map of environment variables
    */
   private parseEnvContent(content: string): Map<string, string> {
-    const envVars = new Map<string, string>();
-    const lines = content.split('\n');
-
-    for (const line of lines) {
-      const trimmedLine = line.trim();
-      // Skip comments and empty lines
-      if (!trimmedLine || trimmedLine.startsWith('#')) {
-        continue;
-      }
-
-      // Parse KEY=VALUE format
-      const eqIndex = trimmedLine.indexOf('=');
-      if (eqIndex === -1) {
-        continue; // Skip invalid lines
-      }
-
-      const key = trimmedLine.slice(0, eqIndex).trim();
-      let value = trimmedLine.slice(eqIndex + 1).trim();
-
-      // Remove quotes if present
-      if (
-        (value.startsWith('"') && value.endsWith('"')) ||
-        (value.startsWith("'") && value.endsWith("'"))
-      ) {
-        value = value.slice(1, -1);
-      }
-
-      envVars.set(key, value);
-    }
-
-    return envVars;
+    return parseEnvContent(content);
   }
 }
 
@@ -399,6 +380,36 @@ class DatabasesResource {
   async deleteBackup(dbUuid: string, backupUuid: string) {
     return unwrap(await this.svc.deleteDatabaseBackup(dbUuid, backupUuid));
   }
+
+  /** List env vars for a database. */
+  async envVars(uuid: string): Promise<ICoolifyEnvVar[]> {
+    return unwrap(await this.svc.listDatabaseEnvVars(uuid));
+  }
+
+  /**
+   * Bulk set (create-or-update) env vars for a database.
+   *
+   * Note: the database schema is narrower than applications — only
+   * `is_literal`, `is_multiline`, `is_shown_once` are accepted. No
+   * `is_preview` / `is_buildtime` / `is_runtime`.
+   */
+  async bulkSetEnv(
+    uuid: string,
+    vars: Array<{
+      key: string;
+      value: string;
+      is_literal?: boolean;
+      is_multiline?: boolean;
+      is_shown_once?: boolean;
+    }>,
+  ) {
+    return unwrap(await this.svc.bulkUpdateDatabaseEnvVars(uuid, vars));
+  }
+
+  /** Delete a database env var by key. Resolves key → UUID, then DELETE. */
+  async deleteEnv(uuid: string, key: string) {
+    return unwrap(await this.svc.deleteDatabaseEnvVar(uuid, key));
+  }
 }
 
 class ServicesResource {
@@ -443,11 +454,48 @@ class ServicesResource {
     return unwrap(await this.svc.listServiceEnvVars(uuid));
   }
 
+  /**
+   * Sets (creates or updates) a single env var for a service.
+   *
+   * Delegates to the bulk endpoint `PATCH /services/{uuid}/envs/bulk`,
+   * which has create-or-update semantics — calling this for the same key
+   * a second time updates the override value rather than failing with
+   * 409 "already exists" (which is what the raw `POST /services/{uuid}/envs`
+   * endpoint does). Mirrors `ApplicationsResource.setEnv`.
+   *
+   * @param uuid - Service UUID
+   * @param data - Env var data (key, value, is_preview)
+   */
   async setEnv(
     uuid: string,
     data: { key: string; value: string; is_preview?: boolean },
   ) {
-    return unwrap(await this.svc.createServiceEnvVar(uuid, data));
+    return unwrap(await this.svc.bulkUpdateServiceEnvVars(uuid, [data]));
+  }
+
+  /**
+   * Bulk set (create-or-update) env vars for a service.
+   * Mirrors `ApplicationsResource.bulkSetEnv`.
+   *
+   * @param uuid - Service UUID
+   * @param vars - Array of env var definitions to upsert
+   */
+  async bulkSetEnv(
+    uuid: string,
+    vars: Array<{
+      key: string;
+      value: string;
+      is_preview?: boolean;
+      is_buildtime?: boolean;
+      is_runtime?: boolean;
+    }>,
+  ) {
+    return unwrap(await this.svc.bulkUpdateServiceEnvVars(uuid, vars));
+  }
+
+  /** Delete a service env var by key. Resolves key → UUID, then DELETE. */
+  async deleteEnv(uuid: string, key: string) {
+    return unwrap(await this.svc.deleteServiceEnvVar(uuid, key));
   }
 }
 

package/src/tools/definitions.ts

@@ -306,6 +306,12 @@ Redeploy after updating to apply changes.`,
           type: "string" as const,
           description: 'Base directory for build context (default: "/")',
         },
+        watchPaths: {
+          type: "string" as const,
+          description:
+            'Watch paths for selective auto-deploy. Newline-separated globs (e.g. "src/**\\npackages/**"). Set to empty string or null to clear.',
+          nullable: true,
+        },
         dockerComposeDomains: {
           type: "string" as const,
           description:
@@ -315,6 +321,22 @@ Redeploy after updating to apply changes.`,
       required: ["uuid"],
     },
   },
+  {
+    name: "get_application",
+    description: `Get detailed information about a Coolify application including settings (auto-deploy, force HTTPS) and watch paths.
+
+Returns full application details that list_applications doesn't include.`,
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        uuid: {
+          type: "string" as const,
+          description: "Application UUID",
+        },
+      },
+      required: ["uuid"],
+    },
+  },
   {
     name: "set_domains",
     description: `Set domains/FQDN for a Coolify application.

package/src/tools/handlers.ts

@@ -159,6 +159,7 @@ export async function handleToolCall(
               domains: a.domains,
               isForceHttpsEnabled: a.isForceHttpsEnabled,
               isAutoDeployEnabled: a.isAutoDeployEnabled,
+              watchPaths: a.watchPaths,
             })
             .then((app) => ({
               message: `Application ${a.uuid} updated`,
@@ -166,6 +167,24 @@ export async function handleToolCall(
             })),
         "Failed to update application",
       );
+    case "get_application":
+      return mcpCall(
+        (s) =>
+          s.applications.get(a.uuid).then((app) => ({
+            uuid: app.uuid,
+            name: app.name,
+            status: app.status,
+            fqdn: app.fqdn,
+            git_repository: app.git_repository,
+            git_branch: app.git_branch,
+            build_pack: app.build_pack,
+            dockerfile_location: app.dockerfile_location,
+            base_directory: app.base_directory,
+            watch_paths: app.watch_paths,
+            settings: app.settings,
+          })),
+        "Failed to get application",
+      );
     case "get_application_logs":
       return mcpCall(
         (s) =>

package/src/utils/env-parser.ts

@@ -0,0 +1,45 @@
+/**
+ * .env file parser shared between the SDK (syncEnv) and the CLI (--sync stdin).
+ *
+ * Kept as a standalone exported function (not a class method) so both the
+ * SDK's ApplicationsResource and the CLI's stdin sync handler can use the
+ * same implementation without coupling to either.
+ *
+ * @module
+ */
+
+/**
+ * Parses .env-style content into a Map.
+ *
+ * Handles:
+ * - Comments (lines starting with `#`)
+ * - Empty lines (skipped)
+ * - Quoted values (`"value"` or `'value'`)
+ * - Values containing `=` (only the first `=` is the separator)
+ * - Lines without `=` (skipped — invalid)
+ *
+ * @param content - File contents in KEY=VALUE format
+ * @returns Map of key → value (empty string for `KEY=` with no value)
+ */
+export function parseEnvContent(content: string): Map<string, string> {
+  const envVars = new Map<string, string>();
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    // Skip comments and empty lines.
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    // Skip invalid lines (no `=`).
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    // Strip matching surrounding quotes.
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (key) envVars.set(key, value);
+  }
+  return envVars;
+}

package/src/utils/format.ts

@@ -86,6 +86,184 @@ export function formatBytes(bytes: number): string {
   return `${bytes.toFixed(1)} ${units[i]}`;
 }
 
+// ─── Validation ─────────────────────────────────────────────────────────────
+
+/**
+ * Validates a port number string (single or comma-separated).
+ * Valid: "3000", "3000,3001", "80,443,8080"
+ * Invalid: "abc", "99999", "0", "-1", "3000,", ",3000"
+ *
+ * @param ports - Port string to validate
+ * @returns Object with valid flag, parsed ports, and error message
+ */
+export function validatePorts(ports: string): {
+  valid: boolean;
+  ports: number[];
+  error?: string;
+} {
+  if (!ports || !ports.trim()) {
+    return { valid: false, ports: [], error: "Port string is empty" };
+  }
+
+  const parts = ports.split(",").map((p) => p.trim());
+  const parsed: number[] = [];
+
+  for (const part of parts) {
+    if (!/^\d+$/.test(part)) {
+      return {
+        valid: false,
+        ports: [],
+        error: `Invalid port "${part}" — must be a number`,
+      };
+    }
+    const num = parseInt(part, 10);
+    if (num < 1 || num > 65535) {
+      return {
+        valid: false,
+        ports: [],
+        error: `Port ${num} out of range (1-65535)`,
+      };
+    }
+    parsed.push(num);
+  }
+
+  const dupes = parsed.filter((p, i) => parsed.indexOf(p) !== i);
+  if (dupes.length > 0) {
+    return {
+      valid: false,
+      ports: parsed,
+      error: `Duplicate port: ${dupes[0]}`,
+    };
+  }
+
+  return { valid: true, ports: parsed };
+}
+
+/**
+ * Parses EXPOSE directives from a Dockerfile.
+ *
+ * @param dockerfilePath - Path to the Dockerfile
+ * @returns Array of exposed port numbers, empty if none found or file unreadable
+ */
+export function parseDockerfileExpose(dockerfilePath: string): number[] {
+  try {
+    const content = require("node:fs").readFileSync(dockerfilePath, "utf-8");
+    const ports: number[] = [];
+    for (const line of content.split("\n")) {
+      const match = line.match(/^\s*EXPOSE\s+(.+)/i);
+      if (match) {
+        for (const token of match[1].split(/\s+/)) {
+          // Handle "3000/tcp", "3000/udp", or just "3000"
+          const portStr = token.split("/")[0].trim();
+          const num = parseInt(portStr, 10);
+          if (!isNaN(num) && num >= 1 && num <= 65535) {
+            ports.push(num);
+          }
+        }
+      }
+    }
+    return [...new Set(ports)];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Validates a .coolify.json state object (single-app format).
+ * Checks required fields, types, and port validity.
+ *
+ * @param state - The parsed JSON object
+ * @returns Object with valid flag, warnings, and errors
+ */
+export function validateCoolifyState(state: Record<string, unknown>): {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+} {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Detect format
+  const isMultiApp = Array.isArray(state.apps);
+  const isSingleApp = typeof state.appUuid === "string";
+
+  if (!isMultiApp && !isSingleApp) {
+    errors.push(
+      'Invalid format: must have "appUuid" (single-app) or "apps" array (multi-app)',
+    );
+    return { valid: false, errors, warnings };
+  }
+
+  // Common required fields
+  const commonRequired = ["serverUuid", "projectUuid", "environmentUuid"];
+  for (const field of commonRequired) {
+    if (!state[field] || typeof state[field] !== "string") {
+      errors.push(`Missing or invalid required field: ${field}`);
+    }
+  }
+
+  if (isSingleApp) {
+    // Validate single-app specific fields
+    if (
+      state.portsExposes &&
+      typeof state.portsExposes === "string"
+    ) {
+      const portResult = validatePorts(state.portsExposes as string);
+      if (!portResult.valid) {
+        warnings.push(`portsExposes: ${portResult.error}`);
+      }
+    }
+
+    if (state.buildPack && typeof state.buildPack === "string") {
+      const validBuildPacks = [
+        "dockerfile",
+        "nixpacks",
+        "static",
+        "dockercompose",
+      ];
+      if (!validBuildPacks.includes(state.buildPack as string)) {
+        warnings.push(
+          `Unknown buildPack "${state.buildPack}" — expected: ${validBuildPacks.join(", ")}`,
+        );
+      }
+    }
+  }
+
+  if (isMultiApp) {
+    const apps = state.apps as Array<Record<string, unknown>>;
+    if (apps.length === 0) {
+      errors.push("Multi-app format requires at least one app");
+    }
+    for (let i = 0; i < apps.length; i++) {
+      const app = apps[i];
+      if (!app.uuid || typeof app.uuid !== "string") {
+        errors.push(`apps[${i}]: missing or invalid "uuid"`);
+      }
+      if (!app.name || typeof app.name !== "string") {
+        errors.push(`apps[${i}]: missing or invalid "name"`);
+      }
+      if (!app.service || typeof app.service !== "string") {
+        errors.push(`apps[${i}]: missing or invalid "service"`);
+      }
+      if (app.port !== undefined) {
+        const port = app.port as number;
+        if (typeof port !== "number" || port < 1 || port > 65535) {
+          warnings.push(`apps[${i}] (${app.name}): invalid port ${port}`);
+        }
+      }
+    }
+
+    // Check for duplicate UUIDs
+    const uuids = apps.map((a) => a.uuid).filter(Boolean);
+    const dupeUuids = uuids.filter((u, i) => uuids.indexOf(u) !== i);
+    if (dupeUuids.length > 0) {
+      errors.push(`Duplicate app UUIDs: ${dupeUuids.join(", ")}`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
 /**
  * Formats timestamp to relative time.
  *