@masonator/coolify-mcp 2.12.0 → 2.13.0

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, jest } from '@jest/globals';
+import { describe, it, expect, beforeEach, afterEach, jest } from '@jest/globals';
 import { CoolifyMcpServer, VERSION, truncateLogs, getApplicationActions, getDeploymentActions, getPagination, } from '../lib/mcp-server.js';
 describe('CoolifyMcpServer v2', () => {
     let server;
@@ -63,6 +63,7 @@ describe('CoolifyMcpServer v2', () => {
             expect(typeof client.createApplicationPrivateGH).toBe('function');
             expect(typeof client.createApplicationPrivateKey).toBe('function');
             expect(typeof client.createApplicationDockerImage).toBe('function');
+            expect(typeof client.createApplicationDockerfile).toBe('function');
             expect(typeof client.updateApplication).toBe('function');
             expect(typeof client.deleteApplication).toBe('function');
             expect(typeof client.getApplicationLogs).toBe('function');
@@ -474,6 +475,36 @@ describe('CoolifyMcpServer v2', () => {
             expect(forwarded).not.toHaveProperty('install_command');
             expect(forwarded).not.toHaveProperty('dockerfile_location');
         });
+        it('forwards fields in create_dockerfile', async () => {
+            const spy = jest
+                .spyOn(server['client'], 'createApplicationDockerfile')
+                .mockResolvedValue({ uuid: 'app-5' });
+            await callApplication(server, {
+                action: 'create_dockerfile',
+                project_uuid: 'proj-uuid',
+                server_uuid: 'server-uuid',
+                dockerfile: 'FROM node:20\nCMD ["node", "index.js"]',
+                dockerfile_location: '/Dockerfile',
+                ports_exposes: '3000',
+                base_directory: '/apps/api',
+            });
+            expect(spy).toHaveBeenCalledWith(expect.objectContaining({
+                project_uuid: 'proj-uuid',
+                server_uuid: 'server-uuid',
+                dockerfile: 'FROM node:20\nCMD ["node", "index.js"]',
+                dockerfile_location: '/Dockerfile',
+                ports_exposes: '3000',
+                base_directory: '/apps/api',
+            }));
+        });
+        it('returns required-param error when create_dockerfile is missing dockerfile', async () => {
+            const result = (await callApplication(server, {
+                action: 'create_dockerfile',
+                project_uuid: 'proj-uuid',
+                server_uuid: 'server-uuid',
+            }));
+            expect(result.content[0].text).toContain('project_uuid, server_uuid, dockerfile required');
+        });
         it('forwards dockerfile_target_build through update (PATCH-only)', async () => {
             const spy = jest.spyOn(server['client'], 'updateApplication').mockResolvedValue({});
             await callApplication(server, {
@@ -494,6 +525,455 @@ describe('CoolifyMcpServer v2', () => {
             expect(updateData).not.toHaveProperty('uuid');
         });
     });
+    describe('database tool handler', () => {
+        // Regression for #217 — the database tool's create action didn't expose
+        // destination_uuid, so Coolify rejected creates on servers with more than
+        // one destination ("Server has multiple destinations. Please provide a
+        // destination_uuid.").
+        const callDatabase = async (srv, args) => {
+            const tool = srv._registeredTools['database'];
+            return tool.handler(args, {});
+        };
+        it('forwards destination_uuid to createPostgresql when provided', async () => {
+            const spy = jest
+                .spyOn(server['client'], 'createPostgresql')
+                .mockResolvedValue({ uuid: 'db-1' });
+            await callDatabase(server, {
+                action: 'create',
+                type: 'postgresql',
+                project_uuid: 'proj-uuid',
+                server_uuid: 'server-uuid',
+                destination_uuid: 'dest-uuid',
+            });
+            expect(spy).toHaveBeenCalledWith(expect.objectContaining({
+                destination_uuid: 'dest-uuid',
+            }));
+        });
+        it('omits destination_uuid from createPostgresql when not provided', async () => {
+            const spy = jest
+                .spyOn(server['client'], 'createPostgresql')
+                .mockResolvedValue({ uuid: 'db-2' });
+            await callDatabase(server, {
+                action: 'create',
+                type: 'postgresql',
+                project_uuid: 'proj-uuid',
+                server_uuid: 'server-uuid',
+            });
+            const forwarded = spy.mock.calls[0]?.[0];
+            expect(forwarded.destination_uuid).toBeUndefined();
+        });
+    });
+    describe('deployment tool handler (#232 essential projection)', () => {
+        // Regression for #232: `deployment {action: get, lines: N}` used to call
+        // getDeployment(uuid, { includeLogs: true }) and spread the RAW upstream
+        // payload into the response — leaking the destination server's
+        // logdrain_custom_config bearer token, sentinel_token, webhook secrets,
+        // and the full docker_compose/application graph. It must now always go
+        // through toDeploymentEssential(), with only the (string) logs attached.
+        const callDeployment = async (srv, args) => {
+            const tool = srv._registeredTools['deployment'];
+            return tool.handler(args, {});
+        };
+        // Mock the raw HTTP layer (not the client) so the test exercises the real
+        // CoolifyClient projection logic, not just the mcp-server spread.
+        const mockFetch = jest.fn();
+        let originalFetch;
+        beforeEach(() => {
+            originalFetch = global.fetch;
+            global.fetch = mockFetch;
+        });
+        afterEach(() => {
+            global.fetch = originalFetch;
+            mockFetch.mockReset();
+        });
+        function mockJsonResponse(data) {
+            return {
+                ok: true,
+                status: 200,
+                statusText: 'OK',
+                headers: new Headers({ 'Content-Type': 'application/json' }),
+                text: async () => JSON.stringify(data),
+            };
+        }
+        // A raw upstream deployment payload shaped like real Coolify responses:
+        // the full application graph plus the destination server object,
+        // including the secrets called out in #232.
+        function rawDeploymentWithSecrets(logsEntryCount) {
+            const logs = JSON.stringify(Array.from({ length: logsEntryCount }, (_, i) => ({
+                output: `log line ${i}`,
+                timestamp: `2026-07-02T00:00:0${i}Z`,
+                hidden: false,
+            })));
+            return {
+                id: 1,
+                uuid: 'dep-uuid',
+                deployment_uuid: 'dep-123',
+                application_uuid: 'app-uuid',
+                application_name: 'test-app',
+                server_name: 'test-server',
+                status: 'finished',
+                commit: 'abc123',
+                force_rebuild: false,
+                is_webhook: false,
+                is_api: true,
+                restart_only: false,
+                created_at: '2024-01-01',
+                updated_at: '2024-01-01',
+                logs,
+                // Raw upstream fields that must never leak through the projection:
+                application: {
+                    uuid: 'app-uuid',
+                    docker_compose: 'x'.repeat(5000),
+                    docker_compose_raw: 'x'.repeat(5000),
+                    custom_labels: 'a'.repeat(2000),
+                    manual_webhook_secret_github: 'ghsecret',
+                    manual_webhook_secret_gitlab: 'glsecret',
+                },
+                destination: {
+                    server: {
+                        uuid: 'server-uuid',
+                        ip: '1.2.3.4',
+                        settings: {
+                            logdrain_custom_config: 'Bearer live-logdrain-token-abc123',
+                            sentinel_token: 'live-sentinel-token-xyz789',
+                        },
+                        proxy: { config: 'y'.repeat(3000) },
+                    },
+                },
+            };
+        }
+        it('returns essential fields + logs only, no leaked secrets or nested graphs', async () => {
+            mockFetch.mockResolvedValueOnce(mockJsonResponse(rawDeploymentWithSecrets(5)));
+            const result = await callDeployment(server, { action: 'get', uuid: 'dep-uuid', lines: 5 });
+            const text = result.content[0].text;
+            expect(text).not.toContain('logdrain');
+            expect(text).not.toContain('sentinel_token');
+            expect(text).not.toContain('manual_webhook_secret');
+            expect(text).not.toContain('docker_compose');
+            expect(text).not.toMatch(/"application":\s*{/);
+            expect(text).not.toMatch(/"server":\s*{/);
+            expect(text).not.toMatch(/"destination":\s*{/);
+            const parsed = JSON.parse(text);
+            expect(parsed.data).toMatchObject({
+                uuid: 'dep-uuid',
+                application_uuid: 'app-uuid',
+                application_name: 'test-app',
+                server_name: 'test-server',
+                status: 'finished',
+            });
+            expect(typeof parsed.data.logs).toBe('string');
+            expect(parsed.data).not.toHaveProperty('application');
+            expect(parsed.data).not.toHaveProperty('destination');
+            expect(parsed.data).not.toHaveProperty('id');
+        });
+        it('keeps the response under 20KB even with a bloated upstream payload', async () => {
+            mockFetch.mockResolvedValueOnce(mockJsonResponse(rawDeploymentWithSecrets(5)));
+            const result = await callDeployment(server, { action: 'get', uuid: 'dep-uuid', lines: 5 });
+            const text = result.content[0].text;
+            expect(text.length).toBeLessThan(20_000);
+        });
+    });
+    describe('scheduled_tasks tool handler', () => {
+        // Regression for #234 — Coolify's `command` column is a 255-char varchar and
+        // rejects longer commands with a bodyless HTTP 500. The zod schema must reject
+        // an over-long command locally, before any HTTP call is attempted.
+        const getScheduledTasksTool = (srv) => srv._registeredTools['scheduled_tasks'];
+        const baseArgs = {
+            resource: 'application',
+            action: 'create',
+            uuid: 'app-uuid',
+            name: 'my-task',
+            frequency: '* * * * *',
+        };
+        it('rejects a command over 255 chars locally, with an actionable message', () => {
+            const createSpy = jest.spyOn(server['client'], 'createApplicationScheduledTask');
+            const updateSpy = jest.spyOn(server['client'], 'updateApplicationScheduledTask');
+            const tool = getScheduledTasksTool(server);
+            const result = tool.inputSchema.safeParse({ ...baseArgs, command: 'a'.repeat(256) });
+            expect(result.success).toBe(false);
+            const error = result.error;
+            expect(error.issues[0]?.message).toContain('Coolify rejects scheduled-task commands longer than 255 chars');
+            // No HTTP call should have been attempted.
+            expect(createSpy).not.toHaveBeenCalled();
+            expect(updateSpy).not.toHaveBeenCalled();
+        });
+        it('accepts a command at exactly 255 chars', () => {
+            const tool = getScheduledTasksTool(server);
+            const result = tool.inputSchema.safeParse({ ...baseArgs, command: 'a'.repeat(255) });
+            expect(result.success).toBe(true);
+        });
+    });
+    describe('scheduled_tasks tool handler - run_once', () => {
+        const callScheduledTasks = async (srv, args) => {
+            const tool = srv._registeredTools['scheduled_tasks'];
+            return tool.handler(args, {});
+        };
+        const baseArgs = {
+            resource: 'application',
+            action: 'run_once',
+            uuid: 'app-uuid',
+            command: 'php artisan migrate',
+            container: 'app',
+            wait_seconds: 10, // small budget -> few poll attempts in tests
+        };
+        const mockTask = {
+            id: 1,
+            uuid: 'task-uuid',
+            enabled: true,
+            name: 'oneoff-abc123',
+            command: 'php artisan migrate',
+            frequency: '* * * * *',
+            timeout: 0,
+            created_at: '',
+            updated_at: '',
+        };
+        beforeEach(() => {
+            // Poll loop uses a real setTimeout by default; override the instance method
+            // directly so tests are instant (jest.spyOn's generic inference struggles
+            // with private methods here, so a plain shadowing assignment is simpler).
+            server.sleep = () => Promise.resolve();
+        });
+        it('validates command and container are required', async () => {
+            const result = await callScheduledTasks(server, {
+                resource: 'application',
+                action: 'run_once',
+                uuid: 'app-uuid',
+            });
+            expect(result.content[0].text).toBe('Error: command, container required');
+        });
+        it('creates a task, polls until a terminal execution, returns its output, and deletes the task', async () => {
+            const createSpy = jest
+                .spyOn(server['client'], 'createApplicationScheduledTask')
+                .mockResolvedValue(mockTask);
+            const listSpy = jest
+                .spyOn(server['client'], 'listApplicationScheduledTaskExecutions')
+                .mockResolvedValueOnce([]) // first poll: nothing yet
+                .mockResolvedValueOnce([
+                {
+                    uuid: 'exec-uuid',
+                    status: 'success',
+                    message: 'Migrated: 2026_01_01_000000_add_col',
+                    retry_count: 0,
+                    created_at: '',
+                    updated_at: '',
+                },
+            ]);
+            const deleteSpy = jest
+                .spyOn(server['client'], 'deleteApplicationScheduledTask')
+                .mockResolvedValue({ message: 'deleted' });
+            const result = await callScheduledTasks(server, baseArgs);
+            expect(createSpy).toHaveBeenCalledWith('app-uuid', expect.objectContaining({
+                command: 'php artisan migrate',
+                frequency: '* * * * *',
+                container: 'app',
+                enabled: true,
+            }));
+            expect(listSpy).toHaveBeenCalledTimes(2);
+            expect(listSpy).toHaveBeenCalledWith('app-uuid', 'task-uuid');
+            expect(deleteSpy).toHaveBeenCalledWith('app-uuid', 'task-uuid');
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.status).toBe('success');
+            expect(parsed.message).toBe('Migrated: 2026_01_01_000000_add_col');
+            expect(parsed.task_uuid).toBe('task-uuid');
+            expect(parsed.cleanup).toContain('deleted');
+        });
+        it('times out when no execution ever appears, and still deletes the task', async () => {
+            jest.spyOn(server['client'], 'createApplicationScheduledTask').mockResolvedValue(mockTask);
+            jest.spyOn(server['client'], 'listApplicationScheduledTaskExecutions').mockResolvedValue([]);
+            const deleteSpy = jest
+                .spyOn(server['client'], 'deleteApplicationScheduledTask')
+                .mockResolvedValue({ message: 'deleted' });
+            const result = await callScheduledTasks(server, baseArgs);
+            expect(deleteSpy).toHaveBeenCalledWith('app-uuid', 'task-uuid');
+            expect(result.content[0].text).toContain('Timed out');
+            expect(result.content[0].text).toContain('task-uuid');
+            expect(result.content[0].text).toContain('deleted');
+        });
+        it('still deletes the task when polling throws, and surfaces the poll error', async () => {
+            jest.spyOn(server['client'], 'createApplicationScheduledTask').mockResolvedValue(mockTask);
+            jest
+                .spyOn(server['client'], 'listApplicationScheduledTaskExecutions')
+                .mockRejectedValue(new Error('network blip'));
+            const deleteSpy = jest
+                .spyOn(server['client'], 'deleteApplicationScheduledTask')
+                .mockResolvedValue({ message: 'deleted' });
+            const result = await callScheduledTasks(server, baseArgs);
+            expect(deleteSpy).toHaveBeenCalledWith('app-uuid', 'task-uuid');
+            expect(result.content[0].text).toContain('network blip');
+            expect(result.content[0].text).toContain('task-uuid');
+        });
+        it('warns loudly with the task UUID when the cleanup delete itself fails', async () => {
+            jest.spyOn(server['client'], 'createApplicationScheduledTask').mockResolvedValue(mockTask);
+            jest.spyOn(server['client'], 'listApplicationScheduledTaskExecutions').mockResolvedValue([
+                {
+                    uuid: 'exec-uuid',
+                    status: 'success',
+                    message: 'ok',
+                    retry_count: 0,
+                    created_at: '',
+                    updated_at: '',
+                },
+            ]);
+            jest
+                .spyOn(server['client'], 'deleteApplicationScheduledTask')
+                .mockRejectedValue(new Error('403 forbidden'));
+            const result = await callScheduledTasks(server, baseArgs);
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.cleanup).toContain('WARNING');
+            expect(parsed.cleanup).toContain('task-uuid');
+            expect(parsed.cleanup).toContain('403 forbidden');
+        });
+        it('supports the service resource', async () => {
+            const createSpy = jest
+                .spyOn(server['client'], 'createServiceScheduledTask')
+                .mockResolvedValue(mockTask);
+            jest.spyOn(server['client'], 'listServiceScheduledTaskExecutions').mockResolvedValue([
+                {
+                    uuid: 'e',
+                    status: 'success',
+                    message: 'ok',
+                    retry_count: 0,
+                    created_at: '',
+                    updated_at: '',
+                },
+            ]);
+            const deleteSpy = jest
+                .spyOn(server['client'], 'deleteServiceScheduledTask')
+                .mockResolvedValue({ message: 'deleted' });
+            await callScheduledTasks(server, { ...baseArgs, resource: 'service', uuid: 'svc-uuid' });
+            expect(createSpy).toHaveBeenCalledWith('svc-uuid', expect.any(Object));
+            expect(deleteSpy).toHaveBeenCalledWith('svc-uuid', 'task-uuid');
+        });
+    });
+    describe('deploy tool handler', () => {
+        // #238 — opt-in `wait` polls the deployment to a terminal status instead
+        // of firing-and-forgetting. The no-wait path must stay byte-for-byte
+        // identical to the pre-#238 behaviour.
+        const callDeploy = async (srv, args) => {
+            const tool = srv._registeredTools['deploy'];
+            return tool.handler(args, {});
+        };
+        const essentialDeployment = (overrides = {}) => ({
+            uuid: 'dep-uuid',
+            deployment_uuid: 'dep-uuid',
+            application_uuid: 'app-uuid',
+            application_name: 'my-app',
+            status: 'in_progress',
+            commit: 'abc123',
+            force_rebuild: false,
+            is_webhook: false,
+            is_api: true,
+            created_at: '2026-01-01T10:00:00Z',
+            updated_at: '2026-01-01T10:00:00Z',
+            ...overrides,
+        });
+        afterEach(() => {
+            jest.useRealTimers();
+        });
+        it('no-wait path is unchanged: triggers deploy and returns immediately', async () => {
+            const spy = jest
+                .spyOn(server['client'], 'deployByTagOrUuid')
+                .mockResolvedValue({ deployments: [{ deployment_uuid: 'dep-uuid' }] });
+            const pollSpy = jest.spyOn(server['client'], 'getDeployment');
+            const result = (await callDeploy(server, { tag_or_uuid: 'my-tag', force: true }));
+            expect(spy).toHaveBeenCalledWith('my-tag', true);
+            expect(pollSpy).not.toHaveBeenCalled();
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.data).toEqual({ deployments: [{ deployment_uuid: 'dep-uuid' }] });
+            expect(parsed._actions).toEqual([
+                { tool: 'list_deployments', args: {}, hint: 'Check deployment status' },
+            ]);
+        });
+        it('wait: true polls until finished', async () => {
+            jest.useFakeTimers();
+            jest
+                .spyOn(server['client'], 'deployByTagOrUuid')
+                .mockResolvedValue({ deployments: [{ deployment_uuid: 'dep-uuid' }] });
+            const getDeploymentSpy = jest
+                .spyOn(server['client'], 'getDeployment')
+                .mockResolvedValueOnce(essentialDeployment({ status: 'in_progress' }))
+                .mockResolvedValueOnce(essentialDeployment({ status: 'finished' }));
+            const resultPromise = callDeploy(server, { tag_or_uuid: 'my-tag', wait: true });
+            await jest.advanceTimersByTimeAsync(5000);
+            const result = await resultPromise;
+            expect(getDeploymentSpy).toHaveBeenCalledTimes(2);
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.data.status).toBe('finished');
+            expect(parsed.data.deployment_uuid).toBe('dep-uuid');
+            expect(parsed.data.logs_tail).toBeUndefined();
+        });
+        it('wait: true returns a bounded log tail on failure, never the raw payload', async () => {
+            jest.useFakeTimers();
+            jest
+                .spyOn(server['client'], 'deployByTagOrUuid')
+                .mockResolvedValue({ deployments: [{ deployment_uuid: 'dep-uuid' }] });
+            jest
+                .spyOn(server['client'], 'getDeployment')
+                .mockImplementation(async (uuid, options) => {
+                if (options?.includeLogs) {
+                    return {
+                        ...essentialDeployment({ status: 'failed' }),
+                        logs: JSON.stringify([{ output: 'build failed: OOM', timestamp: 't1' }]),
+                        // Fields that would only appear on the raw upstream object —
+                        // must never leak into the tool response.
+                        server: { ip: '10.0.0.1', private_key: 'super-secret' },
+                        application: { env_secret: 'shh' },
+                    };
+                }
+                return essentialDeployment({ status: 'failed' });
+            });
+            const resultPromise = callDeploy(server, { tag_or_uuid: 'my-tag', wait: true });
+            const result = await resultPromise;
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.data.status).toBe('failed');
+            expect(parsed.data.deployment_uuid).toBe('dep-uuid');
+            expect(parsed.data.logs_tail).toContain('build failed: OOM');
+            expect(result.content[0].text).not.toContain('private_key');
+            expect(result.content[0].text).not.toContain('env_secret');
+            expect(parsed.data).not.toHaveProperty('server');
+            expect(parsed.data).not.toHaveProperty('application');
+        });
+        it('wait: true returns an explicit timeout with a next-action hint', async () => {
+            jest.useFakeTimers();
+            jest
+                .spyOn(server['client'], 'deployByTagOrUuid')
+                .mockResolvedValue({ deployments: [{ deployment_uuid: 'dep-uuid' }] });
+            jest
+                .spyOn(server['client'], 'getDeployment')
+                .mockResolvedValue(essentialDeployment({ status: 'in_progress' }));
+            const resultPromise = callDeploy(server, {
+                tag_or_uuid: 'my-tag',
+                wait: true,
+                timeout_seconds: 10,
+            });
+            // Let the poll loop exceed the 10s timeout.
+            await jest.advanceTimersByTimeAsync(15_000);
+            const result = await resultPromise;
+            const parsed = JSON.parse(result.content[0].text);
+            expect(parsed.data.status).toBe('in_progress');
+            expect(parsed.data.timed_out).toBe(true);
+            expect(parsed.data.deployment_uuid).toBe('dep-uuid');
+            expect(parsed.data.next_action).toEqual(expect.stringContaining('deployment'));
+        });
+        it('wait: true watches only the first deployment when a tag triggers several', async () => {
+            jest.useFakeTimers();
+            jest.spyOn(server['client'], 'deployByTagOrUuid').mockResolvedValue({
+                deployments: [{ deployment_uuid: 'dep-1' }, { deployment_uuid: 'dep-2' }],
+            });
+            const getDeploymentSpy = jest.spyOn(server['client'], 'getDeployment').mockResolvedValue(essentialDeployment({
+                status: 'finished',
+                deployment_uuid: 'dep-1',
+                uuid: 'dep-1',
+            }));
+            const resultPromise = callDeploy(server, { tag_or_uuid: 'my-tag', wait: true });
+            const result = await resultPromise;
+            const parsed = JSON.parse(result.content[0].text);
+            expect(getDeploymentSpy).toHaveBeenCalledWith('dep-1');
+            expect(getDeploymentSpy).not.toHaveBeenCalledWith('dep-2');
+            expect(parsed.data.deployment_uuid).toBe('dep-1');
+            expect(parsed.data.additional_deployment_uuids).toEqual(['dep-2']);
+        });
+    });
 });
 describe('truncateLogs', () => {
     // Plain text log tests

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, DeploymentEssential, Team, TeamMember, PrivateKey, CreatePrivateKeyRequest, UpdatePrivateKeyRequest, GitHubApp, CreateGitHubAppRequest, UpdateGitHubAppRequest, GitHubAppUpdateResponse, CloudToken, CreateCloudTokenRequest, UpdateCloudTokenRequest, CloudTokenValidation, Version, StorageListResponse, CreateStorageRequest, UpdateStorageRequest, ScheduledTask, ScheduledTaskExecution, CreateScheduledTaskRequest, UpdateScheduledTaskRequest, HetznerLocation, HetznerServerType, HetznerImage, HetznerSSHKey, CreateHetznerServerRequest, CreateHetznerServerResponse, GitHubRepository, GitHubBranch, ApplicationDiagnostic, ServerDiagnostic, InfrastructureIssuesReport, BatchOperationResult, ResourceListItem, ResourceListItemFull } 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, DeployTriggerResponse, Team, TeamMember, PrivateKey, CreatePrivateKeyRequest, UpdatePrivateKeyRequest, GitHubApp, CreateGitHubAppRequest, UpdateGitHubAppRequest, GitHubAppUpdateResponse, CloudToken, CreateCloudTokenRequest, UpdateCloudTokenRequest, CloudTokenValidation, Version, StorageListResponse, CreateStorageRequest, UpdateStorageRequest, ScheduledTask, ScheduledTaskExecution, CreateScheduledTaskRequest, UpdateScheduledTaskRequest, HetznerLocation, HetznerServerType, HetznerImage, HetznerSSHKey, CreateHetznerServerRequest, CreateHetznerServerResponse, GitHubRepository, GitHubBranch, ApplicationDiagnostic, ServerDiagnostic, InfrastructureIssuesReport, BatchOperationResult, ResourceListItem, ResourceListItemFull } from '../types/coolify.js';
 export interface ListOptions {
     page?: number;
     per_page?: number;
@@ -66,6 +66,13 @@ export interface GitHubAppSummary {
     is_public: boolean;
     app_id: number | null;
 }
+/**
+ * Map a failed response's status/path to an actionable hint for known Coolify quirks.
+ * Coolify sometimes returns bodyless errors (e.g. bare `HTTP 500: Internal Server Error`)
+ * that leave the caller guessing at the cause — this appends a short, testable hint for
+ * the cases we've hit in practice. Returns undefined when no known case matches.
+ */
+export declare function errorHint(status: number, path: string): string | undefined;
 /**
  * HTTP client for the Coolify API
  */
@@ -115,6 +122,12 @@ export declare class CoolifyClient {
     createApplicationPrivateKey(data: CreateApplicationPrivateKeyRequest): Promise<UuidResponse>;
     createApplicationDockerfile(data: CreateApplicationDockerfileRequest): Promise<UuidResponse>;
     createApplicationDockerImage(data: CreateApplicationDockerImageRequest): Promise<UuidResponse>;
+    /**
+     * @deprecated Coolify removed POST /applications/dockercompose upstream in
+     * v4.1.0 (coollabsio/coolify commit 6ee75cfa) in favour of POST /services.
+     * This 404s against current Coolify releases; use createService instead.
+     * Not exposed via any MCP tool — see #235.
+     */
     createApplicationDockerCompose(data: CreateApplicationDockerComposeRequest): Promise<UuidResponse>;
     updateApplication(uuid: string, data: UpdateApplicationRequest): Promise<Application>;
     deleteApplication(uuid: string, options?: DeleteOptions): Promise<MessageResponse>;
@@ -162,7 +175,7 @@ export declare class CoolifyClient {
     deleteService(uuid: string, options?: DeleteOptions): Promise<MessageResponse>;
     startService(uuid: string): Promise<MessageResponse>;
     stopService(uuid: string): Promise<MessageResponse>;
-    restartService(uuid: string): Promise<MessageResponse>;
+    restartService(uuid: string, pullLatest?: boolean): Promise<MessageResponse>;
     /**
      * List env vars for a service.
      *
@@ -179,8 +192,8 @@ export declare class CoolifyClient {
     listDeployments(options?: ListOptions): Promise<Deployment[] | DeploymentSummary[]>;
     getDeployment(uuid: string, options?: {
         includeLogs?: boolean;
-    }): Promise<Deployment | DeploymentEssential>;
-    deployByTagOrUuid(tagOrUuid: string, force?: boolean): Promise<MessageResponse>;
+    }): Promise<DeploymentEssential>;
+    deployByTagOrUuid(tagOrUuid: string, force?: boolean): Promise<DeployTriggerResponse>;
     /**
      * List deployments for an application.
      *
@@ -190,13 +203,15 @@ export declare class CoolifyClient {
      * By default returns a DeploymentEssential summary (no `logs` field) because
      * each deployment's log blob can be 30–100KB, and a typical list has 20–35
      * deployments — exceeding MCP response token limits. Pass `includeLogs: true`
-     * to get raw Deployment objects with full build logs.
+     * to also attach the raw log string to each essential projection (never the
+     * raw upstream deployment object, which also embeds the full application/server
+     * graph and secrets).
      */
     listApplicationDeployments(appUuid: string, options?: {
         includeLogs?: boolean;
     }): Promise<{
         count: number;
-        deployments: Deployment[] | DeploymentEssential[];
+        deployments: DeploymentEssential[];
     }>;
     listTeams(): Promise<Team[]>;
     getTeam(id: number): Promise<Team>;