@masonator/coolify-mcp 2.1.0 → 2.3.0

package/README.md

@@ -17,25 +17,25 @@ A Model Context Protocol (MCP) server for [Coolify](https://coolify.io/), enabli
 
 This MCP server provides **34 token-optimized tools** for **debugging, management, and deployment**:
 
-| Category             | Tools                                                                                     |
-| -------------------- | ----------------------------------------------------------------------------------------- |
-| **Infrastructure**   | `get_infrastructure_overview`, `get_mcp_version`, `get_version`                           |
-| **Diagnostics**      | `diagnose_app`, `diagnose_server`, `find_issues`                                          |
-| **Batch Operations** | `restart_project_apps`, `bulk_env_update`, `stop_all_apps`, `redeploy_project`            |
-| **Servers**          | `list_servers`, `get_server`, `validate_server`, `server_resources`, `server_domains`     |
-| **Projects**         | `projects` (list, get, create, update, delete via action param)                           |
-| **Environments**     | `environments` (list, get, create, delete via action param)                               |
-| **Applications**     | `list_applications`, `get_application`, `application` (CRUD), `application_logs`          |
-| **Databases**        | `list_databases`, `get_database`, `database` (create 8 types, delete), `database_backups` |
-| **Services**         | `list_services`, `get_service`, `service` (create, update, delete)                        |
-| **Control**          | `control` (start/stop/restart for apps, databases, services)                              |
-| **Env Vars**         | `env_vars` (CRUD for application and service env vars)                                    |
-| **Deployments**      | `list_deployments`, `deploy`, `deployment` (get, cancel, list_for_app)                    |
-| **Private Keys**     | `private_keys` (list, get, create, update, delete via action param)                       |
-
-### v2.0.0 Token Diet
-
-v2.0.0 reduced token usage by **85%** (from ~43,000 to ~6,600 tokens) by consolidating related operations into single tools with action parameters. This prevents context window exhaustion in AI assistants.
+| Category             | Tools                                                                                                                       |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| **Infrastructure**   | `get_infrastructure_overview`, `get_mcp_version`, `get_version`                                                             |
+| **Diagnostics**      | `diagnose_app`, `diagnose_server`, `find_issues`                                                                            |
+| **Batch Operations** | `restart_project_apps`, `bulk_env_update`, `stop_all_apps`, `redeploy_project`                                              |
+| **Servers**          | `list_servers`, `get_server`, `validate_server`, `server_resources`, `server_domains`                                       |
+| **Projects**         | `projects` (list, get, create, update, delete via action param)                                                             |
+| **Environments**     | `environments` (list, get, create, delete via action param)                                                                 |
+| **Applications**     | `list_applications`, `get_application`, `application` (CRUD), `application_logs`                                            |
+| **Databases**        | `list_databases`, `get_database`, `database` (create 8 types, delete), `database_backups` (CRUD schedules, view executions) |
+| **Services**         | `list_services`, `get_service`, `service` (create, update, delete)                                                          |
+| **Control**          | `control` (start/stop/restart for apps, databases, services)                                                                |
+| **Env Vars**         | `env_vars` (CRUD for application and service env vars)                                                                      |
+| **Deployments**      | `list_deployments`, `deploy`, `deployment` (get, cancel, list_for_app)                                                      |
+| **Private Keys**     | `private_keys` (list, get, create, update, delete via action param)                                                         |
+
+### Token-Optimized Design
+
+The server uses **85% fewer tokens** than a naive implementation (6,600 vs 43,000) by consolidating related operations into single tools with action parameters. This prevents context window exhaustion in AI assistants.
 
 ## Installation
 
@@ -216,78 +216,49 @@ These tools accept human-friendly identifiers instead of just UUIDs:
 
 ### Projects
 
-- `list_projects` - List all projects (returns summary)
-- `get_project` - Get project details
-- `create_project` - Create a new project
-- `update_project` - Update a project
-- `delete_project` - Delete a project
+- `projects` - Manage projects with `action: list|get|create|update|delete`
 
 ### Environments
 
-- `list_environments` - List environments in a project
-- `get_environment` - Get environment details
-- `create_environment` - Create environment in a project
-- `delete_environment` - Delete an environment
+- `environments` - Manage environments with `action: list|get|create|delete`
 
 ### Applications
 
 - `list_applications` - List all applications (returns summary)
 - `get_application` - Get application details
-- `create_application_private_gh` - Create app from private GitHub repo (GitHub App)
-- `create_application_private_key` - Create app from private repo using deploy key
-- `update_application` - Update an application
-- `delete_application` - Delete an application
-- `start_application` - Start an application
-- `stop_application` - Stop an application
-- `restart_application` - Restart an application
-- `get_application_logs` - Get application logs
-- `list_application_envs` - List application environment variables
-- `create_application_env` - Create application environment variable
-- `update_application_env` - Update application environment variable
-- `delete_application_env` - Delete application environment variable
+- `application_logs` - Get application logs
+- `application` - Create, update, or delete apps with `action: create_public|create_github|create_key|create_dockerimage|update|delete`
+- `env_vars` - Manage env vars with `resource: application, action: list|create|update|delete`
+- `control` - Start/stop/restart with `resource: application, action: start|stop|restart`
 
 ### Databases
 
 - `list_databases` - List all databases (returns summary)
 - `get_database` - Get database details
-- `start_database` - Start a database
-- `stop_database` - Stop a database
-- `restart_database` - Restart a database
-- `delete_database` - Delete a database (with optional volume cleanup)
-- `list_database_backups` - List scheduled backups for a database
-- `get_database_backup` - Get details of a scheduled backup
-- `list_backup_executions` - List execution history for a scheduled backup
-- `get_backup_execution` - Get details of a specific backup execution
+- `database` - Create or delete databases with `action: create|delete, type: postgresql|mysql|mariadb|mongodb|redis|keydb|clickhouse|dragonfly`
+- `database_backups` - Manage backup schedules with `action: list_schedules|get_schedule|create|update|delete|list_executions|get_execution`
+  - Configure frequency, retention policies, S3 storage
+  - Enable/disable schedules without deletion
+  - View backup execution history
+- `control` - Start/stop/restart with `resource: database, action: start|stop|restart`
 
 ### Services
 
 - `list_services` - List all services (returns summary)
 - `get_service` - Get service details
-- `create_service` - Create a one-click service (e.g., pocketbase, mysql, redis, wordpress)
-- `update_service` - Update a service
-- `delete_service` - Delete a service
-- `start_service` - Start a service
-- `stop_service` - Stop a service
-- `restart_service` - Restart a service
-- `list_service_envs` - List service environment variables
-- `create_service_env` - Create service environment variable
-- `delete_service_env` - Delete service environment variable
+- `service` - Create, update, or delete services with `action: create|update|delete`
+- `env_vars` - Manage env vars with `resource: service, action: list|create|delete`
+- `control` - Start/stop/restart with `resource: service, action: start|stop|restart`
 
 ### Deployments
 
 - `list_deployments` - List running deployments (returns summary)
-- `get_deployment` - Get deployment details
 - `deploy` - Deploy by tag or UUID
-- `cancel_deployment` - Cancel a running deployment
-- `list_application_deployments` - List deployments for an application
+- `deployment` - Manage deployments with `action: get|cancel|list_for_app`
 
 ### Private Keys
 
-- `list_private_keys` - List all private keys (SSH keys for deployments)
-- `get_private_key` - Get private key details
-- `create_private_key` - Create a new private key for deployments
-- `update_private_key` - Update a private key
-- `delete_private_key` - Delete a private key
+- `private_keys` - Manage SSH keys with `action: list|get|create|update|delete`
 
 ### Batch Operations
 
@@ -303,9 +274,8 @@ Power user tools for operating on multiple resources at once:
 - **Context-Optimized**: Responses are 90-99% smaller than raw API, preventing context window exhaustion
 - **Smart Lookup**: Find apps by domain (`stuartmason.co.uk`), servers by IP, not just UUIDs
 - **Batch Operations**: Restart entire projects, bulk update env vars, emergency stop all apps
-- **Workflow Prompts**: Pre-built guided workflows for common tasks
 - **Production Ready**: 98%+ test coverage, TypeScript strict mode, comprehensive error handling
-- **Always Current**: Weekly OpenAPI drift detection ensures we stay in sync with Coolify
+- **Always Current**: Weekly OpenAPI drift detection ensures the server stays in sync with Coolify
 
 ## Related Links
 

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

@@ -377,6 +377,16 @@ describe('CoolifyClient', () => {
             mockFetch.mockResolvedValueOnce(mockResponse({}, false, 500));
             await expect(client.listServers()).rejects.toThrow('HTTP 500: Error');
         });
+        it('should include validation errors in error message', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({
+                message: 'Validation failed.',
+                errors: {
+                    name: ['The name field is required.'],
+                    email: ['The email must be valid.', 'The email is already taken.'],
+                },
+            }, false, 422));
+            await expect(client.listServers()).rejects.toThrow('Validation failed. - name: The name field is required.; email: The email must be valid., The email is already taken.');
+        });
     });
     // =========================================================================
     // Server endpoints - additional coverage

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

