@masonator/coolify-mcp 2.5.0 → 2.6.1

package/README.md

@@ -106,6 +106,28 @@ The Coolify API returns extremely verbose responses - a single application can c
 | list_services         | ~367KB        | ~1.2KB           | **99%**   |
 | list_servers          | ~4KB          | ~0.4KB           | **90%**   |
 | list_application_envs | ~3KB/var      | ~0.1KB/var       | **97%**   |
+| deployment get        | ~13KB         | ~1KB             | **92%**   |
+
+### HATEOAS-style Response Actions
+
+Responses include contextual `_actions` suggesting relevant next steps:
+
+```json
+{
+  "data": { "uuid": "abc123", "status": "running" },
+  "_actions": [
+    { "tool": "application_logs", "args": { "uuid": "abc123" }, "hint": "View logs" },
+    {
+      "tool": "control",
+      "args": { "resource": "application", "action": "restart", "uuid": "abc123" },
+      "hint": "Restart"
+    }
+  ],
+  "_pagination": { "next": { "tool": "list_applications", "args": { "page": 2 } } }
+}
+```
+
+This helps AI assistants understand logical next steps without consuming extra tokens.
 
 ### Recommended Workflow
 

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

@@ -84,6 +84,10 @@ describe('CoolifyClient', () => {
         deployment_uuid: 'dep-123',
         application_name: 'test-app',
         status: 'finished',
+        force_rebuild: false,
+        is_webhook: false,
+        is_api: true,
+        restart_only: false,
         created_at: '2024-01-01',
         updated_at: '2024-01-01',
     };
@@ -219,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);
@@ -239,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 () => {
@@ -342,6 +365,18 @@ describe('CoolifyClient', () => {
             expect(result).toEqual({ message: 'Deployed' });
             expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/deploy?tag=my-tag&force=true', expect.any(Object));
         });
+        it('should deploy by Coolify UUID (24 char alphanumeric)', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Deployed' }));
+            // Coolify-style UUID: 24 lowercase alphanumeric chars
+            await client.deployByTagOrUuid('xs0sgs4gog044s4k4c88kgsc', false);
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/deploy?uuid=xs0sgs4gog044s4k4c88kgsc&force=false', expect.any(Object));
+        });
+        it('should deploy by standard UUID format', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Deployed' }));
+            // Standard UUID format with hyphens
+            await client.deployByTagOrUuid('a1b2c3d4-e5f6-7890-abcd-ef1234567890', true);
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/deploy?uuid=a1b2c3d4-e5f6-7890-abcd-ef1234567890&force=true', expect.any(Object));
+        });
     });
     describe('private keys', () => {
         it('should list private keys', async () => {
@@ -464,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
@@ -574,6 +628,98 @@ describe('CoolifyClient', () => {
             expect(result).toEqual(mockEnvironment);
             expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/projects/proj-uuid/production', expect.any(Object));
         });
+        it('should get project environment with missing database types', async () => {
+            // Use environment_id to match (what real API uses)
+            const mockDbSummaries = [
+                {
+                    uuid: 'pg-uuid',
+                    name: 'pg-db',
+                    type: 'postgresql',
+                    status: 'running',
+                    is_public: false,
+                    environment_id: 1,
+                },
+                {
+                    uuid: 'dragonfly-uuid',
+                    name: 'dragonfly-cache',
+                    type: 'standalone-dragonfly',
+                    status: 'running',
+                    is_public: false,
+                    environment_id: 1,
+                },
+                {
+                    uuid: 'other-env-db',
+                    name: 'other-db',
+                    type: 'standalone-keydb',
+                    status: 'running',
+                    is_public: false,
+                    environment_id: 999, // different env
+                },
+            ];
+            mockFetch
+                .mockResolvedValueOnce(mockResponse(mockEnvironment))
+                .mockResolvedValueOnce(mockResponse(mockDbSummaries));
+            const result = await client.getProjectEnvironmentWithDatabases('proj-uuid', 'production');
+            expect(result.uuid).toBe('env-uuid');
+            expect(result.dragonflys).toHaveLength(1);
+            expect(result.dragonflys[0].uuid).toBe('dragonfly-uuid');
+            expect(result.keydbs).toBeUndefined(); // other-env-db is in different env
+        });
+        it('should match databases by environment_uuid fallback', async () => {
+            const mockDbSummaries = [
+                {
+                    uuid: 'keydb-uuid',
+                    name: 'keydb-cache',
+                    type: 'standalone-keydb',
+                    status: 'running',
+                    is_public: false,
+                    environment_uuid: 'env-uuid', // matching by uuid
+                },
+            ];
+            mockFetch
+                .mockResolvedValueOnce(mockResponse(mockEnvironment))
+                .mockResolvedValueOnce(mockResponse(mockDbSummaries));
+            const result = await client.getProjectEnvironmentWithDatabases('proj-uuid', 'production');
+            expect(result.keydbs).toHaveLength(1);
+            expect(result.keydbs[0].uuid).toBe('keydb-uuid');
+        });
+        it('should match databases by environment_name fallback', async () => {
+            const mockDbSummaries = [
+                {
+                    uuid: 'clickhouse-uuid',
+                    name: 'clickhouse-analytics',
+                    type: 'standalone-clickhouse',
+                    status: 'running',
+                    is_public: false,
+                    environment_name: 'production', // matching by name
+                },
+            ];
+            mockFetch
+                .mockResolvedValueOnce(mockResponse(mockEnvironment))
+                .mockResolvedValueOnce(mockResponse(mockDbSummaries));
+            const result = await client.getProjectEnvironmentWithDatabases('proj-uuid', 'production');
+            expect(result.clickhouses).toHaveLength(1);
+            expect(result.clickhouses[0].uuid).toBe('clickhouse-uuid');
+        });
+        it('should not add empty arrays when no missing DB types exist', async () => {
+            const mockDbSummaries = [
+                {
+                    uuid: 'pg-uuid',
+                    name: 'pg-db',
+                    type: 'postgresql', // not a "missing" type
+                    status: 'running',
+                    is_public: false,
+                    environment_id: 1,
+                },
+            ];
+            mockFetch
+                .mockResolvedValueOnce(mockResponse(mockEnvironment))
+                .mockResolvedValueOnce(mockResponse(mockDbSummaries));
+            const result = await client.getProjectEnvironmentWithDatabases('proj-uuid', 'production');
+            expect(result.dragonflys).toBeUndefined();
+            expect(result.keydbs).toBeUndefined();
+            expect(result.clickhouses).toBeUndefined();
+        });
         it('should create a project environment', async () => {
             mockFetch.mockResolvedValueOnce(mockResponse({ uuid: 'new-env-uuid' }));
             const result = await client.createProjectEnvironment('proj-uuid', { name: 'staging' });
@@ -687,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
          *
@@ -729,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
          *
@@ -1086,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');
@@ -1165,12 +1336,47 @@ describe('CoolifyClient', () => {
                 },
             ]);
         });
-        it('should get a deployment', async () => {
+        it('should get a deployment (essential by default, no logs)', async () => {
             mockFetch.mockResolvedValueOnce(mockResponse(mockDeployment));
             const result = await client.getDeployment('dep-uuid');
-            expect(result).toEqual(mockDeployment);
+            // By default, returns DeploymentEssential without logs
+            expect(result).toEqual({
+                uuid: 'dep-uuid',
+                deployment_uuid: 'dep-123',
+                application_uuid: undefined,
+                application_name: 'test-app',
+                server_name: undefined,
+                status: 'finished',
+                commit: undefined,
+                force_rebuild: false,
+                is_webhook: false,
+                is_api: true,
+                created_at: '2024-01-01',
+                updated_at: '2024-01-01',
+                logs_available: false,
+                logs_info: undefined,
+            });
             expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/deployments/dep-uuid', expect.any(Object));
         });
+        it('should get a deployment with logs when includeLogs is true', async () => {
+            const deploymentWithLogs = { ...mockDeployment, logs: 'Build started...' };
+            mockFetch.mockResolvedValueOnce(mockResponse(deploymentWithLogs));
+            const result = await client.getDeployment('dep-uuid', { includeLogs: true });
+            // With includeLogs: true, returns full Deployment with logs
+            expect(result).toEqual(deploymentWithLogs);
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/deployments/dep-uuid', expect.any(Object));
+        });
+        it('should include logs_info when deployment has logs but includeLogs is false', async () => {
+            const deploymentWithLogs = { ...mockDeployment, logs: 'Build started...' };
+            mockFetch.mockResolvedValueOnce(mockResponse(deploymentWithLogs));
+            const result = await client.getDeployment('dep-uuid');
+            // Should have logs_info indicating logs are available
+            expect(result).toMatchObject({
+                uuid: 'dep-uuid',
+                logs_available: true,
+                logs_info: 'Logs available (16 chars). Use lines param to retrieve.',
+            });
+        });
         it('should list application deployments', async () => {
             mockFetch.mockResolvedValueOnce(mockResponse([mockDeployment]));
             const result = await client.listApplicationDeployments('app-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 } 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', () => {
@@ -47,6 +53,7 @@ describe('CoolifyMcpServer v2', () => {
             // Environment operations
             expect(typeof client.listProjectEnvironments).toBe('function');
             expect(typeof client.getProjectEnvironment).toBe('function');
+            expect(typeof client.getProjectEnvironmentWithDatabases).toBe('function');
             expect(typeof client.createProjectEnvironment).toBe('function');
             expect(typeof client.deleteProjectEnvironment).toBe('function');
             // Application operations
@@ -186,3 +193,124 @@ describe('truncateLogs', () => {
         expect(result.length).toBe(100);
     });
 });
+// =============================================================================
+// Action Generators Tests
+// =============================================================================
+describe('getApplicationActions', () => {
+    it('should return view logs action for all apps', () => {
+        const actions = getApplicationActions('app-uuid', 'stopped');
+        expect(actions).toContainEqual({
+            tool: 'application_logs',
+            args: { uuid: 'app-uuid' },
+            hint: 'View logs',
+        });
+    });
+    it('should return restart/stop actions for running apps', () => {
+        const actions = getApplicationActions('app-uuid', 'running');
+        expect(actions).toContainEqual({
+            tool: 'control',
+            args: { resource: 'application', action: 'restart', uuid: 'app-uuid' },
+            hint: 'Restart',
+        });
+        expect(actions).toContainEqual({
+            tool: 'control',
+            args: { resource: 'application', action: 'stop', uuid: 'app-uuid' },
+            hint: 'Stop',
+        });
+    });
+    it('should return start action for stopped apps', () => {
+        const actions = getApplicationActions('app-uuid', 'stopped');
+        expect(actions).toContainEqual({
+            tool: 'control',
+            args: { resource: 'application', action: 'start', uuid: 'app-uuid' },
+            hint: 'Start',
+        });
+    });
+    it('should handle running:healthy status', () => {
+        const actions = getApplicationActions('app-uuid', 'running:healthy');
+        expect(actions.some((a) => a.hint === 'Restart')).toBe(true);
+        expect(actions.some((a) => a.hint === 'Stop')).toBe(true);
+    });
+    it('should handle undefined status', () => {
+        const actions = getApplicationActions('app-uuid', undefined);
+        expect(actions).toContainEqual({
+            tool: 'control',
+            args: { resource: 'application', action: 'start', uuid: 'app-uuid' },
+            hint: 'Start',
+        });
+    });
+});
+describe('getDeploymentActions', () => {
+    it('should return cancel action for in_progress deployments', () => {
+        const actions = getDeploymentActions('dep-uuid', 'in_progress', 'app-uuid');
+        expect(actions).toContainEqual({
+            tool: 'deployment',
+            args: { action: 'cancel', uuid: 'dep-uuid' },
+            hint: 'Cancel',
+        });
+    });
+    it('should return cancel action for queued deployments', () => {
+        const actions = getDeploymentActions('dep-uuid', 'queued', 'app-uuid');
+        expect(actions).toContainEqual({
+            tool: 'deployment',
+            args: { action: 'cancel', uuid: 'dep-uuid' },
+            hint: 'Cancel',
+        });
+    });
+    it('should return app actions when appUuid provided', () => {
+        const actions = getDeploymentActions('dep-uuid', 'finished', 'app-uuid');
+        expect(actions).toContainEqual({
+            tool: 'get_application',
+            args: { uuid: 'app-uuid' },
+            hint: 'View app',
+        });
+        expect(actions).toContainEqual({
+            tool: 'application_logs',
+            args: { uuid: 'app-uuid' },
+            hint: 'App logs',
+        });
+    });
+    it('should not return cancel for finished deployments', () => {
+        const actions = getDeploymentActions('dep-uuid', 'finished', 'app-uuid');
+        expect(actions.some((a) => a.hint === 'Cancel')).toBe(false);
+    });
+    it('should return empty actions when no appUuid and not in_progress', () => {
+        const actions = getDeploymentActions('dep-uuid', 'finished', undefined);
+        expect(actions).toEqual([]);
+    });
+});
+describe('getPagination', () => {
+    it('should return undefined when count is less than perPage and page is 1', () => {
+        const result = getPagination('list_apps', 1, 50, 30);
+        expect(result).toBeUndefined();
+    });
+    it('should return next when count equals or exceeds perPage', () => {
+        const result = getPagination('list_apps', 1, 50, 50);
+        expect(result).toEqual({
+            next: { tool: 'list_apps', args: { page: 2, per_page: 50 } },
+        });
+    });
+    it('should return both prev and next for middle pages', () => {
+        const result = getPagination('list_apps', 2, 50, 50);
+        expect(result).toEqual({
+            prev: { tool: 'list_apps', args: { page: 1, per_page: 50 } },
+            next: { tool: 'list_apps', args: { page: 3, per_page: 50 } },
+        });
+    });
+    it('should return prev when page > 1 and count < perPage', () => {
+        const result = getPagination('list_apps', 3, 50, 20);
+        expect(result).toEqual({
+            prev: { tool: 'list_apps', args: { page: 2, per_page: 50 } },
+        });
+    });
+    it('should use default page and perPage when undefined', () => {
+        const result = getPagination('list_apps', undefined, undefined, 100);
+        expect(result).toEqual({
+            next: { tool: 'list_apps', args: { page: 2, per_page: 50 } },
+        });
+    });
+    it('should return undefined when count is undefined', () => {
+        const result = getPagination('list_apps', 1, 50, undefined);
+        expect(result).toBeUndefined();
+    });
+});

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

@@ -2,7 +2,7 @@
  * Coolify API Client
  * Complete HTTP client for the Coolify API v1
  */
-import type { CoolifyConfig, DeleteOptions, MessageResponse, UuidResponse, Server, ServerResource, ServerDomain, ServerValidation, CreateServerRequest, UpdateServerRequest, Project, CreateProjectRequest, UpdateProjectRequest, Environment, CreateEnvironmentRequest, Application, CreateApplicationPublicRequest, CreateApplicationPrivateGHRequest, CreateApplicationPrivateKeyRequest, CreateApplicationDockerfileRequest, CreateApplicationDockerImageRequest, CreateApplicationDockerComposeRequest, UpdateApplicationRequest, ApplicationActionResponse, EnvironmentVariable, EnvVarSummary, CreateEnvVarRequest, UpdateEnvVarRequest, BulkUpdateEnvVarsRequest, Database, UpdateDatabaseRequest, CreatePostgresqlRequest, CreateMysqlRequest, CreateMariadbRequest, CreateMongodbRequest, CreateRedisRequest, CreateKeydbRequest, CreateClickhouseRequest, CreateDragonflyRequest, CreateDatabaseResponse, DatabaseBackup, BackupExecution, CreateDatabaseBackupRequest, UpdateDatabaseBackupRequest, Service, CreateServiceRequest, UpdateServiceRequest, ServiceCreateResponse, Deployment, Team, TeamMember, PrivateKey, CreatePrivateKeyRequest, UpdatePrivateKeyRequest, GitHubApp, CreateGitHubAppRequest, UpdateGitHubAppRequest, GitHubAppUpdateResponse, CloudToken, CreateCloudTokenRequest, UpdateCloudTokenRequest, CloudTokenValidation, Version, ApplicationDiagnostic, ServerDiagnostic, InfrastructureIssuesReport, BatchOperationResult } from '../types/coolify.js';
+import type { CoolifyConfig, DeleteOptions, MessageResponse, UuidResponse, Server, ServerResource, ServerDomain, ServerValidation, CreateServerRequest, UpdateServerRequest, Project, CreateProjectRequest, UpdateProjectRequest, Environment, CreateEnvironmentRequest, Application, CreateApplicationPublicRequest, CreateApplicationPrivateGHRequest, CreateApplicationPrivateKeyRequest, CreateApplicationDockerfileRequest, CreateApplicationDockerImageRequest, CreateApplicationDockerComposeRequest, UpdateApplicationRequest, ApplicationActionResponse, EnvironmentVariable, EnvVarSummary, CreateEnvVarRequest, UpdateEnvVarRequest, BulkUpdateEnvVarsRequest, Database, UpdateDatabaseRequest, CreatePostgresqlRequest, CreateMysqlRequest, CreateMariadbRequest, CreateMongodbRequest, CreateRedisRequest, CreateKeydbRequest, CreateClickhouseRequest, CreateDragonflyRequest, CreateDatabaseResponse, DatabaseBackup, BackupExecution, CreateDatabaseBackupRequest, UpdateDatabaseBackupRequest, Service, CreateServiceRequest, UpdateServiceRequest, ServiceCreateResponse, Deployment, DeploymentEssential, Team, TeamMember, PrivateKey, CreatePrivateKeyRequest, UpdatePrivateKeyRequest, GitHubApp, CreateGitHubAppRequest, UpdateGitHubAppRequest, GitHubAppUpdateResponse, CloudToken, CreateCloudTokenRequest, UpdateCloudTokenRequest, CloudTokenValidation, Version, ApplicationDiagnostic, ServerDiagnostic, InfrastructureIssuesReport, BatchOperationResult } from '../types/coolify.js';
 export interface ListOptions {
     page?: number;
     per_page?: number;
@@ -35,6 +35,9 @@ export interface DatabaseSummary {
     type: string;
     status: string;
     is_public: boolean;
+    environment_uuid?: string;
+    environment_name?: string;
+    environment_id?: number;
 }
 export interface ServiceSummary {
     uuid: string;
@@ -89,6 +92,17 @@ export declare class CoolifyClient {
     deleteProject(uuid: string): Promise<MessageResponse>;
     listProjectEnvironments(projectUuid: string): Promise<Environment[]>;
     getProjectEnvironment(projectUuid: string, environmentNameOrUuid: string): Promise<Environment>;
+    /**
+     * Get environment with missing database types (dragonfly, keydb, clickhouse).
+     * Coolify API omits these from the environment endpoint - we cross-reference
+     * with listDatabases using lightweight summaries.
+     * @see https://github.com/StuMason/coolify-mcp/issues/88
+     */
+    getProjectEnvironmentWithDatabases(projectUuid: string, environmentNameOrUuid: string): Promise<Environment & {
+        dragonflys?: DatabaseSummary[];
+        keydbs?: DatabaseSummary[];
+        clickhouses?: DatabaseSummary[];
+    }>;
     createProjectEnvironment(projectUuid: string, data: CreateEnvironmentRequest): Promise<UuidResponse>;
     deleteProjectEnvironment(projectUuid: string, environmentNameOrUuid: string): Promise<MessageResponse>;
     listApplications(options?: ListOptions): Promise<Application[] | ApplicationSummary[]>;
@@ -143,7 +157,9 @@ export declare class CoolifyClient {
     updateServiceEnvVar(uuid: string, data: UpdateEnvVarRequest): Promise<MessageResponse>;
     deleteServiceEnvVar(uuid: string, envUuid: string): Promise<MessageResponse>;
     listDeployments(options?: ListOptions): Promise<Deployment[] | DeploymentSummary[]>;
-    getDeployment(uuid: string): Promise<Deployment>;
+    getDeployment(uuid: string, options?: {
+        includeLogs?: boolean;
+    }): Promise<Deployment | DeploymentEssential>;
     deployByTagOrUuid(tagOrUuid: string, force?: boolean): Promise<MessageResponse>;
     listApplicationDeployments(appUuid: string): Promise<Deployment[]>;
     listTeams(): Promise<Team[]>;

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
 // =============================================================================
@@ -38,12 +51,17 @@ function toApplicationSummary(app) {
     };
 }
 function toDatabaseSummary(db) {
+    // API returns database_type not type, and environment_id not environment_uuid
+    const raw = db;
     return {
         uuid: db.uuid,
         name: db.name,
-        type: db.type,
+        type: db.type || raw.database_type,
         status: db.status,
         is_public: db.is_public,
+        environment_uuid: db.environment_uuid,
+        environment_name: db.environment_name,
+        environment_id: raw.environment_id,
     };
 }
 function toServiceSummary(svc) {
@@ -64,6 +82,26 @@ function toDeploymentSummary(dep) {
         created_at: dep.created_at,
     };
 }
+function toDeploymentEssential(dep) {
+    return {
+        uuid: dep.uuid,
+        deployment_uuid: dep.deployment_uuid,
+        application_uuid: dep.application_uuid,
+        application_name: dep.application_name,
+        server_name: dep.server_name,
+        status: dep.status,
+        commit: dep.commit,
+        force_rebuild: dep.force_rebuild,
+        is_webhook: dep.is_webhook,
+        is_api: dep.is_api,
+        created_at: dep.created_at,
+        updated_at: dep.updated_at,
+        logs_available: !!dep.logs,
+        logs_info: dep.logs
+            ? `Logs available (${dep.logs.length} chars). Use lines param to retrieve.`
+            : undefined,
+    };
+}
 function toProjectSummary(proj) {
     return {
         uuid: proj.uuid,
@@ -126,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}`;
                 }
@@ -256,6 +294,32 @@ export class CoolifyClient {
     async getProjectEnvironment(projectUuid, environmentNameOrUuid) {
         return this.request(`/projects/${projectUuid}/${environmentNameOrUuid}`);
     }
+    /**
+     * Get environment with missing database types (dragonfly, keydb, clickhouse).
+     * Coolify API omits these from the environment endpoint - we cross-reference
+     * with listDatabases using lightweight summaries.
+     * @see https://github.com/StuMason/coolify-mcp/issues/88
+     */
+    async getProjectEnvironmentWithDatabases(projectUuid, environmentNameOrUuid) {
+        const [environment, dbSummaries] = await Promise.all([
+            this.getProjectEnvironment(projectUuid, environmentNameOrUuid),
+            this.listDatabases({ summary: true }),
+        ]);
+        // Filter for this environment's missing database types
+        // API uses environment_id, not environment_uuid
+        const envDbs = dbSummaries.filter((db) => db.environment_id === environment.id ||
+            db.environment_uuid === environment.uuid ||
+            db.environment_name === environment.name);
+        const dragonflys = envDbs.filter((db) => db.type?.includes('dragonfly'));
+        const keydbs = envDbs.filter((db) => db.type?.includes('keydb'));
+        const clickhouses = envDbs.filter((db) => db.type?.includes('clickhouse'));
+        return {
+            ...environment,
+            ...(dragonflys.length > 0 && { dragonflys }),
+            ...(keydbs.length > 0 && { keydbs }),
+            ...(clickhouses.length > 0 && { clickhouses }),
+        };
+    }
     async createProjectEnvironment(projectUuid, data) {
         return this.request(`/projects/${projectUuid}/environments`, {
             method: 'POST',
@@ -312,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) {
@@ -496,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) {
@@ -569,11 +649,14 @@ export class CoolifyClient {
             ? deployments.map(toDeploymentSummary)
             : deployments;
     }
-    async getDeployment(uuid) {
-        return this.request(`/deployments/${uuid}`);
+    async getDeployment(uuid, options) {
+        const deployment = await this.request(`/deployments/${uuid}`);
+        return options?.includeLogs ? deployment : toDeploymentEssential(deployment);
     }
     async deployByTagOrUuid(tagOrUuid, force = false) {
-        return this.request(`/deploy?tag=${encodeURIComponent(tagOrUuid)}&force=${force}`, { method: 'GET' });
+        // Detect if the value looks like a UUID or a tag name
+        const param = this.isLikelyUuid(tagOrUuid) ? 'uuid' : 'tag';
+        return this.request(`/deploy?${param}=${encodeURIComponent(tagOrUuid)}&force=${force}`, { method: 'GET' });
     }
     async listApplicationDeployments(appUuid) {
         return this.request(`/applications/${appUuid}/deployments`);

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

@@ -1,15 +1,22 @@
 /**
- * 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 } from '../types/coolify.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.
  */
 export declare function truncateLogs(logs: string, lineLimit?: number, charLimit?: number): string;
+/** Generate contextual actions for an application based on its status */
+export declare function getApplicationActions(uuid: string, status?: string): ResponseAction[];
+/** Generate contextual actions for a deployment */
+export declare function getDeploymentActions(uuid: string, status: string, appUuid?: string): ResponseAction[];
+/** Generate pagination info for list endpoints */
+export declare function getPagination(tool: string, page?: number, perPage?: number, count?: number): ResponsePagination | undefined;
 export declare class CoolifyMcpServer extends McpServer {
     private readonly client;
     constructor(config: CoolifyConfig);

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()
@@ -39,6 +41,82 @@ export function truncateLogs(logs, lineLimit = 200, charLimit = 50000) {
     }
     return truncatedLogs;
 }
+// =============================================================================
+// Action Generators for HATEOAS-style responses
+// =============================================================================
+/** Generate contextual actions for an application based on its status */
+export function getApplicationActions(uuid, status) {
+    const actions = [
+        { tool: 'application_logs', args: { uuid }, hint: 'View logs' },
+    ];
+    const s = (status || '').toLowerCase();
+    if (s.includes('running')) {
+        actions.push({
+            tool: 'control',
+            args: { resource: 'application', action: 'restart', uuid },
+            hint: 'Restart',
+        });
+        actions.push({
+            tool: 'control',
+            args: { resource: 'application', action: 'stop', uuid },
+            hint: 'Stop',
+        });
+    }
+    else {
+        actions.push({
+            tool: 'control',
+            args: { resource: 'application', action: 'start', uuid },
+            hint: 'Start',
+        });
+    }
+    return actions;
+}
+/** Generate contextual actions for a deployment */
+export function getDeploymentActions(uuid, status, appUuid) {
+    const actions = [];
+    if (status === 'in_progress' || status === 'queued') {
+        actions.push({ tool: 'deployment', args: { action: 'cancel', uuid }, hint: 'Cancel' });
+    }
+    if (appUuid) {
+        actions.push({ tool: 'get_application', args: { uuid: appUuid }, hint: 'View app' });
+        actions.push({ tool: 'application_logs', args: { uuid: appUuid }, hint: 'App logs' });
+    }
+    return actions;
+}
+/** Generate pagination info for list endpoints */
+export function getPagination(tool, page, perPage, count) {
+    const p = page ?? 1;
+    const pp = perPage ?? 50;
+    if (!count || count < pp) {
+        return p > 1 ? { prev: { tool, args: { page: p - 1, per_page: pp } } } : undefined;
+    }
+    return {
+        ...(p > 1 && { prev: { tool, args: { page: p - 1, per_page: pp } } }),
+        next: { tool, args: { page: p + 1, per_page: pp } },
+    };
+}
+/** Wrap handler with error handling and HATEOAS actions */
+function wrapWithActions(fn, getActions, getPaginationFn) {
+    return fn()
+        .then((result) => {
+        const actions = getActions?.(result) ?? [];
+        const pagination = getPaginationFn?.(result);
+        const response = { data: result };
+        if (actions.length > 0)
+            response._actions = actions;
+        if (pagination)
+            response._pagination = pagination;
+        return { content: [{ type: 'text', text: JSON.stringify(response, null, 2) }] };
+    })
+        .catch((error) => ({
+        content: [
+            {
+                type: 'text',
+                text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+            },
+        ],
+    }));
+}
 export class CoolifyMcpServer extends McpServer {
     constructor(config) {
         super({ name: 'coolify', version: VERSION });
@@ -150,7 +228,7 @@ export class CoolifyMcpServer extends McpServer {
         // =========================================================================
         // Environments (1 tool - consolidated CRUD)
         // =========================================================================
-        this.tool('environments', 'Manage environments: list/get/create/delete', {
+        this.tool('environments', 'Manage environments: list/get/create/delete (get includes dragonfly/keydb/clickhouse DBs missing from API)', {
             action: z.enum(['list', 'get', 'create', 'delete']),
             project_uuid: z.string(),
             name: z.string().optional(),
@@ -162,7 +240,8 @@ export class CoolifyMcpServer extends McpServer {
                 case 'get':
                     if (!name)
                         return { content: [{ type: 'text', text: 'Error: name required' }] };
-                    return wrap(() => this.client.getProjectEnvironment(project_uuid, name));
+                    // Use enhanced method that includes missing DB types (#88)
+                    return wrap(() => this.client.getProjectEnvironmentWithDatabases(project_uuid, name));
                 case 'create':
                     if (!name)
                         return { content: [{ type: 'text', text: 'Error: name required' }] };
@@ -176,8 +255,8 @@ export class CoolifyMcpServer extends McpServer {
         // =========================================================================
         // Applications (4 tools)
         // =========================================================================
-        this.tool('list_applications', 'List apps (summary)', { page: z.number().optional(), per_page: z.number().optional() }, async ({ page, per_page }) => wrap(() => this.client.listApplications({ page, per_page, summary: true })));
-        this.tool('get_application', 'App details', { uuid: z.string() }, async ({ uuid }) => wrap(() => this.client.getApplication(uuid)));
+        this.tool('list_applications', 'List apps (summary)', { page: z.number().optional(), per_page: z.number().optional() }, async ({ page, per_page }) => wrapWithActions(() => this.client.listApplications({ page, per_page, summary: true }), undefined, (result) => getPagination('list_applications', page, per_page, result.length)));
+        this.tool('get_application', 'App details', { uuid: z.string() }, async ({ uuid }) => wrapWithActions(() => this.client.getApplication(uuid), (app) => getApplicationActions(app.uuid, app.status)));
         this.tool('application', 'Manage app: create/update/delete', {
             action: z.enum([
                 'create_public',
@@ -443,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;
@@ -504,7 +586,36 @@ export class CoolifyMcpServer extends McpServer {
                     restart: (u) => this.client.restartService(u),
                 },
             };
-            return wrap(() => methods[resource][action](uuid));
+            // Generate contextual actions based on resource type and action taken
+            const getControlActions = () => {
+                const actions = [];
+                if (resource === 'application') {
+                    actions.push({ tool: 'application_logs', args: { uuid }, hint: 'View logs' });
+                    actions.push({ tool: 'get_application', args: { uuid }, hint: 'Check status' });
+                    if (action === 'start' || action === 'restart') {
+                        actions.push({
+                            tool: 'control',
+                            args: { resource: 'application', action: 'stop', uuid },
+                            hint: 'Stop',
+                        });
+                    }
+                    else {
+                        actions.push({
+                            tool: 'control',
+                            args: { resource: 'application', action: 'start', uuid },
+                            hint: 'Start',
+                        });
+                    }
+                }
+                else if (resource === 'database') {
+                    actions.push({ tool: 'get_database', args: { uuid }, hint: 'Check status' });
+                }
+                else if (resource === 'service') {
+                    actions.push({ tool: 'get_service', args: { uuid }, hint: 'Check status' });
+                }
+                return actions;
+            };
+            return wrapWithActions(() => methods[resource][action](uuid), getControlActions);
         });
         // =========================================================================
         // Environment Variables (1 tool - consolidated)
@@ -516,8 +627,7 @@ export class CoolifyMcpServer extends McpServer {
             key: z.string().optional(),
             value: z.string().optional(),
             env_uuid: z.string().optional(),
-            is_build_time: z.boolean().optional(),
-        }, async ({ resource, action, uuid, key, value, env_uuid, is_build_time }) => {
+        }, async ({ resource, action, uuid, key, value, env_uuid }) => {
             if (resource === 'application') {
                 switch (action) {
                     case 'list':
@@ -525,7 +635,8 @@ export class CoolifyMcpServer extends McpServer {
                     case 'create':
                         if (!key || !value)
                             return { content: [{ type: 'text', text: 'Error: key, value required' }] };
-                        return wrap(() => this.client.createApplicationEnvVar(uuid, { key, value, is_build_time }));
+                        // Note: is_build_time is not passed - Coolify API rejects it for create action
+                        return wrap(() => this.client.createApplicationEnvVar(uuid, { key, value }));
                     case 'update':
                         if (!key || !value)
                             return { content: [{ type: 'text', text: 'Error: key, value required' }] };
@@ -560,23 +671,30 @@ export class CoolifyMcpServer extends McpServer {
         // =========================================================================
         // Deployments (3 tools)
         // =========================================================================
-        this.tool('list_deployments', 'List deployments (summary)', { page: z.number().optional(), per_page: z.number().optional() }, async ({ page, per_page }) => wrap(() => this.client.listDeployments({ page, per_page, summary: true })));
-        this.tool('deploy', 'Deploy by tag/UUID', { tag_or_uuid: z.string(), force: z.boolean().optional() }, async ({ tag_or_uuid, force }) => wrap(() => this.client.deployByTagOrUuid(tag_or_uuid, force)));
-        this.tool('deployment', 'Manage deployment: get/cancel/list_for_app (logs truncated to last 200 lines/50K chars by default)', {
+        this.tool('list_deployments', 'List deployments (summary)', { page: z.number().optional(), per_page: z.number().optional() }, async ({ page, per_page }) => wrapWithActions(() => this.client.listDeployments({ page, per_page, summary: true }), undefined, (result) => getPagination('list_deployments', page, per_page, result.length)));
+        this.tool('deploy', 'Deploy by tag/UUID', { tag_or_uuid: z.string(), force: z.boolean().optional() }, async ({ tag_or_uuid, force }) => wrapWithActions(() => this.client.deployByTagOrUuid(tag_or_uuid, force), () => [{ tool: 'list_deployments', args: {}, hint: 'Check deployment status' }]));
+        this.tool('deployment', 'Manage deployment: get/cancel/list_for_app (logs excluded by default, use lines param to include)', {
             action: z.enum(['get', 'cancel', 'list_for_app']),
             uuid: z.string(),
-            lines: z.number().optional(), // Limit log output to last N lines (default: 200)
+            lines: z.number().optional(), // Include logs truncated to last N lines (omit for no logs)
             max_chars: z.number().optional(), // Limit log output to last N chars (default: 50000)
         }, async ({ action, uuid, lines, max_chars }) => {
             switch (action) {
                 case 'get':
-                    return wrap(async () => {
-                        const deployment = await this.client.getDeployment(uuid);
-                        if (deployment.logs) {
-                            deployment.logs = truncateLogs(deployment.logs, lines ?? 200, max_chars ?? 50000);
-                        }
-                        return deployment;
-                    });
+                    // If lines param specified, include logs and truncate
+                    if (lines !== undefined) {
+                        return wrapWithActions(async () => {
+                            const deployment = (await this.client.getDeployment(uuid, {
+                                includeLogs: true,
+                            }));
+                            if (deployment.logs) {
+                                deployment.logs = truncateLogs(deployment.logs, lines, max_chars ?? 50000);
+                            }
+                            return deployment;
+                        }, (dep) => getDeploymentActions(dep.uuid, dep.status, dep.application_uuid));
+                    }
+                    // Otherwise return essential info without logs
+                    return wrapWithActions(() => this.client.getDeployment(uuid), (dep) => getDeploymentActions(dep.uuid, dep.status, dep.application_uuid));
                 case 'cancel':
                     return wrap(() => this.client.cancelDeployment(uuid));
                 case 'list_for_app':

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;
@@ -901,3 +899,34 @@ export interface BatchOperationResult {
         error: string;
     }>;
 }
+export interface ResponseAction {
+    tool: string;
+    args: Record<string, string | number | boolean>;
+    hint: string;
+}
+export interface ResponsePagination {
+    next?: {
+        tool: string;
+        args: Record<string, number>;
+    };
+    prev?: {
+        tool: string;
+        args: Record<string, number>;
+    };
+}
+export interface DeploymentEssential {
+    uuid: string;
+    deployment_uuid: string;
+    application_uuid?: string;
+    application_name?: string;
+    server_name?: string;
+    status: string;
+    commit?: string;
+    force_rebuild: boolean;
+    is_webhook: boolean;
+    is_api: boolean;
+    created_at: string;
+    updated_at: string;
+    logs_available?: boolean;
+    logs_info?: string;
+}

package/package.json

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