@masonator/coolify-mcp 2.12.1 → 2.13.0

package/README.md

@@ -41,7 +41,7 @@ This MCP server provides **42 token-optimized tools** for **debugging, managemen
 | **Control**          | `control` (start/stop/restart for apps, databases, services)                                                                        |
 | **Env Vars**         | `env_vars` (CRUD + bulk_update for application, service, and database env vars)                                                     |
 | **Storages**         | `storages` (list, create, update, delete persistent/file storages for apps, databases, services)                                    |
-| **Scheduled Tasks**  | `scheduled_tasks` (list, create, update, delete, list_executions for apps and services)                                             |
+| **Scheduled Tasks**  | `scheduled_tasks` (list, create, update, delete, list_executions, run_once for apps and services)                                   |
 | **Deployments**      | `list_deployments`, `deploy`, `deployment` (get, cancel, list_for_app)                                                              |
 | **Private Keys**     | `private_keys` (list, get, create, update, delete via action param)                                                                 |
 | **GitHub Apps**      | `github_apps` (list, get, create, update, delete, list_repos, list_branches)                                                        |
@@ -126,6 +126,39 @@ If your Coolify instance sits behind a Cloudflare Access tunnel or other auth-pr
 
 Multiple `--header` flags can be combined. The reserved headers `Authorization` and `Content-Type` are filtered (with a warning) to prevent silently overriding the Coolify bearer token.
 
+### Multiple Coolify servers
+
+Each running instance of this MCP server is bound to one Coolify (one `COOLIFY_BASE_URL` + token). To work with several Coolify instances, pick whichever of these fits your workflow:
+
+**Per-workspace config (recommended).** Most MCP clients support project-scoped config files (`.mcp.json` / `.cursor/mcp.json` / `.vscode/mcp.json` in the repo root) alongside the global one. Put the Coolify credentials for _that project's_ estate in the project's own config, and "deploy this" automatically routes to the right Coolify whenever you're working in that repo — no server names to remember in conversation.
+
+**Named instances in global config.** Register the server twice (or more) under distinct names, and address them by name in conversation ("deploy this on staging"):
+
+```json
+{
+  "mcpServers": {
+    "coolify-prod": {
+      "command": "npx",
+      "args": ["-y", "@masonator/coolify-mcp"],
+      "env": {
+        "COOLIFY_BASE_URL": "https://prod.coolify.example",
+        "COOLIFY_ACCESS_TOKEN": "..."
+      }
+    },
+    "coolify-staging": {
+      "command": "npx",
+      "args": ["-y", "@masonator/coolify-mcp"],
+      "env": {
+        "COOLIFY_BASE_URL": "https://staging.coolify.example",
+        "COOLIFY_ACCESS_TOKEN": "..."
+      }
+    }
+  }
+}
+```
+
+The MCP server itself can't offer a settings screen or auto-detect the current repo — MCP servers are headless child processes and clients don't pass repo context — so routing lives in your client config, where both patterns above work today (see #164).
+
 ## Context-Optimized Responses
 
 ### Why This Matters
@@ -315,8 +348,9 @@ These tools accept human-friendly identifiers instead of just UUIDs:
 - `list_applications` - List all applications (returns summary)
 - `get_application` - Get application details
 - `application_logs` - Get application logs
-- `application` - Create, update, or delete apps with `action: create_public|create_github|create_key|create_dockerimage|update|delete`
-  - Deploy from public repos, private GitHub, SSH keys, or Docker images
+- `application` - Create, update, or delete apps with `action: create_public|create_github|create_key|create_dockerimage|create_dockerfile|update|delete`
+  - Deploy from public repos, private GitHub, SSH keys, Docker images, or a raw Dockerfile
+  - For docker-compose apps use the `service` tool — Coolify removed `POST /applications/dockercompose` in v4.1.0 in favour of services
   - Configure health checks (path, interval, retries, etc.)
 - `env_vars` - Manage env vars with `resource: application, action: list|create|update|delete`
 - `control` - Start/stop/restart with `resource: application, action: start|stop|restart`

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

@@ -1,5 +1,5 @@
 import { jest, describe, it, expect, beforeEach } from '@jest/globals';
-import { CoolifyClient } from '../lib/coolify-client.js';
+import { CoolifyClient, errorHint } from '../lib/coolify-client.js';
 // Helper to create mock response
 function mockResponse(data, ok = true, status = 200, contentType = 'application/json') {
     const body = contentType.includes('application/json') ? JSON.stringify(data) : String(data);
@@ -403,6 +403,23 @@ 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 parse the deployments envelope Coolify returns for /deploy (#238)', async () => {
+            // Real Coolify returns { deployments: [{ message, resource_uuid, deployment_uuid }] },
+            // one entry per triggered deployment (a tag can match several apps).
+            mockFetch.mockResolvedValueOnce(mockResponse({
+                deployments: [
+                    { message: 'Deployment queued', resource_uuid: 'app-1', deployment_uuid: 'dep-1' },
+                    { message: 'Deployment queued', resource_uuid: 'app-2', deployment_uuid: 'dep-2' },
+                ],
+            }));
+            const result = await client.deployByTagOrUuid('my-tag', true);
+            expect(result).toEqual({
+                deployments: [
+                    { message: 'Deployment queued', resource_uuid: 'app-1', deployment_uuid: 'dep-1' },
+                    { message: 'Deployment queued', resource_uuid: 'app-2', deployment_uuid: 'dep-2' },
+                ],
+            });
+        });
         it('should deploy by Coolify UUID (24 char alphanumeric)', async () => {
             mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Deployed' }));
             // Coolify-style UUID: 24 lowercase alphanumeric chars
@@ -571,6 +588,14 @@ describe('CoolifyClient', () => {
             }, 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.');
         });
+        it('should append a command-length hint on a bodyless 500 from a scheduled-tasks path', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({}, false, 500));
+            await expect(client.createApplicationScheduledTask('app-uuid', {
+                name: 'task',
+                command: 'a'.repeat(300),
+                frequency: '* * * * *',
+            })).rejects.toThrow(/varchar\(255\)/);
+        });
     });
     // =========================================================================
     // Server endpoints - additional coverage
