@masonator/coolify-mcp 2.5.0 → 2.6.0

package/README.md

@@ -106,6 +106,28 @@ The Coolify API returns extremely verbose responses - a single application can c
 | list_services         | ~367KB        | ~1.2KB           | **99%**   |
 | list_servers          | ~4KB          | ~0.4KB           | **90%**   |
 | list_application_envs | ~3KB/var      | ~0.1KB/var       | **97%**   |
+| deployment get        | ~13KB         | ~1KB             | **92%**   |
+
+### HATEOAS-style Response Actions
+
+Responses include contextual `_actions` suggesting relevant next steps:
+
+```json
+{
+  "data": { "uuid": "abc123", "status": "running" },
+  "_actions": [
+    { "tool": "application_logs", "args": { "uuid": "abc123" }, "hint": "View logs" },
+    {
+      "tool": "control",
+      "args": { "resource": "application", "action": "restart", "uuid": "abc123" },
+      "hint": "Restart"
+    }
+  ],
+  "_pagination": { "next": { "tool": "list_applications", "args": { "page": 2 } } }
+}
+```
+
+This helps AI assistants understand logical next steps without consuming extra tokens.
 
 ### Recommended Workflow
 

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

@@ -84,6 +84,10 @@ describe('CoolifyClient', () => {
         deployment_uuid: 'dep-123',
         application_name: 'test-app',
         status: 'finished',
+        force_rebuild: false,
+        is_webhook: false,
+        is_api: true,
+        restart_only: false,
         created_at: '2024-01-01',
         updated_at: '2024-01-01',
     };
@@ -342,6 +346,18 @@ describe('CoolifyClient', () => {
             expect(result).toEqual({ message: 'Deployed' });
             expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/deploy?tag=my-tag&force=true', expect.any(Object));
         });
+        it('should deploy by Coolify UUID (24 char alphanumeric)', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Deployed' }));
+            // Coolify-style UUID: 24 lowercase alphanumeric chars
+            await client.deployByTagOrUuid('xs0sgs4gog044s4k4c88kgsc', false);
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/deploy?uuid=xs0sgs4gog044s4k4c88kgsc&force=false', expect.any(Object));
+        });
+        it('should deploy by standard UUID format', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Deployed' }));
+            // Standard UUID format with hyphens
+            await client.deployByTagOrUuid('a1b2c3d4-e5f6-7890-abcd-ef1234567890', true);
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/deploy?uuid=a1b2c3d4-e5f6-7890-abcd-ef1234567890&force=true', expect.any(Object));
+        });
     });
     describe('private keys', () => {
         it('should list private keys', async () => {
@@ -574,6 +590,98 @@ describe('CoolifyClient', () => {
             expect(result).toEqual(mockEnvironment);
             expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/projects/proj-uuid/production', expect.any(Object));
         });
+        it('should get project environment with missing database types', async () => {
+            // Use environment_id to match (what real API uses)
+            const mockDbSummaries = [
+                {
+                    uuid: 'pg-uuid',
+                    name: 'pg-db',
+                    type: 'postgresql',
+                    status: 'running',
+                    is_public: false,
+                    environment_id: 1,
+                },
+                {
+                    uuid: 'dragonfly-uuid',
+                    name: 'dragonfly-cache',
+                    type: 'standalone-dragonfly',
+                    status: 'running',
+                    is_public: false,
+                    environment_id: 1,
+                },
+                {
+                    uuid: 'other-env-db',
+                    name: 'other-db',
+                    type: 'standalone-keydb',
+                    status: 'running',
+                    is_public: false,
+                    environment_id: 999, // different env
+                },
+            ];
+            mockFetch
+                .mockResolvedValueOnce(mockResponse(mockEnvironment))
+                .mockResolvedValueOnce(mockResponse(mockDbSummaries));
+            const result = await client.getProjectEnvironmentWithDatabases('proj-uuid', 'production');
+            expect(result.uuid).toBe('env-uuid');
+            expect(result.dragonflys).toHaveLength(1);
+            expect(result.dragonflys[0].uuid).toBe('dragonfly-uuid');
+            expect(result.keydbs).toBeUndefined(); // other-env-db is in different env
+        });
+        it('should match databases by environment_uuid fallback', async () => {
+            const mockDbSummaries = [
+                {
+                    uuid: 'keydb-uuid',
+                    name: 'keydb-cache',
+                    type: 'standalone-keydb',
+                    status: 'running',
+                    is_public: false,
+                    environment_uuid: 'env-uuid', // matching by uuid
+                },
+            ];
+            mockFetch
+                .mockResolvedValueOnce(mockResponse(mockEnvironment))
+                .mockResolvedValueOnce(mockResponse(mockDbSummaries));
+            const result = await client.getProjectEnvironmentWithDatabases('proj-uuid', 'production');
+            expect(result.keydbs).toHaveLength(1);
+            expect(result.keydbs[0].uuid).toBe('keydb-uuid');
+        });
+        it('should match databases by environment_name fallback', async () => {
+            const mockDbSummaries = [
+                {
+                    uuid: 'clickhouse-uuid',
+                    name: 'clickhouse-analytics',
+                    type: 'standalone-clickhouse',
+                    status: 'running',
+                    is_public: false,
+                    environment_name: 'production', // matching by name
+                },
+            ];
+            mockFetch
+                .mockResolvedValueOnce(mockResponse(mockEnvironment))
+                .mockResolvedValueOnce(mockResponse(mockDbSummaries));
+            const result = await client.getProjectEnvironmentWithDatabases('proj-uuid', 'production');
+            expect(result.clickhouses).toHaveLength(1);
+            expect(result.clickhouses[0].uuid).toBe('clickhouse-uuid');
+        });
+        it('should not add empty arrays when no missing DB types exist', async () => {
+            const mockDbSummaries = [
+                {
+                    uuid: 'pg-uuid',
+                    name: 'pg-db',
+                    type: 'postgresql', // not a "missing" type
+                    status: 'running',
+                    is_public: false,
+                    environment_id: 1,
+                },
+            ];
+            mockFetch
+                .mockResolvedValueOnce(mockResponse(mockEnvironment))
+                .mockResolvedValueOnce(mockResponse(mockDbSummaries));
+            const result = await client.getProjectEnvironmentWithDatabases('proj-uuid', 'production');
+            expect(result.dragonflys).toBeUndefined();
+            expect(result.keydbs).toBeUndefined();
+            expect(result.clickhouses).toBeUndefined();
+        });
         it('should create a project environment', async () => {
             mockFetch.mockResolvedValueOnce(mockResponse({ uuid: 'new-env-uuid' }));
             const result = await client.createProjectEnvironment('proj-uuid', { name: 'staging' });
@@ -1165,12 +1273,47 @@ describe('CoolifyClient', () => {
                 },
             ]);
         });
-        it('should get a deployment', async () => {
+        it('should get a deployment (essential by default, no logs)', async () => {
             mockFetch.mockResolvedValueOnce(mockResponse(mockDeployment));
             const result = await client.getDeployment('dep-uuid');
-            expect(result).toEqual(mockDeployment);
+            // By default, returns DeploymentEssential without logs
+            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: false,
+                logs_info: undefined,
+            });
             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...' };
+            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);
+            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 () => {
+            const deploymentWithLogs = { ...mockDeployment, logs: 'Build started...' };
+            mockFetch.mockResolvedValueOnce(mockResponse(deploymentWithLogs));
+            const result = await client.getDeployment('dep-uuid');
+            // Should have logs_info indicating logs are available
+            expect(result).toMatchObject({
+                uuid: 'dep-uuid',
+                logs_available: true,
+                logs_info: 'Logs available (16 chars). Use lines param to retrieve.',
+            });
+        });
         it('should list application deployments', async () => {
             mockFetch.mockResolvedValueOnce(mockResponse([mockDeployment]));
             const result = await client.listApplicationDeployments('app-uuid');

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

@@ -6,7 +6,7 @@
  * These tests verify MCP server instantiation and structure.
  */
 import { describe, it, expect, beforeEach } from '@jest/globals';
-import { CoolifyMcpServer, truncateLogs } from '../lib/mcp-server.js';
+import { CoolifyMcpServer, truncateLogs, getApplicationActions, getDeploymentActions, getPagination, } from '../lib/mcp-server.js';
 describe('CoolifyMcpServer v2', () => {
     let server;
     beforeEach(() => {
@@ -47,6 +47,7 @@ describe('CoolifyMcpServer v2', () => {
             // Environment operations
             expect(typeof client.listProjectEnvironments).toBe('function');
             expect(typeof client.getProjectEnvironment).toBe('function');
+            expect(typeof client.getProjectEnvironmentWithDatabases).toBe('function');
             expect(typeof client.createProjectEnvironment).toBe('function');
             expect(typeof client.deleteProjectEnvironment).toBe('function');
             // Application operations
@@ -186,3 +187,124 @@ describe('truncateLogs', () => {
         expect(result.length).toBe(100);
     });
 });
+// =============================================================================
+// Action Generators Tests
+// =============================================================================
+describe('getApplicationActions', () => {
+    it('should return view logs action for all apps', () => {
+        const actions = getApplicationActions('app-uuid', 'stopped');
+        expect(actions).toContainEqual({
+            tool: 'application_logs',
+            args: { uuid: 'app-uuid' },
+            hint: 'View logs',
+        });
+    });
+    it('should return restart/stop actions for running apps', () => {
+        const actions = getApplicationActions('app-uuid', 'running');
+        expect(actions).toContainEqual({
+            tool: 'control',
+            args: { resource: 'application', action: 'restart', uuid: 'app-uuid' },
+            hint: 'Restart',
+        });
+        expect(actions).toContainEqual({
+            tool: 'control',
+            args: { resource: 'application', action: 'stop', uuid: 'app-uuid' },
+            hint: 'Stop',
+        });
+    });
+    it('should return start action for stopped apps', () => {
+        const actions = getApplicationActions('app-uuid', 'stopped');
+        expect(actions).toContainEqual({
+            tool: 'control',
+            args: { resource: 'application', action: 'start', uuid: 'app-uuid' },
+            hint: 'Start',
+        });
+    });
+    it('should handle running:healthy status', () => {
+        const actions = getApplicationActions('app-uuid', 'running:healthy');
+        expect(actions.some((a) => a.hint === 'Restart')).toBe(true);
+        expect(actions.some((a) => a.hint === 'Stop')).toBe(true);
+    });
+    it('should handle undefined status', () => {
+        const actions = getApplicationActions('app-uuid', undefined);
+        expect(actions).toContainEqual({
+            tool: 'control',
+            args: { resource: 'application', action: 'start', uuid: 'app-uuid' },
+            hint: 'Start',
+        });
+    });
+});
+describe('getDeploymentActions', () => {
+    it('should return cancel action for in_progress deployments', () => {
+        const actions = getDeploymentActions('dep-uuid', 'in_progress', 'app-uuid');
+        expect(actions).toContainEqual({
+            tool: 'deployment',
+            args: { action: 'cancel', uuid: 'dep-uuid' },
+            hint: 'Cancel',
+        });
+    });
+    it('should return cancel action for queued deployments', () => {
+        const actions = getDeploymentActions('dep-uuid', 'queued', 'app-uuid');
+        expect(actions).toContainEqual({
+            tool: 'deployment',
+            args: { action: 'cancel', uuid: 'dep-uuid' },
+            hint: 'Cancel',
+        });
+    });
+    it('should return app actions when appUuid provided', () => {
+        const actions = getDeploymentActions('dep-uuid', 'finished', 'app-uuid');
+        expect(actions).toContainEqual({
+            tool: 'get_application',
+            args: { uuid: 'app-uuid' },
+            hint: 'View app',
+        });
+        expect(actions).toContainEqual({
+            tool: 'application_logs',
+            args: { uuid: 'app-uuid' },
+            hint: 'App logs',
+        });
+    });
+    it('should not return cancel for finished deployments', () => {
+        const actions = getDeploymentActions('dep-uuid', 'finished', 'app-uuid');
+        expect(actions.some((a) => a.hint === 'Cancel')).toBe(false);
+    });
+    it('should return empty actions when no appUuid and not in_progress', () => {
+        const actions = getDeploymentActions('dep-uuid', 'finished', undefined);
+        expect(actions).toEqual([]);
+    });
+});
+describe('getPagination', () => {
+    it('should return undefined when count is less than perPage and page is 1', () => {
+        const result = getPagination('list_apps', 1, 50, 30);
+        expect(result).toBeUndefined();
+    });
+    it('should return next when count equals or exceeds perPage', () => {
+        const result = getPagination('list_apps', 1, 50, 50);
+        expect(result).toEqual({
+            next: { tool: 'list_apps', args: { page: 2, per_page: 50 } },
+        });
+    });
+    it('should return both prev and next for middle pages', () => {
+        const result = getPagination('list_apps', 2, 50, 50);
+        expect(result).toEqual({
+            prev: { tool: 'list_apps', args: { page: 1, per_page: 50 } },
+            next: { tool: 'list_apps', args: { page: 3, per_page: 50 } },
+        });
+    });
+    it('should return prev when page > 1 and count < perPage', () => {
+        const result = getPagination('list_apps', 3, 50, 20);
+        expect(result).toEqual({
+            prev: { tool: 'list_apps', args: { page: 2, per_page: 50 } },
+        });
+    });
+    it('should use default page and perPage when undefined', () => {
+        const result = getPagination('list_apps', undefined, undefined, 100);
+        expect(result).toEqual({
+            next: { tool: 'list_apps', args: { page: 2, per_page: 50 } },
+        });
+    });
+    it('should return undefined when count is undefined', () => {
+        const result = getPagination('list_apps', 1, 50, undefined);
+        expect(result).toBeUndefined();
+    });
+});

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, EnvVarSummary, CreateEnvVarRequest, UpdateEnvVarRequest, BulkUpdateEnvVarsRequest, Database, UpdateDatabaseRequest, CreatePostgresqlRequest, CreateMysqlRequest, CreateMariadbRequest, CreateMongodbRequest, CreateRedisRequest, CreateKeydbRequest, CreateClickhouseRequest, CreateDragonflyRequest, CreateDatabaseResponse, DatabaseBackup, BackupExecution, CreateDatabaseBackupRequest, UpdateDatabaseBackupRequest, Service, CreateServiceRequest, UpdateServiceRequest, ServiceCreateResponse, Deployment, Team, TeamMember, PrivateKey, CreatePrivateKeyRequest, UpdatePrivateKeyRequest, GitHubApp, CreateGitHubAppRequest, UpdateGitHubAppRequest, GitHubAppUpdateResponse, CloudToken, CreateCloudTokenRequest, UpdateCloudTokenRequest, CloudTokenValidation, Version, ApplicationDiagnostic, ServerDiagnostic, InfrastructureIssuesReport, BatchOperationResult } 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, CreatePostgresqlRequest, CreateMysqlRequest, CreateMariadbRequest, CreateMongodbRequest, CreateRedisRequest, CreateKeydbRequest, CreateClickhouseRequest, CreateDragonflyRequest, CreateDatabaseResponse, DatabaseBackup, BackupExecution, CreateDatabaseBackupRequest, UpdateDatabaseBackupRequest, Service, CreateServiceRequest, UpdateServiceRequest, ServiceCreateResponse, Deployment, DeploymentEssential, Team, TeamMember, PrivateKey, CreatePrivateKeyRequest, UpdatePrivateKeyRequest, GitHubApp, CreateGitHubAppRequest, UpdateGitHubAppRequest, GitHubAppUpdateResponse, CloudToken, CreateCloudTokenRequest, UpdateCloudTokenRequest, CloudTokenValidation, Version, ApplicationDiagnostic, ServerDiagnostic, InfrastructureIssuesReport, BatchOperationResult } from '../types/coolify.js';
 export interface ListOptions {
     page?: number;
     per_page?: number;
@@ -35,6 +35,9 @@ export interface DatabaseSummary {
     type: string;
     status: string;
     is_public: boolean;
+    environment_uuid?: string;
+    environment_name?: string;
+    environment_id?: number;
 }
 export interface ServiceSummary {
     uuid: string;
@@ -89,6 +92,17 @@ export declare class CoolifyClient {
     deleteProject(uuid: string): Promise<MessageResponse>;
     listProjectEnvironments(projectUuid: string): Promise<Environment[]>;
     getProjectEnvironment(projectUuid: string, environmentNameOrUuid: string): Promise<Environment>;
+    /**
+     * Get environment with missing database types (dragonfly, keydb, clickhouse).
+     * Coolify API omits these from the environment endpoint - we cross-reference
+     * with listDatabases using lightweight summaries.
+     * @see https://github.com/StuMason/coolify-mcp/issues/88
+     */
+    getProjectEnvironmentWithDatabases(projectUuid: string, environmentNameOrUuid: string): Promise<Environment & {
+        dragonflys?: DatabaseSummary[];
+        keydbs?: DatabaseSummary[];
+        clickhouses?: DatabaseSummary[];
+    }>;
     createProjectEnvironment(projectUuid: string, data: CreateEnvironmentRequest): Promise<UuidResponse>;
     deleteProjectEnvironment(projectUuid: string, environmentNameOrUuid: string): Promise<MessageResponse>;
     listApplications(options?: ListOptions): Promise<Application[] | ApplicationSummary[]>;
@@ -143,7 +157,9 @@ export declare class CoolifyClient {
     updateServiceEnvVar(uuid: string, data: UpdateEnvVarRequest): Promise<MessageResponse>;
     deleteServiceEnvVar(uuid: string, envUuid: string): Promise<MessageResponse>;
     listDeployments(options?: ListOptions): Promise<Deployment[] | DeploymentSummary[]>;
-    getDeployment(uuid: string): Promise<Deployment>;
+    getDeployment(uuid: string, options?: {
+        includeLogs?: boolean;
+    }): Promise<Deployment | DeploymentEssential>;
     deployByTagOrUuid(tagOrUuid: string, force?: boolean): Promise<MessageResponse>;
     listApplicationDeployments(appUuid: string): Promise<Deployment[]>;
     listTeams(): Promise<Team[]>;

package/dist/lib/coolify-client.js

@@ -38,12 +38,17 @@ function toApplicationSummary(app) {
     };
 }
 function toDatabaseSummary(db) {
+    // API returns database_type not type, and environment_id not environment_uuid
+    const raw = db;
     return {
         uuid: db.uuid,
         name: db.name,
-        type: db.type,
+        type: db.type || raw.database_type,
         status: db.status,
         is_public: db.is_public,
+        environment_uuid: db.environment_uuid,
+        environment_name: db.environment_name,
+        environment_id: raw.environment_id,
     };
 }
 function toServiceSummary(svc) {
@@ -64,6 +69,26 @@ function toDeploymentSummary(dep) {
         created_at: dep.created_at,
     };
 }
+function toDeploymentEssential(dep) {
+    return {
+        uuid: dep.uuid,
+        deployment_uuid: dep.deployment_uuid,
+        application_uuid: dep.application_uuid,
+        application_name: dep.application_name,
+        server_name: dep.server_name,
+        status: dep.status,
+        commit: dep.commit,
+        force_rebuild: dep.force_rebuild,
+        is_webhook: dep.is_webhook,
+        is_api: dep.is_api,
+        created_at: dep.created_at,
+        updated_at: dep.updated_at,
+        logs_available: !!dep.logs,
+        logs_info: dep.logs
+            ? `Logs available (${dep.logs.length} chars). Use lines param to retrieve.`
+            : undefined,
+    };
+}
 function toProjectSummary(proj) {
     return {
         uuid: proj.uuid,
@@ -256,6 +281,32 @@ export class CoolifyClient {
     async getProjectEnvironment(projectUuid, environmentNameOrUuid) {
         return this.request(`/projects/${projectUuid}/${environmentNameOrUuid}`);
     }
+    /**
+     * Get environment with missing database types (dragonfly, keydb, clickhouse).
+     * Coolify API omits these from the environment endpoint - we cross-reference
+     * with listDatabases using lightweight summaries.
+     * @see https://github.com/StuMason/coolify-mcp/issues/88
+     */
+    async getProjectEnvironmentWithDatabases(projectUuid, environmentNameOrUuid) {
+        const [environment, dbSummaries] = await Promise.all([
+            this.getProjectEnvironment(projectUuid, environmentNameOrUuid),
+            this.listDatabases({ summary: true }),
+        ]);
+        // Filter for this environment's missing database types
+        // API uses environment_id, not environment_uuid
+        const envDbs = dbSummaries.filter((db) => db.environment_id === environment.id ||
+            db.environment_uuid === environment.uuid ||
+            db.environment_name === environment.name);
+        const dragonflys = envDbs.filter((db) => db.type?.includes('dragonfly'));
+        const keydbs = envDbs.filter((db) => db.type?.includes('keydb'));
+        const clickhouses = envDbs.filter((db) => db.type?.includes('clickhouse'));
+        return {
+            ...environment,
+            ...(dragonflys.length > 0 && { dragonflys }),
+            ...(keydbs.length > 0 && { keydbs }),
+            ...(clickhouses.length > 0 && { clickhouses }),
+        };
+    }
     async createProjectEnvironment(projectUuid, data) {
         return this.request(`/projects/${projectUuid}/environments`, {
             method: 'POST',
@@ -569,11 +620,14 @@ export class CoolifyClient {
             ? deployments.map(toDeploymentSummary)
             : deployments;
     }
-    async getDeployment(uuid) {
-        return this.request(`/deployments/${uuid}`);
+    async getDeployment(uuid, options) {
+        const deployment = await this.request(`/deployments/${uuid}`);
+        return options?.includeLogs ? deployment : toDeploymentEssential(deployment);
     }
     async deployByTagOrUuid(tagOrUuid, force = false) {
-        return this.request(`/deploy?tag=${encodeURIComponent(tagOrUuid)}&force=${force}`, { method: 'GET' });
+        // Detect if the value looks like a UUID or a tag name
+        const param = this.isLikelyUuid(tagOrUuid) ? 'uuid' : 'tag';
+        return this.request(`/deploy?${param}=${encodeURIComponent(tagOrUuid)}&force=${force}`, { method: 'GET' });
     }
     async listApplicationDeployments(appUuid) {
         return this.request(`/applications/${appUuid}/deployments`);

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

@@ -4,12 +4,18 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
-import type { CoolifyConfig } from '../types/coolify.js';
+import type { CoolifyConfig, ResponseAction, ResponsePagination } from '../types/coolify.js';
 /**
  * Truncate logs by line count and character count.
  * Exported for testing.
  */
 export declare function truncateLogs(logs: string, lineLimit?: number, charLimit?: number): string;
+/** Generate contextual actions for an application based on its status */
+export declare function getApplicationActions(uuid: string, status?: string): ResponseAction[];
+/** Generate contextual actions for a deployment */
+export declare function getDeploymentActions(uuid: string, status: string, appUuid?: string): ResponseAction[];
+/** Generate pagination info for list endpoints */
+export declare function getPagination(tool: string, page?: number, perPage?: number, count?: number): ResponsePagination | undefined;
 export declare class CoolifyMcpServer extends McpServer {
     private readonly client;
     constructor(config: CoolifyConfig);

package/dist/lib/mcp-server.js

@@ -39,6 +39,82 @@ export function truncateLogs(logs, lineLimit = 200, charLimit = 50000) {
     }
     return truncatedLogs;
 }
+// =============================================================================
+// Action Generators for HATEOAS-style responses
+// =============================================================================
+/** Generate contextual actions for an application based on its status */
+export function getApplicationActions(uuid, status) {
+    const actions = [
+        { tool: 'application_logs', args: { uuid }, hint: 'View logs' },
+    ];
+    const s = (status || '').toLowerCase();
+    if (s.includes('running')) {
+        actions.push({
+            tool: 'control',
+            args: { resource: 'application', action: 'restart', uuid },
+            hint: 'Restart',
+        });
+        actions.push({
+            tool: 'control',
+            args: { resource: 'application', action: 'stop', uuid },
+            hint: 'Stop',
+        });
+    }
+    else {
+        actions.push({
+            tool: 'control',
+            args: { resource: 'application', action: 'start', uuid },
+            hint: 'Start',
+        });
+    }
+    return actions;
+}
+/** Generate contextual actions for a deployment */
+export function getDeploymentActions(uuid, status, appUuid) {
+    const actions = [];
+    if (status === 'in_progress' || status === 'queued') {
+        actions.push({ tool: 'deployment', args: { action: 'cancel', uuid }, hint: 'Cancel' });
+    }
+    if (appUuid) {
+        actions.push({ tool: 'get_application', args: { uuid: appUuid }, hint: 'View app' });
+        actions.push({ tool: 'application_logs', args: { uuid: appUuid }, hint: 'App logs' });
+    }
+    return actions;
+}
+/** Generate pagination info for list endpoints */
+export function getPagination(tool, page, perPage, count) {
+    const p = page ?? 1;
+    const pp = perPage ?? 50;
+    if (!count || count < pp) {
+        return p > 1 ? { prev: { tool, args: { page: p - 1, per_page: pp } } } : undefined;
+    }
+    return {
+        ...(p > 1 && { prev: { tool, args: { page: p - 1, per_page: pp } } }),
+        next: { tool, args: { page: p + 1, per_page: pp } },
+    };
+}
+/** Wrap handler with error handling and HATEOAS actions */
+function wrapWithActions(fn, getActions, getPaginationFn) {
+    return fn()
+        .then((result) => {
+        const actions = getActions?.(result) ?? [];
+        const pagination = getPaginationFn?.(result);
+        const response = { data: result };
+        if (actions.length > 0)
+            response._actions = actions;
+        if (pagination)
+            response._pagination = pagination;
+        return { content: [{ type: 'text', text: JSON.stringify(response, null, 2) }] };
+    })
+        .catch((error) => ({
+        content: [
+            {
+                type: 'text',
+                text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+            },
+        ],
+    }));
+}
 export class CoolifyMcpServer extends McpServer {
     constructor(config) {
         super({ name: 'coolify', version: VERSION });
@@ -150,7 +226,7 @@ export class CoolifyMcpServer extends McpServer {
         // =========================================================================
         // Environments (1 tool - consolidated CRUD)
         // =========================================================================
-        this.tool('environments', 'Manage environments: list/get/create/delete', {
+        this.tool('environments', 'Manage environments: list/get/create/delete (get includes dragonfly/keydb/clickhouse DBs missing from API)', {
             action: z.enum(['list', 'get', 'create', 'delete']),
             project_uuid: z.string(),
             name: z.string().optional(),
@@ -162,7 +238,8 @@ export class CoolifyMcpServer extends McpServer {
                 case 'get':
                     if (!name)
                         return { content: [{ type: 'text', text: 'Error: name required' }] };
-                    return wrap(() => this.client.getProjectEnvironment(project_uuid, name));
+                    // Use enhanced method that includes missing DB types (#88)
+                    return wrap(() => this.client.getProjectEnvironmentWithDatabases(project_uuid, name));
                 case 'create':
                     if (!name)
                         return { content: [{ type: 'text', text: 'Error: name required' }] };
@@ -176,8 +253,8 @@ export class CoolifyMcpServer extends McpServer {
         // =========================================================================
         // Applications (4 tools)
         // =========================================================================
-        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('list_applications', 'List apps (summary)', { page: z.number().optional(), per_page: z.number().optional() }, async ({ page, per_page }) => wrapWithActions(() => this.client.listApplications({ page, per_page, summary: true }), undefined, (result) => getPagination('list_applications', page, per_page, result.length)));
+        this.tool('get_application', 'App details', { uuid: z.string() }, async ({ uuid }) => wrapWithActions(() => this.client.getApplication(uuid), (app) => getApplicationActions(app.uuid, app.status)));
         this.tool('application', 'Manage app: create/update/delete', {
             action: z.enum([
                 'create_public',
@@ -504,7 +581,36 @@ export class CoolifyMcpServer extends McpServer {
                     restart: (u) => this.client.restartService(u),
                 },
             };
-            return wrap(() => methods[resource][action](uuid));
+            // Generate contextual actions based on resource type and action taken
+            const getControlActions = () => {
+                const actions = [];
+                if (resource === 'application') {
+                    actions.push({ tool: 'application_logs', args: { uuid }, hint: 'View logs' });
+                    actions.push({ tool: 'get_application', args: { uuid }, hint: 'Check status' });
+                    if (action === 'start' || action === 'restart') {
+                        actions.push({
+                            tool: 'control',
+                            args: { resource: 'application', action: 'stop', uuid },
+                            hint: 'Stop',
+                        });
+                    }
+                    else {
+                        actions.push({
+                            tool: 'control',
+                            args: { resource: 'application', action: 'start', uuid },
+                            hint: 'Start',
+                        });
+                    }
+                }
+                else if (resource === 'database') {
+                    actions.push({ tool: 'get_database', args: { uuid }, hint: 'Check status' });
+                }
+                else if (resource === 'service') {
+                    actions.push({ tool: 'get_service', args: { uuid }, hint: 'Check status' });
+                }
+                return actions;
+            };
+            return wrapWithActions(() => methods[resource][action](uuid), getControlActions);
         });
         // =========================================================================
         // Environment Variables (1 tool - consolidated)
@@ -516,8 +622,7 @@ export class CoolifyMcpServer extends McpServer {
             key: z.string().optional(),
             value: z.string().optional(),
             env_uuid: z.string().optional(),
-            is_build_time: z.boolean().optional(),
-        }, async ({ resource, action, uuid, key, value, env_uuid, is_build_time }) => {
+        }, async ({ resource, action, uuid, key, value, env_uuid }) => {
             if (resource === 'application') {
                 switch (action) {
                     case 'list':
@@ -525,7 +630,8 @@ export class CoolifyMcpServer extends McpServer {
                     case 'create':
                         if (!key || !value)
                             return { content: [{ type: 'text', text: 'Error: key, value required' }] };
-                        return wrap(() => this.client.createApplicationEnvVar(uuid, { key, value, is_build_time }));
+                        // Note: is_build_time is not passed - Coolify API rejects it for create action
+                        return wrap(() => this.client.createApplicationEnvVar(uuid, { key, value }));
                     case 'update':
                         if (!key || !value)
                             return { content: [{ type: 'text', text: 'Error: key, value required' }] };
@@ -560,23 +666,30 @@ export class CoolifyMcpServer extends McpServer {
         // =========================================================================
         // Deployments (3 tools)
         // =========================================================================
-        this.tool('list_deployments', 'List deployments (summary)', { page: z.number().optional(), per_page: z.number().optional() }, async ({ page, per_page }) => wrap(() => this.client.listDeployments({ page, per_page, summary: true })));
-        this.tool('deploy', 'Deploy by tag/UUID', { tag_or_uuid: z.string(), force: z.boolean().optional() }, async ({ tag_or_uuid, force }) => wrap(() => this.client.deployByTagOrUuid(tag_or_uuid, force)));
-        this.tool('deployment', 'Manage deployment: get/cancel/list_for_app (logs truncated to last 200 lines/50K chars by default)', {
+        this.tool('list_deployments', 'List deployments (summary)', { page: z.number().optional(), per_page: z.number().optional() }, async ({ page, per_page }) => wrapWithActions(() => this.client.listDeployments({ page, per_page, summary: true }), undefined, (result) => getPagination('list_deployments', page, per_page, result.length)));
+        this.tool('deploy', 'Deploy by tag/UUID', { tag_or_uuid: z.string(), force: z.boolean().optional() }, async ({ tag_or_uuid, force }) => wrapWithActions(() => this.client.deployByTagOrUuid(tag_or_uuid, force), () => [{ tool: 'list_deployments', args: {}, hint: 'Check deployment status' }]));
+        this.tool('deployment', 'Manage deployment: get/cancel/list_for_app (logs excluded by default, use lines param to include)', {
             action: z.enum(['get', 'cancel', 'list_for_app']),
             uuid: z.string(),
-            lines: z.number().optional(), // Limit log output to last N lines (default: 200)
+            lines: z.number().optional(), // Include logs truncated to last N lines (omit for no logs)
             max_chars: z.number().optional(), // Limit log output to last N chars (default: 50000)
         }, async ({ action, uuid, lines, max_chars }) => {
             switch (action) {
                 case 'get':
-                    return wrap(async () => {
-                        const deployment = await this.client.getDeployment(uuid);
-                        if (deployment.logs) {
-                            deployment.logs = truncateLogs(deployment.logs, lines ?? 200, max_chars ?? 50000);
-                        }
-                        return deployment;
-                    });
+                    // If lines param specified, include logs and truncate
+                    if (lines !== undefined) {
+                        return wrapWithActions(async () => {
+                            const deployment = (await this.client.getDeployment(uuid, {
+                                includeLogs: true,
+                            }));
+                            if (deployment.logs) {
+                                deployment.logs = truncateLogs(deployment.logs, lines, max_chars ?? 50000);
+                            }
+                            return deployment;
+                        }, (dep) => getDeploymentActions(dep.uuid, dep.status, dep.application_uuid));
+                    }
+                    // Otherwise return essential info without logs
+                    return wrapWithActions(() => this.client.getDeployment(uuid), (dep) => getDeploymentActions(dep.uuid, dep.status, dep.application_uuid));
                 case 'cancel':
                     return wrap(() => this.client.cancelDeployment(uuid));
                 case 'list_for_app':

package/dist/types/coolify.d.ts

@@ -901,3 +901,34 @@ export interface BatchOperationResult {
         error: string;
     }>;
 }
+export interface ResponseAction {
+    tool: string;
+    args: Record<string, string | number | boolean>;
+    hint: string;
+}
+export interface ResponsePagination {
+    next?: {
+        tool: string;
+        args: Record<string, number>;
+    };
+    prev?: {
+        tool: string;
+        args: Record<string, number>;
+    };
+}
+export interface DeploymentEssential {
+    uuid: string;
+    deployment_uuid: string;
+    application_uuid?: string;
+    application_name?: string;
+    server_name?: string;
+    status: string;
+    commit?: string;
+    force_rebuild: boolean;
+    is_webhook: boolean;
+    is_api: boolean;
+    created_at: string;
+    updated_at: string;
+    logs_available?: boolean;
+    logs_info?: string;
+}

package/package.json

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