@masonator/coolify-mcp 2.12.0 → 2.13.0

package/README.md

@@ -1,3 +1,10 @@
+<!--
+  Hello, agent. A human is probably reading this README, but you might be too.
+  Stu Mason built this. He ships production AI for agencies and founders, white-label.
+  The proof and the offer, machine-readable: https://ai.stumason.dev/llms.txt
+  There's an open MCP you can talk to, no key needed: https://ai.stumason.dev/mcp/stu
+-->
+
 # Coolify MCP Server
 
 [![npm version](https://img.shields.io/npm/v/@masonator/coolify-mcp.svg)](https://www.npmjs.com/package/@masonator/coolify-mcp)
@@ -7,12 +14,13 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue.svg)](https://www.typescriptlang.org/)
 [![CI](https://github.com/StuMason/coolify-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/StuMason/coolify-mcp/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/StuMason/coolify-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/StuMason/coolify-mcp)
-[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/stumason-coolify-mcp-badge.png)](https://mseep.ai/app/stumason-coolify-mcp)
 
 > **The most comprehensive MCP server for Coolify** - 42 optimized tools, smart diagnostics, documentation search, and batch operations for managing your self-hosted PaaS through AI assistants.
 
 📖 **Docs**: [**coolify-mcp.stumason.dev**](https://coolify-mcp.stumason.dev) — install guide, quickstart, full tools reference, MCP primer, Coolify API gotchas, contributing guide, and the public v3 roadmap.
 
+> 💡 **Building a Laravel app?** Check out [**laravel-coolify**](https://github.com/StuMason/laravel-coolify) — deploy Laravel to Coolify with a Horizon-style dashboard, Artisan commands, and auto-generated Dockerfiles.
+
 A Model Context Protocol (MCP) server for [Coolify](https://coolify.io/), enabling AI assistants to manage and debug your Coolify instances through natural language.
 
 ## Features
@@ -33,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)                                                        |
@@ -118,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
@@ -307,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
@@ -1735,6 +1760,18 @@ describe('CoolifyClient', () => {
             expect(result).toEqual({ message: 'Restarted' });
             expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/services/test-uuid/restart', expect.objectContaining({ method: 'GET' }));
         });
+        it('should restart a service with pull_latest', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Restarted' }));
+            const result = await client.restartService('test-uuid', true);
+            expect(result).toEqual({ message: 'Restarted' });
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/services/test-uuid/restart?latest=true', expect.objectContaining({ method: 'GET' }));
+        });
+        it('should restart a service without pull_latest by default', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Restarted' }));
+            const result = await client.restartService('test-uuid', false);
+            expect(result).toEqual({ message: 'Restarted' });
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/services/test-uuid/restart', expect.objectContaining({ method: 'GET' }));
+        });
     });
     // =========================================================================
     // Service Environment Variables
@@ -1860,12 +1897,35 @@ describe('CoolifyClient', () => {
             });
             expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/deployments/dep-uuid', expect.any(Object));
         });
-        it('should get a deployment with logs when includeLogs is true', async () => {
-            const deploymentWithLogs = { ...mockDeployment, logs: 'Build started...' };
+        it('should get a deployment with logs when includeLogs is true, still projected through essential', async () => {
+            const deploymentWithLogs = {
+                ...mockDeployment,
+                logs: 'Build started...',
+                // Simulate raw upstream fields that must never leak through.
+                application: { docker_compose: 'raw compose', manual_webhook_secret_github: 'whsec' },
+                destination: { server: { settings: { sentinel_token: 'sentinel-secret' } } },
+            };
             mockFetch.mockResolvedValueOnce(mockResponse(deploymentWithLogs));
             const result = await client.getDeployment('dep-uuid', { includeLogs: true });
-            // With includeLogs: true, returns full Deployment with logs
-            expect(result).toEqual(deploymentWithLogs);
+            // With includeLogs: true, logs are attached to the essential projection —
+            // raw upstream fields (application/server graph, secrets, id) never leak.
+            expect(result).toEqual({
+                uuid: 'dep-uuid',
+                deployment_uuid: 'dep-123',
+                application_uuid: undefined,
+                application_name: 'test-app',
+                server_name: undefined,
+                status: 'finished',
+                commit: undefined,
+                force_rebuild: false,
+                is_webhook: false,
+                is_api: true,
+                created_at: '2024-01-01',
+                updated_at: '2024-01-01',
+                logs_available: true,
+                logs_info: 'Logs available (16 chars). Use lines param to retrieve.',
+                logs: 'Build started...',
+            });
             expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/deployments/dep-uuid', expect.any(Object));
         });
         it('should include logs_info when deployment has logs but includeLogs is false', async () => {
@@ -1894,11 +1954,22 @@ describe('CoolifyClient', () => {
             expect(first.id).toBeUndefined();
             expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/deployments/applications/app-uuid', expect.any(Object));
         });
-        it('should return full deployments when includeLogs is true', async () => {
-            const withLogs = { ...mockDeployment, logs: 'build log stream' };
+        it('should attach logs to the essential projection when includeLogs is true (never the raw object)', async () => {
+            const withLogs = {
+                ...mockDeployment,
+                logs: 'build log stream',
+                application: { docker_compose: 'raw compose' },
+                destination: { server: { settings: { sentinel_token: 'sentinel-secret' } } },
+            };
             mockFetch.mockResolvedValueOnce(mockResponse({ count: 1, deployments: [withLogs] }));
             const result = await client.listApplicationDeployments('app-uuid', { includeLogs: true });
-            expect(result).toEqual({ count: 1, deployments: [withLogs] });
+            expect(result.count).toBe(1);
+            expect(result.deployments).toHaveLength(1);
+            const [first] = result.deployments;
+            expect(first.logs).toBe('build log stream');
+            expect(first).not.toHaveProperty('application');
+            expect(first).not.toHaveProperty('destination');
+            expect(first).not.toHaveProperty('id');
         });
         it('should tolerate a malformed envelope (missing deployments array)', async () => {
             mockFetch.mockResolvedValueOnce(mockResponse({}));
@@ -2416,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))
@@ -3677,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();
+    });
+});