@@ -2462,6 +2487,43 @@ describe('CoolifyClient', () => {
                 const result = await client.diagnoseApplication(testAppUuid);
                 expect(result.health.issues).toContain('2 failed deployment(s) in last 5');
             });
+            it('should flag stale code when app is running but the latest deployment failed', async () => {
+                const staleDeployments = [
+                    { ...mockDeployments[0], uuid: 'deploy-latest', status: 'failed' },
+                    { ...mockDeployments[1], status: 'finished' },
+                ];
+                mockFetch
+                    .mockResolvedValueOnce(mockResponse(mockApp)) // status: running:healthy
+                    .mockResolvedValueOnce(mockResponse(mockLogs))
+                    .mockResolvedValueOnce(mockResponse(mockEnvVars))
+                    .mockResolvedValueOnce(mockResponse({ count: staleDeployments.length, deployments: staleDeployments }));
+                const result = await client.diagnoseApplication(testAppUuid);
+                expect(result.health.status).toBe('unhealthy');
+                expect(result.health.issues).toContain('Running container predates the last (failed) deployment (deploy-latest) — the app is serving stale code. Use the deployment tool (action: get, uuid: deploy-latest, lines) to see why it failed.');
+            });
+            it('should not flag stale code when the latest deployment succeeded', async () => {
+                mockFetch
+                    .mockResolvedValueOnce(mockResponse(mockApp))
+                    .mockResolvedValueOnce(mockResponse(mockLogs))
+                    .mockResolvedValueOnce(mockResponse(mockEnvVars))
+                    .mockResolvedValueOnce(mockResponse({ count: mockDeployments.length, deployments: mockDeployments }));
+                const result = await client.diagnoseApplication(testAppUuid);
+                expect(result.health.status).toBe('healthy');
+                expect(result.health.issues.some((issue) => issue.includes('stale code'))).toBe(false);
+            });
+            it('should skip the deployment-freshness check without breaking diagnosis when deployments are unavailable', async () => {
+                mockFetch
+                    .mockResolvedValueOnce(mockResponse(mockApp))
+                    .mockResolvedValueOnce(mockResponse(mockLogs))
+                    .mockResolvedValueOnce(mockResponse(mockEnvVars))
+                    .mockRejectedValueOnce(new Error('Deployments unavailable'));
+                const result = await client.diagnoseApplication(testAppUuid);
+                expect(result.application).not.toBeNull();
+                expect(result.health.status).toBe('healthy');
+                expect(result.recent_deployments).toEqual([]);
+                expect(result.errors).toContain('deployments: Deployments unavailable');
+                expect(result.health.issues.some((issue) => issue.includes('stale code'))).toBe(false);
+            });
             it('should handle partial failures gracefully', async () => {
                 mockFetch
                     .mockResolvedValueOnce(mockResponse(mockApp))
@@ -3723,3 +3785,24 @@ describe('CoolifyClient', () => {
         });
     });
 });