@@ -52,8 +52,10 @@ describe('CoolifyMcpServer v2', () => {
             // Application operations
             expect(typeof client.listApplications).toBe('function');
             expect(typeof client.getApplication).toBe('function');
+            expect(typeof client.createApplicationPublic).toBe('function');
             expect(typeof client.createApplicationPrivateGH).toBe('function');
             expect(typeof client.createApplicationPrivateKey).toBe('function');
+            expect(typeof client.createApplicationDockerImage).toBe('function');
             expect(typeof client.updateApplication).toBe('function');
             expect(typeof client.deleteApplication).toBe('function');
             expect(typeof client.getApplicationLogs).toBe('function');

package/dist/lib/coolify-client.js

@@ -112,7 +112,15 @@ export class CoolifyClient {
             const data = text ? JSON.parse(text) : {};
             if (!response.ok) {
                 const error = data;
-                throw new Error(error.message || `HTTP ${response.status}: ${response.statusText}`);
+                // Include validation errors if present
+                let errorMessage = error.message || `HTTP ${response.status}: ${response.statusText}`;
+                if (error.errors && Object.keys(error.errors).length > 0) {
+                    const validationDetails = Object.entries(error.errors)
+                        .map(([field, messages]) => `${field}: ${messages.join(', ')}`)
+                        .join('; ');
+                    errorMessage = `${errorMessage} - ${validationDetails}`;
+                }
+                throw new Error(errorMessage);
             }
             return data;
         }

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

@@ -1,5 +1,5 @@
 /**
- * Coolify MCP Server v2.1.0
+ * Coolify MCP Server v2.3.0
  * Consolidated tools for efficient token usage
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

package/dist/lib/mcp-server.js

@@ -1,12 +1,12 @@
 /**
- * Coolify MCP Server v2.1.0
+ * Coolify MCP Server v2.3.0
  * Consolidated tools for efficient token usage
  */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { CoolifyClient, } from './coolify-client.js';
-const VERSION = '2.1.0';
+const VERSION = '2.3.0';
 /** Wrap handler with error handling */
 function wrap(fn) {
     return fn()
@@ -162,7 +162,14 @@ export class CoolifyMcpServer extends McpServer {
         this.tool('list_applications', 'List apps (summary)', { page: z.number().optional(), per_page: z.number().optional() }, async ({ page, per_page }) => wrap(() => this.client.listApplications({ page, per_page, summary: true })));
         this.tool('get_application', 'App details', { uuid: z.string() }, async ({ uuid }) => wrap(() => this.client.getApplication(uuid)));
         this.tool('application', 'Manage app: create/update/delete', {
-            action: z.enum(['create_github', 'create_key', 'update', 'delete']),
+            action: z.enum([
+                'create_public',
+                'create_github',
+                'create_key',
+                'create_dockerimage',
+                'update',
+                'delete',
+            ]),
             uuid: z.string().optional(),
             // Create fields
             project_uuid: z.string().optional(),
@@ -172,17 +179,51 @@ export class CoolifyMcpServer extends McpServer {
             git_repository: z.string().optional(),
             git_branch: z.string().optional(),
             environment_name: z.string().optional(),
+            environment_uuid: z.string().optional(),
             build_pack: z.string().optional(),
             ports_exposes: z.string().optional(),
+            // Docker image fields
+            docker_registry_image_name: z.string().optional(),
+            docker_registry_image_tag: z.string().optional(),
             // Update fields
             name: z.string().optional(),
             description: z.string().optional(),
             fqdn: z.string().optional(),
+            // Health check fields
+            health_check_enabled: z.boolean().optional(),
+            health_check_path: z.string().optional(),
+            health_check_port: z.number().optional(),
+            health_check_host: z.string().optional(),
+            health_check_method: z.string().optional(),
+            health_check_return_code: z.number().optional(),
+            health_check_scheme: z.string().optional(),
+            health_check_response_text: z.string().optional(),
+            health_check_interval: z.number().optional(),
+            health_check_timeout: z.number().optional(),
+            health_check_retries: z.number().optional(),
+            health_check_start_period: z.number().optional(),
             // Delete fields
             delete_volumes: z.boolean().optional(),
         }, async (args) => {
             const { action, uuid } = args;
             switch (action) {
+                case 'create_public':
+                    if (!args.project_uuid ||
+                        !args.server_uuid ||
+                        !args.git_repository ||
+                        !args.git_branch ||
+                        !args.build_pack ||
+                        !args.ports_exposes) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'Error: project_uuid, server_uuid, git_repository, git_branch, build_pack, ports_exposes required',
+                                },
+                            ],
+                        };
+                    }
+                    return wrap(() => this.client.createApplicationPublic(args));
                 case 'create_github':
                     if (!args.project_uuid ||
                         !args.server_uuid ||
@@ -215,6 +256,21 @@ export class CoolifyMcpServer extends McpServer {
                         };
                     }
                     return wrap(() => this.client.createApplicationPrivateKey(args));
+                case 'create_dockerimage':
+                    if (!args.project_uuid ||
+                        !args.server_uuid ||
+                        !args.docker_registry_image_name ||
+                        !args.ports_exposes) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'Error: project_uuid, server_uuid, docker_registry_image_name, ports_exposes required',
+                                },
+                            ],
+                        };
+                    }
+                    return wrap(() => this.client.createApplicationDockerImage(args));
                 case 'update':
                     if (!uuid)
                         return { content: [{ type: 'text', text: 'Error: uuid required' }] };
