@mks2508/coolify-mks-cli-mcp 0.6.3 → 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,33 @@ 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") */
+  healthCheckPath?: string;
+  /** Health check port (defaults to application port) */
+  healthCheckPort?: string | number;
+  /** Health check HTTP method (e.g., "GET") */
+  healthCheckMethod?: string;
+  /** Health check interval in seconds */
+  healthCheckInterval?: number;
+  /** Health check timeout in seconds */
+  healthCheckTimeout?: number;
+  /** Number of retries before marking unhealthy */
+  healthCheckRetries?: number;
+  /** Grace period in seconds before health checks start */
+  healthCheckStartPeriod?: number;
+  /** Expected HTTP return code for healthy status */
+  healthCheckReturnCode?: number;
 }
 
 /**
@@ -222,10 +249,29 @@ 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 */
+  /** Environment ID (numeric) */
   environment_id?: number;
+  /** Project UUID */
+  project_uuid?: string;
+  /** Environment UUID */
+  environment_uuid?: string;
+  /** Source type (e.g., "App\\Models\\GithubApp", "App\\Models\\DeployKey") */
+  source_type?: string;
+  /** Type (legacy, may be null) */
+  type?: string;
   /** Destination info */
   destination?: {
     uuid: string;
@@ -361,6 +407,8 @@ export interface ICoolifyDatabase {
   status: string;
   version?: string;
   description?: string | null;
+  /** Environment ID (numeric, for grouping under projects) */
+  environment_id?: number;
   destination?: {
     uuid: string;
     name: string;
@@ -382,6 +430,8 @@ export interface ICoolifyService {
   status: string;
   version?: string;
   description?: string | null;
+  /** Environment ID (numeric, for grouping under projects) */
+  environment_id?: number;
   project_uuid?: string;
   environment_uuid?: string;
   server_uuid?: string;
@@ -439,3 +489,116 @@ export interface ICoolifyVersion {
   latest_version?: string;
   is_latest?: boolean;
 }
+
+/**
+ * A resource (app, database, or service) within an environment.
+ */
+export interface ICoolifyResource {
+  /** Resource UUID */
+  uuid: string;
+  /** Resource name */
+  name: string;
+  /** Resource type: app, database, or service */
+  kind: "app" | "database" | "service";
+  /** Current status */
+  status: string;
+  /** FQDN/domain if configured */
+  fqdn?: string | null;
+  /** Database engine type (only for databases) */
+  dbType?: string;
+}
+
+/**
+ * An environment within a project, containing resources.
+ */
+export interface ICoolifyEnvironmentNode {
+  /** Environment ID (numeric) */
+  id: number;
+  /** Environment UUID */
+  uuid: string;
+  /** Environment name (e.g., "production", "staging") */
+  name: string;
+  /** Resources in this environment */
+  resources: ICoolifyResource[];
+}
+
+/**
+ * A project node in the infrastructure tree.
+ */
+export interface ICoolifyProjectNode {
+  /** Project UUID */
+  uuid: string;
+  /** Project name */
+  name: string;
+  /** Project description */
+  description?: string | null;
+  /** Environments in this project */
+  environments: ICoolifyEnvironmentNode[];
+}
+
+/**
+ * Full infrastructure tree: projects → environments → resources.
+ * Also includes global server info and aggregate counts.
+ */
+export interface ICoolifyInfrastructureTree {
+  /** Server info */
+  server: {
+    name: string;
+    ip?: string;
+    uuid?: string;
+  };
+  /** Projects with their environments and resources */
+  projects: ICoolifyProjectNode[];
+  /** Aggregate counts */
+  counts: {
+    projects: number;
+    apps: number;
+    databases: number;
+    services: number;
+    healthy: number;
+    running: number;
+    stopped: number;
+    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/examples/demo-ui.ts

@@ -0,0 +1,78 @@
+#!/usr/bin/env bun
+/**
+ * Demo script showing new CLI UI features.
+ *
+ * @module
+ */
+
+import { highlightEnvBlock, createEnvTable, createChangeSummary } from "../cli/ui/index.js";
+
+const sampleEnvVars = [
+  {
+    key: "DATABASE_URL",
+    value: "postgresql://user:pass@localhost:5432/mydb",
+    is_runtime: true,
+    is_buildtime: false,
+    is_required: true,
+  },
+  {
+    key: "API_KEY",
+    value: "sk_test_1234567890abcdef",
+    is_runtime: true,
+    is_buildtime: false,
+    is_required: false,
+  },
+  {
+    key: "NODE_ENV",
+    value: "production",
+    is_runtime: true,
+    is_buildtime: true,
+    is_required: false,
+  },
+  {
+    key: "BUILD_ARG",
+    value: "some_value",
+    is_runtime: false,
+    is_buildtime: true,
+    is_required: false,
+  },
+];
+
+const sampleChanges = {
+  added: [
+    { key: "NEW_VAR", value: "new_value" },
+    { key: "ANOTHER_NEW", value: "another" },
+  ],
+  updated: [
+    { key: "DATABASE_URL", value: "new_db_url", oldValue: "old_db_url" },
+    { key: "API_KEY", value: "new_key", oldValue: "old_key" },
+  ],
+  removed: ["DEPRECATED_VAR", "OLD_SETTING"],
+};
+
+console.log("\n" + "=".repeat(60));
+console.log("  CLI UI Demo - Syntax Highlighting");
+console.log("=".repeat(60) + "\n");
+
+// Demo 1: Syntax highlighted .env file
+console.log("1️⃣  Syntax Highlighted .env File");
+console.log("─".repeat(60));
+const envContent = await Bun.file("/tmp/test.env").text();
+console.log(highlightEnvBlock(envContent));
+console.log();
+
+// Demo 2: Table view
+console.log("2️⃣  Table View with cli-table3");
+console.log("─".repeat(60));
+console.log(createEnvTable(sampleEnvVars, { compact: true, showType: true }));
+console.log();
+
+// Demo 3: Change summary
+console.log("3️⃣  Change Summary for Sync");
+console.log("─".repeat(60));
+console.log(createChangeSummary(sampleChanges));
+console.log();
+
+console.log("=".repeat(60));
+console.log("  ✨ Demo complete!");
+console.log("=".repeat(60) + "\n");

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));
@@ -180,6 +186,143 @@ class ApplicationsResource {
   async deleteEnv(uuid: string, key: string) {
     return unwrap(await this.svc.deleteEnvironmentVariable(uuid, key));
   }
+
+  /**
+   * Sync environment variables from a local .env file to Coolify.
+   *
+   * @param uuid - Application UUID
+   * @param options - Sync options
+   * @returns Sync result with changes applied
+   */
+  async syncEnv(
+    uuid: string,
+    options: {
+      /** Path to .env file (default: reads from .env in cwd) */
+      filePath?: string;
+      /** Preview changes without applying */
+      dryRun?: boolean;
+      /** Delete vars not in file */
+      prune?: boolean;
+      /** Callback for progress updates (optional) */
+      onProgress?: (update: {
+        type: 'add' | 'update' | 'remove';
+        key: string;
+        value?: string;
+      }) => void;
+    } = {},
+  ): Promise<{
+    added: Array<{ key: string; value: string }>;
+    updated: Array<{ key: string; value: string; oldValue: string }>;
+    removed: string[];
+    skipped: number;
+  }> {
+    const { filePath, dryRun = false, prune = false, onProgress } = options;
+
+    // 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 {
+      // 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(
+        `Cannot read env file at ${absoluteTarget} (resolved from ${target}): ${msg}`,
+      );
+    }
+
+    const localVars = this.parseEnvContent(envContent);
+
+    if (localVars.size === 0) {
+      return { added: [], updated: [], removed: [], skipped: 0 };
+    }
+
+    // 2. Get current vars from Coolify
+    const currentVarsList = await this.envVars(uuid);
+    const currentVars = new Map(
+      currentVarsList.map((v) => [v.key, v.value]),
+    );
+
+    // 3. Calculate changes
+    const toAdd: Array<{ key: string; value: string }> = [];
+    const toUpdate: Array<{
+      key: string;
+      value: string;
+      oldValue: string;
+    }> = [];
+    const toRemove: string[] = [];
+
+    for (const [key, value] of localVars.entries()) {
+      const currentValue = currentVars.get(key);
+      if (!currentValue) {
+        toAdd.push({ key, value });
+      } else if (currentValue !== value) {
+        toUpdate.push({ key, value, oldValue: currentValue });
+      }
+    }
+
+    if (prune) {
+      for (const key of currentVars.keys()) {
+        if (!localVars.has(key)) {
+          toRemove.push(key);
+        }
+      }
+    }
+
+    // 4. Apply changes (unless dry-run)
+    if (!dryRun) {
+      // Add new variables
+      for (const { key, value } of toAdd) {
+        await this.setEnv(uuid, key, value, false);
+        onProgress?.({ type: 'add', key, value });
+      }
+
+      // Update existing variables
+      for (const { key, value } of toUpdate) {
+        await this.setEnv(uuid, key, value, false);
+        onProgress?.({ type: 'update', key, value });
+      }
+
+      // Remove pruned variables
+      for (const key of toRemove) {
+        await this.deleteEnv(uuid, key);
+        onProgress?.({ type: 'remove', key });
+      }
+    } else {
+      // Report what would happen in dry-run
+      for (const { key, value } of toAdd) {
+        onProgress?.({ type: 'add', key, value });
+      }
+      for (const { key, value } of toUpdate) {
+        onProgress?.({ type: 'update', key, value });
+      }
+      for (const key of toRemove) {
+        onProgress?.({ type: 'remove', key });
+      }
+    }
+
+    return {
+      added: toAdd,
+      updated: toUpdate,
+      removed: toRemove,
+      skipped: currentVars.size - toUpdate.length - toRemove.length,
+    };
+  }
+
+  /**
+   * Parse .env file content into a Map.
+   * 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> {
+    return parseEnvContent(content);
+  }
 }
 
 class DatabasesResource {
@@ -237,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 {
@@ -281,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;
+}