@masonator/coolify-mcp 2.8.0 → 2.9.0

package/README.md

@@ -85,6 +85,34 @@ claude mcp add coolify \
 env COOLIFY_ACCESS_TOKEN=your-api-token COOLIFY_BASE_URL=https://your-coolify-instance.com npx -y @masonator/coolify-mcp
 ```
 
+### Custom HTTP Headers (Cloudflare Zero Trust, Auth Proxies)
+
+If your Coolify instance sits behind a Cloudflare Access tunnel or other auth-proxy middleware, pass extra headers on every outbound request with `--header`:
+
+```json
+{
+  "mcpServers": {
+    "coolify": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@masonator/coolify-mcp",
+        "--header",
+        "CF-Access-Client-Id: abc123.access",
+        "--header",
+        "CF-Access-Client-Secret: your-secret"
+      ],
+      "env": {
+        "COOLIFY_ACCESS_TOKEN": "your-api-token",
+        "COOLIFY_BASE_URL": "https://your-coolify-instance.com"
+      }
+    }
+  }
+}
+```
+
+Multiple `--header` flags can be combined. The reserved headers `Authorization` and `Content-Type` are filtered (with a warning) to prevent silently overriding the Coolify bearer token.
+
 ## Context-Optimized Responses
 
 ### Why This Matters

package/dist/__tests__/coolify-client.test.js

@@ -1,12 +1,14 @@
 import { jest, describe, it, expect, beforeEach } from '@jest/globals';
 import { CoolifyClient } from '../lib/coolify-client.js';
 // Helper to create mock response
-function mockResponse(data, ok = true, status = 200) {
+function mockResponse(data, ok = true, status = 200, contentType = 'application/json') {
+    const body = contentType.includes('application/json') ? JSON.stringify(data) : String(data);
     return {
         ok,
         status,
         statusText: ok ? 'OK' : 'Error',
-        text: async () => JSON.stringify(data),
+        headers: new Headers({ 'Content-Type': contentType }),
+        text: async () => body,
     };
 }
 const mockFetch = jest.fn();
@@ -126,6 +128,42 @@ describe('CoolifyClient', () => {
             c.getVersion();
             expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/version', expect.any(Object));
         });
+        it('should merge customHeaders into outgoing requests', async () => {
+            const c = new CoolifyClient({
+                baseUrl: 'http://localhost:3000',
+                accessToken: 'test-token',
+                customHeaders: { 'CF-Access-Client-Id': 'abc', 'CF-Access-Client-Secret': 'xyz' },
+            });
+            mockFetch.mockResolvedValueOnce(mockResponse([{ uuid: 's1', name: 'srv' }]));
+            await c.listServers();
+            expect(mockFetch).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+                headers: expect.objectContaining({
+                    'CF-Access-Client-Id': 'abc',
+                    'CF-Access-Client-Secret': 'xyz',
+                    Authorization: 'Bearer test-token',
+                }),
+            }));
+        });
+        it('should filter reserved headers from customHeaders', async () => {
+            const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => { });
+            const c = new CoolifyClient({
+                baseUrl: 'http://localhost:3000',
+                accessToken: 'test-token',
+                customHeaders: {
+                    Authorization: 'Bearer override',
+                    'Content-Type': 'text/plain',
+                    'X-Safe-Header': 'allowed',
+                },
+            });
+            mockFetch.mockResolvedValueOnce(mockResponse([{ uuid: 's1', name: 'srv' }]));
+            await c.listServers();
+            const headers = mockFetch.mock.calls[0][1]?.headers;
+            expect(headers['Authorization']).toBe('Bearer test-token');
+            expect(headers['Content-Type']).toBe('application/json');
+            expect(headers['X-Safe-Header']).toBe('allowed');
+            expect(warnSpy).toHaveBeenCalledTimes(2);
+            warnSpy.mockRestore();
+        });
     });
     describe('listServers', () => {
         it('should return a list of servers', async () => {
@@ -485,6 +523,21 @@ describe('CoolifyClient', () => {
             const result = await client.deleteServer('test-uuid');
             expect(result).toEqual({});
         });
+        it('should return plain text responses without JSON parsing', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse('log line 1\nlog line 2', true, 200, 'text/plain; charset=utf-8'));
+            const result = await client.getApplicationLogs('app-uuid', 50);
+            expect(result).toBe('log line 1\nlog line 2');
+        });
+        it('should fall back to raw text when JSON responses are malformed', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                headers: new Headers({ 'Content-Type': 'application/json' }),
+                text: async () => 'not valid json',
+            });
+            const result = await client.getApplicationLogs('app-uuid', 50);
+            expect(result).toBe('not valid json');
+        });
         it('should handle API errors without message', async () => {
             mockFetch.mockResolvedValueOnce(mockResponse({}, false, 500));
             await expect(client.listServers()).rejects.toThrow('HTTP 500: Error');
@@ -1118,21 +1171,72 @@ describe('CoolifyClient', () => {
             uuid: 'env-var-uuid',
             key: 'API_KEY',
             value: 'secret123',
-            is_build_time: false,
+            is_buildtime: false,
+            is_runtime: true,
         };
-        it('should list application env vars', async () => {
+        it('should list application env vars with values masked by default (#159)', async () => {
             mockFetch.mockResolvedValueOnce(mockResponse([mockEnvVar]));
             const result = await client.listApplicationEnvVars('app-uuid');
-            expect(result).toEqual([mockEnvVar]);
+            // value masked, metadata preserved
+            expect(result).toEqual([
+                {
+                    uuid: 'env-var-uuid',
+                    key: 'API_KEY',
+                    value: '***',
+                    is_buildtime: false,
+                    is_runtime: true,
+                },
+            ]);
             expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/applications/app-uuid/envs', expect.any(Object));
         });
-        it('should list application env vars with summary', async () => {
+        it('should list application env vars with real_value also masked on the full projection (#159)', async () => {
+            const fullEnvVar = {
+                id: 1,
+                uuid: 'env-var-uuid',
+                key: 'API_KEY',
+                value: 'secret123',
+                real_value: 'secret123',
+                is_buildtime: false,
+                is_runtime: true,
+                is_literal: true,
+                is_multiline: false,
+                is_preview: false,
+                is_shared: false,
+                is_shown_once: false,
+                application_id: 1,
+                created_at: '2024-01-01',
+                updated_at: '2024-01-01',
+            };
+            mockFetch.mockResolvedValueOnce(mockResponse([fullEnvVar]));
+            const result = (await client.listApplicationEnvVars('app-uuid'));
+            expect(result[0].value).toBe('***');
+            expect(result[0].real_value).toBe('***');
+            // Metadata stays intact
+            expect(result[0]).toMatchObject({
+                uuid: 'env-var-uuid',
+                key: 'API_KEY',
+                is_buildtime: false,
+                is_runtime: true,
+                is_literal: true,
+                is_preview: false,
+                application_id: 1,
+                created_at: '2024-01-01',
+                updated_at: '2024-01-01',
+            });
+        });
+        it('should list application env vars with real values when reveal=true (#159)', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse([mockEnvVar]));
+            const result = await client.listApplicationEnvVars('app-uuid', { reveal: true });
+            expect(result).toEqual([mockEnvVar]);
+        });
+        it('should list application env vars with summary, masked by default (#159)', async () => {
             const fullEnvVar = {
                 id: 1,
                 uuid: 'env-var-uuid',
                 key: 'API_KEY',
                 value: 'secret123',
-                is_build_time: false,
+                is_buildtime: false,
+                is_runtime: true,
                 is_literal: true,
                 is_multiline: false,
                 is_preview: false,
@@ -1144,13 +1248,46 @@ describe('CoolifyClient', () => {
             };
             mockFetch.mockResolvedValueOnce(mockResponse([fullEnvVar]));
             const result = await client.listApplicationEnvVars('app-uuid', { summary: true });
-            // Summary should only include uuid, key, value, is_build_time
+            // Summary should only include uuid, key, value, is_buildtime, is_runtime — and value masked
+            expect(result).toEqual([
+                {
+                    uuid: 'env-var-uuid',
+                    key: 'API_KEY',
+                    value: '***',
+                    is_buildtime: false,
+                    is_runtime: true,
+                },
+            ]);
+        });
+        it('should list application env vars with summary and reveal=true returning real values (#159)', async () => {
+            const fullEnvVar = {
+                id: 1,
+                uuid: 'env-var-uuid',
+                key: 'API_KEY',
+                value: 'secret123',
+                is_buildtime: false,
+                is_runtime: true,
+                is_literal: true,
+                is_multiline: false,
+                is_preview: false,
+                is_shared: false,
+                is_shown_once: false,
+                application_id: 1,
+                created_at: '2024-01-01',
+                updated_at: '2024-01-01',
+            };
+            mockFetch.mockResolvedValueOnce(mockResponse([fullEnvVar]));
+            const result = await client.listApplicationEnvVars('app-uuid', {
+                summary: true,
+                reveal: true,
+            });
             expect(result).toEqual([
                 {
                     uuid: 'env-var-uuid',
                     key: 'API_KEY',
                     value: 'secret123',
-                    is_build_time: false,
+                    is_buildtime: false,
+                    is_runtime: true,
                 },
             ]);
         });
@@ -1159,10 +1296,31 @@ describe('CoolifyClient', () => {
             const result = await client.createApplicationEnvVar('app-uuid', {
                 key: 'NEW_VAR',
                 value: 'new-value',
-                is_build_time: true,
+                is_buildtime: true,
             });
             expect(result).toEqual({ uuid: 'new-env-uuid' });
         });
+        it('should create runtime-only env var (no Dockerfile ARG injection)', async () => {
+            // Regression for #135: setting is_buildtime=false avoids multiline values
+            // (PEM keys, etc.) being injected as Dockerfile ARG and breaking the build.
+            mockFetch.mockResolvedValueOnce(mockResponse({ uuid: 'new-env-uuid' }));
+            await client.createApplicationEnvVar('app-uuid', {
+                key: 'PASSPORT_PRIVATE_KEY',
+                value: '-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----',
+                is_buildtime: false,
+                is_runtime: true,
+            });
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/applications/app-uuid/envs', expect.objectContaining({
+                method: 'POST',
+                body: expect.stringContaining('"is_buildtime":false'),
+            }));
+            const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+            expect(body).toMatchObject({
+                key: 'PASSPORT_PRIVATE_KEY',
+                is_buildtime: false,
+                is_runtime: true,
+            });
+        });
         it('should update application env var', async () => {
             mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Updated' }));
             const result = await client.updateApplicationEnvVar('app-uuid', {
@@ -1171,6 +1329,22 @@ describe('CoolifyClient', () => {
             });
             expect(result).toEqual({ message: 'Updated' });
         });
+        it('should update env var to runtime-only (flip is_buildtime=false)', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Updated' }));
+            await client.updateApplicationEnvVar('app-uuid', {
+                key: 'NODE_ENV',
+                value: 'production',
+                is_buildtime: false,
+                is_runtime: true,
+            });
+            const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+            expect(body).toEqual({
+                key: 'NODE_ENV',
+                value: 'production',
+                is_buildtime: false,
+                is_runtime: true,
+            });
+        });
         it('should bulk update application env vars', async () => {
             mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Updated' }));
             const result = await client.bulkUpdateApplicationEnvVars('app-uuid', {
@@ -1446,12 +1620,54 @@ describe('CoolifyClient', () => {
             key: 'SVC_KEY',
             value: 'svc-value',
         };
-        it('should list service env vars', async () => {
+        it('should list service env vars with values masked by default (#159)', async () => {
             mockFetch.mockResolvedValueOnce(mockResponse([mockEnvVar]));
             const result = await client.listServiceEnvVars('test-uuid');
-            expect(result).toEqual([mockEnvVar]);
+            // value masked, metadata (uuid, key) preserved
+            expect(result).toEqual([
+                {
+                    uuid: 'svc-env-uuid',
+                    key: 'SVC_KEY',
+                    value: '***',
+                },
+            ]);
             expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/services/test-uuid/envs', expect.any(Object));
         });
+        it('should list service env vars with real_value masked on the full projection (#159)', async () => {
+            const fullEnvVar = {
+                id: 1,
+                uuid: 'svc-env-uuid',
+                key: 'SVC_KEY',
+                value: 'svc-value',
+                real_value: 'svc-value',
+                is_buildtime: false,
+                is_runtime: true,
+                is_literal: true,
+                is_multiline: false,
+                is_preview: false,
+                is_shared: false,
+                is_shown_once: false,
+                service_id: 42,
+                created_at: '2024-01-01',
+                updated_at: '2024-01-01',
+            };
+            mockFetch.mockResolvedValueOnce(mockResponse([fullEnvVar]));
+            const result = await client.listServiceEnvVars('test-uuid');
+            expect(result[0].value).toBe('***');
+            expect(result[0].real_value).toBe('***');
+            expect(result[0]).toMatchObject({
+                uuid: 'svc-env-uuid',
+                key: 'SVC_KEY',
+                is_buildtime: false,
+                is_runtime: true,
+                service_id: 42,
+            });
+        });
+        it('should list service env vars with real values when reveal=true (#159)', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse([mockEnvVar]));
+            const result = await client.listServiceEnvVars('test-uuid', { reveal: true });
+            expect(result).toEqual([mockEnvVar]);
+        });
         it('should create service env var', async () => {
             mockFetch.mockResolvedValueOnce(mockResponse({ uuid: 'new-env-uuid' }));
             const result = await client.createServiceEnvVar('test-uuid', {
@@ -1972,9 +2188,17 @@ describe('CoolifyClient', () => {
                     uuid: 'env-1',
                     key: 'DATABASE_URL',
                     value: 'postgres://...',
-                    is_build_time: false,
+                    is_buildtime: false,
+                    is_runtime: true,
+                },
+                {
+                    id: 2,
+                    uuid: 'env-2',
+                    key: 'NODE_ENV',
+                    value: 'production',
+                    is_buildtime: true,
+                    is_runtime: true,
                 },
-                { id: 2, uuid: 'env-2', key: 'NODE_ENV', value: 'production', is_build_time: true },
             ];
             const mockDeployments = [
                 {
@@ -2021,12 +2245,28 @@ describe('CoolifyClient', () => {
                 expect(result.logs).toBe(mockLogs);
                 expect(result.environment_variables.count).toBe(2);
                 expect(result.environment_variables.variables).toEqual([
-                    { key: 'DATABASE_URL', is_build_time: false },
-                    { key: 'NODE_ENV', is_build_time: true },
+                    { key: 'DATABASE_URL', is_buildtime: false, is_runtime: true },
+                    { key: 'NODE_ENV', is_buildtime: true, is_runtime: true },
                 ]);
                 expect(result.recent_deployments).toHaveLength(2);
                 expect(result.errors).toBeUndefined();
             });
+            it('should apply default flags when env var omits is_buildtime/is_runtime', async () => {
+                // Hits the `?? false` / `?? true` fallback branches in the diagnose mapping
+                // for legacy Coolify responses that don't carry both flags explicitly.
+                const envVarsMissingFlags = [
+                    { id: 1, uuid: 'env-1', key: 'LEGACY_VAR', value: 'x' },
+                ];
+                mockFetch
+                    .mockResolvedValueOnce(mockResponse(mockApp))
+                    .mockResolvedValueOnce(mockResponse(mockLogs))
+                    .mockResolvedValueOnce(mockResponse(envVarsMissingFlags))
+                    .mockResolvedValueOnce(mockResponse({ count: 0, deployments: [] }));
+                const result = await client.diagnoseApplication(testAppUuid);
+                expect(result.environment_variables.variables).toEqual([
+                    { key: 'LEGACY_VAR', is_buildtime: false, is_runtime: true },
+                ]);
+            });
             it('should detect unhealthy application status', async () => {
                 const unhealthyApp = { ...mockApp, status: 'exited:unhealthy' };
                 mockFetch
@@ -2507,15 +2747,40 @@ describe('CoolifyClient', () => {
                 // No API calls should be made
                 expect(mockFetch).not.toHaveBeenCalled();
             });
-            it('should send build time flag when specified', async () => {
+            it('should send buildtime flag when specified', async () => {
                 mockFetch
                     .mockResolvedValueOnce(mockResponse(mockApps))
                     .mockResolvedValueOnce(mockResponse({ message: 'Updated' }));
                 await client.bulkEnvUpdate(['app-1'], 'BUILD_VAR', 'value', true);
-                // Verify the PATCH call was made with is_build_time
+                // Verify the PATCH call was made with is_buildtime (one word — Coolify API field name)
+                expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/applications/app-1/envs', expect.objectContaining({
+                    method: 'PATCH',
+                    body: JSON.stringify({ key: 'BUILD_VAR', value: 'value', is_buildtime: true }),
+                }));
+            });
+            it('should send both buildtime and runtime flags for runtime-only vars', async () => {
+                mockFetch
+                    .mockResolvedValueOnce(mockResponse(mockApps))
+                    .mockResolvedValueOnce(mockResponse({ message: 'Updated' }));
+                await client.bulkEnvUpdate(['app-1'], 'PEM_KEY', 'multiline-value', false, true);
+                expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/applications/app-1/envs', expect.objectContaining({
+                    method: 'PATCH',
+                    body: JSON.stringify({
+                        key: 'PEM_KEY',
+                        value: 'multiline-value',
+                        is_buildtime: false,
+                        is_runtime: true,
+                    }),
+                }));
+            });
+            it('should send only is_runtime when buildtime is left undefined', async () => {
+                mockFetch
+                    .mockResolvedValueOnce(mockResponse(mockApps))
+                    .mockResolvedValueOnce(mockResponse({ message: 'Updated' }));
+                await client.bulkEnvUpdate(['app-1'], 'API_KEY', 'val', undefined, false);
                 expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/applications/app-1/envs', expect.objectContaining({
                     method: 'PATCH',
-                    body: JSON.stringify({ key: 'BUILD_VAR', value: 'value', is_build_time: true }),
+                    body: JSON.stringify({ key: 'API_KEY', value: 'val', is_runtime: false }),
                 }));
             });
         });

package/dist/__tests__/integration/diagnostics.integration.test.js

@@ -54,11 +54,12 @@ describeFn('Diagnostic Integration Tests', () => {
             expect(result.environment_variables).toBeDefined();
             expect(typeof result.environment_variables.count).toBe('number');
             expect(Array.isArray(result.environment_variables.variables)).toBe(true);
-            // Values should be hidden (only key and is_build_time exposed)
+            // Values should be hidden (only key, is_buildtime, is_runtime exposed)
             if (result.environment_variables.variables.length > 0) {
                 const firstVar = result.environment_variables.variables[0];
                 expect(firstVar).toHaveProperty('key');
-                expect(firstVar).toHaveProperty('is_build_time');
+                expect(firstVar).toHaveProperty('is_buildtime');
+                expect(firstVar).toHaveProperty('is_runtime');
                 expect(firstVar).not.toHaveProperty('value');
             }
             // Should have recent deployments array

package/dist/__tests__/mcp-server.test.js

@@ -6,7 +6,7 @@
  * These tests verify MCP server instantiation and structure.
  */
 import { createRequire } from 'module';
-import { describe, it, expect, beforeEach } from '@jest/globals';
+import { describe, it, expect, beforeEach, jest } from '@jest/globals';
 import { CoolifyMcpServer, VERSION, truncateLogs, getApplicationActions, getDeploymentActions, getPagination, } from '../lib/mcp-server.js';
 describe('CoolifyMcpServer v2', () => {
     let server;
@@ -161,6 +161,108 @@ describe('CoolifyMcpServer v2', () => {
             expect(client['accessToken']).toBe('test-token');
         });
     });
+    describe('env_vars tool handler', () => {
+        // Reach the SDK-registered handler so the is_buildtime / is_runtime
+        // passthrough lines are actually executed (not just type-checked).
+        const callEnvVars = async (srv, args) => {
+            const tool = srv._registeredTools['env_vars'];
+            return tool.handler(args, {});
+        };
+        it('forwards is_buildtime/is_runtime to createApplicationEnvVar', async () => {
+            const spy = jest
+                .spyOn(server['client'], 'createApplicationEnvVar')
+                .mockResolvedValue({ uuid: 'env-1' });
+            await callEnvVars(server, {
+                resource: 'application',
+                action: 'create',
+                uuid: 'app-uuid',
+                key: 'PEM_KEY',
+                value: '-----BEGIN-----',
+                is_buildtime: false,
+                is_runtime: true,
+            });
+            expect(spy).toHaveBeenCalledWith('app-uuid', {
+                key: 'PEM_KEY',
+                value: '-----BEGIN-----',
+                is_buildtime: false,
+                is_runtime: true,
+            });
+        });
+        it('forwards is_buildtime/is_runtime to updateApplicationEnvVar', async () => {
+            const spy = jest
+                .spyOn(server['client'], 'updateApplicationEnvVar')
+                .mockResolvedValue({ message: 'Updated' });
+            await callEnvVars(server, {
+                resource: 'application',
+                action: 'update',
+                uuid: 'app-uuid',
+                key: 'NODE_ENV',
+                value: 'production',
+                is_buildtime: false,
+                is_runtime: true,
+            });
+            expect(spy).toHaveBeenCalledWith('app-uuid', {
+                key: 'NODE_ENV',
+                value: 'production',
+                is_buildtime: false,
+                is_runtime: true,
+            });
+        });
+        it('forwards is_buildtime/is_runtime to createServiceEnvVar', async () => {
+            const spy = jest
+                .spyOn(server['client'], 'createServiceEnvVar')
+                .mockResolvedValue({ uuid: 'env-1' });
+            await callEnvVars(server, {
+                resource: 'service',
+                action: 'create',
+                uuid: 'svc-uuid',
+                key: 'API_KEY',
+                value: 'secret',
+                is_buildtime: true,
+                is_runtime: undefined,
+            });
+            expect(spy).toHaveBeenCalledWith('svc-uuid', {
+                key: 'API_KEY',
+                value: 'secret',
+                is_buildtime: true,
+                is_runtime: undefined,
+            });
+        });
+        it('returns key/value error when create is missing required fields', async () => {
+            const result = (await callEnvVars(server, {
+                resource: 'application',
+                action: 'create',
+                uuid: 'app-uuid',
+            }));
+            expect(result.content[0].text).toContain('key, value required');
+        });
+        it('returns key/value error when service create is missing required fields', async () => {
+            const result = (await callEnvVars(server, {
+                resource: 'service',
+                action: 'create',
+                uuid: 'svc-uuid',
+            }));
+            expect(result.content[0].text).toContain('key, value required');
+        });
+    });
+    describe('bulk_env_update tool handler', () => {
+        it('forwards is_buildtime/is_runtime to bulkEnvUpdate', async () => {
+            const spy = jest.spyOn(server['client'], 'bulkEnvUpdate').mockResolvedValue({
+                summary: { total: 2, succeeded: 2, failed: 0 },
+                succeeded: [],
+                failed: [],
+            });
+            const tool = server._registeredTools['bulk_env_update'];
+            await tool.handler({
+                app_uuids: ['app-1', 'app-2'],
+                key: 'PEM_KEY',
+                value: 'multiline',
+                is_buildtime: false,
+                is_runtime: true,
+            }, {});
+            expect(spy).toHaveBeenCalledWith(['app-1', 'app-2'], 'PEM_KEY', 'multiline', false, true);
+        });
+    });
 });
 describe('truncateLogs', () => {
     // Plain text log tests

package/dist/__tests__/parse-headers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/parse-headers.test.js

@@ -0,0 +1,32 @@
+import { describe, it, expect } from '@jest/globals';
+import { parseHeaders } from '../lib/parse-headers.js';
+describe('parseHeaders', () => {
+    it('should parse a single header', () => {
+        const result = parseHeaders(['--header', 'X-Custom: value']);
+        expect(result).toEqual({ 'X-Custom': 'value' });
+    });
+    it('should parse multiple headers', () => {
+        const result = parseHeaders(['--header', 'X-First: one', '--header', 'X-Second: two']);
+        expect(result).toEqual({ 'X-First': 'one', 'X-Second': 'two' });
+    });
+    it('should ignore malformed headers without a colon', () => {
+        const result = parseHeaders(['--header', 'no-colon-here']);
+        expect(result).toEqual({});
+    });
+    it('should trim whitespace from key and value', () => {
+        const result = parseHeaders(['--header', '  X-Spaced  :  some value  ']);
+        expect(result).toEqual({ 'X-Spaced': 'some value' });
+    });
+    it('should handle header value containing colons', () => {
+        const result = parseHeaders(['--header', 'Authorization: Bearer abc:def:ghi']);
+        expect(result).toEqual({ Authorization: 'Bearer abc:def:ghi' });
+    });
+    it('should return empty object when no headers provided', () => {
+        expect(parseHeaders([])).toEqual({});
+        expect(parseHeaders(['--other', 'flag'])).toEqual({});
+    });
+    it('should ignore --header without a following value', () => {
+        const result = parseHeaders(['--header']);
+        expect(result).toEqual({});
+    });
+});

package/dist/index.js

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CoolifyMcpServer } from './lib/mcp-server.js';
+import { parseHeaders } from './lib/parse-headers.js';
 async function main() {
+    const customHeaders = parseHeaders(process.argv);
     const config = {
         baseUrl: process.env.COOLIFY_BASE_URL || 'http://localhost:3000',
         accessToken: process.env.COOLIFY_ACCESS_TOKEN || '',
+        customHeaders: Object.keys(customHeaders).length > 0 ? customHeaders : undefined,
     };
     if (!config.accessToken) {
         throw new Error('COOLIFY_ACCESS_TOKEN environment variable is required');

package/dist/lib/coolify-client.d.ts

@@ -72,6 +72,7 @@ export interface GitHubAppSummary {
 export declare class CoolifyClient {
     private readonly baseUrl;
     private readonly accessToken;
+    private readonly customHeaders;
     private cachedVersion;
     constructor(config: CoolifyConfig);
     private request;
@@ -124,8 +125,16 @@ export declare class CoolifyClient {
     }): Promise<ApplicationActionResponse>;
     stopApplication(uuid: string): Promise<ApplicationActionResponse>;
     restartApplication(uuid: string): Promise<ApplicationActionResponse>;
+    /**
+     * List env vars for an application.
+     *
+     * Default behaviour masks `value` (and `real_value` on the full projection)
+     * with a sentinel string so secrets are not leaked to MCP clients. Pass
+     * `reveal: true` when the caller explicitly needs the plaintext value.
+     */
     listApplicationEnvVars(uuid: string, options?: {
         summary?: boolean;
+        reveal?: boolean;
     }): Promise<EnvironmentVariable[] | EnvVarSummary[]>;
     createApplicationEnvVar(uuid: string, data: CreateEnvVarRequest): Promise<UuidResponse>;
     updateApplicationEnvVar(uuid: string, data: UpdateEnvVarRequest): Promise<MessageResponse>;
@@ -154,7 +163,16 @@ export declare class CoolifyClient {
     startService(uuid: string): Promise<MessageResponse>;
     stopService(uuid: string): Promise<MessageResponse>;
     restartService(uuid: string): Promise<MessageResponse>;
-    listServiceEnvVars(uuid: string): Promise<EnvironmentVariable[]>;
+    /**
+     * List env vars for a service.
+     *
+     * Default behaviour masks `value` (and `real_value`) with a sentinel string
+     * so secrets are not leaked to MCP clients. Pass `reveal: true` when the
+     * caller explicitly needs the plaintext value.
+     */
+    listServiceEnvVars(uuid: string, options?: {
+        reveal?: boolean;
+    }): Promise<EnvironmentVariable[]>;
     createServiceEnvVar(uuid: string, data: CreateEnvVarRequest): Promise<UuidResponse>;
     updateServiceEnvVar(uuid: string, data: UpdateEnvVarRequest): Promise<MessageResponse>;
     deleteServiceEnvVar(uuid: string, envUuid: string): Promise<MessageResponse>;
@@ -256,9 +274,10 @@ export declare class CoolifyClient {
      * @param appUuids - Array of application UUIDs
      * @param key - Environment variable key
      * @param value - Environment variable value
-     * @param isBuildTime - Whether this is a build-time variable (default: false)
+     * @param isBuildtime - Sets the build-time flag on the variable when provided
+     * @param isRuntime - Sets the runtime flag on the variable when provided
      */
-    bulkEnvUpdate(appUuids: string[], key: string, value: string, isBuildTime?: boolean): Promise<BatchOperationResult>;
+    bulkEnvUpdate(appUuids: string[], key: string, value: string, isBuildtime?: boolean, isRuntime?: boolean): Promise<BatchOperationResult>;
     /**
      * Emergency stop all running applications across entire infrastructure.
      */

package/dist/lib/coolify-client.js

@@ -142,7 +142,42 @@ function toEnvVarSummary(envVar) {
         uuid: envVar.uuid,
         key: envVar.key,
         value: envVar.value,
-        is_build_time: envVar.is_build_time,
+        is_buildtime: envVar.is_buildtime,
+        is_runtime: envVar.is_runtime,
+    };
+}
+/**
+ * Sentinel string used to replace plaintext env var values when masking.
+ * Exported via behaviour, not as a public API — clients should treat any
+ * non-real string as "value not returned".
+ */
+const MASKED_VALUE = '***';
+/**
+ * Mask the `value` and `real_value` fields on a full {@link EnvironmentVariable}.
+ * All other metadata (uuid, key, flags, timestamps, ids) is preserved verbatim.
+ *
+ * Applied at the API boundary so callers cannot accidentally leak secrets to
+ * an LLM client by forgetting to strip values downstream. Pair with the
+ * `reveal: true` opt-in on list methods when the caller genuinely needs the
+ * plaintext (e.g. "what is FOO set to right now?").
+ */
+function maskEnvVar(envVar) {
+    const masked = {
+        ...envVar,
+        value: MASKED_VALUE,
+    };
+    if (envVar.real_value !== undefined) {
+        masked.real_value = MASKED_VALUE;
+    }
+    return masked;
+}
+/**
+ * Mask the `value` field on an {@link EnvVarSummary}. Metadata is preserved.
+ */
+function maskEnvVarSummary(envVar) {
+    return {
+        ...envVar,
+        value: MASKED_VALUE,
     };
 }
 /**
@@ -151,6 +186,7 @@ function toEnvVarSummary(envVar) {
 export class CoolifyClient {
     baseUrl;
     accessToken;
+    customHeaders;
     cachedVersion = null;
     constructor(config) {
         if (!config.baseUrl) {
@@ -161,6 +197,18 @@ export class CoolifyClient {
         }
         this.baseUrl = config.baseUrl.replace(/\/$/, '');
         this.accessToken = config.accessToken;
+        const reserved = new Set(['authorization', 'content-type']);
+        const raw = config.customHeaders ?? {};
+        const filtered = {};
+        for (const [key, value] of Object.entries(raw)) {
+            if (reserved.has(key.toLowerCase())) {
+                console.warn(`Custom header "${key}" ignored: reserved by the Coolify client`);
+            }
+            else {
+                filtered[key] = value;
+            }
+        }
+        this.customHeaders = filtered;
     }
     // ===========================================================================
     // Private HTTP methods
@@ -173,12 +221,28 @@ export class CoolifyClient {
                 headers: {
                     'Content-Type': 'application/json',
                     Authorization: `Bearer ${this.accessToken}`,
+                    ...this.customHeaders,
                     ...options.headers,
                 },
             });
             // Handle empty responses (204 No Content, etc.)
             const text = await response.text();
-            const data = text ? JSON.parse(text) : {};
+            const contentType = response.headers?.get('Content-Type')?.toLowerCase() ?? '';
+            const isJsonResponse = !contentType || contentType.includes('application/json') || contentType.includes('+json');
+            let data = {};
+            if (text) {
+                if (isJsonResponse) {
+                    try {
+                        data = JSON.parse(text);
+                    }
+                    catch {
+                        data = text;
+                    }
+                }
+                else {
+                    data = text;
+                }
+            }
             if (!response.ok) {
                 const error = data;
                 // Include validation errors if present
@@ -222,6 +286,7 @@ export class CoolifyClient {
         const response = await fetch(url, {
             headers: {
                 Authorization: `Bearer ${this.accessToken}`,
+                ...this.customHeaders,
             },
         });
         if (!response.ok) {
@@ -461,9 +526,21 @@ export class CoolifyClient {
     // ===========================================================================
     // Application Environment Variables
     // ===========================================================================
+    /**
+     * List env vars for an application.
+     *
+     * Default behaviour masks `value` (and `real_value` on the full projection)
+     * with a sentinel string so secrets are not leaked to MCP clients. Pass
+     * `reveal: true` when the caller explicitly needs the plaintext value.
+     */
     async listApplicationEnvVars(uuid, options) {
         const envVars = await this.request(`/applications/${uuid}/envs`);
-        return options?.summary ? envVars.map(toEnvVarSummary) : envVars;
+        const reveal = options?.reveal === true;
+        if (options?.summary) {
+            const summaries = envVars.map(toEnvVarSummary);
+            return reveal ? summaries : summaries.map(maskEnvVarSummary);
+        }
+        return reveal ? envVars : envVars.map(maskEnvVar);
     }
     async createApplicationEnvVar(uuid, data) {
         return this.request(`/applications/${uuid}/envs`, {
@@ -646,8 +723,16 @@ export class CoolifyClient {
     // ===========================================================================
     // Service Environment Variables
     // ===========================================================================
-    async listServiceEnvVars(uuid) {
-        return this.request(`/services/${uuid}/envs`);
+    /**
+     * List env vars for a service.
+     *
+     * Default behaviour masks `value` (and `real_value`) with a sentinel string
+     * so secrets are not leaked to MCP clients. Pass `reveal: true` when the
+     * caller explicitly needs the plaintext value.
+     */
+    async listServiceEnvVars(uuid, options) {
+        const envVars = await this.request(`/services/${uuid}/envs`);
+        return options?.reveal === true ? envVars : envVars.map(maskEnvVar);
     }
     async createServiceEnvVar(uuid, data) {
         return this.request(`/services/${uuid}/envs`, {
@@ -1011,7 +1096,8 @@ export class CoolifyClient {
                 count: envVars?.length || 0,
                 variables: (envVars || []).map((v) => ({
                     key: v.key,
-                    is_build_time: v.is_build_time ?? false,
+                    is_buildtime: v.is_buildtime ?? false,
+                    is_runtime: v.is_runtime ?? true,
                 })),
             },
             recent_deployments: (deployments || []).slice(0, 5).map((d) => ({
@@ -1277,9 +1363,10 @@ export class CoolifyClient {
      * @param appUuids - Array of application UUIDs
      * @param key - Environment variable key
      * @param value - Environment variable value
-     * @param isBuildTime - Whether this is a build-time variable (default: false)
+     * @param isBuildtime - Sets the build-time flag on the variable when provided
+     * @param isRuntime - Sets the runtime flag on the variable when provided
      */
-    async bulkEnvUpdate(appUuids, key, value, isBuildTime = false) {
+    async bulkEnvUpdate(appUuids, key, value, isBuildtime, isRuntime) {
         // Early return for empty array - avoid unnecessary API call
         if (appUuids.length === 0) {
             return {
@@ -1296,7 +1383,12 @@ export class CoolifyClient {
             uuid,
             name: appMap.get(uuid) || uuid,
         }));
-        const results = await Promise.allSettled(appUuids.map((uuid) => this.updateApplicationEnvVar(uuid, { key, value, is_build_time: isBuildTime })));
+        const results = await Promise.allSettled(appUuids.map((uuid) => this.updateApplicationEnvVar(uuid, {
+            key,
+            value,
+            is_buildtime: isBuildtime,
+            is_runtime: isRuntime,
+        })));
         return this.aggregateBatchResults(resources, results);
     }
     /**

package/dist/lib/mcp-server.js

@@ -682,27 +682,39 @@ export class CoolifyMcpServer extends McpServer {
         // =========================================================================
         // Environment Variables (1 tool - consolidated)
         // =========================================================================
-        this.tool('env_vars', 'Manage env vars for app or service', {
+        this.tool('env_vars', "Manage env vars for app or service. Values are masked by default (returned as '***') to avoid leaking secrets to MCP clients; pass reveal=true on the list action when the caller explicitly needs the plaintext (e.g. 'what is FOO set to?'). Set is_buildtime=false (and/or is_runtime=true) for runtime-only vars to avoid Dockerfile ARG issues with multiline values like PEM keys.", {
             resource: z.enum(['application', 'service']),
             action: z.enum(['list', 'create', 'update', 'delete']),
             uuid: z.string(),
             key: z.string().optional(),
             value: z.string().optional(),
             env_uuid: z.string().optional(),
-        }, async ({ resource, action, uuid, key, value, env_uuid }) => {
+            is_buildtime: z.boolean().optional(),
+            is_runtime: z.boolean().optional(),
+            reveal: z.boolean().optional(),
+        }, async ({ resource, action, uuid, key, value, env_uuid, is_buildtime, is_runtime, reveal, }) => {
             if (resource === 'application') {
                 switch (action) {
                     case 'list':
-                        return wrap(() => this.client.listApplicationEnvVars(uuid, { summary: true }));
+                        return wrap(() => this.client.listApplicationEnvVars(uuid, { summary: true, reveal }));
                     case 'create':
                         if (!key || !value)
                             return { content: [{ type: 'text', text: 'Error: key, value required' }] };
-                        // Note: is_build_time is not passed - Coolify API rejects it for create action
-                        return wrap(() => this.client.createApplicationEnvVar(uuid, { key, value }));
+                        return wrap(() => this.client.createApplicationEnvVar(uuid, {
+                            key,
+                            value,
+                            is_buildtime,
+                            is_runtime,
+                        }));
                     case 'update':
                         if (!key || !value)
                             return { content: [{ type: 'text', text: 'Error: key, value required' }] };
-                        return wrap(() => this.client.updateApplicationEnvVar(uuid, { key, value }));
+                        return wrap(() => this.client.updateApplicationEnvVar(uuid, {
+                            key,
+                            value,
+                            is_buildtime,
+                            is_runtime,
+                        }));
                     case 'delete':
                         if (!env_uuid)
                             return { content: [{ type: 'text', text: 'Error: env_uuid required' }] };
@@ -712,11 +724,16 @@ export class CoolifyMcpServer extends McpServer {
             else {
                 switch (action) {
                     case 'list':
-                        return wrap(() => this.client.listServiceEnvVars(uuid));
+                        return wrap(() => this.client.listServiceEnvVars(uuid, { reveal }));
                     case 'create':
                         if (!key || !value)
                             return { content: [{ type: 'text', text: 'Error: key, value required' }] };
-                        return wrap(() => this.client.createServiceEnvVar(uuid, { key, value }));
+                        return wrap(() => this.client.createServiceEnvVar(uuid, {
+                            key,
+                            value,
+                            is_buildtime,
+                            is_runtime,
+                        }));
                     case 'update':
                         return {
                             content: [
@@ -1056,8 +1073,9 @@ export class CoolifyMcpServer extends McpServer {
             app_uuids: z.array(z.string()),
             key: z.string(),
             value: z.string(),
-            is_build_time: z.boolean().optional(),
-        }, async ({ app_uuids, key, value, is_build_time }) => wrap(() => this.client.bulkEnvUpdate(app_uuids, key, value, is_build_time)));
+            is_buildtime: z.boolean().optional(),
+            is_runtime: z.boolean().optional(),
+        }, async ({ app_uuids, key, value, is_buildtime, is_runtime }) => wrap(() => this.client.bulkEnvUpdate(app_uuids, key, value, is_buildtime, is_runtime)));
         this.tool('stop_all_apps', 'EMERGENCY: Stop all running apps', { confirm: z.literal(true) }, async ({ confirm }) => {
             if (!confirm)
                 return { content: [{ type: 'text', text: 'Error: confirm=true required' }] };

package/dist/lib/parse-headers.d.ts

@@ -0,0 +1 @@
+export declare function parseHeaders(argv: string[]): Record<string, string>;

package/dist/lib/parse-headers.js

@@ -0,0 +1,14 @@
+export function parseHeaders(argv) {
+    const headers = {};
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--header' && i + 1 < argv.length) {
+            const value = argv[i + 1];
+            const colonIndex = value.indexOf(':');
+            if (colonIndex > 0) {
+                headers[value.slice(0, colonIndex).trim()] = value.slice(colonIndex + 1).trim();
+            }
+            i++;
+        }
+    }
+    return headers;
+}

package/dist/types/coolify.d.ts

@@ -5,6 +5,7 @@
 export interface CoolifyConfig {
     baseUrl: string;
     accessToken: string;
+    customHeaders?: Record<string, string>;
 }
 export interface ErrorResponse {
     error?: string;
@@ -343,7 +344,8 @@ export interface EnvironmentVariable {
     uuid: string;
     key: string;
     value: string;
-    is_build_time: boolean;
+    is_buildtime: boolean;
+    is_runtime: boolean;
     is_literal: boolean;
     is_multiline: boolean;
     is_preview: boolean;
@@ -364,7 +366,8 @@ export interface CreateEnvVarRequest {
     is_literal?: boolean;
     is_multiline?: boolean;
     is_shown_once?: boolean;
-    is_build_time?: boolean;
+    is_buildtime?: boolean;
+    is_runtime?: boolean;
 }
 export interface UpdateEnvVarRequest {
     key: string;
@@ -373,7 +376,8 @@ export interface UpdateEnvVarRequest {
     is_literal?: boolean;
     is_multiline?: boolean;
     is_shown_once?: boolean;
-    is_build_time?: boolean;
+    is_buildtime?: boolean;
+    is_runtime?: boolean;
 }
 export interface BulkUpdateEnvVarsRequest {
     data: CreateEnvVarRequest[];
@@ -382,7 +386,8 @@ export interface EnvVarSummary {
     uuid: string;
     key: string;
     value: string;
-    is_build_time: boolean;
+    is_buildtime: boolean;
+    is_runtime: boolean;
 }
 export type DatabaseType = 'postgresql' | 'mysql' | 'mariadb' | 'mongodb' | 'redis' | 'keydb' | 'clickhouse' | 'dragonfly';
 export interface DatabaseLimits {
@@ -843,7 +848,8 @@ export interface ApplicationDiagnostic {
         count: number;
         variables: Array<{
             key: string;
-            is_build_time: boolean;
+            is_buildtime: boolean;
+            is_runtime: boolean;
         }>;
     };
     recent_deployments: Array<{

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@masonator/coolify-mcp",
   "scope": "@masonator",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "mcpName": "io.github.StuMason/coolify",
   "description": "MCP server for Coolify — 38 optimized tools for infrastructure management, diagnostics, and documentation search",
   "type": "module",
@@ -75,8 +75,8 @@
     "globals": "^17.0.0",
     "husky": "^9.0.11",
     "jest": "^30.3.0",
-    "jest-junit": "^16.0.0",
-    "lint-staged": "^16.2.7",
+    "jest-junit": "^17.0.0",
+    "lint-staged": "^17.0.4",
     "markdownlint-cli2": "^0.22.0",
     "prettier": "^3.5.3",
     "shx": "^0.4.0",