@jurislm/coolify-plugin 4.0.24 → 4.0.27

package/.codex-plugin/plugin.json

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

package/.mcp.json

@@ -2,9 +2,9 @@
   "mcpServers": {
     "coolify": {
       "type": "stdio",
-      "command": "bunx",
-      "args": ["-y", "@jurislm/coolify-plugin@latest"],
-      "env_vars": ["COOLIFY_BASE_URL", "COOLIFY_ACCESS_TOKEN"]
+      "command": "bun",
+      "args": ["x", "@jurislm/coolify-plugin@latest"],
+      "env_vars": ["COOLIFY_CLOUD_BASE_URL", "COOLIFY_CLOUD_ACCESS_TOKEN", "CURSOR_COOLIFY_BASE_URL", "CURSOR_COOLIFY_ACCESS_TOKEN", "COOLIFY_BASE_URL", "COOLIFY_ACCESS_TOKEN"]
     }
   }
 }

package/.mcp.json.example

@@ -1,8 +1,8 @@
 {
   "mcpServers": {
     "coolify": {
-      "command": "bunx",
-      "args": ["-y", "@jurislm/coolify-plugin@latest"],
+      "command": "bun",
+      "args": ["x", "@jurislm/coolify-plugin@latest"],
       "env": {
         "COOLIFY_BASE_URL": "https://coolify.example",
         "COOLIFY_ACCESS_TOKEN": "<set-in-host-environment>"

package/README.md

@@ -4,6 +4,8 @@ Portable Coolify MCP plugin. It exposes focused `coolify_*` tools generated from
 
 Official website: [JurisLM Coolify Plugin](https://jurislm.github.io/coolify-plugin/).
 
+Follow the shared [JurisLM Plugin Architecture v1](https://github.com/jurislm/woodpecker-ci-plugin/blob/main/docs/plugin-architecture.md) for package, host configuration and acceptance boundaries.
+
 ## Scope
 
 This repository provides a local Codex and Cursor plugin. It runs a stdio MCP server against a user-configured Coolify instance. OpenAI public Plugin Directory submission is outside this scope; public HTTPS, OAuth, and listing requirements are not acceptance criteria for this local plugin.
@@ -25,16 +27,34 @@ bun run check
 bun dist/index.js
 ```
 
-`mcp.json` and `.mcp.json` use the same published-package `bunx` stdio registration as the Woodpecker CI plugin. `.mcp.json.example` contains placeholder environment values only. NPM package release is allowed.
+`mcp.json`, `.mcp.json` and `plugins/cursor/mcp.json` launch the published package with `bun x` (not the separate `bunx` executable, which some package-manager shims break). When a connection variable is missing, empty, or an unsubstituted `${...}` placeholder, the server fills it from `~/.config/jurislm/plugin.env` (`KEY=value` or `export KEY=value` lines; override the path with `JURISLM_PLUGIN_ENV`); host values always take precedence and values are never logged. `.mcp.json.example` contains placeholder environment values only. NPM package release is allowed.
 
 For Codex repository marketplace installation, use the repository root and leave the sparse path empty. The supported marketplace manifest is `.agents/plugins/marketplace.json`; do not enter `plugins/codex`.
-The Codex MCP registration forwards `COOLIFY_BASE_URL` and `COOLIFY_ACCESS_TOKEN` from the Codex session environment. A desktop session may not inherit values exported in a terminal; start a new task after configuring the app environment, then verify a read-only Coolify tool before making changes.
+The native Codex registration forwards `COOLIFY_CLOUD_BASE_URL`, `COOLIFY_CLOUD_ACCESS_TOKEN`, `CURSOR_COOLIFY_BASE_URL`, `CURSOR_COOLIFY_ACCESS_TOKEN`, `COOLIFY_BASE_URL` and `COOLIFY_ACCESS_TOKEN` from its owning environment. Portable `mcp.json` contains no host-specific fields or credential defaults.
 
 ```sh
 codex plugin marketplace add https://github.com/jurislm/coolify-plugin
 codex plugin add coolify-plugin@coolify-marketplace
 ```
 
+### Codex desktop on macOS
+
+A Codex process launched from the Dock or Finder does not read zsh startup files. If your connection settings are exported by `.zshenv`, copy [`launchers/coolify-desktop.zsh`](launchers/coolify-desktop.zsh) to `~/.codex/bin/coolify-mcp.zsh`, then add this opt-in override to `~/.codex/config.toml`:
+
+```toml
+[plugins."coolify-plugin@coolify-marketplace".mcp_servers.coolify]
+enabled = false
+
+[mcp_servers.coolify]
+command = "/bin/zsh"
+args = ["-f", "-c", 'source "$HOME/.codex/bin/coolify-mcp.zsh"']
+startup_timeout_sec = 30
+```
+
+The launcher checks startup-file syntax before explicitly sourcing `${ZDOTDIR:-$HOME}/.zshenv`, suppresses stdout and preserves stderr. Source status 0 or 1 is accepted because a final optional guard can return 1; higher statuses stop startup. It retains only the six supported connection variables, `HOME`, `PATH`, `TMPDIR` and `LANG`, fixes PATH to `$HOME/.bun/bin:/usr/bin:/bin` and executes the absolute `$HOME/.bun/bin/bun x` path. The `--require-config` option reuses `loadConfig` to require the selected complete URL/token pair before starting stdio; trim, placeholder handling and pair precedence remain the same. Ordinary portable initialization and tool discovery can still start without credentials.
+
+Check `codex mcp get coolify`, restart Codex and open a fresh chat. Read `coolify_get_mcp_version` before connection checks and authenticated reads. Record the resolved package version, actual registration source, HTTP status and returned counts. Standalone stdio checks establish process behavior; fresh chat registration and provider reads require their own evidence.
+
 To check a connection, call `coolify_get_mcp_version`, then `coolify_check_connection`. The second tool reports the selected variable pair, whether a URL and credential are present, and the HTTP status of `/health` and `/version`. It never returns credential values. With a URL but no credential, it still checks public `/health` and leaves `/version` unattempted. A healthy `/health` with a 401 from `/version` means the instance is reachable but rejected the authenticated request; the response alone does not establish whether the credential expired, was revoked, or came from the wrong launcher.
 
 Check the active MCP registration separately. A standalone server named `coolify` can run the same package while the marketplace plugin's MCP is disabled. `coolify_get_mcp_version` identifies the package version, not which registration launched it. `coolify_get_infrastructure_overview` reports authentication failures and all-list failures as tool errors. When only some lists fail for other reasons, their counts are `null` and `complete` is `false`.
@@ -60,7 +80,9 @@ bun run api:check
 ## Checks
 
 ```sh
+bun run check
 bun run api:check
+bun run lint
 bun run typecheck
 bun test
 bun run build

package/dist/capabilities.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { CoolifyApiError, redactSensitive } from "./client.js";
+import { errorMessage as safeErrorMessage } from "./errors.js";
 import { operations } from "./generated/operations.js";
 import { pluginVersion } from "./version.js";
 const outputSchema = z.object({ data: z.unknown(), status: z.number(), request: z.object({ method: z.string(), path: z.string() }) });
@@ -13,7 +14,6 @@ function rows(value) {
 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) {
     if (logs.split("\n").length <= lineLimit && logs.length <= charLimit)
         return logs;
@@ -28,6 +28,7 @@ function environmentSummary(value) {
     return rows(value).map((item) => ({ key: item.key, is_build_time: item.is_buildtime === true }));
 }
 export function registerCapabilities(server, client, config) {
+    const errorMessage = (error) => safeErrorMessage(error, [config.token]);
     const call = async (name, input = {}) => {
         const operation = operations.find((item) => item.name === name);
         if (!operation)
@@ -40,7 +41,14 @@ export function registerCapabilities(server, client, config) {
         return { structuredContent, content: [{ type: "text", text: JSON.stringify(structuredContent) }] };
     };
     const register = (name, description, inputSchema, annotations, handler) => {
-        server.registerTool(name, { title: description, description, inputSchema, outputSchema, annotations }, async (input) => result(name, await handler(input)));
+        server.registerTool(name, { title: description, description, inputSchema, outputSchema, annotations }, async (input) => {
+            try {
+                return result(name, await handler(input));
+            }
+            catch (error) {
+                return { isError: true, content: [{ type: "text", text: errorMessage(error) }] };
+            }
+        });
     };
     const settledRows = async (names) => {
         const settled = await Promise.allSettled(names.map((name) => call(`coolify_list_${name}`)));
@@ -100,7 +108,7 @@ export function registerCapabilities(server, client, config) {
         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_mcp_version", "Get the local Coolify plugin version.", z.object({}), { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, () => Promise.resolve({ name: "@jurislm/coolify-plugin", version: pluginVersion }));
     register("coolify_check_connection", "Check selected configuration and Coolify API status without exposing credentials.", z.object({}), { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async () => {
         const probe = async (name) => {
             const operation = operations.find((item) => item.name === name);
@@ -126,7 +134,7 @@ export function registerCapabilities(server, client, config) {
             return { application: null, health: { status: "unknown", issues: [] }, logs: null, environment_variables: { count: 0, variables: [] }, recent_deployments: [], errors: [errorMessage(error)] };
         }
         if (!app?.uuid)
-            return { application: null, health: { status: "unknown", issues: [] }, logs: null, environment_variables: { count: 0, variables: [] }, recent_deployments: [], errors: [`No application found matching ${query}`] };
+            return { application: null, health: { status: "unknown", issues: [] }, logs: null, environment_variables: { count: 0, variables: [] }, recent_deployments: [], errors: [`No application found matching ${String(query)}`] };
         const names = ["application", "logs", "environment_variables", "deployments"];
         const settled = await Promise.allSettled([
             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 }),
@@ -166,7 +174,7 @@ export function registerCapabilities(server, client, config) {
             return { server: null, health: { status: "unknown", issues: [] }, resources: [], domains: [], errors: [errorMessage(error)] };
         }
         if (!found?.uuid)
-            return { server: null, health: { status: "unknown", issues: [] }, resources: [], domains: [], errors: [`No server found matching ${query}`] };
+            return { server: null, health: { status: "unknown", issues: [] }, resources: [], domains: [], errors: [`No server found matching ${String(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 }),
@@ -198,7 +206,7 @@ export function registerCapabilities(server, client, config) {
     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);
+            return batch([], () => Promise.resolve(undefined));
         const names = rows(await call("coolify_list_applications"));
         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 } }));
@@ -214,7 +222,7 @@ export function registerCapabilities(server, client, config) {
             return { environment: null, missing_database_types: [...databaseTypes], ...(errors.length ? { errors } : {}) };
         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 ?? "").toLowerCase(); for (const expected of databaseTypes)
+        matching.forEach((database) => { const type = typeof database.database_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));
@@ -223,6 +231,6 @@ export function registerCapabilities(server, client, config) {
     register("coolify_docker_network_alias", "Generate Docker network alias remediation commands.", z.object({ server_uuid: z.string().regex(/^[a-zA-Z0-9-]{1,64}$/u), db_uuid: z.string().regex(/^[a-zA-Z0-9-]{1,64}$/u), name: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,62}$/u), network: z.string().optional() }), { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async ({ server_uuid, db_uuid, name, network = "coolify" }) => {
         const server = await call("coolify_get_server_by_uuid", { uuid: server_uuid }).catch(() => null);
         const quote = (value) => `'${value.replace(/'/gu, "'\\''")}'`;
-        return { bug: "Coolify database containers may require a friendly Docker network alias.", warning: "The alias is lost after a rebuild or redeploy.", ...(server ? { server: { ip: server.ip, user: server.user, port: server.port } } : { server_lookup_failed: "Could not retrieve server details" }), commands: { ssh_connect: server ? `ssh -p ${server.port} ${server.user}@${server.ip}` : "ssh -p <port> <user>@<server-ip>", add_alias: [`docker network disconnect ${quote(String(network))} ${quote(String(db_uuid))}`, `docker network connect ${quote(String(network))} ${quote(String(db_uuid))} --alias ${quote(String(name))} --alias ${quote(String(db_uuid))}`], verify: `docker exec <any-app-container> getent hosts ${quote(String(name))}` }, next_actions: [{ tool: "coolify_get_database_by_uuid", args: { uuid: db_uuid }, hint: "Check database status" }] };
+        return { bug: "Coolify database containers may require a friendly Docker network alias.", warning: "The alias is lost after a rebuild or redeploy.", ...(server ? { server: { ip: server.ip, user: server.user, port: server.port } } : { server_lookup_failed: "Could not retrieve server details" }), commands: { ssh_connect: server ? `ssh -p ${String(server.port)} ${String(server.user)}@${String(server.ip)}` : "ssh -p <port> <user>@<server-ip>", add_alias: [`docker network disconnect ${quote(String(network))} ${quote(String(db_uuid))}`, `docker network connect ${quote(String(network))} ${quote(String(db_uuid))} --alias ${quote(String(name))} --alias ${quote(String(db_uuid))}`], verify: `docker exec <any-app-container> getent hosts ${quote(String(name))}` }, next_actions: [{ tool: "coolify_get_database_by_uuid", args: { uuid: db_uuid }, hint: "Check database status" }] };
     });
 }

package/dist/client.js

@@ -1,28 +1,30 @@
-import { CoolifyApiError } from "./errors.js";
+import { CoolifyApiError, redactErrorText } from "./errors.js";
 const sensitiveKey = /(^value$|real_?value|private_?key|api_?key|user_?key|webhook_?url|token|secret|password|authorization|cookie)/iu;
 export function redactSensitive(value) {
     if (Array.isArray(value))
         return value.map(redactSensitive);
     if (!value || typeof value !== "object")
         return value;
+    const binary = value.encoding === "base64" && typeof value.contentType === "string" && typeof value.value === "string";
     return Object.fromEntries(Object.entries(value).map(([key, child]) => [
         key,
-        sensitiveKey.test(key) ? "[REDACTED]" : redactSensitive(child),
+        sensitiveKey.test(key) && !(binary && key === "value") ? "[REDACTED]" : redactSensitive(child),
     ]));
 }
 function pathValue(value, name) {
     if (value === undefined || value === null)
         throw new Error(`Missing required path parameter: ${name}`);
-    return encodeURIComponent(String(value));
+    return encodeURIComponent(stringifyScalar(value));
 }
+function stringifyScalar(value) { return String(value); }
 function appendQuery(url, name, value) {
     if (value === undefined || value === null)
         return;
     if (Array.isArray(value))
         for (const item of value)
-            url.searchParams.append(name, String(item));
+            url.searchParams.append(name, stringifyScalar(item));
     else
-        url.searchParams.set(name, typeof value === "object" ? JSON.stringify(value) : String(value));
+        url.searchParams.set(name, typeof value === "object" ? JSON.stringify(value) : stringifyScalar(value));
 }
 function base64(bytes) {
     let text = "";
@@ -72,7 +74,7 @@ export class CoolifyClient {
         }
         catch (error) {
             const cause = error instanceof Error ? error.message : "request error";
-            throw new CoolifyApiError(0, operation.method, path, `Coolify request failed for ${operation.method} ${path}: ${token ? cause.replaceAll(token, "[REDACTED]") : cause}`);
+            throw new CoolifyApiError(0, operation.method, path, `Coolify request failed for ${operation.method} ${path}: ${redactErrorText(cause, [token])}`);
         }
         if (!response.ok) {
             let fields = "";
@@ -84,19 +86,26 @@ export class CoolifyClient {
                         fields = Object.keys(errors).filter((key) => /^[a-z][a-z0-9_.-]{0,63}$/iu.test(key)).slice(0, 8).map((key) => token ? key.replaceAll(token, "[REDACTED]") : key).join(", ");
                     }
                 }
-                catch { }
+                catch {
+                    fields = "";
+                }
             }
             throw new CoolifyApiError(response.status, operation.method, path, `Coolify API returned ${response.status} for ${operation.method} ${path}${fields ? `; fields: ${fields}` : ""}`);
         }
         let data = null;
-        if (response.status !== 204) {
-            const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
-            if (contentType.includes("json"))
-                data = await response.json();
-            else if (contentType.startsWith("text/") || contentType.includes("xml"))
-                data = await response.text();
-            else
-                data = { encoding: "base64", contentType: contentType || "application/octet-stream", value: base64(await response.arrayBuffer()) };
+        try {
+            if (response.status !== 204) {
+                const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
+                if (contentType.includes("json"))
+                    data = await response.json();
+                else if (contentType.startsWith("text/") || contentType.includes("xml"))
+                    data = await response.text();
+                else
+                    data = { encoding: "base64", contentType: contentType || "application/octet-stream", value: base64(await response.arrayBuffer()) };
+            }
+        }
+        catch {
+            throw new Error("Coolify API returned an unreadable response body");
         }
         return redactSensitive({ data, status: response.status, request: { method: operation.method, path } });
     }

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+export declare const CREDENTIAL_GROUPS: readonly [readonly ["COOLIFY_CLOUD_BASE_URL", "COOLIFY_CLOUD_ACCESS_TOKEN"], readonly ["CURSOR_COOLIFY_BASE_URL", "CURSOR_COOLIFY_ACCESS_TOKEN"], readonly ["COOLIFY_BASE_URL", "COOLIFY_ACCESS_TOKEN"]];
 export interface CoolifyConfig {
     baseUrl?: string;
     token?: string;

package/dist/config.js

@@ -1,3 +1,8 @@
+export const CREDENTIAL_GROUPS = [
+    ["COOLIFY_CLOUD_BASE_URL", "COOLIFY_CLOUD_ACCESS_TOKEN"],
+    ["CURSOR_COOLIFY_BASE_URL", "CURSOR_COOLIFY_ACCESS_TOKEN"],
+    ["COOLIFY_BASE_URL", "COOLIFY_ACCESS_TOKEN"],
+];
 export class ConfigError extends Error {
     constructor(message) {
         super(message);

package/dist/errors.d.ts

@@ -4,3 +4,18 @@ export declare class CoolifyApiError extends Error {
     readonly path: string;
     constructor(status: number, method: string, path: string, message: string);
 }
+export declare function redactErrorText(message: string, tokens?: Array<string | undefined>): string;
+export declare function errorMessage(error: unknown, tokens?: Array<string | undefined>): string;
+export declare function formatToolError(error: unknown, tokens: Array<string | undefined>): {
+    code: string;
+    status: number;
+    method: string;
+    path: string;
+    message: string;
+} | {
+    code: string;
+    message: string;
+    status?: undefined;
+    method?: undefined;
+    path?: undefined;
+};

package/dist/errors.js

@@ -10,3 +10,18 @@ export class CoolifyApiError extends Error {
         this.name = "CoolifyApiError";
     }
 }
+export function redactErrorText(message, tokens = []) {
+    let redacted = message;
+    for (const token of tokens)
+        if (token)
+            redacted = redacted.replaceAll(token, "[REDACTED]");
+    return redacted.replace(/Bearer\s+[^\s,;]+/giu, "Bearer [REDACTED]");
+}
+export function errorMessage(error, tokens = []) {
+    return redactErrorText(error instanceof Error ? error.message : String(error), tokens);
+}
+export function formatToolError(error, tokens) {
+    return error instanceof CoolifyApiError
+        ? { code: "COOLIFY_API_ERROR", status: error.status, method: error.method, path: error.path, message: errorMessage(error, tokens) }
+        : { code: "COOLIFY_TOOL_ERROR", message: errorMessage(error, tokens) };
+}

package/dist/index.js

@@ -1,9 +1,13 @@
 #!/usr/bin/env bun
-import { loadConfig } from "./config.js";
+import { CREDENTIAL_GROUPS, ConfigError, loadConfig } from "./config.js";
+import { withPluginEnv } from "./plugin-env.js";
 import { createServer } from "./server.js";
 import { createStdioTransport } from "./transports/stdio.js";
 try {
-    await createServer(loadConfig()).connect(createStdioTransport());
+    const config = loadConfig(withPluginEnv(process.env, CREDENTIAL_GROUPS));
+    if (process.argv.includes("--require-config") && (!config.baseUrl || !config.token))
+        throw new ConfigError("A complete URL/token pair is required for the selected Coolify configuration");
+    await createServer(config).connect(createStdioTransport());
 }
 catch (error) {
     console.error(`Coolify MCP server failed: ${error instanceof Error ? error.message : String(error)}`);

package/dist/plugin-env.d.ts

@@ -0,0 +1,6 @@
+export type Environment = Record<string, string | undefined>;
+export type CredentialGroups = readonly (readonly string[])[];
+export declare const PLUGIN_ENV_PATH_VARIABLE = "JURISLM_PLUGIN_ENV";
+export declare function parsePluginEnv(text: string): Record<string, string>;
+export declare function pluginEnvPath(env: Environment): string;
+export declare function withPluginEnv(env: Environment, groups: CredentialGroups, readText?: (path: string) => string, warn?: (message: string) => void): Environment;

package/dist/plugin-env.js

@@ -0,0 +1,66 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+export const PLUGIN_ENV_PATH_VARIABLE = "JURISLM_PLUGIN_ENV";
+const PLACEHOLDER = /^\$\{[^}]*\}$/u;
+const ASSIGNMENT = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/u;
+function isUnset(value) {
+    const trimmed = value?.trim();
+    return !trimmed || PLACEHOLDER.test(trimmed);
+}
+export function parsePluginEnv(text) {
+    const values = {};
+    for (const rawLine of text.split(/\r?\n/u)) {
+        const match = ASSIGNMENT.exec(rawLine.trim());
+        if (!match)
+            continue;
+        const [, name, rawValue] = match;
+        const quote = rawValue[0];
+        if (quote === '"' || quote === "'") {
+            const end = rawValue.indexOf(quote, 1);
+            if (end > 0)
+                values[name] = rawValue.slice(1, end);
+        }
+        else {
+            values[name] = rawValue.replace(/\s+#.*$/u, "").trim();
+        }
+    }
+    return values;
+}
+export function pluginEnvPath(env) {
+    const home = env.HOME?.trim() || homedir();
+    const override = env[PLUGIN_ENV_PATH_VARIABLE];
+    if (!override || isUnset(override))
+        return join(home, ".config", "jurislm", "plugin.env");
+    const path = override.trim();
+    return resolve(path === "~" || path.startsWith("~/") ? join(home, path.slice(1)) : path);
+}
+function readPluginEnv(path, readText, warn) {
+    try {
+        return parsePluginEnv(readText(path));
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT")
+            warn(`Could not read plugin env file ${path} (${code ?? "unknown error"})`);
+        return {};
+    }
+}
+export function withPluginEnv(env, groups, readText = (path) => readFileSync(path, "utf8"), warn = (message) => console.error(message)) {
+    if (groups.every((group) => group.every((name) => !isUnset(env[name]))))
+        return env;
+    const fileValues = groups.some((group) => group.every((name) => isUnset(env[name]))) ? readPluginEnv(pluginEnvPath(env), readText, warn) : {};
+    const resolved = { ...env };
+    for (const group of groups) {
+        const fillFromFile = group.every((name) => isUnset(env[name]));
+        for (const name of group) {
+            if (!isUnset(env[name]))
+                continue;
+            if (fillFromFile && !isUnset(fileValues[name]))
+                resolved[name] = fileValues[name];
+            else
+                delete resolved[name];
+        }
+    }
+    return resolved;
+}

package/dist/server.js

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { CoolifyApiError, CoolifyClient, redactSensitive } from "./client.js";
+import { CoolifyClient, redactSensitive } from "./client.js";
+import { formatToolError } from "./errors.js";
 import { registerCapabilities } from "./capabilities.js";
 import { operations } from "./generated/operations.js";
 import { pluginVersion } from "./version.js";
@@ -23,9 +24,7 @@ export function createServer(config, fetchImpl) {
                 return { structuredContent, content: [{ type: "text", text: JSON.stringify(structuredContent) }] };
             }
             catch (error) {
-                const details = error instanceof CoolifyApiError
-                    ? { code: "COOLIFY_API_ERROR", status: error.status, method: error.method, path: error.path, message: error.message }
-                    : { code: "COOLIFY_TOOL_ERROR", message: error instanceof Error ? error.message : String(error) };
+                const details = formatToolError(error, [config.token]);
                 return { isError: true, content: [{ type: "text", text: JSON.stringify({ error: details }) }] };
             }
         });

package/launchers/coolify-desktop.zsh

@@ -0,0 +1,23 @@
+#!/bin/zsh -f
+startup_file="${ZDOTDIR:-$HOME}/.zshenv"
+if [[ -r $startup_file ]]; then
+  /bin/zsh -f -n "$startup_file" >/dev/null || exit $?
+  startup_status=0
+  source "$startup_file" >/dev/null || startup_status=$?
+  if (( startup_status > 1 )); then
+    exit "$startup_status"
+  fi
+fi
+zmodload zsh/parameter
+export PATH="$HOME/.bun/bin:/usr/bin:/bin"
+for name in ${(k)parameters}; do
+  case "$name" in
+    HOME|PATH|TMPDIR|LANG|COOLIFY_CLOUD_BASE_URL|COOLIFY_CLOUD_ACCESS_TOKEN|CURSOR_COOLIFY_BASE_URL|CURSOR_COOLIFY_ACCESS_TOKEN|COOLIFY_BASE_URL|COOLIFY_ACCESS_TOKEN) ;;
+    *)
+      if [[ ${parameters[$name]} == *export* ]]; then
+        unset "$name"
+      fi
+      ;;
+  esac
+done
+exec "$HOME/.bun/bin/bun" x @jurislm/coolify-plugin@latest --require-config

package/mcp.json

@@ -3,8 +3,8 @@
   "mcpServers": {
     "coolify": {
       "type": "stdio",
-      "command": "bunx",
-      "args": ["-y", "@jurislm/coolify-plugin@latest"]
+      "command": "bun",
+      "args": ["x", "@jurislm/coolify-plugin@latest"]
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jurislm/coolify-plugin",
-  "version": "4.0.24",
+  "version": "4.0.27",
   "description": "Portable local stdio MCP plugin for Coolify",
   "publishConfig": {
     "access": "public"
@@ -11,6 +11,7 @@
   },
   "files": [
     "dist",
+    "launchers",
     "api",
     "openapi",
     "assets",
@@ -31,6 +32,7 @@
     "clean": "rm -rf dist",
     "build": "bun run clean && tsc",
     "start": "bun dist/index.js",
+    "lint": "bun ./node_modules/eslint/bin/eslint.js src scripts --max-warnings=0",
     "typecheck": "tsc --noEmit",
     "typecheck:tests": "tsc --noEmit -p tsconfig.test.json",
     "test": "bun test --path-ignore-patterns dist",
@@ -40,7 +42,7 @@
     "manifest:check": "bun scripts/validate-plugin-manifests.ts",
     "package:check": "bun pm pack --dry-run 2>&1 | bun scripts/package-contents-check.ts",
     "release:test": "bun scripts/ci/test-release-pr-auto-merge.ts && bun scripts/ci/test-release-workflows.ts",
-    "check": "bun run manifest:check && bun run api:check && bun run typecheck && bun run typecheck:tests && bun run build && bun test && bun run release:test && bun pm pack --dry-run 2>&1 | bun scripts/package-contents-check.ts",
+    "check": "bun run manifest:check && bun run api:check && bun run lint && bun run typecheck && bun run typecheck:tests && bun run build && bun test && bun run release:test && bun pm pack --dry-run 2>&1 | bun scripts/package-contents-check.ts",
     "prepublishOnly": "bun run check"
   },
   "dependencies": {
@@ -48,10 +50,14 @@
     "zod": "4.6.5"
   },
   "devDependencies": {
+    "@eslint/js": "10.0.1",
     "@types/bun": "1.4.2",
+    "ajv": "8.20.0",
+    "eslint": "10.11.0",
     "json-schema-to-zod": "2.8.1",
     "openapi-typescript": "7.13.0",
     "typescript": "5.9.3",
+    "typescript-eslint": "8.70.1",
     "yaml": "2.9.1"
   },
   "packageManager": "bun@1.3.14"

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "coolify-plugin",
-  "version": "4.0.24",
+  "version": "4.0.27",
   "description": "Portable Coolify MCP plugin with local stdio tools generated from the official OpenAPI contract.",
   "author": {
     "name": "JurisLM",