@jurislm/coolify-plugin 3.7.11 → 4.0.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "coolify-plugin",
-  "version": "3.7.11",
+  "version": "4.0.0",
   "description": "Fallback Codex metadata for local stdio Coolify tools.",
   "author": {
     "name": "JurisLM",

package/.mcp.json.example

@@ -4,8 +4,8 @@
       "command": "bunx",
       "args": ["-y", "@jurislm/coolify-plugin@latest"],
       "env": {
-        "COOLIFY_URL": "https://coolify.example",
-        "COOLIFY_TOKEN": "<set-in-host-environment>"
+        "COOLIFY_BASE_URL": "https://coolify.example",
+        "COOLIFY_ACCESS_TOKEN": "<set-in-host-environment>"
       }
     }
   }

package/README.md

@@ -1,14 +1,14 @@
 # @jurislm/coolify-plugin
 
-Portable Coolify MCP plugin. It exposes focused `coolify_*` stdio tools generated from the committed official Coolify OpenAPI snapshot.
+Portable Coolify MCP plugin. It exposes focused `coolify_*` stdio tools generated from one pinned Coolify API contract.
 
 ## Configure
 
-Only these environment variables are accepted:
+The plugin reads the same global environment variables used by the Coolify setup:
 
 ```sh
-export COOLIFY_URL=https://coolify.example
-export COOLIFY_TOKEN=your-api-token
+export COOLIFY_BASE_URL=https://coolify.example
+export COOLIFY_ACCESS_TOKEN=your-api-token
 ```
 
 Build and run locally:
@@ -30,7 +30,7 @@ codex plugin add coolify-plugin@coolify-marketplace
 
 ## OpenAPI contract
 
