@masonator/coolify-mcp 2.11.0 → 2.12.0

package/README.md

@@ -11,6 +11,8 @@
 
 > **The most comprehensive MCP server for Coolify** - 42 optimized tools, smart diagnostics, documentation search, and batch operations for managing your self-hosted PaaS through AI assistants.
 
+📖 **Docs**: [**coolify-mcp.stumason.dev**](https://coolify-mcp.stumason.dev) — install guide, quickstart, full tools reference, MCP primer, Coolify API gotchas, contributing guide, and the public v3 roadmap.
+
 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

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

@@ -3198,7 +3198,7 @@ describe('CoolifyClient', () => {
                     uuid: 'env-1',
                     key: 'DB_HOST',
                     value: 'localhost',
-                    is_build_time: false,
+                    is_buildtime: false,
                     is_literal: false,
                     is_multiline: false,
                     is_preview: false,
@@ -3532,13 +3532,119 @@ describe('CoolifyClient', () => {
     // Resources endpoint
     // ===========================================================================
     describe('listResources', () => {
-        it('should list all resources', async () => {
-            const mockData = [{ uuid: 'r1', type: 'application' }];
-            mockFetch.mockResolvedValueOnce(mockResponse(mockData));
+        const fluffyResource = {
+            uuid: 'r1',
+            name: 'my-app',
+            type: 'application',
+            status: 'running:healthy',
+            // ---- fluff that the essential projection should drop ----
+            id: 6,
+            config_hash: 'd1b84af30038c5902cced139b19e5f6f',
+            build_pack: 'dockerfile',
+            health_check_path: '/',
+            ports_exposes: '3500',
+            dockerfile_location: '/Dockerfile',
+            custom_labels: 'dHJhZWZpa...',
+            docker_compose: null,
+        };
+        it('returns essential projection by default (uuid/name/type/status only)', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse([fluffyResource]));
             const result = await client.listResources();
-            expect(result).toEqual(mockData);
+            expect(result).toEqual([
+                { uuid: 'r1', name: 'my-app', type: 'application', status: 'running:healthy' },
+            ]);
+            const [first] = result;
+            expect(Object.keys(first).sort()).toEqual(['name', 'status', 'type', 'uuid']);
             expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/resources', expect.any(Object));
         });
+        it('omits status when the resource has none', async () => {
+            const noStatus = { ...fluffyResource };
+            delete noStatus.status;
+            mockFetch.mockResolvedValueOnce(mockResponse([noStatus]));
+            const result = await client.listResources();
+            expect(result).toEqual([{ uuid: 'r1', name: 'my-app', type: 'application' }]);
+            expect('status' in result[0]).toBe(false);
+        });
+        it('returns the raw Coolify payload when include_full is true', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse([fluffyResource]));
+            const result = await client.listResources({ include_full: true });
+            expect(result).toEqual([fluffyResource]);
+            const [first] = result;
+            expect(first.config_hash).toBe(fluffyResource.config_hash);
+            expect(first.custom_labels).toBe(fluffyResource.custom_labels);
+        });
+        it('treats include_full=false as the default essential projection', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse([fluffyResource]));
+            const result = await client.listResources({ include_full: false });
+            expect(Object.keys(result[0]).sort()).toEqual(['name', 'status', 'type', 'uuid']);
+        });
+        it('returns [] on an empty payload (default projection)', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse([]));
+            const result = await client.listResources();
+            expect(result).toEqual([]);
+        });
+        it('returns [] on an empty payload (include_full=true, mask path)', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse([]));
+            const result = await client.listResources({ include_full: true });
+            expect(result).toEqual([]);
+        });
+        it('drops status when Coolify returns a non-string shape (defensive)', async () => {
+            // Hypothetical future Coolify divergence: status emitted as an object/null.
+            // The essential projection must not propagate a non-string into a `string`-typed field.
+            const objStatus = { ...fluffyResource, status: { state: 'running', healthy: true } };
+            mockFetch.mockResolvedValueOnce(mockResponse([objStatus]));
+            const result = await client.listResources();
+            expect(result).toEqual([{ uuid: 'r1', name: 'my-app', type: 'application' }]);
+            expect('status' in result[0]).toBe(false);
+        });
+        describe('sensitive-field masking on include_full', () => {
+            const sensitiveResource = {
+                ...fluffyResource,
+                manual_webhook_secret_github: 'real-github-secret',
+                manual_webhook_secret_gitlab: 'real-gitlab-secret',
+                manual_webhook_secret_gitea: 'real-gitea-secret',
+                manual_webhook_secret_bitbucket: 'real-bitbucket-secret',
+                http_basic_auth_password: 'real-basic-auth-pwd',
+            };
+            it('masks webhook secrets and basic-auth password by default on include_full=true', async () => {
+                mockFetch.mockResolvedValueOnce(mockResponse([sensitiveResource]));
+                const [first] = (await client.listResources({ include_full: true }));
+                expect(first.manual_webhook_secret_github).toBe('***');
+                expect(first.manual_webhook_secret_gitlab).toBe('***');
+                expect(first.manual_webhook_secret_gitea).toBe('***');
+                expect(first.manual_webhook_secret_bitbucket).toBe('***');
+                expect(first.http_basic_auth_password).toBe('***');
+                expect(first.config_hash).toBe(sensitiveResource.config_hash);
+            });
+            it('round-trips plaintext when reveal=true', async () => {
+                mockFetch.mockResolvedValueOnce(mockResponse([sensitiveResource]));
+                const [first] = (await client.listResources({
+                    include_full: true,
+                    reveal: true,
+                }));
+                expect(first.manual_webhook_secret_github).toBe('real-github-secret');
+                expect(first.http_basic_auth_password).toBe('real-basic-auth-pwd');
+            });
+            it('leaves null secret values untouched (Coolify uses null when unset)', async () => {
+                const noSecrets = {
+                    ...fluffyResource,
+                    manual_webhook_secret_github: null,
+                    manual_webhook_secret_gitlab: null,
+                    manual_webhook_secret_gitea: null,
+                    manual_webhook_secret_bitbucket: null,
+                    http_basic_auth_password: null,
+                };
+                mockFetch.mockResolvedValueOnce(mockResponse([noSecrets]));
+                const [first] = (await client.listResources({ include_full: true }));
+                expect(first.manual_webhook_secret_github).toBeNull();
+                expect(first.http_basic_auth_password).toBeNull();
+            });
+            it('reveal=true on the default projection is a no-op (no fluff to reveal)', async () => {
+                mockFetch.mockResolvedValueOnce(mockResponse([sensitiveResource]));
+                const result = await client.listResources({ reveal: true });
+                expect(Object.keys(result[0]).sort()).toEqual(['name', 'status', 'type', 'uuid']);
+            });
+        });
     });
     // ===========================================================================
     // Health endpoint

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