+describe('errorHint', () => {
+    it('hints at the command-length limit for a 500 on a scheduled-tasks path', () => {
+        expect(errorHint(500, '/applications/app-uuid/scheduled-tasks')).toMatch(/varchar\(255\)/);
+        expect(errorHint(500, '/services/svc-uuid/scheduled-tasks/task-uuid')).toMatch(/varchar\(255\)/);
+    });
+    it('does not hint at the command-length limit for a 500 on unrelated paths', () => {
+        expect(errorHint(500, '/servers')).toBeUndefined();
+    });
+    it('hints at the access token for 401 and 403', () => {
+        expect(errorHint(401, '/version')).toMatch(/COOLIFY_ACCESS_TOKEN/);
+        expect(errorHint(403, '/servers')).toMatch(/COOLIFY_ACCESS_TOKEN/);
+    });
+    it('hints at a possible resource-type mismatch for a 404 on a uuid route', () => {
+        expect(errorHint(404, '/applications/app-uuid')).toMatch(/different resource type/);
+    });
+    it('returns undefined for anything else (default passthrough)', () => {
+        expect(errorHint(200, '/servers')).toBeUndefined();
+        expect(errorHint(422, '/applications/app-uuid')).toBeUndefined();
+        expect(errorHint(404, '/health')).toBeUndefined();
+    });
+});

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

