@masonator/coolify-mcp 2.6.0 → 2.6.1

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

@@ -223,18 +223,19 @@ describe('CoolifyClient', () => {
                 body: JSON.stringify(createData),
             }));
         });
-        it('should create a service with docker_compose_raw instead of type', async () => {
+        it('should pass through already base64-encoded docker_compose_raw', async () => {
             const responseData = {
                 uuid: 'compose-uuid',
                 domains: ['custom.example.com'],
             };
             mockFetch.mockResolvedValueOnce(mockResponse(responseData));
+            const base64Value = 'dmVyc2lvbjogIjMiCnNlcnZpY2VzOgogIGFwcDoKICAgIGltYWdlOiBuZ2lueA==';
             const createData = {
                 name: 'custom-compose-service',
                 project_uuid: 'project-uuid',
                 environment_uuid: 'env-uuid',
                 server_uuid: 'server-uuid',
-                docker_compose_raw: 'dmVyc2lvbjogIjMiCnNlcnZpY2VzOgogIGFwcDoKICAgIGltYWdlOiBuZ2lueA==',
+                docker_compose_raw: base64Value,
             };
             const result = await client.createService(createData);
             expect(result).toEqual(responseData);
@@ -243,6 +244,24 @@ describe('CoolifyClient', () => {
                 body: JSON.stringify(createData),
             }));
         });
+        it('should auto base64-encode raw YAML docker_compose_raw', async () => {
+            const responseData = { uuid: 'compose-uuid', domains: ['test.com'] };
+            mockFetch.mockResolvedValueOnce(mockResponse(responseData));
+            const rawYaml = 'services:\n  test:\n    image: nginx';
+            const createData = {
+                name: 'raw-compose',
+                project_uuid: 'project-uuid',
+                environment_uuid: 'env-uuid',
+                server_uuid: 'server-uuid',
+                docker_compose_raw: rawYaml,
+            };
+            await client.createService(createData);
+            const callBody = JSON.parse(mockFetch.mock.calls[0][1]?.body);
+            // Should be base64-encoded in the request
+            expect(callBody.docker_compose_raw).toBe(Buffer.from(rawYaml, 'utf-8').toString('base64'));
+            // Should NOT be the raw YAML
+            expect(callBody.docker_compose_raw).not.toBe(rawYaml);
+        });
     });
     describe('deleteService', () => {
         it('should delete a service', async () => {
@@ -480,6 +499,25 @@ describe('CoolifyClient', () => {
             }, false, 422));
             await expect(client.listServers()).rejects.toThrow('Validation failed. - name: The name field is required.; email: The email must be valid., The email is already taken.');
         });
+        it('should handle validation errors with string messages', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({
+                message: 'Validation failed.',
+                errors: {
+                    docker_compose_raw: 'The docker compose raw field is required.',
+                },
+            }, false, 422));
+            await expect(client.listServers()).rejects.toThrow('Validation failed. - docker_compose_raw: The docker compose raw field is required.');
+        });
+        it('should handle validation errors with mixed array and string messages', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({
+                message: 'Validation failed.',
+                errors: {
+                    name: ['The name field is required.'],
+                    docker_compose_raw: 'The docker compose raw field is required.',
+                },
+            }, false, 422));
+            await expect(client.listServers()).rejects.toThrow('Validation failed. - name: The name field is required.; docker_compose_raw: The docker compose raw field is required.');
+        });
     });
     // =========================================================================
     // Server endpoints - additional coverage
@@ -795,6 +833,17 @@ describe('CoolifyClient', () => {
             expect(result).toEqual({ uuid: 'new-app-uuid' });
             expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/applications/dockercompose', expect.objectContaining({ method: 'POST' }));
         });
