@masonator/coolify-mcp
Version:
MCP server implementation for Coolify
255 lines (254 loc) • 13.8 kB
TypeScript
/**
* 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, ApplicationDiagnostic, ServerDiagnostic, InfrastructureIssuesReport, BatchOperationResult } from '../types/coolify.js';
export interface ListOptions {
page?: number;
per_page?: number;
summary?: boolean;
}
export interface PaginatedResponse<T> {
data: T[];
total?: number;
page?: number;
per_page?: number;
}
export interface ServerSummary {
uuid: string;
name: string;
ip: string;
status?: string;
is_reachable?: boolean;
}
export interface ApplicationSummary {
uuid: string;
name: string;
status?: string;
fqdn?: string;
git_repository?: string;
git_branch?: string;
}
export interface DatabaseSummary {
uuid: string;
name: string;
type: string;
status: string;
is_public: boolean;
environment_uuid?: string;
environment_name?: string;
environment_id?: number;
}
export interface ServiceSummary {
uuid: string;
name: string;
type: string;
status: string;
domains?: string[];
}
export interface DeploymentSummary {
uuid: string;
deployment_uuid: string;
application_name?: string;
status: string;
created_at: string;
}
export interface ProjectSummary {
uuid: string;
name: string;
description?: string;
}
export interface GitHubAppSummary {
id: number;
uuid: string;
name: string;
organization: string | null;
is_public: boolean;
app_id: number | null;
}
/**
* HTTP client for the Coolify API
*/
export declare class CoolifyClient {
private readonly baseUrl;
private readonly accessToken;
constructor(config: CoolifyConfig);
private request;
private buildQueryString;
getVersion(): Promise<Version>;
validateConnection(): Promise<void>;
listServers(options?: ListOptions): Promise<Server[] | ServerSummary[]>;
getServer(uuid: string): Promise<Server>;
createServer(data: CreateServerRequest): Promise<UuidResponse>;
updateServer(uuid: string, data: UpdateServerRequest): Promise<Server>;
deleteServer(uuid: string): Promise<MessageResponse>;
getServerResources(uuid: string): Promise<ServerResource[]>;
getServerDomains(uuid: string): Promise<ServerDomain[]>;
validateServer(uuid: string): Promise<ServerValidation>;
listProjects(options?: ListOptions): Promise<Project[] | ProjectSummary[]>;
getProject(uuid: string): Promise<Project>;
createProject(data: CreateProjectRequest): Promise<UuidResponse>;
updateProject(uuid: string, data: UpdateProjectRequest): Promise<Project>;
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[]>;
getApplication(uuid: string): Promise<Application>;
createApplicationPublic(data: CreateApplicationPublicRequest): Promise<UuidResponse>;
createApplicationPrivateGH(data: CreateApplicationPrivateGHRequest): Promise<UuidResponse>;
createApplicationPrivateKey(data: CreateApplicationPrivateKeyRequest): Promise<UuidResponse>;
createApplicationDockerfile(data: CreateApplicationDockerfileRequest): Promise<UuidResponse>;
createApplicationDockerImage(data: CreateApplicationDockerImageRequest): Promise<UuidResponse>;
createApplicationDockerCompose(data: CreateApplicationDockerComposeRequest): Promise<UuidResponse>;
updateApplication(uuid: string, data: UpdateApplicationRequest): Promise<Application>;
deleteApplication(uuid: string, options?: DeleteOptions): Promise<MessageResponse>;
getApplicationLogs(uuid: string, lines?: number): Promise<string>;
startApplication(uuid: string, options?: {
force?: boolean;
instant_deploy?: boolean;
}): Promise<ApplicationActionResponse>;
stopApplication(uuid: string): Promise<ApplicationActionResponse>;
restartApplication(uuid: string): Promise<ApplicationActionResponse>;
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>;
deleteApplicationEnvVar(uuid: string, envUuid: string): Promise<MessageResponse>;
listDatabases(options?: ListOptions): Promise<Database[] | DatabaseSummary[]>;
getDatabase(uuid: string): Promise<Database>;
updateDatabase(uuid: string, data: UpdateDatabaseRequest): Promise<Database>;
deleteDatabase(uuid: string, options?: DeleteOptions): Promise<MessageResponse>;
startDatabase(uuid: string): Promise<MessageResponse>;
stopDatabase(uuid: string): Promise<MessageResponse>;
restartDatabase(uuid: string): Promise<MessageResponse>;
createPostgresql(data: CreatePostgresqlRequest): Promise<CreateDatabaseResponse>;
createMysql(data: CreateMysqlRequest): Promise<CreateDatabaseResponse>;
createMariadb(data: CreateMariadbRequest): Promise<CreateDatabaseResponse>;
createMongodb(data: CreateMongodbRequest): Promise<CreateDatabaseResponse>;
createRedis(data: CreateRedisRequest): Promise<CreateDatabaseResponse>;
createKeydb(data: CreateKeydbRequest): Promise<CreateDatabaseResponse>;
createClickhouse(data: CreateClickhouseRequest): Promise<CreateDatabaseResponse>;
createDragonfly(data: CreateDragonflyRequest): Promise<CreateDatabaseResponse>;
listServices(options?: ListOptions): Promise<Service[] | ServiceSummary[]>;
getService(uuid: string): Promise<Service>;
createService(data: CreateServiceRequest): Promise<ServiceCreateResponse>;
updateService(uuid: string, data: UpdateServiceRequest): Promise<Service>;
deleteService(uuid: string, options?: DeleteOptions): Promise<MessageResponse>;
startService(uuid: string): Promise<MessageResponse>;
stopService(uuid: string): Promise<MessageResponse>;
restartService(uuid: string): Promise<MessageResponse>;
listServiceEnvVars(uuid: string): Promise<EnvironmentVariable[]>;
createServiceEnvVar(uuid: string, data: CreateEnvVarRequest): Promise<UuidResponse>;
updateServiceEnvVar(uuid: string, data: UpdateEnvVarRequest): Promise<MessageResponse>;
deleteServiceEnvVar(uuid: string, envUuid: string): Promise<MessageResponse>;
listDeployments(options?: ListOptions): Promise<Deployment[] | DeploymentSummary[]>;
getDeployment(uuid: string, options?: {
includeLogs?: boolean;
}): Promise<Deployment | DeploymentEssential>;
deployByTagOrUuid(tagOrUuid: string, force?: boolean): Promise<MessageResponse>;
listApplicationDeployments(appUuid: string): Promise<Deployment[]>;
listTeams(): Promise<Team[]>;
getTeam(id: number): Promise<Team>;
getTeamMembers(id: number): Promise<TeamMember[]>;
getCurrentTeam(): Promise<Team>;
getCurrentTeamMembers(): Promise<TeamMember[]>;
listPrivateKeys(): Promise<PrivateKey[]>;
getPrivateKey(uuid: string): Promise<PrivateKey>;
createPrivateKey(data: CreatePrivateKeyRequest): Promise<UuidResponse>;
updatePrivateKey(uuid: string, data: UpdatePrivateKeyRequest): Promise<PrivateKey>;
deletePrivateKey(uuid: string): Promise<MessageResponse>;
listGitHubApps(options?: ListOptions): Promise<GitHubApp[] | GitHubAppSummary[]>;
createGitHubApp(data: CreateGitHubAppRequest): Promise<GitHubApp>;
updateGitHubApp(id: number, data: UpdateGitHubAppRequest): Promise<GitHubAppUpdateResponse>;
deleteGitHubApp(id: number): Promise<MessageResponse>;
listCloudTokens(): Promise<CloudToken[]>;
getCloudToken(uuid: string): Promise<CloudToken>;
createCloudToken(data: CreateCloudTokenRequest): Promise<UuidResponse>;
updateCloudToken(uuid: string, data: UpdateCloudTokenRequest): Promise<CloudToken>;
deleteCloudToken(uuid: string): Promise<MessageResponse>;
validateCloudToken(uuid: string): Promise<CloudTokenValidation>;
listDatabaseBackups(databaseUuid: string): Promise<DatabaseBackup[]>;
getDatabaseBackup(databaseUuid: string, backupUuid: string): Promise<DatabaseBackup>;
listBackupExecutions(databaseUuid: string, backupUuid: string): Promise<BackupExecution[]>;
getBackupExecution(databaseUuid: string, backupUuid: string, executionUuid: string): Promise<BackupExecution>;
createDatabaseBackup(databaseUuid: string, data: CreateDatabaseBackupRequest): Promise<DatabaseBackup>;
updateDatabaseBackup(databaseUuid: string, backupUuid: string, data: UpdateDatabaseBackupRequest): Promise<MessageResponse>;
deleteDatabaseBackup(databaseUuid: string, backupUuid: string): Promise<MessageResponse>;
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>;
/**
* Aggregate results from Promise.allSettled into a BatchOperationResult.
*/
private aggregateBatchResults;
/**
* Restart all applications in a project.
* @param projectUuid - Project UUID
*/
restartProjectApps(projectUuid: string): Promise<BatchOperationResult>;
/**
* Update or create an environment variable across multiple applications.
* Uses upsert behavior: creates if not exists, updates if exists.
* @param appUuids - Array of application UUIDs
* @param key - Environment variable key
* @param value - Environment variable value
* @param isBuildTime - Whether this is a build-time variable (default: false)
*/
bulkEnvUpdate(appUuids: string[], key: string, value: string, isBuildTime?: boolean): Promise<BatchOperationResult>;
/**
* Emergency stop all running applications across entire infrastructure.
*/
stopAllApps(): Promise<BatchOperationResult>;
/**
* Redeploy all applications in a project.
* @param projectUuid - Project UUID
* @param force - Force rebuild (default: true)
*/
redeployProjectApps(projectUuid: string, force?: boolean): Promise<BatchOperationResult>;
}