@masonator/coolify-mcp 0.7.0 → 0.8.1

package/dist/__tests__/integration/diagnostics.integration.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Integration tests for diagnostic tools.
+ *
+ * These tests hit the real Coolify API to verify diagnostic methods work correctly.
+ * They are skipped in CI and should be run manually when testing against a real instance.
+ *
+ * Prerequisites:
+ * - COOLIFY_URL and COOLIFY_TOKEN environment variables set (from .env)
+ * - Access to a running Coolify instance
+ *
+ * Run with: npm run test:integration
+ */
+export {};

package/dist/__tests__/integration/diagnostics.integration.test.js

@@ -0,0 +1,140 @@
+/**
+ * Integration tests for diagnostic tools.
+ *
+ * These tests hit the real Coolify API to verify diagnostic methods work correctly.
+ * They are skipped in CI and should be run manually when testing against a real instance.
+ *
+ * Prerequisites:
+ * - COOLIFY_URL and COOLIFY_TOKEN environment variables set (from .env)
+ * - Access to a running Coolify instance
+ *
+ * Run with: npm run test:integration
+ */
+import { config } from 'dotenv';
+import { CoolifyClient } from '../../lib/coolify-client.js';
+// Load environment variables from .env file
+config();
+const COOLIFY_URL = process.env.COOLIFY_URL;
+const COOLIFY_TOKEN = process.env.COOLIFY_TOKEN;
+// Skip all tests if environment variables are not set
+const shouldRun = COOLIFY_URL && COOLIFY_TOKEN;
+// Test data - UUIDs from actual infrastructure
+// These should be updated to match your test environment
+const TEST_DATA = {
+    // Server: coolify-apps (running, reachable)
+    SERVER_UUID: 'ggkk8w4c08gw48oowsg4g0oc',
+    // Application: test-system (running)
+    APP_UUID_HEALTHY: 'xs0sgs4gog044s4k4c88kgsc',
+    // Application: Bumnail Benerator (exited:unhealthy)
+    APP_UUID_UNHEALTHY: 't444wg40s4kkwcc04s084wgw',
+};
+const describeFn = shouldRun ? describe : describe.skip;
+describeFn('Diagnostic Integration Tests', () => {
+    let client;
+    beforeAll(() => {
+        if (!COOLIFY_URL || !COOLIFY_TOKEN) {
+            throw new Error('COOLIFY_URL and COOLIFY_TOKEN must be set for integration tests');
+        }
+        client = new CoolifyClient({
+            baseUrl: COOLIFY_URL,
+            accessToken: COOLIFY_TOKEN,
+        });
+    });
+    describe('diagnoseApplication', () => {
+        it('should return diagnostic data for a healthy application', async () => {
+            const result = await client.diagnoseApplication(TEST_DATA.APP_UUID_HEALTHY);
+            // Should have application info
+            expect(result.application).not.toBeNull();
+            expect(result.application?.uuid).toBe(TEST_DATA.APP_UUID_HEALTHY);
+            expect(result.application?.name).toBeDefined();
+            // Should have health assessment
+            expect(result.health).toBeDefined();
+            expect(['healthy', 'unhealthy', 'unknown']).toContain(result.health.status);
+            // Should have environment variables (even if empty)
+            expect(result.environment_variables).toBeDefined();
+            expect(typeof result.environment_variables.count).toBe('number');
+            expect(Array.isArray(result.environment_variables.variables)).toBe(true);
+            // Values should be hidden (only key and is_build_time exposed)
+            if (result.environment_variables.variables.length > 0) {
+                const firstVar = result.environment_variables.variables[0];
+                expect(firstVar).toHaveProperty('key');
+                expect(firstVar).toHaveProperty('is_build_time');
+                expect(firstVar).not.toHaveProperty('value');
+            }
+            // Should have recent deployments array
+            expect(Array.isArray(result.recent_deployments)).toBe(true);
+            // Should not have errors if all calls succeeded
+            // (errors array might be present if some endpoints failed)
+            console.log('Healthy app diagnostic result:', JSON.stringify(result, null, 2));
+        }, 30000);
+        it('should detect issues in an unhealthy application', async () => {
+            const result = await client.diagnoseApplication(TEST_DATA.APP_UUID_UNHEALTHY);
+            expect(result.application).not.toBeNull();
+            // Should detect unhealthy status
+            if (result.application?.status?.includes('exited') ||
+                result.application?.status?.includes('unhealthy')) {
+                expect(result.health.status).toBe('unhealthy');
+                expect(result.health.issues.length).toBeGreaterThan(0);
+            }
+            console.log('Unhealthy app diagnostic result:', JSON.stringify(result, null, 2));
+        }, 30000);
+        it('should handle non-existent application gracefully', async () => {
+            const result = await client.diagnoseApplication('non-existent-uuid');
+            // Should have errors but not throw
+            expect(result.errors).toBeDefined();
+            expect(result.errors.length).toBeGreaterThan(0);
+            expect(result.application).toBeNull();
+        }, 30000);
+    });
+    describe('diagnoseServer', () => {
+        it('should return diagnostic data for a server', async () => {
+            const result = await client.diagnoseServer(TEST_DATA.SERVER_UUID);
+            // Should have server info
+            expect(result.server).not.toBeNull();
+            expect(result.server?.uuid).toBe(TEST_DATA.SERVER_UUID);
+            expect(result.server?.name).toBeDefined();
+            expect(result.server?.ip).toBeDefined();
+            // Should have health assessment
+            expect(result.health).toBeDefined();
+            expect(['healthy', 'unhealthy', 'unknown']).toContain(result.health.status);
+            // Should have resources array
+            expect(Array.isArray(result.resources)).toBe(true);
+            // Should have domains array
+            expect(Array.isArray(result.domains)).toBe(true);
+            // Should have validation result
+            expect(result.validation).toBeDefined();
+            console.log('Server diagnostic result:', JSON.stringify(result, null, 2));
+        }, 30000);
+        it('should handle non-existent server gracefully', async () => {
+            const result = await client.diagnoseServer('non-existent-uuid');
+            expect(result.errors).toBeDefined();
+            expect(result.errors.length).toBeGreaterThan(0);
+            expect(result.server).toBeNull();
+        }, 30000);
+    });
+    describe('findInfrastructureIssues', () => {
+        it('should return infrastructure issues report', async () => {
+            const result = await client.findInfrastructureIssues();
+            // Should have summary
+            expect(result.summary).toBeDefined();
+            expect(typeof result.summary.total_issues).toBe('number');
+            expect(typeof result.summary.unhealthy_applications).toBe('number');
+            expect(typeof result.summary.unhealthy_databases).toBe('number');
+            expect(typeof result.summary.unhealthy_services).toBe('number');
+            expect(typeof result.summary.unreachable_servers).toBe('number');
+            // Should have issues array
+            expect(Array.isArray(result.issues)).toBe(true);
+            // Each issue should have required fields
+            for (const issue of result.issues) {
+                expect(['application', 'database', 'service', 'server']).toContain(issue.type);
+                expect(issue.uuid).toBeDefined();
+                expect(issue.name).toBeDefined();
+                expect(issue.issue).toBeDefined();
+                expect(issue.status).toBeDefined();
+            }
+            // Summary counts should match issues array
+            expect(result.summary.total_issues).toBe(result.issues.length);
+            console.log('Infrastructure issues report:', JSON.stringify(result, null, 2));
+        }, 60000);
+    });
+});

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

