@masonator/coolify-mcp 0.2.18 → 0.3.0

package/dist/types/coolify.d.ts

@@ -0,0 +1,640 @@
+/**
+ * Coolify MCP Server Type Definitions
+ * Complete type definitions for the Coolify API v1
+ */
+export interface CoolifyConfig {
+    baseUrl: string;
+    accessToken: string;
+}
+export interface ErrorResponse {
+    error?: string;
+    message: string;
+    status?: number;
+}
+export interface DeleteOptions {
+    deleteConfigurations?: boolean;
+    deleteVolumes?: boolean;
+    dockerCleanup?: boolean;
+    deleteConnectedNetworks?: boolean;
+}
+export interface MessageResponse {
+    message: string;
+}
+export interface UuidResponse {
+    uuid: string;
+}
+export interface Server {
+    id: number;
+    uuid: string;
+    name: string;
+    description?: string;
+    ip: string;
+    user: string;
+    port: number;
+    status?: 'running' | 'stopped' | 'error' | 'unknown';
+    is_reachable?: boolean;
+    is_usable?: boolean;
+    is_swarm_manager?: boolean;
+    is_swarm_worker?: boolean;
+    is_build_server?: boolean;
+    validation_logs?: string;
+    log_drain_notification_sent?: boolean;
+    high_disk_usage_notification_sent?: boolean;
+    unreachable_notification_sent?: boolean;
+    unreachable_count?: number;
+    proxy_type?: 'traefik' | 'caddy' | 'none';
+    proxy_status?: string;
+    settings?: ServerSettings;
+    team_id?: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface ServerSettings {
+    id: number;
+    server_id: number;
+    concurrent_builds: number;
+    dynamic_timeout: number;
+    force_disabled: boolean;
+    force_docker_cleanup: boolean;
+    docker_cleanup_frequency: string;
+    docker_cleanup_threshold: number;
+    is_cloudflare_tunnel: boolean;
+    is_jump_server: boolean;
+    is_logdrain_axiom_enabled: boolean;
+    is_logdrain_highlight_enabled: boolean;
+    is_logdrain_custom_enabled: boolean;
+    is_logdrain_newrelic_enabled: boolean;
+    is_metrics_enabled: boolean;
+    is_reachable: boolean;
+    is_sentinel_enabled: boolean;
+    is_swarm_manager: boolean;
+    is_swarm_worker: boolean;
+    is_usable: boolean;
+    wildcard_domain?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface ServerResource {
+    id: number;
+    uuid: string;
+    name: string;
+    type: 'application' | 'database' | 'service';
+    status: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface ServerDomain {
+    ip: string;
+    domains: string[];
+}
+export interface ServerValidation {
+    message: string;
+    validation_logs?: string;
+}
+export interface CreateServerRequest {
+    name: string;
+    description?: string;
+    ip: string;
+    port?: number;
+    user?: string;
+    private_key_uuid: string;
+    is_build_server?: boolean;
+    instant_validate?: boolean;
+}
+export interface UpdateServerRequest {
+    name?: string;
+    description?: string;
+    ip?: string;
+    port?: number;
+    user?: string;
+    private_key_uuid?: string;
+    is_build_server?: boolean;
+}
+export interface Project {
+    id: number;
+    uuid: string;
+    name: string;
+    description?: string;
+    team_id?: number;
+    environments?: Environment[];
+    created_at?: string;
+    updated_at?: string;
+}
+export interface CreateProjectRequest {
+    name: string;
+    description?: string;
+}
+export interface UpdateProjectRequest {
+    name?: string;
+    description?: string;
+}
+export interface Environment {
+    id: number;
+    uuid: string;
+    name: string;
+    description?: string;
+    project_id?: number;
+    project_uuid?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface CreateEnvironmentRequest {
+    name: string;
+    description?: string;
+}
+export type BuildPack = 'nixpacks' | 'static' | 'dockerfile' | 'dockercompose' | 'dockerimage';
+export interface Application {
+    id: number;
+    uuid: string;
+    name: string;
+    description?: string;
+    fqdn?: string;
+    git_repository?: string;
+    git_branch?: string;
+    git_commit_sha?: string;
+    build_pack?: BuildPack;
+    ports_exposes?: string;
+    ports_mappings?: string;
+    dockerfile?: string;
+    dockerfile_location?: string;
+    docker_registry_image_name?: string;
+    docker_registry_image_tag?: string;
+    docker_compose_location?: string;
+    docker_compose_raw?: string;
+    docker_compose_custom_start_command?: string;
+    docker_compose_custom_build_command?: string;
+    base_directory?: string;
+    publish_directory?: string;
+    install_command?: string;
+    build_command?: string;
+    start_command?: string;
+    health_check_enabled?: boolean;
+    health_check_path?: string;
+    health_check_port?: number;
+    health_check_host?: string;
+    health_check_method?: string;
+    health_check_return_code?: number;
+    health_check_scheme?: string;
+    health_check_response_text?: string;
+    health_check_interval?: number;
+    health_check_timeout?: number;
+    health_check_retries?: number;
+    health_check_start_period?: number;
+    limits_memory?: string;
+    limits_memory_swap?: string;
+    limits_memory_swappiness?: number;
+    limits_memory_reservation?: string;
+    limits_cpus?: string;
+    limits_cpuset?: string;
+    limits_cpu_shares?: number;
+    status?: 'running' | 'stopped' | 'error' | 'building' | 'deploying';
+    preview_url_template?: string;
+    destination_type?: string;
+    destination_id?: number;
+    source_type?: string;
+    source_id?: number;
+    private_key_id?: number;
+    environment_id?: number;
+    project_uuid?: string;
+    environment_uuid?: string;
+    server_uuid?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface CreateApplicationPublicRequest {
+    project_uuid: string;
+    server_uuid: string;
+    environment_name?: string;
+    environment_uuid?: string;
+    destination_uuid?: string;
+    name?: string;
+    description?: string;
+    fqdn?: string;
+    git_repository: string;
+    git_branch: string;
+    git_commit_sha?: string;
+    build_pack: BuildPack;
+    ports_exposes: string;
+    ports_mappings?: string;
+    base_directory?: string;
+    publish_directory?: string;
+    install_command?: string;
+    build_command?: string;
+    start_command?: string;
+    instant_deploy?: boolean;
+}
+export interface CreateApplicationPrivateGHRequest extends CreateApplicationPublicRequest {
+    github_app_uuid: string;
+}
+export interface CreateApplicationPrivateKeyRequest extends CreateApplicationPublicRequest {
+    private_key_uuid: string;
+}
+export interface CreateApplicationDockerfileRequest {
+    project_uuid: string;
+    server_uuid: string;
+    environment_name?: string;
+    environment_uuid?: string;
+    destination_uuid?: string;
+    name?: string;
+    description?: string;
+    fqdn?: string;
+    dockerfile: string;
+    dockerfile_location?: string;
+    ports_exposes?: string;
+    ports_mappings?: string;
+    base_directory?: string;
+    instant_deploy?: boolean;
+}
+export interface CreateApplicationDockerImageRequest {
+    project_uuid: string;
+    server_uuid: string;
+    environment_name?: string;
+    environment_uuid?: string;
+    destination_uuid?: string;
+    name?: string;
+    description?: string;
+    fqdn?: string;
+    docker_registry_image_name: string;
+    docker_registry_image_tag?: string;
+    ports_exposes: string;
+    ports_mappings?: string;
+    instant_deploy?: boolean;
+}
+export interface CreateApplicationDockerComposeRequest {
+    project_uuid: string;
+    server_uuid: string;
+    environment_name?: string;
+    environment_uuid?: string;
+    destination_uuid?: string;
+    name?: string;
+    description?: string;
+    docker_compose_raw: string;
+    docker_compose_location?: string;
+    docker_compose_custom_start_command?: string;
+    docker_compose_custom_build_command?: string;
+    instant_deploy?: boolean;
+}
+export interface UpdateApplicationRequest {
+    name?: string;
+    description?: string;
+    fqdn?: string;
+    git_repository?: string;
+    git_branch?: string;
+    git_commit_sha?: string;
+    ports_exposes?: string;
+    ports_mappings?: string;
+    dockerfile?: string;
+    dockerfile_location?: string;
+    docker_registry_image_name?: string;
+    docker_registry_image_tag?: string;
+    docker_compose_raw?: string;
+    docker_compose_location?: string;
+    base_directory?: string;
+    publish_directory?: string;
+    install_command?: string;
+    build_command?: string;
+    start_command?: string;
+    health_check_enabled?: boolean;
+    health_check_path?: string;
+    health_check_port?: number;
+    limits_memory?: string;
+    limits_memory_swap?: string;
+    limits_cpus?: string;
+}
+export interface ApplicationActionResponse {
+    message: string;
+    deployment_uuid?: string;
+}
+export interface EnvironmentVariable {
+    id: number;
+    uuid: string;
+    key: string;
+    value: string;
+    is_build_time: boolean;
+    is_literal: boolean;
+    is_multiline: boolean;
+    is_preview: boolean;
+    is_shared: boolean;
+    is_shown_once: boolean;
+    real_value?: string;
+    version?: string;
+    application_id?: number;
+    service_id?: number;
+    database_id?: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface CreateEnvVarRequest {
+    key: string;
+    value: string;
+    is_preview?: boolean;
+    is_literal?: boolean;
+    is_multiline?: boolean;
+    is_shown_once?: boolean;
+    is_build_time?: boolean;
+}
+export interface UpdateEnvVarRequest {
+    key: string;
+    value: string;
+    is_preview?: boolean;
+    is_literal?: boolean;
+    is_multiline?: boolean;
+    is_shown_once?: boolean;
+    is_build_time?: boolean;
+}
+export interface BulkUpdateEnvVarsRequest {
+    data: CreateEnvVarRequest[];
+}
+export type DatabaseType = 'postgresql' | 'mysql' | 'mariadb' | 'mongodb' | 'redis' | 'keydb' | 'clickhouse' | 'dragonfly';
+export interface DatabaseLimits {
+    memory?: string;
+    memory_swap?: string;
+    memory_swappiness?: number;
+    memory_reservation?: string;
+    cpus?: string;
+    cpuset?: string;
+    cpu_shares?: number;
+}
+export interface Database {
+    id: number;
+    uuid: string;
+    name: string;
+    description?: string;
+    type: DatabaseType;
+    status: 'running' | 'stopped' | 'error' | 'restarting';
+    is_public: boolean;
+    public_port?: number;
+    image: string;
+    started_at?: string;
+    internal_db_url?: string;
+    external_db_url?: string;
+    project_uuid?: string;
+    environment_uuid?: string;
+    environment_name?: string;
+    server_uuid?: string;
+    limits?: DatabaseLimits;
+    created_at: string;
+    updated_at: string;
+    postgres_user?: string;
+    postgres_password?: string;
+    postgres_db?: string;
+    postgres_initdb_args?: string;
+    postgres_host_auth_method?: string;
+    postgres_conf?: string;
+    mysql_root_password?: string;
+    mysql_user?: string;
+    mysql_password?: string;
+    mysql_database?: string;
+    mariadb_root_password?: string;
+    mariadb_user?: string;
+    mariadb_password?: string;
+    mariadb_database?: string;
+    mariadb_conf?: string;
+    mongo_initdb_root_username?: string;
+    mongo_initdb_root_password?: string;
+    mongo_initdb_database?: string;
+    mongo_conf?: string;
+    redis_password?: string;
+    redis_conf?: string;
+    keydb_password?: string;
+    keydb_conf?: string;
+    clickhouse_admin_user?: string;
+    clickhouse_admin_password?: string;
+    dragonfly_password?: string;
+}
+export interface UpdateDatabaseRequest {
+    name?: string;
+    description?: string;
+    image?: string;
+    is_public?: boolean;
+    public_port?: number;
+    limits_memory?: string;
+    limits_memory_swap?: string;
+    limits_memory_swappiness?: number;
+    limits_memory_reservation?: string;
+    limits_cpus?: string;
+    limits_cpuset?: string;
+    limits_cpu_shares?: number;
+    postgres_user?: string;
+    postgres_password?: string;
+    postgres_db?: string;
+    postgres_initdb_args?: string;
+    postgres_host_auth_method?: string;
+    postgres_conf?: string;
+    mysql_root_password?: string;
+    mysql_user?: string;
+    mysql_password?: string;
+    mysql_database?: string;
+    mariadb_root_password?: string;
+    mariadb_user?: string;
+    mariadb_password?: string;
+    mariadb_database?: string;
+    mariadb_conf?: string;
+    mongo_initdb_root_username?: string;
+    mongo_initdb_root_password?: string;
+    mongo_initdb_database?: string;
+    mongo_conf?: string;
+    redis_password?: string;
+    redis_conf?: string;
+    keydb_password?: string;
+    keydb_conf?: string;
+    clickhouse_admin_user?: string;
+    clickhouse_admin_password?: string;
+    dragonfly_password?: string;
+}
+export interface DatabaseBackup {
+    id: number;
+    uuid: string;
+    database_id: number;
+    database_type: DatabaseType;
+    status: 'pending' | 'running' | 'success' | 'failed';
+    filename?: string;
+    size?: number;
+    frequency: string;
+    enabled: boolean;
+    save_s3: boolean;
+    s3_storage_id?: number;
+    databases_to_backup?: string;
+    dump_all: boolean;
+    created_at: string;
+    updated_at: string;
+}
+export interface CreateDatabaseBackupRequest {
+    frequency: string;
+    enabled?: boolean;
+    save_s3?: boolean;
+    s3_storage_uuid?: string;
+    databases_to_backup?: string;
+    dump_all?: boolean;
+    backup_now?: boolean;
+    backup_retention?: number;
+    backup_retention_days?: number;
+}
+/**
+ * Available one-click service types in Coolify.
+ * This is a string type to avoid TypeScript memory issues with large const arrays.
+ * Common types include: activepieces, appsmith, appwrite, authentik, ghost, gitea,
+ * grafana, jellyfin, minio, n8n, nextcloud, pocketbase, supabase, uptime-kuma,
+ * vaultwarden, wordpress-with-mariadb, wordpress-with-mysql, etc.
+ */
+export type ServiceType = string;
+export interface Service {
+    id: number;
+    uuid: string;
+    name: string;
+    description?: string;
+    type: ServiceType;
+    status: 'running' | 'stopped' | 'error' | 'restarting';
+    project_uuid?: string;
+    environment_name?: string;
+    environment_uuid?: string;
+    server_uuid?: string;
+    destination_uuid?: string;
+    domains?: string[];
+    config_hash?: string;
+    connect_to_docker_network?: boolean;
+    created_at: string;
+    updated_at: string;
+}
+export interface CreateServiceRequest {
+    type: ServiceType;
+    name?: string;
+    description?: string;
+    project_uuid: string;
+    environment_name?: string;
+    environment_uuid?: string;
+    server_uuid: string;
+    destination_uuid?: string;
+    instant_deploy?: boolean;
+}
+/**
+ * CRITICAL: When updating services with Traefik basic auth labels
+ *
+ * 1. MANUAL STEP REQUIRED: You MUST disable "Escape characters in labels" in Coolify UI
+ *    - Navigate to: Service Settings > Advanced > Container Label Character Escaping
+ *    - This setting CANNOT be changed via API
+ *    - Without this, Coolify will double-escape $ signs, breaking htpasswd
+ *
+ * 2. Even with escaping disabled, Traefik still requires $$ in htpasswd hashes
+ *    - Correct: "user:$$apr1$$hash$$here"
+ *    - Wrong: "user:$apr1$hash$here"
+ *    - Docker Compose processes $$ → $ for Traefik
+ *
+ * 3. docker_compose_raw must be base64 encoded when sent to API
+ *    - Example: Buffer.from(yamlString).toString('base64')
+ *
+ * Summary for htpasswd with basic auth:
+ *   - Generate hash: htpasswd -nb username password
+ *   - Replace $ with $$ in the hash
+ *   - Disable label escaping in Coolify UI (manual step!)
+ *   - Base64 encode the entire docker-compose YAML
+ */
+export interface UpdateServiceRequest {
+    name?: string;
+    description?: string;
+    docker_compose_raw?: string;
+}
+export interface ServiceCreateResponse {
+    uuid: string;
+    domains: string[];
+}
+export interface Deployment {
+    id: number;
+    uuid: string;
+    application_id?: number;
+    application_uuid?: string;
+    application_name?: string;
+    deployment_uuid: string;
+    pull_request_id?: number;
+    force_rebuild: boolean;
+    commit?: string;
+    status: 'queued' | 'in_progress' | 'finished' | 'failed' | 'cancelled';
+    is_webhook: boolean;
+    is_api: boolean;
+    logs?: string;
+    current_process_id?: string;
+    restart_only: boolean;
+    git_type?: string;
+    server_id?: number;
+    server_name?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface DeployByTagRequest {
+    tag?: string;
+    uuid?: string;
+    force?: boolean;
+}
+export interface Team {
+    id: number;
+    uuid?: string;
+    name: string;
+    description?: string;
+    personal_team: boolean;
+    show_boarding?: boolean;
+    custom_server_limit?: number;
+    members?: TeamMember[];
+    created_at: string;
+    updated_at: string;
+}
+export interface TeamMember {
+    id: number;
+    name: string;
+    email: string;
+    role?: 'owner' | 'admin' | 'member' | 'readonly';
+    created_at: string;
+    updated_at: string;
+}
+export interface PrivateKey {
+    id: number;
+    uuid: string;
+    name: string;
+    description?: string;
+    private_key: string;
+    public_key?: string;
+    fingerprint?: string;
+    is_git_related: boolean;
+    team_id: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface CreatePrivateKeyRequest {
+    name: string;
+    description?: string;
+    private_key: string;
+}
+export interface UpdatePrivateKeyRequest {
+    name?: string;
+    description?: string;
+    private_key?: string;
+}
+export type CloudProvider = 'hetzner' | 'digitalocean';
+export interface CloudToken {
+    id: number;
+    uuid: string;
+    name: string;
+    provider: CloudProvider;
+    team_id: number;
+    servers_count?: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface CreateCloudTokenRequest {
+    provider: CloudProvider;
+    token: string;
+    name: string;
+}
+export interface UpdateCloudTokenRequest {
+    name?: string;
+}
+export interface CloudTokenValidation {
+    valid: boolean;
+    message: string;
+}
+export interface Version {
+    version: string;
+}
+export interface HealthCheck {
+    status: 'healthy' | 'unhealthy';
+    version?: string;
+}

package/dist/types/coolify.js

@@ -0,0 +1,5 @@
+/**
+ * Coolify MCP Server Type Definitions
+ * Complete type definitions for the Coolify API v1
+ */
+export {};

package/package.json

@@ -1,18 +1,37 @@
 {
   "name": "@masonator/coolify-mcp",
-  "version": "0.2.18",
-  "description": "Model Context Protocol server for Coolify",
+  "scope": "@masonator",
+  "version": "0.3.0",
+  "description": "MCP server implementation for Coolify",
   "type": "module",
   "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
   "bin": {
-    "coolify-mcp": "./dist/index.js"
+    "coolify-mcp": "dist/index.js"
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "tsc && chmod +x dist/index.js",
-    "prepublishOnly": "npm run build"
+    "build": "tsc && shx chmod +x dist/*.js",
+    "dev": "tsc --watch",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch",
+    "test:coverage": "NODE_OPTIONS=--experimental-vm-modules jest --coverage",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepare": "husky",
+    "prepublishOnly": "npm test && npm run lint",
+    "start": "node dist/index.js"
   },
   "keywords": [
     "coolify",
@@ -26,7 +45,19 @@
     "zod": "^3.24.2"
   },
   "devDependencies": {
+    "@types/jest": "^29.5.14",
     "@types/node": "^20.17.23",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.56.0",
+    "eslint-config-prettier": "^9.1.0",
+    "husky": "^9.0.11",
+    "jest": "^29.7.0",
+    "lint-staged": "^15.2.2",
+    "markdownlint-cli2": "^0.20.0",
+    "prettier": "^3.5.3",
+    "shx": "^0.3.4",
+    "ts-jest": "^29.2.6",
     "typescript": "^5.8.2"
   },
   "engines": {