@masonator/coolify-mcp 0.9.0 → 1.1.0

package/README.md

@@ -6,22 +6,36 @@ A Model Context Protocol (MCP) server for [Coolify](https://coolify.io/), enabli
 
 ## Features
 
-This MCP server provides **65 tools** focused on **debugging, management, and deployment**:
+This MCP server provides **67 tools** and **7 workflow prompts** for **debugging, management, and deployment**:
 
 | Category             | Tools                                                                                                    |
 | -------------------- | -------------------------------------------------------------------------------------------------------- |
-| **Infrastructure**   | overview (all resources at once)                                                                         |
+| **Infrastructure**   | overview, mcp_version (all resources at once)                                                            |
 | **Diagnostics**      | diagnose_app, diagnose_server, find_issues (smart lookup by name/domain/IP)                              |
 | **Batch Operations** | restart_project_apps, bulk_env_update, stop_all_apps, redeploy_project                                   |
 | **Servers**          | list, get, validate, resources, domains                                                                  |
 | **Projects**         | list, get, create, update, delete                                                                        |
 | **Environments**     | list, get, create, delete                                                                                |
 | **Applications**     | list, get, update, delete, start, stop, restart, logs, env vars (CRUD), create (private-gh, private-key) |
-| **Databases**        | list, get, start, stop, restart, backups (list, get), backup executions (list, get)                      |
+| **Databases**        | list, get, delete, start, stop, restart, backups (list, get), backup executions (list, get)              |
 | **Services**         | list, get, create, update, delete, start, stop, restart, env vars (list, create, delete)                 |
 | **Deployments**      | list, get, deploy, cancel, list by application                                                           |
 | **Private Keys**     | list, get, create, update, delete                                                                        |
 
+### Workflow Prompts
+
+Pre-built guided workflows that walk you through common tasks:
+
+| Prompt             | Description                                                 |
+| ------------------ | ----------------------------------------------------------- |
+| `debug-app`        | Debug an application - gathers logs, status, env vars       |
+| `health-check`     | Full infrastructure health analysis                         |
+| `deploy-app`       | Step-by-step deployment wizard from Git repository          |
+| `troubleshoot-ssl` | SSL/TLS certificate diagnosis workflow                      |
+| `restart-project`  | Safely restart all apps in a project with status monitoring |
+| `env-audit`        | Audit and compare environment variables across applications |
+| `backup-status`    | Check database backup status and history                    |
+
 ## Installation
 
 ### Prerequisites
@@ -180,6 +194,7 @@ node dist/index.js
 ### Infrastructure
 
 - `get_version` - Get Coolify API version
+- `get_mcp_version` - Get coolify-mcp server version (useful to verify which version is installed)
 - `get_infrastructure_overview` - Get a high-level overview of all infrastructure (servers, projects, applications, databases, services)
 
 ### Diagnostics (Smart Lookup)
@@ -237,6 +252,7 @@ These tools accept human-friendly identifiers instead of just UUIDs:
 - `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

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

@@ -15,6 +15,7 @@ const mockListServices = jest.fn();
 const mockDiagnoseApplication = jest.fn();
 const mockDiagnoseServer = jest.fn();
 const mockFindInfrastructureIssues = jest.fn();
+const mockDeleteDatabase = jest.fn();
 // Mock the CoolifyClient module
 jest.mock('../lib/coolify-client.js', () => ({
     CoolifyClient: jest.fn().mockImplementation(() => ({
@@ -26,6 +27,7 @@ jest.mock('../lib/coolify-client.js', () => ({
         diagnoseApplication: mockDiagnoseApplication,
         diagnoseServer: mockDiagnoseServer,
         findInfrastructureIssues: mockFindInfrastructureIssues,
+        deleteDatabase: mockDeleteDatabase,
         getVersion: jest.fn(),
     })),
 }));
@@ -303,5 +305,29 @@ describe('CoolifyMcpServer', () => {
                 expect(result.issues).toHaveLength(0);
             });
         });
+        describe('delete_database', () => {
+            it('should call deleteDatabase with uuid', async () => {
+                mockDeleteDatabase.mockResolvedValue({ message: 'Database deletion request queued.' });
+                await mockDeleteDatabase('db-uuid-123');
+                expect(mockDeleteDatabase).toHaveBeenCalledWith('db-uuid-123');
+            });
+            it('should call deleteDatabase with delete_volumes option', async () => {
+                mockDeleteDatabase.mockResolvedValue({ message: 'Database deletion request queued.' });
+                await mockDeleteDatabase('db-uuid-123', { deleteVolumes: true });
+                expect(mockDeleteDatabase).toHaveBeenCalledWith('db-uuid-123', { deleteVolumes: true });
+            });
+        });
+    });
+    describe('version tools', () => {
+        it('get_mcp_version should return correct version format', () => {
+            // The VERSION constant is '1.1.0' in mcp-server.ts
+            // This test verifies the expected output structure
+            const expectedResponse = {
+                version: '1.1.0',
+                name: '@masonator/coolify-mcp',
+            };
+            expect(expectedResponse.version).toBe('1.1.0');
+            expect(expectedResponse.name).toBe('@masonator/coolify-mcp');
+        });
     });
 });

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

@@ -26,4 +26,5 @@ export declare class CoolifyMcpServer extends McpServer {
     constructor(config: CoolifyConfig);
     connect(transport: Transport): Promise<void>;
     private registerTools;
+    private registerPrompts;
 }

package/dist/lib/mcp-server.js

@@ -20,7 +20,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { CoolifyClient, } from './coolify-client.js';
-const VERSION = '0.9.0';
+const VERSION = '1.1.0';
 /** Wrap tool handler with consistent error handling */
 function wrapHandler(fn) {
     return fn()
@@ -44,17 +44,26 @@ export class CoolifyMcpServer extends McpServer {
         super({
             name: 'coolify',
             version: VERSION,
-            capabilities: { tools: {} },
+            capabilities: { tools: {}, prompts: {} },
         });
         this.client = new CoolifyClient(config);
         this.registerTools();
+        this.registerPrompts();
     }
     async connect(transport) {
         await super.connect(transport);
     }
     registerTools() {
-        // Version
+        // Version tools
         this.tool('get_version', 'Get Coolify API version', {}, async () => wrapHandler(() => this.client.getVersion()));
+        this.tool('get_mcp_version', 'Get the version of this MCP server (coolify-mcp). Useful to verify which version is installed.', {}, async () => ({
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ version: VERSION, name: '@masonator/coolify-mcp' }, null, 2),
+                },
+            ],
+        }));
         // Infrastructure Overview - high-level view of all resources
         this.tool('get_infrastructure_overview', 'Get a high-level overview of all infrastructure (servers, projects, applications, databases, services). Returns counts and summaries. Start here to understand the infrastructure.', {}, async () => wrapHandler(async () => {
             const results = await Promise.allSettled([
@@ -210,7 +219,7 @@ export class CoolifyMcpServer extends McpServer {
             env_uuid: z.string().describe('Env variable UUID'),
         }, async ({ uuid, env_uuid }) => wrapHandler(() => this.client.deleteApplicationEnvVar(uuid, env_uuid)));
         // =========================================================================
-        // Databases (5 tools)
+        // Databases (6 tools)
         // =========================================================================
         this.tool('list_databases', 'List all databases (returns summary: uuid, name, type, status). Use get_database for full details.', {
             page: z.number().optional().describe('Page number for pagination'),
@@ -220,6 +229,10 @@ export class CoolifyMcpServer extends McpServer {
         this.tool('start_database', 'Start a database', { uuid: z.string().describe('Database UUID') }, async ({ uuid }) => wrapHandler(() => this.client.startDatabase(uuid)));
         this.tool('stop_database', 'Stop a database', { uuid: z.string().describe('Database UUID') }, async ({ uuid }) => wrapHandler(() => this.client.stopDatabase(uuid)));
         this.tool('restart_database', 'Restart a database', { uuid: z.string().describe('Database UUID') }, async ({ uuid }) => wrapHandler(() => this.client.restartDatabase(uuid)));
+        this.tool('delete_database', 'Delete a database. WARNING: This permanently deletes the database and optionally its volumes. Data cannot be recovered unless you have backups.', {
+            uuid: z.string().describe('Database UUID'),
+            delete_volumes: z.boolean().optional().describe('Delete volumes (default: false)'),
+        }, async ({ uuid, delete_volumes }) => wrapHandler(() => this.client.deleteDatabase(uuid, { deleteVolumes: delete_volumes })));
         // =========================================================================
         // Services (11 tools)
         // =========================================================================
@@ -374,4 +387,239 @@ export class CoolifyMcpServer extends McpServer {
             force: z.boolean().optional().describe('Force rebuild (default: true)'),
         }, async ({ project_uuid, force }) => wrapHandler(() => this.client.redeployProjectApps(project_uuid, force ?? true)));
     }
+    // ===========================================================================
+    // Prompt Templates - Guided Workflows
+    // ===========================================================================
+    registerPrompts() {
+        // -------------------------------------------------------------------------
+        // debug-app: Comprehensive application debugging workflow
+        // -------------------------------------------------------------------------
+        this.prompt('debug-app', 'Debug an application - gathers status, logs, env vars, and recent deployments to diagnose issues', {
+            query: z
+                .string()
+                .describe('Application identifier: UUID, name, or domain (e.g., "my-app" or "example.com")'),
+        }, async ({ query }) => {
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `I need help debugging my Coolify application "${query}". Please:
+
+1. First, use the diagnose_app tool with query="${query}" to get comprehensive diagnostics
+2. Analyze the results and identify:
+   - Current health status and any issues
+   - Recent deployment failures or errors in logs
+   - Missing or misconfigured environment variables
+   - Any patterns suggesting the root cause
+3. Provide a clear diagnosis with:
+   - What's wrong (if anything)
+   - Likely root cause
+   - Recommended fix steps
+4. If the app seems healthy, confirm this and suggest any optimizations
+
+Start by running diagnose_app now.`,
+                        },
+                    },
+                ],
+            };
+        });
+        // -------------------------------------------------------------------------
+        // health-check: Full infrastructure health analysis
+        // -------------------------------------------------------------------------
+        this.prompt('health-check', 'Perform a comprehensive health check of your entire Coolify infrastructure', {}, async () => {
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `Please perform a comprehensive health check of my Coolify infrastructure:
+
+1. Run find_issues to scan for problems across all servers, apps, databases, and services
+2. Run get_infrastructure_overview to get the full picture
+3. For any issues found, provide:
+   - Severity (critical/warning/info)
+   - Affected resource and current status
+   - Recommended remediation steps
+4. Summarize the overall health:
+   - Total resources and their states
+   - Any immediate actions needed
+   - Preventive recommendations
+
+Start by running find_issues now.`,
+                        },
+                    },
+                ],
+            };
+        });
+        // -------------------------------------------------------------------------
+        // deploy-app: Step-by-step deployment wizard
+        // -------------------------------------------------------------------------
+        this.prompt('deploy-app', 'Step-by-step wizard to deploy a new application from a Git repository', {
+            repo: z.string().describe('Git repository URL or org/repo format'),
+            branch: z.string().optional().describe('Branch to deploy (default: main)'),
+        }, async ({ repo, branch }) => {
+            const branchName = branch || 'main';
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `I want to deploy a new application from ${repo} (branch: ${branchName}). Please guide me through the process:
+
+1. First, run list_projects to show available projects
+2. Ask me which project to deploy to (or help create a new one)
+3. Run list_servers to show available servers
+4. Ask me which server to deploy on
+5. Run list_private_keys to check available deploy keys
+6. Based on the repository type:
+   - If GitHub and we have a GitHub App configured, use create_application_private_gh
+   - Otherwise, help set up a deploy key and use create_application_private_key
+7. After creation, ask about:
+   - Environment variables needed
+   - Domain/FQDN configuration
+   - Whether to deploy immediately
+
+Start by showing me the available projects.`,
+                        },
+                    },
+                ],
+            };
+        });
+        // -------------------------------------------------------------------------
+        // troubleshoot-ssl: SSL certificate diagnosis workflow
+        // -------------------------------------------------------------------------
+        this.prompt('troubleshoot-ssl', 'Diagnose SSL/TLS certificate issues for a domain', {
+            domain: z.string().describe('Domain having SSL issues (e.g., "example.com")'),
+        }, async ({ domain }) => {
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `I'm having SSL/TLS certificate issues with the domain "${domain}". Please help me diagnose:
+
+1. First, use diagnose_app with query="${domain}" to find the application
+2. Check the application's FQDN configuration
+3. Look for common SSL issues:
+   - Is the domain correctly configured in the FQDN field?
+   - Are there any proxy/redirect issues in the logs?
+   - Is Let's Encrypt renewal working (check for ACME errors)?
+4. Check the server's domain configuration using get_server_domains
+5. Provide remediation steps:
+   - If domain misconfiguration: show how to fix with update_application
+   - If SSL renewal issue: suggest checking DNS and Traefik config
+   - If proxy issue: suggest checking Traefik labels
+
+Start by finding the application for this domain.`,
+                        },
+                    },
+                ],
+            };
+        });
+        // -------------------------------------------------------------------------
+        // restart-project: Safely restart all apps in a project
+        // -------------------------------------------------------------------------
+        this.prompt('restart-project', 'Safely restart all applications in a project with status monitoring', {
+            project: z.string().describe('Project UUID or name'),
+        }, async ({ project }) => {
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `I need to restart all applications in the project "${project}". Please handle this safely:
+
+1. First, run list_projects to find the project UUID (if a name was given)
+2. Run get_project to confirm the project details and list its environments
+3. Run list_applications to find all apps in this project
+4. Show me a summary of what will be restarted:
+   - List each application with current status
+   - Warn about any that are already unhealthy
+5. Ask for my confirmation before proceeding
+6. If confirmed, run restart_project_apps with the project UUID
+7. After restart, check the results and report:
+   - Which apps restarted successfully
+   - Any failures and why
+   - Current status of each app
+
+Start by finding the project.`,
+                        },
+                    },
+                ],
+            };
+        });
+        // -------------------------------------------------------------------------
+        // env-audit: Audit environment variables across apps
+        // -------------------------------------------------------------------------
+        this.prompt('env-audit', 'Audit and compare environment variables across applications', {
+            apps: z
+                .string()
+                .optional()
+                .describe('Comma-separated app names/UUIDs to audit (optional, defaults to all)'),
+            key: z.string().optional().describe('Specific env var key to check across apps'),
+        }, async ({ apps, key }) => {
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `Please audit environment variables across my applications${apps ? ` (${apps})` : ''}${key ? ` focusing on the "${key}" variable` : ''}:
+
+1. Run list_applications to get the list of apps
+2. For ${apps ? 'the specified apps' : 'each application'}, run list_application_envs
+3. Analyze the environment variables:
+   ${key ? `- Check if "${key}" is set consistently across all apps` : '- Identify common variables that differ between apps'}
+   - Flag any sensitive-looking values that might be exposed
+   - Identify missing variables that exist in some apps but not others
+   - Check for any empty or placeholder values
+4. Provide a summary:
+   - Table showing variable presence across apps
+   - Recommendations for standardization
+   - Any security concerns
+
+Start by listing the applications.`,
+                        },
+                    },
+                ],
+            };
+        });
+        // -------------------------------------------------------------------------
+        // backup-status: Check database backup status
+        // -------------------------------------------------------------------------
+        this.prompt('backup-status', 'Check backup status and history for all databases', {}, async () => {
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `Please check the backup status of all my databases:
+
+1. Run list_databases to get all databases
+2. For each database, run list_database_backups to check scheduled backups
+3. For databases with backups configured, run list_backup_executions to check recent history
+4. Report:
+   - Databases WITHOUT any backup schedules (critical!)
+   - Last successful backup for each database
+   - Any failed backups in the last 7 days
+   - Backup frequency and retention settings
+5. Provide recommendations:
+   - Which databases need backup configuration
+   - Any backup schedules that seem too infrequent
+   - Storage concerns if backups are piling up
+
+Start by listing all databases.`,
+                        },
+                    },
+                ],
+            };
+        });
+    }
 }

package/package.json

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