@@ -12,6 +12,9 @@ const mockListProjects = jest.fn();
 const mockListApplications = jest.fn();
 const mockListDatabases = jest.fn();
 const mockListServices = jest.fn();
+const mockDiagnoseApplication = jest.fn();
+const mockDiagnoseServer = jest.fn();
+const mockFindInfrastructureIssues = jest.fn();
 // Mock the CoolifyClient module
 jest.mock('../lib/coolify-client.js', () => ({
     CoolifyClient: jest.fn().mockImplementation(() => ({
@@ -20,6 +23,9 @@ jest.mock('../lib/coolify-client.js', () => ({
         listApplications: mockListApplications,
         listDatabases: mockListDatabases,
         listServices: mockListServices,
+        diagnoseApplication: mockDiagnoseApplication,
+        diagnoseServer: mockDiagnoseServer,
+        findInfrastructureIssues: mockFindInfrastructureIssues,
         getVersion: jest.fn(),
     })),
 }));
@@ -138,4 +144,164 @@ describe('CoolifyMcpServer', () => {
             await expect(mockListServers({ summary: true })).rejects.toThrow('Connection failed');
         });
     });
+    describe('diagnostic tools', () => {
+        beforeEach(() => {
+            new CoolifyMcpServer({
+                baseUrl: 'http://localhost:3000',
+                accessToken: 'test-token',
+            });
+        });
+        describe('diagnose_app', () => {
+            it('should call diagnoseApplication with the query', async () => {
+                mockDiagnoseApplication.mockResolvedValue({
+                    application: {
+                        uuid: 'app-uuid-123',
+                        name: 'test-app',
+                        status: 'running',
+                        fqdn: 'https://test.example.com',
+                        git_repository: 'org/repo',
+                        git_branch: 'main',
+                    },
+                    health: { status: 'healthy', issues: [] },
+                    logs: 'Application started',
+                    environment_variables: {
+                        count: 2,
+                        variables: [{ key: 'NODE_ENV', is_build_time: false }],
+                    },
+                    recent_deployments: [],
+                });
+                await mockDiagnoseApplication('test-app');
+                expect(mockDiagnoseApplication).toHaveBeenCalledWith('test-app');
+            });
+            it('should call diagnoseApplication with a domain', async () => {
+                mockDiagnoseApplication.mockResolvedValue({
+                    application: null,
+                    health: { status: 'unknown', issues: [] },
+                    logs: null,
+                    environment_variables: { count: 0, variables: [] },
+                    recent_deployments: [],
+                    errors: ['Application not found'],
+                });
+                await mockDiagnoseApplication('tidylinker.com');
+                expect(mockDiagnoseApplication).toHaveBeenCalledWith('tidylinker.com');
+            });
+            it('should call diagnoseApplication with a UUID', async () => {
+                mockDiagnoseApplication.mockResolvedValue({
+                    application: {
+                        uuid: 'xs0sgs4gog044s4k4c88kgsc',
+                        name: 'test-app',
+                        status: 'running',
+                        fqdn: null,
+                        git_repository: null,
+                        git_branch: null,
+                    },
+                    health: { status: 'healthy', issues: [] },
+                    logs: null,
+                    environment_variables: { count: 0, variables: [] },
+                    recent_deployments: [],
+                });
+                await mockDiagnoseApplication('xs0sgs4gog044s4k4c88kgsc');
+                expect(mockDiagnoseApplication).toHaveBeenCalledWith('xs0sgs4gog044s4k4c88kgsc');
+            });
+        });
+        describe('diagnose_server', () => {
+            it('should call diagnoseServer with the query', async () => {
+                mockDiagnoseServer.mockResolvedValue({
+                    server: {
+                        uuid: 'srv-uuid-123',
+                        name: 'production-server',
+                        ip: '192.168.1.100',
+                        status: 'running',
+                        is_reachable: true,
+                    },
+                    health: { status: 'healthy', issues: [] },
+                    resources: [],
+                    domains: [],
+                    validation: { message: 'Server is reachable' },
+                });
+                await mockDiagnoseServer('production-server');
+                expect(mockDiagnoseServer).toHaveBeenCalledWith('production-server');
+            });
+            it('should call diagnoseServer with an IP address', async () => {
+                mockDiagnoseServer.mockResolvedValue({
+                    server: {
+                        uuid: 'srv-uuid-123',
+                        name: 'production-server',
+                        ip: '192.168.1.100',
+                        status: 'running',
+                        is_reachable: true,
+                    },
+                    health: { status: 'healthy', issues: [] },
+                    resources: [],
+                    domains: [],
+                    validation: { message: 'Server is reachable' },
+                });
+                await mockDiagnoseServer('192.168.1.100');
+                expect(mockDiagnoseServer).toHaveBeenCalledWith('192.168.1.100');
+            });
+            it('should call diagnoseServer with a UUID', async () => {
+                mockDiagnoseServer.mockResolvedValue({
+                    server: {
+                        uuid: 'ggkk8w4c08gw48oowsg4g0oc',
+                        name: 'coolify-apps',
+                        ip: '10.0.0.1',
+                        status: 'running',
+                        is_reachable: true,
+                    },
+                    health: { status: 'healthy', issues: [] },
+                    resources: [],
+                    domains: [],
+                    validation: { message: 'Server is reachable' },
+                });
+                await mockDiagnoseServer('ggkk8w4c08gw48oowsg4g0oc');
+                expect(mockDiagnoseServer).toHaveBeenCalledWith('ggkk8w4c08gw48oowsg4g0oc');
+            });
+        });
+        describe('find_issues', () => {
+            it('should call findInfrastructureIssues', async () => {
+                mockFindInfrastructureIssues.mockResolvedValue({
+                    summary: {
+                        total_issues: 2,
+                        unhealthy_applications: 1,
+                        unhealthy_databases: 0,
+                        unhealthy_services: 1,
+                        unreachable_servers: 0,
+                    },
+                    issues: [
+                        {
+                            type: 'application',
+                            uuid: 'app-1',
+                            name: 'broken-app',
+                            issue: 'Application is unhealthy',
+                            status: 'exited:unhealthy',
+                        },
+                        {
+                            type: 'service',
+                            uuid: 'svc-1',
+                            name: 'broken-service',
+                            issue: 'Service has exited',
+                            status: 'exited',
+                        },
+                    ],
+                });
+                await mockFindInfrastructureIssues();
+                expect(mockFindInfrastructureIssues).toHaveBeenCalled();
+            });
+            it('should return empty issues when infrastructure is healthy', async () => {
+                mockFindInfrastructureIssues.mockResolvedValue({
+                    summary: {
+                        total_issues: 0,
+                        unhealthy_applications: 0,
+                        unhealthy_databases: 0,
+                        unhealthy_services: 0,
+                        unreachable_servers: 0,
+                    },
+                    issues: [],
+                });
+                const result = await mockFindInfrastructureIssues();
+                expect(result.summary.total_issues).toBe(0);
+                expect(result.issues).toHaveLength(0);
+            });
+        });
+    });
 });

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 } 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>;
@@ -149,4 +151,37 @@ export declare class CoolifyClient {
     listBackupExecutions(databaseUuid: string, backupUuid: string): Promise<BackupExecution[]>;
     getBackupExecution(databaseUuid: string, backupUuid: string, executionUuid: string): Promise<BackupExecution>;
     cancelDeployment(uuid: string): Promise<MessageResponse>;
+    /**
+     * Check if a string looks like a UUID (Coolify format or standard format).
+     * Coolify UUIDs are alphanumeric strings, typically 24 chars like "xs0sgs4gog044s4k4c88kgsc"
+     * Also accepts standard UUID format with hyphens like "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+     */
+    private isLikelyUuid;
+    /**
+     * Find an application by UUID, name, or domain (FQDN).
+     * Returns the UUID if found, throws if not found or multiple matches.
+     */
+    resolveApplicationUuid(query: string): Promise<string>;
+    /**
+     * Find a server by UUID, name, or IP address.
+     * Returns the UUID if found, throws if not found or multiple matches.
+     */
+    resolveServerUuid(query: string): Promise<string>;
+    /**
+     * Get comprehensive diagnostic info for an application.
+     * Aggregates: application details, logs, env vars, recent deployments.
+     * @param query - Application UUID, name, or domain (FQDN)
+     */
+    diagnoseApplication(query: string): Promise<ApplicationDiagnostic>;
+    /**
+     * Get comprehensive diagnostic info for a server.
+     * Aggregates: server details, resources, domains, validation.
+     * @param query - Server UUID, name, or IP address
+     */
+    diagnoseServer(query: string): Promise<ServerDiagnostic>;
+    /**
+     * Scan infrastructure for common issues.
+     * Finds: unreachable servers, unhealthy apps, exited databases, stopped services.
+     */
+    findInfrastructureIssues(): Promise<InfrastructureIssuesReport>;
 }