+        it('should auto base64-encode docker_compose_raw in createApplicationDockerCompose', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({ uuid: 'new-app-uuid' }));
+            const rawYaml = 'services:\n  app:\n    image: nginx';
+            await client.createApplicationDockerCompose({
+                project_uuid: 'proj-uuid',
+                server_uuid: 'server-uuid',
+                docker_compose_raw: rawYaml,
+            });
+            const callBody = JSON.parse(mockFetch.mock.calls[0][1]?.body);
+            expect(callBody.docker_compose_raw).toBe(Buffer.from(rawYaml, 'utf-8').toString('base64'));
+        });
         /**
          * Issue #76 - Client Layer Behavior Test
          *
@@ -837,6 +886,13 @@ describe('CoolifyClient', () => {
                 body: JSON.stringify({ name: 'updated-app', description: 'new desc' }),
             }));
         });
+        it('should auto base64-encode docker_compose_raw in updateApplication', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse(mockApplication));
+            const rawYaml = 'services:\n  app:\n    image: nginx';
+            await client.updateApplication('app-uuid', { docker_compose_raw: rawYaml });
+            const callBody = JSON.parse(mockFetch.mock.calls[0][1]?.body);
+            expect(callBody.docker_compose_raw).toBe(Buffer.from(rawYaml, 'utf-8').toString('base64'));
+        });
         /**
          * Issue #76 - Client Layer Behavior Test
          *
@@ -1194,6 +1250,13 @@ describe('CoolifyClient', () => {
             const result = await client.updateService('test-uuid', { name: 'updated-service' });
             expect(result.name).toBe('updated-service');
         });
+        it('should auto base64-encode docker_compose_raw in updateService', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse(mockService));
+            const rawYaml = 'services:\n  app:\n    image: nginx';
+            await client.updateService('test-uuid', { docker_compose_raw: rawYaml });
+            const callBody = JSON.parse(mockFetch.mock.calls[0][1]?.body);
+            expect(callBody.docker_compose_raw).toBe(Buffer.from(rawYaml, 'utf-8').toString('base64'));
+        });
         it('should start a service', async () => {
             mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Started' }));
             const result = await client.startService('test-uuid');

package/dist/__tests__/integration/smoke.integration.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Smoke integration tests — quick sanity checks against a real Coolify instance.
+ *
+ * Run with: npm run test:integration
+ *
+ * Prerequisites:
+ * - COOLIFY_URL and COOLIFY_TOKEN environment variables set (from .env)
+ * - Access to a running Coolify instance
+ *
+ * NOTE: These tests make real API calls. The error handling tests rely on the
+ * API rejecting invalid input (nonexistent project_uuid). If Coolify changes
+ * its validation behaviour, these tests may need updating.
+ */
+export {};

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

@@ -0,0 +1,71 @@
+/**
+ * Smoke integration tests — quick sanity checks against a real Coolify instance.
+ *
+ * Run with: npm run test:integration
+ *
+ * Prerequisites:
+ * - COOLIFY_URL and COOLIFY_TOKEN environment variables set (from .env)
+ * - Access to a running Coolify instance
+ *
+ * NOTE: These tests make real API calls. The error handling tests rely on the
+ * API rejecting invalid input (nonexistent project_uuid). If Coolify changes
+ * its validation behaviour, these tests may need updating.
+ */
+import { config } from 'dotenv';
+import { CoolifyClient } from '../../lib/coolify-client.js';
+config();
+const COOLIFY_URL = process.env.COOLIFY_URL;
+const COOLIFY_TOKEN = process.env.COOLIFY_TOKEN;
+const shouldRun = COOLIFY_URL && COOLIFY_TOKEN;
+const describeFn = shouldRun ? describe : describe.skip;
+describeFn('Smoke Integration Tests', () => {
+    let client;
+    beforeAll(() => {
+        if (!COOLIFY_URL || !COOLIFY_TOKEN) {
+            throw new Error('COOLIFY_URL and COOLIFY_TOKEN must be set');
+        }
+        client = new CoolifyClient({
+            baseUrl: COOLIFY_URL,
+            accessToken: COOLIFY_TOKEN,
+        });
+    });
+    describe('connectivity', () => {
+        it('should connect to Coolify API', async () => {
+            const version = await client.getVersion();
+            expect(version).toBeDefined();
+        }, 10000);
+    });
+    describe('error handling', () => {
+        it('should handle validation errors with string messages (issue #107)', async () => {
+            // Creating a service with docker_compose_raw but no type triggers
+            // a validation error where Coolify returns string values, not arrays.
+            const servers = await client.listServers();
+            expect(servers.length).toBeGreaterThan(0);
+            await expect(client.createService({
+                server_uuid: servers[0].uuid,
+                project_uuid: 'nonexistent',
+                environment_name: 'production',
+                docker_compose_raw: 'services:\n  test:\n    image: nginx',
+            })).rejects.toThrow(/./); // Should throw a readable error, not crash
+        }, 15000);
+        it('should produce a readable error message from string validation errors', async () => {
+            const servers = await client.listServers();
+            try {
+                await client.createService({
+                    server_uuid: servers[0].uuid,
+                    project_uuid: 'nonexistent',
+                    environment_name: 'production',
+                    docker_compose_raw: 'services:\n  test:\n    image: nginx',
+                });
+                throw new Error('Expected a validation error to be thrown');
+            }
+            catch (e) {
+                const msg = e.message;
+                // Should NOT contain "join is not a function"
+                expect(msg).not.toContain('join is not a function');
+                // Should contain something useful
+                expect(msg.length).toBeGreaterThan(0);
+            }
+        }, 15000);
+    });
+});

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

