@masonator/coolify-mcp 2.8.0 → 2.8.1

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

@@ -126,6 +126,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 () => {

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;

package/dist/lib/coolify-client.js

@@ -151,6 +151,7 @@ function toEnvVarSummary(envVar) {
 export class CoolifyClient {
     baseUrl;
     accessToken;
+    customHeaders;
     cachedVersion = null;
     constructor(config) {
         if (!config.baseUrl) {
@@ -161,6 +162,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,6 +186,7 @@ export class CoolifyClient {
                 headers: {
                     'Content-Type': 'application/json',
                     Authorization: `Bearer ${this.accessToken}`,
+                    ...this.customHeaders,
                     ...options.headers,
                 },
             });
@@ -222,6 +236,7 @@ export class CoolifyClient {
         const response = await fetch(url, {
             headers: {
                 Authorization: `Bearer ${this.accessToken}`,
+                ...this.customHeaders,
             },
         });
         if (!response.ok) {

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;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@masonator/coolify-mcp",
   "scope": "@masonator",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "mcpName": "io.github.StuMason/coolify",
   "description": "MCP server for Coolify — 38 optimized tools for infrastructure management, diagnostics, and documentation search",
   "type": "module",