-`openapi/coolify-openapi.json` is fetched from the official Coolify repository. `api/manifest.json` records its source, fetch time, persisted-snapshot SHA-256, document/info versions, path count, and operation count. `bun run api:check` verifies the snapshot offline before checking generated parity.
+`openapi/coolify-openapi.json` is built from the official Coolify v4.3.23 release. `api/manifest.json` records the upstream SHA-256, the current API contract corrections, and the persisted SHA-256. `bun run api:check` verifies the contract offline before checking generated parity. The runtime uses the generated schemas directly.
 
 ```sh
 bun run api:fetch

package/api/manifest.json

@@ -1,9 +1,20 @@
 {
-  "sourceUrl": "https://raw.githubusercontent.com/coollabsio/coolify/main/openapi.json",
-  "fetchedAt": "2026-09-16T10:31:42.036Z",
-  "sha256": "4dbb392aac5e0a46186c4e6e5237f86d9534bb99bf6b8b82351a513598af3900",
+  "sourceUrl": "https://raw.githubusercontent.com/coollabsio/coolify/v4.3.23/openapi.json",
+  "fetchedAt": "2026-09-23T12:23:33.000Z",
+  "sha256": "e80f5efe8df44d0887285a8b923bca84bfc3af6a62b1e63405164e71939d6595",
+  "upstreamSha256": "964360ffb3d4c026252aa4657d6561190f59ac4256395bf0645bf6a4f171ec88",
   "openapiVersion": "3.1.0",
   "infoVersion": "0.1",
   "pathCount": 192,
-  "operationCount": 275
+  "operationCount": 275,
+  "contractCorrections": [
+    "List database and resource responses are arrays",
+    "Application deployment history is a count plus deployments collection",
+    "Resource field nullability and identifiers match the active API",
+    "Database updates expose custom Docker run options",
+    "Unsupported server validation operation removed",
+    "Database PATCH omits unspecified health-check defaults",
+    "Server reachability and service status are response fields",
+    "Server metadata, deployment git type, and environment descriptions can be null"
+  ]
 }

package/dist/capabilities.d.ts

@@ -1,3 +1,3 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CoolifyClient } from "./client.js";
-export declare function registerV36Capabilities(server: McpServer, client: CoolifyClient): void;
+export declare function registerCapabilities(server: McpServer, client: CoolifyClient): void;

package/dist/capabilities.js

@@ -8,16 +8,10 @@ const truncationPrefix = "...[truncated]...\n";
 function rows(value) {
     if (Array.isArray(value))
         return value.filter((item) => !!item && typeof item === "object");
-    if (!value || typeof value !== "object")
-        return [];
-    for (const key of ["data", "items", "results", "deployments", "applications", "databases", "resources", "services"]) {
-        const nested = value[key];
-        if (Array.isArray(nested))
-            return rows(nested);
-    }
     return [];
 }
 function status(value) { return typeof value.status === "string" ? value.status : ""; }
+function running(value) { return /(^|:)running($|:)/iu.test(status(value)); }
 function unhealthy(value) { return /exited|unhealthy|error|stopped/iu.test(status(value)); }
 function errorMessage(value) { return value instanceof Error ? value.message : String(value); }
 function truncateLogs(logs, lineLimit = 200, charLimit = 50_000) {
@@ -31,14 +25,15 @@ function truncateLogs(logs, lineLimit = 200, charLimit = 50_000) {
     return result;
 }
 function environmentSummary(value) {
-    return rows(value).map((item) => ({ key: item.key, is_build_time: item.is_build_time ?? item.is_buildtime ?? false }));
+    return rows(value).map((item) => ({ key: item.key, is_build_time: item.is_buildtime === true }));
 }
-export function registerV36Capabilities(server, client) {
+export function registerCapabilities(server, client) {
     const call = async (name, input = {}) => {
         const operation = operations.find((item) => item.name === name);
         if (!operation)
             throw new Error(`Missing generated operation: ${name}`);
-        return (await client.request(operation, operation.inputSchema.parse(input))).data;
+        const data = (await client.request(operation, operation.inputSchema.parse(input))).data;
+        return operation.responseSchema.parse(data);
     };
     const result = (name, data) => {
         const structuredContent = redactSensitive({ data, status: 200, request: { method: "COMPOSITE", path: `/capabilities/${name}` } });
@@ -89,6 +84,14 @@ export function registerV36Capabilities(server, client) {
         const servers = rows(await call("coolify_list_servers"));
         return servers.find((item) => [item.uuid, item.name, item.ip].some((value) => typeof value === "string" && value.toLowerCase().includes(query.toLowerCase())));
     };
+    const projectApplications = async (projectUuid) => {
+        const [apps, environments] = await Promise.all([
+            call("coolify_list_applications"),
+            call("coolify_get_environments", { uuid: projectUuid }),
+        ]);
+        const environmentIds = new Set(rows(environments).map((environment) => environment.id));
+        return rows(apps).filter((app) => environmentIds.has(app.environment_id));
+    };
     register("coolify_get_mcp_version", "Get the local Coolify plugin version.", z.object({}), { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async () => ({ name: "@jurislm/coolify-plugin", version: pluginVersion }));
     register("coolify_get_infrastructure_overview", "Summarize Coolify infrastructure.", z.object({}), { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, overview);
     register("coolify_diagnose_application", "Diagnose an application by UUID, name, or domain.", z.object({ query: z.string() }), { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ query }) => {
@@ -103,7 +106,7 @@ export function registerV36Capabilities(server, client) {
             return { application: null, health: { status: "unknown", issues: [] }, logs: null, environment_variables: { count: 0, variables: [] }, recent_deployments: [], errors: [`No application found matching ${query}`] };
         const names = ["application", "logs", "environment_variables", "deployments"];
         const settled = await Promise.allSettled([
-            call("coolify_get_application_by_uuid", { uuid: app.uuid }), call("coolify_get_application_logs_by_uuid", { uuid: app.uuid, lines: 50 }), call("coolify_list_envs_by_application_uuid", { uuid: app.uuid }), call("coolify_list_deployments_by_app_uuid", { uuid: app.uuid }),
+            call("coolify_get_application_by_uuid", { uuid: app.uuid }), running(app) ? call("coolify_get_application_logs_by_uuid", { uuid: app.uuid, lines: 50 }) : Promise.resolve(null), call("coolify_list_envs_by_application_uuid", { uuid: app.uuid }), call("coolify_list_deployments_by_app_uuid", { uuid: app.uuid }),
         ]);
         const errors = [];
         const value = (index) => { const entry = settled[index]; if (entry.status === "fulfilled")
@@ -111,7 +114,8 @@ export function registerV36Capabilities(server, client) {
         const details = value(0);
         const rawLogs = value(1);
         const envVars = environmentSummary(value(2));
-        const deployments = rows(value(3));
+        const deploymentCollection = value(3);
+        const deployments = rows(deploymentCollection?.deployments);
         const appInfo = details ?? app;
         const appStatus = status(appInfo);
         const issues = [];
@@ -127,8 +131,8 @@ export function registerV36Capabilities(server, client) {
             health = "unhealthy";
             issues.push(`${failed} failed deployment(s) in last 5`);
         }
-        const logs = typeof rawLogs === "string" ? rawLogs : rawLogs && typeof rawLogs === "object" && typeof rawLogs.logs === "string" ? rawLogs.logs : null;
-        return { application: { uuid: appInfo.uuid, name: appInfo.name, status: appStatus || "unknown", fqdn: appInfo.fqdn ?? null, git_repository: appInfo.git_repository ?? null, git_branch: appInfo.git_branch ?? null }, health: { status: health, issues }, logs: logs === null ? null : truncateLogs(logs), environment_variables: { count: envVars.length, variables: envVars }, recent_deployments: deployments.slice(0, 5).map((item) => ({ uuid: item.uuid, status: item.status, created_at: item.created_at })), ...(errors.length ? { errors } : {}) };
+        const logs = rawLogs && typeof rawLogs === "object" && typeof rawLogs.logs === "string" ? rawLogs.logs : null;
+        return { application: { uuid: appInfo.uuid, name: appInfo.name, status: appStatus || "unknown", fqdn: appInfo.fqdn ?? null, git_repository: appInfo.git_repository ?? null, git_branch: appInfo.git_branch ?? null }, health: { status: health, issues }, logs: logs === null ? null : truncateLogs(logs), environment_variables: { count: envVars.length, variables: envVars }, recent_deployments: deployments.slice(0, 5).map((item) => ({ uuid: item.deployment_uuid, status: item.status, created_at: item.created_at })), ...(errors.length ? { errors } : {}) };
     });
     register("coolify_diagnose_server", "Diagnose a server by UUID, name, or IP.", z.object({ query: z.string() }), { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ query }) => {
         let found;
@@ -136,13 +140,13 @@ export function registerV36Capabilities(server, client) {
             found = await serverByQuery(String(query));
         }
         catch (error) {
-            return { server: null, health: { status: "unknown", issues: [] }, resources: [], domains: [], validation: null, errors: [errorMessage(error)] };
+            return { server: null, health: { status: "unknown", issues: [] }, resources: [], domains: [], errors: [errorMessage(error)] };
         }
         if (!found?.uuid)
-            return { server: null, health: { status: "unknown", issues: [] }, resources: [], domains: [], validation: null, errors: [`No server found matching ${query}`] };
-        const names = ["server", "resources", "domains", "validation"];
+            return { server: null, health: { status: "unknown", issues: [] }, resources: [], domains: [], errors: [`No server found matching ${query}`] };
+        const names = ["server", "resources", "domains"];
         const settled = await Promise.allSettled([
-            call("coolify_get_server_by_uuid", { uuid: found.uuid }), call("coolify_get_resources_by_server_uuid", { uuid: found.uuid }), call("coolify_get_domains_by_server_uuid", { uuid: found.uuid }), call("coolify_validate_server_by_uuid", { uuid: found.uuid }),
+            call("coolify_get_server_by_uuid", { uuid: found.uuid }), call("coolify_get_resources_by_server_uuid", { uuid: found.uuid }), call("coolify_get_domains_by_server_uuid", { uuid: found.uuid }),
         ]);
         const errors = [];
         const value = (index) => { const entry = settled[index]; if (entry.status === "fulfilled")
@@ -157,7 +161,7 @@ export function registerV36Capabilities(server, client) {
         const unhealthyResources = resources.filter(unhealthy).length;
         if (unhealthyResources)
             issues.push(`${unhealthyResources} unhealthy resource(s)`);
-        return { server: { uuid: details.uuid, name: details.name, ip: details.ip, status: details.status ?? null, is_reachable: details.is_reachable ?? null }, health: { status: issues.length ? "unhealthy" : details.is_reachable === true ? "healthy" : "unknown", issues }, resources: resources.map((item) => ({ uuid: item.uuid, name: item.name, type: item.type, status: item.status })), domains: rows(value(2)), validation: value(3), ...(errors.length ? { errors } : {}) };
+        return { server: { uuid: details.uuid, name: details.name, ip: details.ip, status: details.status ?? null, is_reachable: details.is_reachable ?? null }, health: { status: issues.length ? "unhealthy" : details.is_reachable === true ? "healthy" : "unknown", issues }, resources: resources.map((item) => ({ uuid: item.uuid, name: item.name, type: item.type, status: item.status })), domains: rows(value(2)), ...(errors.length ? { errors } : {}) };
     });
     register("coolify_find_issues", "Find unhealthy Coolify infrastructure.", z.object({}), { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async () => {
         const names = ["servers", "applications", "databases", "services"];
@@ -168,7 +172,7 @@ export function registerV36Capabilities(server, client) {
         values.slice(1).forEach((items, index) => items.filter(unhealthy).forEach((item) => issues.push({ type: names[index + 1].slice(0, -1), uuid: item.uuid, name: item.name, issue: `${names[index + 1].slice(0, -1)} status: ${status(item)}`, status: status(item) })));
         return { summary: { total_issues: issues.length, unhealthy_applications: issues.filter((item) => item.type === "application").length, unhealthy_databases: issues.filter((item) => item.type === "database").length, unhealthy_services: issues.filter((item) => item.type === "service").length, unreachable_servers: issues.filter((item) => item.type === "server").length }, issues, ...(errors.length ? { errors } : {}) };
     });
-    register("coolify_restart_project_applications", "Restart every application in a project.", z.object({ project_uuid: z.string() }), { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }, async ({ project_uuid }) => batch(rows(await call("coolify_list_applications")).filter((app) => app.project_uuid === project_uuid), (app) => call("coolify_restart_application_by_uuid", { uuid: app.uuid })));
+    register("coolify_restart_project_applications", "Restart every application in a project.", z.object({ project_uuid: z.string() }), { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }, async ({ project_uuid }) => batch(await projectApplications(String(project_uuid)), (app) => call("coolify_restart_application_by_uuid", { uuid: app.uuid })));
     register("coolify_bulk_update_application_env", "Update an environment variable across applications.", z.object({ app_uuids: z.array(z.string()), key: z.string(), value: z.string() }).strict(), { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }, async ({ app_uuids, key, value }) => {
         if (!app_uuids.length)
             return batch([], async () => undefined);
@@ -176,8 +180,8 @@ export function registerV36Capabilities(server, client) {
         const labels = new Map(names.map((item) => [item.uuid, item.name ?? item.uuid]));
         return batch(app_uuids.map((uuid) => ({ uuid, name: labels.get(uuid) ?? uuid })), (app) => call("coolify_update_env_by_application_uuid", { uuid: app.uuid, body: { key, value } }));
     });
-    register("coolify_stop_all_applications", "Emergency stop every running application.", z.object({ confirm_stop_all_applications: z.literal(true) }), { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }, async () => batch(rows(await call("coolify_list_applications")).filter((app) => /running|healthy/iu.test(status(app))), (app) => call("coolify_stop_application_by_uuid", { uuid: app.uuid })));
-    register("coolify_redeploy_project_applications", "Redeploy every application in a project.", z.object({ project_uuid: z.string(), force: z.boolean().optional() }), { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }, async ({ project_uuid, force }) => batch(rows(await call("coolify_list_applications")).filter((app) => app.project_uuid === project_uuid), (app) => call("coolify_deploy_by_tag_or_uuid", { uuid: app.uuid, force: force ?? true })));
+    register("coolify_stop_all_applications", "Emergency stop every running application.", z.object({ confirm_stop_all_applications: z.literal(true) }), { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }, async () => batch(rows(await call("coolify_list_applications")).filter(running), (app) => call("coolify_stop_application_by_uuid", { uuid: app.uuid })));
+    register("coolify_redeploy_project_applications", "Redeploy every application in a project.", z.object({ project_uuid: z.string(), force: z.boolean().optional() }), { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }, async ({ project_uuid, force }) => batch(await projectApplications(String(project_uuid)), (app) => call("coolify_deploy_by_tag_or_uuid", { uuid: app.uuid, force: force ?? true })));
     register("coolify_get_environment", "Get an environment and its relevant database types.", z.object({ project_uuid: z.string(), environment_name_or_uuid: z.string() }), { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ project_uuid, environment_name_or_uuid }) => {
         const settled = await Promise.allSettled([call("coolify_get_environment_by_name_or_uuid", { uuid: project_uuid, environment_name_or_uuid }), call("coolify_list_databases")]);
         const errors = [];
@@ -185,9 +189,9 @@ export function registerV36Capabilities(server, client) {
         const databases = settled[1].status === "fulfilled" ? rows(settled[1].value) : (errors.push(`databases: ${errorMessage(settled[1].reason)}`), []);
         if (!environment)
             return { environment: null, missing_database_types: [...databaseTypes], ...(errors.length ? { errors } : {}) };
-        const matching = databases.filter((database) => (environment.id !== undefined && database.environment_id === environment.id) || (environment.uuid !== undefined && database.environment_uuid === environment.uuid) || (environment.name !== undefined && database.environment_name === environment.name));
+        const matching = databases.filter((database) => environment.id !== undefined && database.environment_id === environment.id);
         const byType = new Map();
-        matching.forEach((database) => { const type = String(database.database_type ?? database.type ?? "").toLowerCase(); for (const expected of databaseTypes)
+        matching.forEach((database) => { const type = String(database.database_type ?? "").toLowerCase(); for (const expected of databaseTypes)
             if (type.includes(expected))
                 byType.set(expected, [...(byType.get(expected) ?? []), database]); });
         const missing = databaseTypes.filter((type) => !byType.has(type));

package/dist/client.js

@@ -30,21 +30,6 @@ function base64(bytes) {
         text += String.fromCharCode(byte);
     return btoa(text);
 }
-function normalizeKnownCollection(path, value) {
-    const collectionPaths = new Set(["/databases", "/resources", "/deployments", "/deployments/applications/{uuid}"]);
-    if (!collectionPaths.has(path))
-        return value;
-    if (Array.isArray(value))
-        return value;
-    if (!value || typeof value !== "object")
-        throw new Error(`Coolify collection response for ${path} must be an array or named array wrapper`);
-    for (const key of ["data", "items", "results", "databases", "resources", "deployments"]) {
-        const nested = value[key];
-        if (Array.isArray(nested))
-            return nested;
-    }
-    throw new Error(`Coolify collection response for ${path} must be an array or named array wrapper`);
-}
 export class CoolifyClient {
     config;
     fetchImpl;
@@ -55,10 +40,10 @@ export class CoolifyClient {
     async request(operation, input) {
         const baseUrl = this.config.baseUrl;
         if (!baseUrl)
-            throw new CoolifyApiError(0, operation.method, operation.path, "COOLIFY_URL is required");
+            throw new CoolifyApiError(0, operation.method, operation.path, "COOLIFY_BASE_URL is required");
         const token = this.config.token;
         if (!token)
-            throw new CoolifyApiError(0, operation.method, operation.path, "COOLIFY_TOKEN is required");
+            throw new CoolifyApiError(0, operation.method, operation.path, "COOLIFY_ACCESS_TOKEN is required");
         let path = operation.path;
         for (const parameter of operation.parameters)
             if (parameter.location === "path") {
@@ -89,7 +74,7 @@ export class CoolifyClient {
         if (response.status !== 204) {
             const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
             if (contentType.includes("json"))
-                data = normalizeKnownCollection(operation.path, await response.json());
+                data = await response.json();
             else if (contentType.startsWith("text/") || contentType.includes("xml"))
                 data = await response.text();
             else

package/dist/config.js

@@ -5,8 +5,8 @@ export class ConfigError extends Error {
     }
 }
 export function loadConfig(env = process.env) {
-    const rawUrl = env.COOLIFY_URL?.trim();
-    const token = env.COOLIFY_TOKEN?.trim();
+    const rawUrl = env.COOLIFY_BASE_URL?.trim();
+    const token = env.COOLIFY_ACCESS_TOKEN?.trim();
     if (!rawUrl)
         return { ...(token ? { token } : {}), timeoutMs: 30_000 };
     let url;
@@ -14,13 +14,13 @@ export function loadConfig(env = process.env) {
         url = new URL(rawUrl);
     }
     catch {
-        throw new ConfigError("COOLIFY_URL must be a valid HTTP(S) URL");
+        throw new ConfigError("COOLIFY_BASE_URL must be a valid HTTP(S) URL");
     }
     if (url.protocol !== "http:" && url.protocol !== "https:") {
-        throw new ConfigError("COOLIFY_URL must use http:// or https://");
+        throw new ConfigError("COOLIFY_BASE_URL must use http:// or https://");
     }
     if (url.search || url.hash)
-        throw new ConfigError("COOLIFY_URL must not include a query or fragment");
+        throw new ConfigError("COOLIFY_BASE_URL must not include a query or fragment");
     url.pathname = url.pathname.replace(/\/+$/u, "");
     if (!url.pathname.endsWith("/api/v1"))
         url.pathname = `${url.pathname}/api/v1`.replace(/^\/\//u, "/");