@masonator/coolify-mcp 0.8.0 → 0.8.1

package/README.md

@@ -1,16 +1,17 @@
-[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/stumason-coolify-mcp-badge.png)](https://mseep.ai/app/stumason-coolify-mcp)
-
 # Coolify MCP Server
 
+[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/stumason-coolify-mcp-badge.png)](https://mseep.ai/app/stumason-coolify-mcp)
+
 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
 
-This MCP server provides **58 tools** focused on **debugging, management, and deployment**:
+This MCP server provides **61 tools** focused on **debugging, management, and deployment**:
 
 | Category           | Tools                                                                                                    |
 | ------------------ | -------------------------------------------------------------------------------------------------------- |
 | **Infrastructure** | overview (all resources at once)                                                                         |
+| **Diagnostics**    | diagnose_app, diagnose_server, find_issues (smart lookup by name/domain/IP)                              |
 | **Servers**        | list, get, validate, resources, domains                                                                  |
 | **Projects**       | list, get, create, update, delete                                                                        |
 | **Environments**   | list, get, create, delete                                                                                |
@@ -82,11 +83,12 @@ The Coolify API returns extremely verbose responses - a single application can c
 
 ### Response Size Comparison
 
-| Endpoint          | Full Response | Summary Response | Reduction |
-| ----------------- | ------------- | ---------------- | --------- |
-| list_applications | ~170KB        | ~4.4KB           | **97%**   |
-| list_services     | ~367KB        | ~1.2KB           | **99%**   |
-| list_servers      | ~4KB          | ~0.4KB           | **90%**   |
+| Endpoint              | Full Response | Summary Response | Reduction |
+| --------------------- | ------------- | ---------------- | --------- |
+| list_applications     | ~170KB        | ~4.4KB           | **97%**   |
+| list_services         | ~367KB        | ~1.2KB           | **99%**   |
+| list_servers          | ~4KB          | ~0.4KB           | **90%**   |
+| list_application_envs | ~3KB/var      | ~0.1KB/var       | **97%**   |
 
 ### Recommended Workflow
 
@@ -108,7 +110,7 @@ list_applications(page=2, per_page=10)
 
 ### Getting Started
 
-```
+```text
 Give me an overview of my infrastructure
 Show me all my applications
 What's running on my servers?
@@ -116,9 +118,12 @@ What's running on my servers?
 
 ### Debugging & Monitoring
 
-```
+```text
+Diagnose my stuartmason.co.uk app
+What's wrong with my-api application?
+Check the status of server 192.168.1.100
+Find any issues in my infrastructure
 Get the logs for application {uuid}
-What's the status of application {uuid}?
 What environment variables are set for application {uuid}?
 Show me recent deployments for application {uuid}
 What resources are running on server {uuid}?
@@ -126,7 +131,7 @@ What resources are running on server {uuid}?
 
 ### Application Management
 
-```
+```text
 Restart application {uuid}
 Stop the database {uuid}
 Start service {uuid}
@@ -136,7 +141,7 @@ Update the DATABASE_URL env var for application {uuid}
 
 ### Project Setup
 
-```
+```text
 Create a new project called "my-app"
 Create a staging environment in project {uuid}
 Deploy my app from private GitHub repo org/repo on branch main
@@ -176,6 +181,14 @@ node dist/index.js
 - `get_version` - Get Coolify API version
 - `get_infrastructure_overview` - Get a high-level overview of all infrastructure (servers, projects, applications, databases, services)
 
+### Diagnostics (Smart Lookup)
+
+These tools accept human-friendly identifiers instead of just UUIDs:
+
+- `diagnose_app` - Get comprehensive app diagnostics (status, logs, env vars, deployments). Accepts UUID, name, or domain (e.g., "stuartmason.co.uk" or "my-app")
+- `diagnose_server` - Get server diagnostics (status, resources, domains, validation). Accepts UUID, name, or IP address (e.g., "coolify-apps" or "192.168.1.100")
+- `find_issues` - Scan entire infrastructure for unhealthy apps, databases, services, and unreachable servers
+
 ### Servers
 
 - `list_servers` - List all servers (returns summary)

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

@@ -649,6 +649,34 @@ describe('CoolifyClient', () => {
             expect(result).toEqual([mockEnvVar]);
             expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/applications/app-uuid/envs', expect.any(Object));
         });
+        it('should list application env vars with summary', async () => {
+            const fullEnvVar = {
+                id: 1,
+                uuid: 'env-var-uuid',
+                key: 'API_KEY',
+                value: 'secret123',
+                is_build_time: false,
+                is_literal: true,
+                is_multiline: false,
+                is_preview: false,
+                is_shared: false,
+                is_shown_once: false,
+                application_id: 1,
+                created_at: '2024-01-01',
+                updated_at: '2024-01-01',
+            };
+            mockFetch.mockResolvedValueOnce(mockResponse([fullEnvVar]));
+            const result = await client.listApplicationEnvVars('app-uuid', { summary: true });
+            // Summary should only include uuid, key, value, is_build_time
+            expect(result).toEqual([
+                {
+                    uuid: 'env-var-uuid',
+                    key: 'API_KEY',
+                    value: 'secret123',
+                    is_build_time: false,
+                },
+            ]);
+        });
         it('should create application env var', async () => {
             mockFetch.mockResolvedValueOnce(mockResponse({ uuid: 'new-env-uuid' }));
             const result = await client.createApplicationEnvVar('app-uuid', {

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, CreateEnvVarRequest, UpdateEnvVarRequest, BulkUpdateEnvVarsRequest, Database, UpdateDatabaseRequest, DatabaseBackup, BackupExecution, Service, CreateServiceRequest, UpdateServiceRequest, ServiceCreateResponse, Deployment, Team, TeamMember, PrivateKey, CreatePrivateKeyRequest, UpdatePrivateKeyRequest, CloudToken, CreateCloudTokenRequest, UpdateCloudTokenRequest, CloudTokenValidation, Version, ApplicationDiagnostic, ServerDiagnostic, InfrastructureIssuesReport } 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, DatabaseBackup, BackupExecution, Service, CreateServiceRequest, UpdateServiceRequest, ServiceCreateResponse, Deployment, Team, TeamMember, PrivateKey, CreatePrivateKeyRequest, UpdatePrivateKeyRequest, CloudToken, CreateCloudTokenRequest, UpdateCloudTokenRequest, CloudTokenValidation, Version, ApplicationDiagnostic, ServerDiagnostic, InfrastructureIssuesReport } from '../types/coolify.js';
 export interface ListOptions {
     page?: number;
     per_page?: number;
@@ -100,7 +100,9 @@ export declare class CoolifyClient {
     }): Promise<ApplicationActionResponse>;
     stopApplication(uuid: string): Promise<ApplicationActionResponse>;
     restartApplication(uuid: string): Promise<ApplicationActionResponse>;
-    listApplicationEnvVars(uuid: string): Promise<EnvironmentVariable[]>;
+    listApplicationEnvVars(uuid: string, options?: {
+        summary?: boolean;
+    }): Promise<EnvironmentVariable[] | EnvVarSummary[]>;
     createApplicationEnvVar(uuid: string, data: CreateEnvVarRequest): Promise<UuidResponse>;
     updateApplicationEnvVar(uuid: string, data: UpdateEnvVarRequest): Promise<MessageResponse>;
     bulkUpdateApplicationEnvVars(uuid: string, data: BulkUpdateEnvVarsRequest): Promise<MessageResponse>;

package/dist/lib/coolify-client.js

@@ -71,6 +71,14 @@ function toProjectSummary(proj) {
         description: proj.description,
     };
 }
+function toEnvVarSummary(envVar) {
+    return {
+        uuid: envVar.uuid,
+        key: envVar.key,
+        value: envVar.value,
+        is_build_time: envVar.is_build_time,
+    };
+}
 /**
  * HTTP client for the Coolify API
  */
@@ -333,8 +341,9 @@ export class CoolifyClient {
     // ===========================================================================
     // Application Environment Variables
     // ===========================================================================
-    async listApplicationEnvVars(uuid) {
-        return this.request(`/applications/${uuid}/envs`);
+    async listApplicationEnvVars(uuid, options) {
+        const envVars = await this.request(`/applications/${uuid}/envs`);
+        return options?.summary ? envVars.map(toEnvVarSummary) : envVars;
     }
     async createApplicationEnvVar(uuid, data) {
         return this.request(`/applications/${uuid}/envs`, {

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.8.0';
+const VERSION = '0.8.1';
 /** Wrap tool handler with consistent error handling */
 function wrapHandler(fn) {
     return fn()
@@ -193,7 +193,7 @@ export class CoolifyMcpServer extends McpServer {
             lines: z.number().optional().describe('Number of lines'),
         }, async ({ uuid, lines }) => wrapHandler(() => this.client.getApplicationLogs(uuid, lines)));
         // Application env vars
-        this.tool('list_application_envs', 'List application environment variables', { uuid: z.string().describe('Application UUID') }, async ({ uuid }) => wrapHandler(() => this.client.listApplicationEnvVars(uuid)));
+        this.tool('list_application_envs', 'List application environment variables (returns summary: uuid, key, value, is_build_time)', { uuid: z.string().describe('Application UUID') }, async ({ uuid }) => wrapHandler(() => this.client.listApplicationEnvVars(uuid, { summary: true })));
         this.tool('create_application_env', 'Create application environment variable', {
             uuid: z.string().describe('Application UUID'),
             key: z.string().describe('Variable key'),
@@ -344,7 +344,7 @@ export class CoolifyMcpServer extends McpServer {
         // =========================================================================
         // Diagnostics (3 tools) - Composite tools for debugging
         // =========================================================================
-        this.tool('diagnose_app', 'Get comprehensive diagnostic info for an application. Accepts UUID, name, or domain (e.g., "tidylinker.com" or "my-app"). Aggregates: status, health assessment, logs (last 50 lines), environment variables (keys only, values hidden), and recent deployments. Use this for debugging application issues.', { query: z.string().describe('Application UUID, name, or domain (FQDN)') }, async ({ query }) => wrapHandler(() => this.client.diagnoseApplication(query)));
+        this.tool('diagnose_app', 'Get comprehensive diagnostic info for an application. Accepts UUID, name, or domain (e.g., "stuartmason.co.uk" or "my-app"). Aggregates: status, health assessment, logs (last 50 lines), environment variables (keys only, values hidden), and recent deployments. Use this for debugging application issues.', { query: z.string().describe('Application UUID, name, or domain (FQDN)') }, async ({ query }) => wrapHandler(() => this.client.diagnoseApplication(query)));
         this.tool('diagnose_server', 'Get comprehensive diagnostic info for a server. Accepts UUID, name, or IP address (e.g., "coolify-apps" or "192.168.1.100"). Aggregates: server status, health assessment, running resources, configured domains, and connection validation. Use this for debugging server issues.', { query: z.string().describe('Server UUID, name, or IP address') }, async ({ query }) => wrapHandler(() => this.client.diagnoseServer(query)));
         this.tool('find_issues', 'Scan entire infrastructure for common issues. Finds: unreachable servers, unhealthy/stopped applications, exited databases, and stopped services. Returns a summary with issue counts and detailed list of problems.', {}, async () => wrapHandler(() => this.client.findInfrastructureIssues()));
     }

package/dist/types/coolify.d.ts

@@ -348,6 +348,12 @@ export interface UpdateEnvVarRequest {
 export interface BulkUpdateEnvVarsRequest {
     data: CreateEnvVarRequest[];
 }
+export interface EnvVarSummary {
+    uuid: string;
+    key: string;
+    value: string;
+    is_build_time: boolean;
+}
 export type DatabaseType = 'postgresql' | 'mysql' | 'mariadb' | 'mongodb' | 'redis' | 'keydb' | 'clickhouse' | 'dragonfly';
 export interface DatabaseLimits {
     memory?: string;

package/package.json

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