@@ -5,8 +5,9 @@
  * CoolifyClient methods are fully tested in coolify-client.test.ts (174 tests).
  * These tests verify MCP server instantiation and structure.
  */
+import { createRequire } from 'module';
 import { describe, it, expect, beforeEach } from '@jest/globals';
-import { CoolifyMcpServer, truncateLogs, getApplicationActions, getDeploymentActions, getPagination, } from '../lib/mcp-server.js';
+import { CoolifyMcpServer, VERSION, truncateLogs, getApplicationActions, getDeploymentActions, getPagination, } from '../lib/mcp-server.js';
 describe('CoolifyMcpServer v2', () => {
     let server;
     beforeEach(() => {
@@ -22,6 +23,11 @@ describe('CoolifyMcpServer v2', () => {
         it('should be an MCP server with connect method', () => {
             expect(typeof server.connect).toBe('function');
         });
+        it('should report version matching package.json', () => {
+            const _require = createRequire(import.meta.url);
+            const { version } = _require('../../package.json');
+            expect(VERSION).toBe(version);
+        });
     });
     describe('client', () => {
         it('should have client instance', () => {

package/dist/lib/coolify-client.js

@@ -15,6 +15,19 @@ function cleanRequestData(data) {
     }
     return cleaned;
 }
+/** Base64-encode a string, passing through values that are already base64. */
+function toBase64(value) {
+    try {
+        const decoded = Buffer.from(value, 'base64').toString('utf-8');
+        if (Buffer.from(decoded, 'utf-8').toString('base64') === value) {
+            return value; // Already valid base64
+        }
+    }
+    catch {
+        // Not base64, encode it
+    }
+    return Buffer.from(value, 'utf-8').toString('base64');
+}
 // =============================================================================
 // Summary Transformers - reduce full objects to essential fields
 // =============================================================================
@@ -151,7 +164,7 @@ export class CoolifyClient {
                 let errorMessage = error.message || `HTTP ${response.status}: ${response.statusText}`;
                 if (error.errors && Object.keys(error.errors).length > 0) {
                     const validationDetails = Object.entries(error.errors)
-                        .map(([field, messages]) => `${field}: ${messages.join(', ')}`)
+                        .map(([field, messages]) => `${field}: ${Array.isArray(messages) ? messages.join(', ') : String(messages)}`)
                         .join('; ');
                     errorMessage = `${errorMessage} - ${validationDetails}`;
                 }
@@ -363,15 +376,23 @@ export class CoolifyClient {
         });
     }
     async createApplicationDockerCompose(data) {
+        const payload = { ...data };
+        if (payload.docker_compose_raw) {
+            payload.docker_compose_raw = toBase64(payload.docker_compose_raw);
+        }
         return this.request('/applications/dockercompose', {
             method: 'POST',
-            body: JSON.stringify(data),
+            body: JSON.stringify(payload),
         });
     }
     async updateApplication(uuid, data) {
+        const payload = { ...data };
+        if (payload.docker_compose_raw) {
+            payload.docker_compose_raw = toBase64(payload.docker_compose_raw);
+        }
         return this.request(`/applications/${uuid}`, {
             method: 'PATCH',
-            body: JSON.stringify(data),
+            body: JSON.stringify(payload),
         });
     }
     async deleteApplication(uuid, options) {
@@ -547,15 +568,23 @@ export class CoolifyClient {
         return this.request(`/services/${uuid}`);
     }
     async createService(data) {
+        const payload = { ...data };
+        if (payload.docker_compose_raw) {
+            payload.docker_compose_raw = toBase64(payload.docker_compose_raw);
+        }
         return this.request('/services', {
             method: 'POST',
-            body: JSON.stringify(data),
+            body: JSON.stringify(payload),
         });
     }
     async updateService(uuid, data) {
+        const payload = { ...data };
+        if (payload.docker_compose_raw) {
+            payload.docker_compose_raw = toBase64(payload.docker_compose_raw);
+        }
         return this.request(`/services/${uuid}`, {
             method: 'PATCH',
-            body: JSON.stringify(data),
+            body: JSON.stringify(payload),
         });
     }
     async deleteService(uuid, options) {

package/dist/lib/mcp-server.d.ts

@@ -1,10 +1,11 @@
 /**
- * Coolify MCP Server v2.4.0
+ * Coolify MCP Server
  * Consolidated tools for efficient token usage
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import type { CoolifyConfig, ResponseAction, ResponsePagination } from '../types/coolify.js';
+export declare const VERSION: string;
 /**
  * Truncate logs by line count and character count.
  * Exported for testing.

package/dist/lib/mcp-server.js

@@ -1,11 +1,13 @@
 /**
- * Coolify MCP Server v2.4.0
+ * Coolify MCP Server
  * Consolidated tools for efficient token usage
  */
+import { createRequire } from 'module';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { CoolifyClient, } from './coolify-client.js';
-const VERSION = '2.5.0';
+const _require = createRequire(import.meta.url);
+export const VERSION = _require('../../package.json').version;
 /** Wrap handler with error handling */
 function wrap(fn) {
     return fn()
@@ -520,7 +522,10 @@ export class CoolifyMcpServer extends McpServer {
             name: z.string().optional(),
             description: z.string().optional(),
             instant_deploy: z.boolean().optional(),
-            docker_compose_raw: z.string().optional(),
+            docker_compose_raw: z
+                .string()
+                .optional()
+                .describe('Raw docker-compose YAML for custom services (auto base64-encoded)'),
             delete_volumes: z.boolean().optional(),
         }, async (args) => {
             const { action, uuid, delete_volumes } = args;

package/dist/types/coolify.d.ts

@@ -10,7 +10,7 @@ export interface ErrorResponse {
     error?: string;
     message: string;
     status?: number;
-    errors?: Record<string, string[]>;
+    errors?: Record<string, string[] | string>;
 }
 export interface DeleteOptions {
     deleteConfigurations?: boolean;
@@ -634,14 +634,12 @@ export interface CreateServiceRequest {
  *    - Wrong: "user:$apr1$hash$here"
  *    - Docker Compose processes $$ → $ for Traefik
  *
- * 3. docker_compose_raw must be base64 encoded when sent to API
- *    - Example: Buffer.from(yamlString).toString('base64')
+ * 3. docker_compose_raw is auto base64-encoded by the client — pass raw YAML
  *
  * Summary for htpasswd with basic auth:
  *   - Generate hash: htpasswd -nb username password
  *   - Replace $ with $$ in the hash
  *   - Disable label escaping in Coolify UI (manual step!)
- *   - Base64 encode the entire docker-compose YAML
  */
 export interface UpdateServiceRequest {
     name?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@masonator/coolify-mcp",
   "scope": "@masonator",
-  "version": "2.6.0",
+  "version": "2.6.1",
   "description": "MCP server implementation for Coolify",
   "type": "module",
   "main": "./dist/index.js",