@@ -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, {
@@ -642,6 +673,307 @@ describe('CoolifyMcpServer v2', () => {
             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>;
@@ -180,7 +193,7 @@ export declare class CoolifyClient {
     getDeployment(uuid: string, options?: {
         includeLogs?: boolean;
     }): Promise<DeploymentEssential>;
-    deployByTagOrUuid(tagOrUuid: string, force?: boolean): Promise<MessageResponse>;
+    deployByTagOrUuid(tagOrUuid: string, force?: boolean): Promise<DeployTriggerResponse>;
     /**
      * List deployments for an application.
      *

package/dist/lib/coolify-client.js

@@ -46,6 +46,24 @@ function mapFqdnToDomains(data) {
     }
     return { ...rest, domains: fqdn };
 }
+/**
+ * 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 function errorHint(status, path) {
+    if (status === 500 && /\/scheduled-tasks(\/|$)/.test(path)) {
+        return 'Known cause: Coolify stores scheduled-task `command` in a varchar(255) column and rejects longer commands with a bodyless 500 — check the command length (limit 255 chars).';
+    }
+    if (status === 401 || status === 403) {
+        return 'Check that COOLIFY_ACCESS_TOKEN is valid and has the required scopes for this operation.';
+    }
+    if (status === 404 && /\/[\w-]{8,}(\/|$)/.test(path)) {
+        return 'The uuid may belong to a different resource type than requested (e.g. an application uuid used on a service/database route).';
+    }
+    return undefined;
+}
 // =============================================================================
 // Summary Transformers - reduce full objects to essential fields
 // =============================================================================
@@ -305,6 +323,10 @@ export class CoolifyClient {
                         .join('; ');
                     errorMessage = `${errorMessage} - ${validationDetails}`;
                 }
+                const hint = errorHint(response.status, path);
+                if (hint) {
+                    errorMessage = `${errorMessage} (${hint})`;
+                }
                 throw new Error(errorMessage);
             }
             return data;
@@ -520,6 +542,12 @@ export class CoolifyClient {
             body: JSON.stringify(mapFqdnToDomains(data)),
         });
     }
+    /**
+     * @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.
+     */
     async createApplicationDockerCompose(data) {
         const mapped = mapFqdnToDomains(data);
         const payload = { ...mapped };
@@ -1387,6 +1415,18 @@ export class CoolifyClient {
                     healthStatus = 'unhealthy';
             }
         }
+        // Cross-check: the container can be running:healthy while the latest
+        // deployment failed/was cancelled — old code still serving, new code
+        // never arrived (#239). Skip silently if we have no app or no deployments.
+        if (app && deployments && deployments.length > 0) {
+            const latestDeployment = deployments[0];
+            const appIsRunning = (app.status || '').includes('running');
+            if (appIsRunning &&
+                (latestDeployment.status === 'failed' || latestDeployment.status === 'cancelled')) {
+                issues.push(`Running container predates the last (${latestDeployment.status}) deployment (${latestDeployment.uuid}) — the app is serving stale code. Use the deployment tool (action: get, uuid: ${latestDeployment.uuid}, lines) to see why it ${latestDeployment.status}.`);
+                healthStatus = 'unhealthy';
+            }
+        }
         return {
             application: app
                 ? {

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

@@ -30,5 +30,38 @@ export declare class CoolifyMcpServer extends McpServer {
     private readonly docsSearch;
     constructor(config: CoolifyConfig);
     connect(transport: Transport): Promise<void>;
+    /**
+     * Poll a single deployment until it reaches a terminal status or the
+     * timeout elapses. Uses `getDeployment`'s no-logs projection
+     * (`DeploymentEssential`) while polling, and only fetches logs (once,
+     * truncated) if the deployment failed.
+     */
+    private pollDeployment;
+    /**
+     * Trigger a deploy and wait for it to finish. A tag can resolve to
+     * multiple applications, so `deployByTagOrUuid` may return several
+     * `deployment_uuid`s — only the first is polled; any others are
+     * surfaced under `additional_deployment_uuids` for the caller to check
+     * separately via `deployment get`.
+     */
+    private triggerAndWaitForDeploy;
     private registerTools;
+    /**
+     * Injectable delay for the run_once poll loop. A real setTimeout in production;
+     * tests replace it with `jest.spyOn(server, 'sleep').mockResolvedValue(undefined)`
+     * so polling logic runs without waiting on the wall clock.
+     */
+    private sleep;
+    /**
+     * Composite one-off command execution (#233 / #208): there is no upstream
+     * "run now" endpoint for scheduled tasks, so this creates a throwaway
+     * `* * * * *` task, polls list_executions until the first execution reaches a
+     * terminal status (or the poll budget runs out), and returns its status+message.
+     *
+     * The task is deleted in a finally-equivalent (try/finally-style) block so cleanup
+     * always runs — on success, on timeout, and on a polling error. If cleanup itself
+     * fails, the returned message says so loudly with the task UUID so a human can
+     * remove it manually (it would otherwise keep firing every minute).
+     */
+    private runOnceScheduledTask;
 }

package/dist/lib/mcp-server.js

@@ -152,6 +152,33 @@ function wrapWithActions(fn, getActions, getPaginationFn) {
         ],
     }));
 }
+// =============================================================================
+// Deploy wait/poll helpers (#238)
+// =============================================================================
+/** Deployment statuses that end a run — polling stops once one of these is hit. */
+const TERMINAL_DEPLOYMENT_STATUSES = new Set([
+    'finished',
+    'failed',
+    'cancelled',
+]);
+const DEFAULT_DEPLOY_TIMEOUT_SECONDS = 300;
+const DEPLOY_POLL_INTERVAL_MS = 5000;
+function isTerminalDeploymentStatus(status) {
+    return TERMINAL_DEPLOYMENT_STATUSES.has(status);
+}
+/** Isolated so tests can drive polling with jest fake timers instead of real waits. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function durationSeconds(createdAt, updatedAt) {
+    if (!createdAt || !updatedAt)
+        return undefined;
+    const start = Date.parse(createdAt);
+    const end = Date.parse(updatedAt);
+    if (Number.isNaN(start) || Number.isNaN(end))
+        return undefined;
+    return Math.max(0, Math.round((end - start) / 1000));
+}
 export class CoolifyMcpServer extends McpServer {
     client;
     docsSearch = new DocsSearchEngine();
@@ -163,6 +190,82 @@ export class CoolifyMcpServer extends McpServer {
     async connect(transport) {
         await super.connect(transport);
     }
+    /**
+     * Poll a single deployment until it reaches a terminal status or the
+     * timeout elapses. Uses `getDeployment`'s no-logs projection
+     * (`DeploymentEssential`) while polling, and only fetches logs (once,
+     * truncated) if the deployment failed.
+     */
+    async pollDeployment(uuid, timeoutSeconds) {
+        const deadline = Date.now() + timeoutSeconds * 1000;
+        let current = (await this.client.getDeployment(uuid));
+        while (!isTerminalDeploymentStatus(current.status) && Date.now() < deadline) {
+            await sleep(DEPLOY_POLL_INTERVAL_MS);
+            current = (await this.client.getDeployment(uuid));
+        }
+        if (!isTerminalDeploymentStatus(current.status)) {
+            return {
+                status: current.status,
+                deployment_uuid: uuid,
+                application_uuid: current.application_uuid,
+                timed_out: true,
+                next_action: `Still "${current.status}" after ${timeoutSeconds}s — poll \`deployment\` (action: "get", uuid: "${uuid}") to keep watching.`,
+            };
+        }
+        if (current.status === 'failed') {
+            const withLogs = (await this.client.getDeployment(uuid, {
+                includeLogs: true,
+            }));
+            const tail = withLogs.logs ? truncateLogs(withLogs.logs, 30, 10_000) : undefined;
+            return {
+                status: current.status,
+                deployment_uuid: uuid,
+                application_uuid: current.application_uuid,
+                commit: current.commit,
+                created_at: current.created_at,
+                updated_at: current.updated_at,
+                duration_seconds: durationSeconds(current.created_at, current.updated_at),
+                logs_tail: tail?.logs,
+                logs_meta: tail
+                    ? {
+                        total_entries: tail.total,
+                        showing: `${tail.showing_start}-${tail.showing_end} of ${tail.total}`,
+                    }
+                    : undefined,
+                next_action: `Deployment failed. See logs_tail above, or \`deployment\` (action: "get", uuid: "${uuid}", lines: N) for more.`,
+            };
+        }
+        return {
+            status: current.status,
+            deployment_uuid: uuid,
+            application_uuid: current.application_uuid,
+            commit: current.commit,
+            created_at: current.created_at,
+            updated_at: current.updated_at,
+            duration_seconds: durationSeconds(current.created_at, current.updated_at),
+        };
+    }
+    /**
+     * Trigger a deploy and wait for it to finish. A tag can resolve to
+     * multiple applications, so `deployByTagOrUuid` may return several
+     * `deployment_uuid`s — only the first is polled; any others are
+     * surfaced under `additional_deployment_uuids` for the caller to check
+     * separately via `deployment get`.
+     */
+    async triggerAndWaitForDeploy(tagOrUuid, force, timeoutSeconds) {
+        const triggered = await this.client.deployByTagOrUuid(tagOrUuid, force);
+        const [first, ...rest] = triggered.deployments ?? [];
+        if (!first?.deployment_uuid) {
+            // Nothing to poll against — hand back the trigger response as-is.
+            return triggered;
+        }
+        const result = await this.pollDeployment(first.deployment_uuid, timeoutSeconds);
+        const additional = rest.map((d) => d.deployment_uuid).filter((u) => !!u);
+        if (additional.length > 0) {
+            result.additional_deployment_uuids = additional;
+        }
+        return result;
+    }
     registerTools() {
         // =========================================================================
         // Meta (2 tools)
@@ -300,6 +403,7 @@ export class CoolifyMcpServer extends McpServer {
                 'create_github',
                 'create_key',
                 'create_dockerimage',
+                'create_dockerfile',
                 'update',
                 'delete',
                 'delete_preview',
@@ -320,6 +424,8 @@ export class CoolifyMcpServer extends McpServer {
             // Docker image fields
             docker_registry_image_name: z.string().optional(),
             docker_registry_image_tag: z.string().optional(),
+            // Dockerfile fields (create_dockerfile)
+            dockerfile: z.string().optional(),
             // Update fields
             name: z.string().optional(),
             description: z.string().optional(),
@@ -565,6 +671,35 @@ export class CoolifyMcpServer extends McpServer {
                         custom_labels: args.custom_labels,
                         instant_deploy: args.instant_deploy,
                     }));
+                case 'create_dockerfile':
+                    if (!args.project_uuid || !args.server_uuid || !args.dockerfile) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'Error: project_uuid, server_uuid, dockerfile required',
+                                },
+                            ],
+                        };
+                    }
+                    return wrap(() => this.client.createApplicationDockerfile({
+                        project_uuid: args.project_uuid,
+                        server_uuid: args.server_uuid,
+                        destination_uuid: args.destination_uuid,
+                        dockerfile: args.dockerfile,
+                        dockerfile_location: args.dockerfile_location,
+                        ports_exposes: args.ports_exposes,
+                        base_directory: args.base_directory,
+                        environment_name: args.environment_name,
+                        environment_uuid: args.environment_uuid,
+                        name: args.name,
+                        description: args.description,
+                        fqdn: args.fqdn,
+                        domains: args.domains,
+                        custom_docker_run_options: args.custom_docker_run_options,
+                        custom_labels: args.custom_labels,
+                        instant_deploy: args.instant_deploy,
+                    }));
                 case 'update': {
                     if (!uuid)
                         return { content: [{ type: 'text', text: 'Error: uuid required' }] };
@@ -887,7 +1022,25 @@ 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 }) => 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('deploy', 'Deploy by tag/UUID', {
+            tag_or_uuid: z.string(),
+            force: z.boolean().optional(),
+            wait: z
+                .boolean()
+                .optional()
+                .describe('Wait for the deployment to reach a terminal status (finished/failed/cancelled) instead of returning immediately, polling every ~5s. If tag_or_uuid matches multiple applications (a tag can trigger several deployments), only the first is watched — the rest are returned under additional_deployment_uuids for you to check separately via `deployment get`. On failure the response includes a bounded log tail. Default false (fire-and-forget, unchanged response).'),
+            timeout_seconds: z
+                .number()
+                .optional()
+                .describe('Max seconds to poll when wait is true before giving up and returning the current status plus a next-action hint (default 300). Ignored when wait is false.'),
+        }, async ({ tag_or_uuid, force, wait, timeout_seconds }) => {
+            if (!wait) {
+                return wrapWithActions(() => this.client.deployByTagOrUuid(tag_or_uuid, force), () => [{ tool: 'list_deployments', args: {}, hint: 'Check deployment status' }]);
+            }
+            return wrapWithActions(() => this.triggerAndWaitForDeploy(tag_or_uuid, force, timeout_seconds ?? DEFAULT_DEPLOY_TIMEOUT_SECONDS), (result) => 'deployment_uuid' in result
+                ? getDeploymentActions(result.deployment_uuid, result.status, result.application_uuid)
+                : []);
+        });
         this.tool('deployment', 'Manage deployment: get/cancel/list_for_app. Logs excluded by default on all actions — for get use `lines` (paginated tail), for list_for_app use `include_logs: true` to include raw build-log blobs.', {
             action: z.enum(['get', 'cancel', 'list_for_app']),
             uuid: z.string(),
@@ -1323,17 +1476,31 @@ export class CoolifyMcpServer extends McpServer {
         // =========================================================================
         // Scheduled Tasks (1 tool - consolidated for app/service)
         // =========================================================================
-        this.tool('scheduled_tasks', 'Manage scheduled tasks for app or service: list/create/update/delete/list_executions', {
+        this.tool('scheduled_tasks', 'Manage scheduled tasks for app or service: list/create/update/delete/list_executions/run_once. ' +
+            "list_executions: the command's stdout comes back in the execution's message field. " +
+            'run_once: composite that creates a throwaway "* * * * *" task, polls list_executions every ~5s ' +
+            'for the first terminal execution (or until wait_seconds elapses, default 90), deletes the task, ' +
+            'and returns status+message. WARNING: the underlying cron may fire more than once before cleanup ' +
+            'completes — make the command idempotent (e.g. `where not exists`) or tolerate re-execution. ' +
+            'Coolify stores `command` in a varchar(255) column and rejects longer commands with a bodyless ' +
+            'HTTP 500 — keep commands to 255 chars or fewer (#234).', {
             resource: z.enum(['application', 'service']),
-            action: z.enum(['list', 'create', 'update', 'delete', 'list_executions']),
+            action: z.enum(['list', 'create', 'update', 'delete', 'list_executions', 'run_once']),
             uuid: z.string(),
             task_uuid: z.string().optional(),
             name: z.string().optional(),
-            command: z.string().optional(),
+            command: z
+                .string()
+                .max(255, 'Coolify rejects scheduled-task commands longer than 255 chars — split the command or bake a script into the container image')
+                .optional(),
             frequency: z.string().optional(),
             container: z.string().optional(),
             timeout: z.number().optional(),
             enabled: z.boolean().optional(),
+            wait_seconds: z
+                .number()
+                .optional()
+                .describe('run_once only: poll budget in seconds before giving up (default 90)'),
         }, async (args) => {
             const { resource, action, uuid, task_uuid } = args;
             const isApp = resource === 'application';
@@ -1390,6 +1557,12 @@ export class CoolifyMcpServer extends McpServer {
                     return wrap(() => isApp
                         ? this.client.listApplicationScheduledTaskExecutions(uuid, task_uuid)
                         : this.client.listServiceScheduledTaskExecutions(uuid, task_uuid));
+                case 'run_once':
+                    if (!args.command || !args.container)
+                        return {
+                            content: [{ type: 'text', text: 'Error: command, container required' }],
+                        };
+                    return this.runOnceScheduledTask(resource, uuid, args.command, args.container, args.timeout, args.wait_seconds);
             }
         });
         // =========================================================================
@@ -1524,4 +1697,131 @@ export class CoolifyMcpServer extends McpServer {
         });
         this.tool('redeploy_project', 'Redeploy all apps in project', { project_uuid: z.string(), force: z.boolean().optional() }, async ({ project_uuid, force }) => wrap(() => this.client.redeployProjectApps(project_uuid, force ?? true)));
     }
+    /**
+     * Injectable delay for the run_once poll loop. A real setTimeout in production;
+     * tests replace it with `jest.spyOn(server, 'sleep').mockResolvedValue(undefined)`
+     * so polling logic runs without waiting on the wall clock.
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Composite one-off command execution (#233 / #208): there is no upstream
+     * "run now" endpoint for scheduled tasks, so this creates a throwaway
+     * `* * * * *` task, polls list_executions until the first execution reaches a
+     * terminal status (or the poll budget runs out), and returns its status+message.
+     *
+     * The task is deleted in a finally-equivalent (try/finally-style) block so cleanup
+     * always runs — on success, on timeout, and on a polling error. If cleanup itself
+     * fails, the returned message says so loudly with the task UUID so a human can
+     * remove it manually (it would otherwise keep firing every minute).
+     */
+    async runOnceScheduledTask(resource, uuid, command, container, timeout, waitSeconds) {
+        const isApp = resource === 'application';
+        const pollIntervalMs = 5000;
+        const budgetSeconds = waitSeconds ?? 90;
+        const maxAttempts = Math.max(1, Math.ceil((budgetSeconds * 1000) / pollIntervalMs));
+        const name = `oneoff-${Math.random().toString(36).slice(2, 10)}`;
+        let taskUuid;
+        try {
+            const task = isApp
+                ? await this.client.createApplicationScheduledTask(uuid, {
+                    name,
+                    command,
+                    frequency: '* * * * *',
+                    container,
+                    timeout,
+                    enabled: true,
+                })
+                : await this.client.createServiceScheduledTask(uuid, {
+                    name,
+                    command,
+                    frequency: '* * * * *',
+                    container,
+                    timeout,
+                    enabled: true,
+                });
+            taskUuid = task.uuid;
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error creating one-off task: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+        let execution;
+        let pollErrorMessage;
+        try {
+            for (let attempt = 0; attempt < maxAttempts; attempt++) {
+                const executions = isApp
+                    ? await this.client.listApplicationScheduledTaskExecutions(uuid, taskUuid)
+                    : await this.client.listServiceScheduledTaskExecutions(uuid, taskUuid);
+                const first = executions[0];
+                if (first && first.status !== 'running') {
+                    execution = first;
+                    break;
+                }
+                if (attempt < maxAttempts - 1)
+                    await this.sleep(pollIntervalMs);
+            }
+        }
+        catch (error) {
+            pollErrorMessage = error instanceof Error ? error.message : String(error);
+        }
+        // Cleanup always runs, regardless of how the poll loop above ended.
+        let deleteErrorMessage;
+        try {
+            if (isApp) {
+                await this.client.deleteApplicationScheduledTask(uuid, taskUuid);
+            }
+            else {
+                await this.client.deleteServiceScheduledTask(uuid, taskUuid);
+            }
+        }
+        catch (error) {
+            deleteErrorMessage = error instanceof Error ? error.message : String(error);
+        }
+        const cleanupNote = deleteErrorMessage
+            ? `WARNING: failed to delete one-off task ${taskUuid} — it will keep firing every minute ` +
+                `until it is removed manually. Delete error: ${deleteErrorMessage}`
+            : `One-off task ${taskUuid} deleted.`;
+        if (pollErrorMessage) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error polling one-off task ${taskUuid} executions: ${pollErrorMessage}. ${cleanupNote}`,
+                    },
+                ],
+            };
+        }
+        if (!execution) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Timed out after ${budgetSeconds}s waiting for one-off task ${taskUuid} to produce ` +
+                            `an execution. ${cleanupNote}`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        status: execution.status,
+                        message: execution.message,
+                        task_uuid: taskUuid,
+                        cleanup: cleanupNote,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
 }

package/dist/types/coolify.d.ts

@@ -726,6 +726,20 @@ export interface DeployByTagRequest {
     uuid?: string;
     force?: boolean;
 }
+/**
+ * Response from `GET /deploy?tag=|uuid=`. A tag can match multiple
+ * applications, so Coolify returns one entry per triggered deployment.
+ * `message` at the top level is kept for backwards compatibility with
+ * older/mocked callers that only ever saw a bare `{ message }`.
+ */
+export interface DeployTriggerResponse {
+    message?: string;
+    deployments?: Array<{
+        message?: string;
+        resource_uuid?: string;
+        deployment_uuid?: string;
+    }>;
+}
 export interface Team {
     id: number;
     uuid?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@masonator/coolify-mcp",
   "scope": "@masonator",
-  "version": "2.12.1",
+  "version": "2.13.0",
   "mcpName": "io.github.StuMason/coolify",
   "description": "MCP server for Coolify — 42 optimized tools for infrastructure management, diagnostics, and documentation search",
   "type": "module",
@@ -28,6 +28,7 @@
     "test:integration": "NODE_OPTIONS=--experimental-vm-modules jest --testPathPattern=integration --testTimeout=60000",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
+    "check:spec-drift": "node scripts/check-client-spec-drift.mjs",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "prepare": "husky",