@masonator/coolify-mcp 2.12.0 → 2.12.1

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

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

@@ -1735,6 +1735,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 +1872,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 +1929,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({}));

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;
@@ -494,6 +494,154 @@ 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('truncateLogs', () => {
     // Plain text log tests

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

@@ -162,7 +162,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,7 +179,7 @@ export declare class CoolifyClient {
     listDeployments(options?: ListOptions): Promise<Deployment[] | DeploymentSummary[]>;
     getDeployment(uuid: string, options?: {
         includeLogs?: boolean;
-    }): Promise<Deployment | DeploymentEssential>;
+    }): Promise<DeploymentEssential>;
     deployByTagOrUuid(tagOrUuid: string, force?: boolean): Promise<MessageResponse>;
     /**
      * List deployments for an application.
@@ -190,13 +190,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>;

package/dist/lib/coolify-client.js

@@ -767,8 +767,9 @@ export class CoolifyClient {
             method: 'GET',
         });
     }
-    async restartService(uuid) {
-        return this.request(`/services/${uuid}/restart`, {
+    async restartService(uuid, pullLatest = false) {
+        const qs = pullLatest ? '?latest=true' : '';
+        return this.request(`/services/${uuid}/restart${qs}`, {
             method: 'GET',
         });
     }
@@ -818,7 +819,13 @@ export class CoolifyClient {
     }
     async getDeployment(uuid, options) {
         const deployment = await this.request(`/deployments/${uuid}`);
-        return options?.includeLogs ? deployment : toDeploymentEssential(deployment);
+        const essential = toDeploymentEssential(deployment);
+        // Attach the raw log string (never the raw upstream object, which also embeds
+        // the full application/server graph and secrets) onto the essential projection.
+        if (options?.includeLogs && deployment.logs) {
+            essential.logs = deployment.logs;
+        }
+        return essential;
     }
     async deployByTagOrUuid(tagOrUuid, force = false) {
         // Detect if the value looks like a UUID or a tag name
@@ -834,14 +841,22 @@ export 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).
      */
     async listApplicationDeployments(appUuid, options) {
         const envelope = await this.request(`/deployments/applications/${appUuid}`);
         const deployments = Array.isArray(envelope?.deployments) ? envelope.deployments : [];
         return {
             count: typeof envelope?.count === 'number' ? envelope.count : deployments.length,
-            deployments: options?.includeLogs ? deployments : deployments.map(toDeploymentEssential),
+            deployments: deployments.map((dep) => {
+                const essential = toDeploymentEssential(dep);
+                if (options?.includeLogs && dep.logs) {
+                    essential.logs = dep.logs;
+                }
+                return essential;
+            }),
         };
     }
     // ===========================================================================

package/dist/lib/mcp-server.js

@@ -608,6 +608,10 @@ export class CoolifyMcpServer extends McpServer {
             server_uuid: z.string().optional(),
             project_uuid: z.string().optional(),
             environment_name: z.string().optional(),
+            destination_uuid: z
+                .string()
+                .optional()
+                .describe('Destination UUID. Required if server has multiple destinations.'),
             name: z.string().optional(),
             description: z.string().optional(),
             image: z.string().optional(),
@@ -723,7 +727,11 @@ export class CoolifyMcpServer extends McpServer {
             resource: z.enum(['application', 'database', 'service']),
             action: z.enum(['start', 'stop', 'restart']),
             uuid: z.string(),
-        }, async ({ resource, action, uuid }) => {
+            pull_latest: z
+                .boolean()
+                .optional()
+                .describe('Pull latest images before restarting (services only)'),
+        }, async ({ resource, action, uuid, pull_latest }) => {
             const methods = {
                 application: {
                     start: (u) => this.client.startApplication(u),
@@ -738,7 +746,7 @@ export class CoolifyMcpServer extends McpServer {
                 service: {
                     start: (u) => this.client.startService(u),
                     stop: (u) => this.client.stopService(u),
-                    restart: (u) => this.client.restartService(u),
+                    restart: (u) => this.client.restartService(u, pull_latest),
                 },
             };
             // Generate contextual actions based on resource type and action taken
@@ -895,9 +903,9 @@ export class CoolifyMcpServer extends McpServer {
                         const p = page ?? 1;
                         const ll = lines;
                         return wrapWithActions(async () => {
-                            const deployment = (await this.client.getDeployment(uuid, {
+                            const deployment = await this.client.getDeployment(uuid, {
                                 includeLogs: true,
-                            }));
+                            });
                             if (deployment.logs) {
                                 const result = truncateLogs(deployment.logs, ll, max_chars ?? 50000, p);
                                 deployment.logs = result.logs;

package/dist/types/coolify.d.ts

@@ -1131,4 +1131,5 @@ export interface DeploymentEssential {
     updated_at: string;
     logs_available?: boolean;
     logs_info?: string;
+    logs?: string;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@masonator/coolify-mcp",
   "scope": "@masonator",
-  "version": "2.12.0",
+  "version": "2.12.1",
   "mcpName": "io.github.StuMason/coolify",
   "description": "MCP server for Coolify — 42 optimized tools for infrastructure management, diagnostics, and documentation search",
   "type": "module",
@@ -66,7 +66,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.0.3",
+    "@types/node": "^26.0.0",
     "@typescript-eslint/eslint-plugin": "^8.51.0",
     "@typescript-eslint/parser": "^8.51.0",
     "dotenv": "^17.2.3",
@@ -88,7 +88,22 @@
     "node": ">=20"
   },
   "overrides": {
-    "handlebars": "^4.7.9"
+    "handlebars": "^4.7.9",
+    "qs": "^6.15.2",
+    "hono": "^4.12.25",
+    "@hono/node-server": "^2.0.5",
+    "express-rate-limit": "^8.5.2",
+    "path-to-regexp": "^8.4.2",
+    "@modelcontextprotocol/sdk": {
+      "ajv": "^8.20.0"
+    },
+    "fast-uri": "^4.0.0",
+    "ip-address": "^10.2.0",
+    "flatted": "^3.4.2",
+    "brace-expansion": "^5.0.6",
+    "picomatch": "^4.0.4",
+    "js-yaml": "^4.2.0",
+    "markdown-it": "^14.2.0"
   },
   "lint-staged": {
     "*.{ts,js,json,md,yaml,yml}": "prettier --write",