@@ -428,10 +484,21 @@ export class CoolifyMcpServer extends McpServer {
         this.tool('deployment', 'Manage deployment: get/cancel/list_for_app', {
             action: z.enum(['get', 'cancel', 'list_for_app']),
             uuid: z.string(),
-        }, async ({ action, uuid }) => {
+            lines: z.number().optional(), // Limit log output to last N lines (for 'get' action)
+        }, async ({ action, uuid, lines }) => {
             switch (action) {
                 case 'get':
-                    return wrap(() => this.client.getDeployment(uuid));
+                    return wrap(async () => {
+                        const deployment = await this.client.getDeployment(uuid);
+                        // Truncate logs to last N lines if specified
+                        if (lines && deployment.logs) {
+                            const logLines = deployment.logs.split('\n');
+                            if (logLines.length > lines) {
+                                deployment.logs = logLines.slice(-lines).join('\n');
+                            }
+                        }
+                        return deployment;
+                    });
                 case 'cancel':
                     return wrap(() => this.client.cancelDeployment(uuid));
                 case 'list_for_app':

package/dist/types/coolify.d.ts

@@ -10,6 +10,7 @@ export interface ErrorResponse {
     error?: string;
     message: string;
     status?: number;
+    errors?: Record<string, string[]>;
 }
 export interface DeleteOptions {
     deleteConfigurations?: boolean;
@@ -297,6 +298,15 @@ export interface UpdateApplicationRequest {
     health_check_enabled?: boolean;
     health_check_path?: string;
     health_check_port?: number;
+    health_check_host?: string;
+    health_check_method?: string;
+    health_check_return_code?: number;
+    health_check_scheme?: string;
+    health_check_response_text?: string;
+    health_check_interval?: number;
+    health_check_timeout?: number;
+    health_check_retries?: number;
+    health_check_start_period?: number;
     limits_memory?: string;
     limits_memory_swap?: string;
     limits_cpus?: string;

package/package.json

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