@@ -300,6 +300,22 @@ describe('CoolifyMcpServer v2', () => {
             expect(result.content[0].text).toContain('key, value required');
         });
     });
+    describe('system tool handler', () => {
+        const callSystem = async (srv, args) => {
+            const tool = srv._registeredTools['system'];
+            return tool.handler(args, {});
+        };
+        it('forwards include_full and reveal to listResources', async () => {
+            const spy = jest.spyOn(server['client'], 'listResources').mockResolvedValue([]);
+            await callSystem(server, { action: 'list_resources', include_full: true, reveal: true });
+            expect(spy).toHaveBeenCalledWith({ include_full: true, reveal: true });
+        });
+        it('calls listResources with undefined flags when neither is passed', async () => {
+            const spy = jest.spyOn(server['client'], 'listResources').mockResolvedValue([]);
+            await callSystem(server, { action: 'list_resources' });
+            expect(spy).toHaveBeenCalledWith({ include_full: undefined, reveal: undefined });
+        });
+    });
     describe('bulk_env_update tool handler', () => {
         it('forwards is_buildtime/is_runtime to bulkEnvUpdate', async () => {
             const spy = jest.spyOn(server['client'], 'bulkEnvUpdate').mockResolvedValue({

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, DeploymentEssential, Team, TeamMember, PrivateKey, CreatePrivateKeyRequest, UpdatePrivateKeyRequest, GitHubApp, CreateGitHubAppRequest, UpdateGitHubAppRequest, GitHubAppUpdateResponse, CloudToken, CreateCloudTokenRequest, UpdateCloudTokenRequest, CloudTokenValidation, Version, StorageListResponse, CreateStorageRequest, UpdateStorageRequest, ScheduledTask, ScheduledTaskExecution, CreateScheduledTaskRequest, UpdateScheduledTaskRequest, HetznerLocation, HetznerServerType, HetznerImage, HetznerSSHKey, CreateHetznerServerRequest, CreateHetznerServerResponse, GitHubRepository, GitHubBranch, ApplicationDiagnostic, ServerDiagnostic, InfrastructureIssuesReport, BatchOperationResult, ResourceListItem } 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, StorageListResponse, CreateStorageRequest, UpdateStorageRequest, ScheduledTask, ScheduledTaskExecution, CreateScheduledTaskRequest, UpdateScheduledTaskRequest, HetznerLocation, HetznerServerType, HetznerImage, HetznerSSHKey, CreateHetznerServerRequest, CreateHetznerServerResponse, GitHubRepository, GitHubBranch, ApplicationDiagnostic, ServerDiagnostic, InfrastructureIssuesReport, BatchOperationResult, ResourceListItem, ResourceListItemFull } from '../types/coolify.js';
 export interface ListOptions {
     page?: number;
     per_page?: number;
@@ -262,7 +262,25 @@ export declare class CoolifyClient {
     createHetznerServer(data: CreateHetznerServerRequest): Promise<CreateHetznerServerResponse>;
     listGitHubAppRepositories(githubAppId: number): Promise<GitHubRepository[]>;
     listGitHubAppBranches(githubAppId: number, owner: string, repo: string): Promise<GitHubBranch[]>;
-    listResources(): Promise<ResourceListItem[]>;
+    /**
+     * List every resource on the Coolify instance.
+     *
+     * Defaults to an essential projection ({@link ResourceListItem}: uuid, name,
+     * type, optional status) — Coolify's `/api/v1/resources` endpoint actually
+     * returns ~95 fields per row including the full build/healthcheck/limits
+     * config, which on a moderate instance can exceed 500 KB on a single call
+     * and blow MCP/LLM context budgets. Set `include_full: true` to opt back
+     * into the raw response shape ({@link ResourceListItemFull}).
+     *
+     * When `include_full: true`, sensitive fields ({@link SENSITIVE_RESOURCE_FIELDS}:
+     * webhook HMAC secrets + basic-auth password) are replaced with `'***'`
+     * unless the caller also passes `reveal: true`. Mirrors the v2.9.0 env_vars
+     * masking posture.
+     */
+    listResources(options?: {
+        include_full?: boolean;
+        reveal?: boolean;
+    }): Promise<ResourceListItem[] | ResourceListItemFull[]>;
     getHealth(): Promise<MessageResponse>;
     enableApi(): Promise<MessageResponse>;
     disableApi(): Promise<MessageResponse>;

package/dist/lib/coolify-client.js

@@ -180,6 +180,58 @@ function maskEnvVarSummary(envVar) {
         value: MASKED_VALUE,
     };
 }
+/**
+ * Project a full Coolify resource row down to {@link ResourceListItem} — the
+ * four fields callers actually need for enumeration (uuid, name, type, status).
+ * Drops the ~90 extra fields Coolify returns by default to keep MCP token
+ * budgets sane.
+ */
+function toResourceListItemEssential(item) {
+    const essential = {
+        uuid: item.uuid,
+        name: item.name,
+        type: item.type,
+    };
+    if (typeof item.status === 'string') {
+        essential.status = item.status;
+    }
+    return essential;
+}
+/**
+ * Per-resource sensitive fields returned by Coolify's `/api/v1/resources`
+ * endpoint that are masked by default in {@link CoolifyClient.listResources}
+ * when `include_full: true` is passed. Mirrors the v2.9.0 env-var masking
+ * posture: the underlying API exposes these via the same access token, but
+ * the MCP layer narrows the trust boundary so an LLM client that was granted
+ * "list resources" doesn't silently exfiltrate webhook HMAC secrets or
+ * basic-auth credentials.
+ *
+ * The `manual_webhook_secret_*` fields are HMAC signing keys for inbound
+ * deploy webhooks — anyone with one can forge deploys for that repo
+ * independently of the Coolify API token. `http_basic_auth_password` is the
+ * password gating front-of-app access.
+ */
+const SENSITIVE_RESOURCE_FIELDS = [
+    'manual_webhook_secret_github',
+    'manual_webhook_secret_gitlab',
+    'manual_webhook_secret_gitea',
+    'manual_webhook_secret_bitbucket',
+    'http_basic_auth_password',
+];
+/**
+ * Replace each {@link SENSITIVE_RESOURCE_FIELDS} entry with `'***'` on a full
+ * resource row. Null/undefined values are preserved (since `null` conveys
+ * "no secret set" and matters to callers); only populated values get masked.
+ */
+function maskResourceItemFull(item) {
+    const masked = { ...item };
+    for (const field of SENSITIVE_RESOURCE_FIELDS) {
+        if (masked[field] != null) {
+            masked[field] = MASKED_VALUE;
+        }
+    }
+    return masked;
+}
 /**
  * HTTP client for the Coolify API
  */
@@ -1128,8 +1180,27 @@ export class CoolifyClient {
     // ===========================================================================
     // Resources endpoint
     // ===========================================================================
-    async listResources() {
-        return this.request('/resources');
+    /**
+     * List every resource on the Coolify instance.
+     *
+     * Defaults to an essential projection ({@link ResourceListItem}: uuid, name,
+     * type, optional status) — Coolify's `/api/v1/resources` endpoint actually
+     * returns ~95 fields per row including the full build/healthcheck/limits
+     * config, which on a moderate instance can exceed 500 KB on a single call
+     * and blow MCP/LLM context budgets. Set `include_full: true` to opt back
+     * into the raw response shape ({@link ResourceListItemFull}).
+     *
+     * When `include_full: true`, sensitive fields ({@link SENSITIVE_RESOURCE_FIELDS}:
+     * webhook HMAC secrets + basic-auth password) are replaced with `'***'`
+     * unless the caller also passes `reveal: true`. Mirrors the v2.9.0 env_vars
+     * masking posture.
+     */
+    async listResources(options) {
+        const full = await this.request('/resources');
+        if (options?.include_full !== true) {
+            return full.map(toResourceListItemEssential);
+        }
+        return options.reveal === true ? full : full.map(maskResourceItemFull);
     }
     // ===========================================================================
     // Health endpoint

package/dist/lib/mcp-server.js

@@ -1469,12 +1469,16 @@ export class CoolifyMcpServer extends McpServer {
         // =========================================================================
         // System (1 tool - health/list_resources/api_control consolidated)
         // =========================================================================
-        this.tool('system', 'System operations: health/list_resources/enable_api/disable_api', { action: z.enum(['health', 'list_resources', 'enable_api', 'disable_api']) }, async ({ action }) => {
+        this.tool('system', 'System operations: health/list_resources/enable_api/disable_api. `list_resources` defaults to an essential projection (uuid/name/type/status) to keep token budgets sane on instances with many resources; pass `include_full: true` for the raw Coolify payload. When `include_full: true`, webhook HMAC secrets and basic-auth password are masked unless `reveal: true` is also set (matches the `env_vars` `reveal` ergonomics).', {
+            action: z.enum(['health', 'list_resources', 'enable_api', 'disable_api']),
+            include_full: z.boolean().optional(),
+            reveal: z.boolean().optional(),
+        }, async ({ action, include_full, reveal }) => {
             switch (action) {
                 case 'health':
                     return wrap(() => this.client.getHealth());
                 case 'list_resources':
-                    return wrap(() => this.client.listResources());
+                    return wrap(() => this.client.listResources({ include_full, reveal }));
                 case 'enable_api':
                     return wrap(() => this.client.enableApi());
                 case 'disable_api':

package/dist/types/coolify.d.ts

@@ -1093,6 +1093,14 @@ export interface ResourceListItem {
     type: 'server' | 'application' | 'database' | 'service' | string;
     status?: string;
 }
+/**
+ * Full Coolify `/api/v1/resources` row — the typed essentials plus every other
+ * field Coolify returns (build/healthcheck/limits/git/docker-compose config,
+ * etc.). Only surfaced when the caller passes `include_full: true`; the default
+ * `listResources()` response uses {@link ResourceListItem} to keep MCP token
+ * budgets sane on instances with many resources.
+ */
+export type ResourceListItemFull = ResourceListItem & Record<string, unknown>;
 export interface ResponseAction {
     tool: string;
     args: Record<string, string | number | boolean>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@masonator/coolify-mcp",
   "scope": "@masonator",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "mcpName": "io.github.StuMason/coolify",
   "description": "MCP server for Coolify — 42 optimized tools for infrastructure management, diagnostics, and documentation search",
   "type": "module",