@masonator/coolify-mcp 0.2.18 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Stu Mason
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,92 +1,22 @@
-# Coolify MCP Server
-
-A Model Context Protocol (MCP) server implementation for [Coolify](https://coolify.io/), enabling AI assistants to interact with your Coolify instances through natural language.
-
-## Example Prompts
-
-Here are example prompts you can use with MCP-compatible AI assistants to interact with your Coolify instance:
-
-### Server Management
-
-```
-# List and Inspect Servers
-- Show me all Coolify servers in my instance
-- What's the status of server {uuid}?
-- Show me the resources running on server {uuid}
-- What domains are configured for server {uuid}?
-- Can you validate the connection to server {uuid}?
-
-# Resource Monitoring
-- How much CPU and memory is server {uuid} using?
-- List all resources running on server {uuid}
-- Show me the current status of all servers
-```
-
-### Project Management
-
-```
-# Project Operations
-- List all my Coolify projects
-- Create a new project called "my-webapp" with description "My web application"
-- Show me the details of project {uuid}
-- Update project {uuid} to change its name to "new-name"
-- Delete project {uuid}
-
-# Environment Management
-- Show me the environments in project {uuid}
-- Get details of the production environment in project {uuid}
-- What variables are set in the staging environment of project {uuid}?
-```
-
-### Application and Service Management
+[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/stumason-coolify-mcp-badge.png)](https://mseep.ai/app/stumason-coolify-mcp)
 
-```
-# Application Management
-- List all applications
-- Show me details of application {uuid}
-- Create a new application called "my-nodejs-app"
-- Delete application {uuid}
-
-# Service Operations
-- Show me all running services
-- Create a new WordPress service:
-  - Name: my-blog
-  - Project UUID: {project_uuid}
-  - Server UUID: {server_uuid}
-  - Type: wordpress-with-mysql
-- What's the status of service {uuid}?
-- Delete service {uuid} and clean up its resources
-```
+# Coolify MCP Server
 
-### Database Management
+A Model Context Protocol (MCP) server for [Coolify](https://coolify.io/), enabling AI assistants to manage and debug your Coolify instances through natural language.
 
-```
-# Database Operations
-- List all databases
-- Show me the configuration of database {uuid}
-- Update database {uuid}:
-  - Increase memory limit to 1GB
-  - Change public port to 5432
-  - Update password
-- Delete database {uuid} and clean up volumes
-
-# Database Types
-- Create a PostgreSQL database
-- Set up a Redis instance
-- Configure a MongoDB database
-- Initialize a MySQL database
-```
+## Features
 
-### Deployment Management
+This MCP server provides 46 tools focused on **debugging, management, and deployment**:
 
-```
-# Deployment Operations
-- Show me all active deployments
-- What's the status of deployment {uuid}?
-- Deploy application {uuid}
-- Force rebuild and deploy application {uuid}
-- List recent deployments for application {uuid}
-```
+| Category         | Tools                                                                                                    |
+| ---------------- | -------------------------------------------------------------------------------------------------------- |
+| **Servers**      | list, get, validate, resources, domains                                                                  |
+| **Projects**     | list, get, create, update, delete                                                                        |
+| **Environments** | list, get, create, delete                                                                                |
+| **Applications** | list, get, update, delete, start, stop, restart, logs, env vars (CRUD), create (private-gh, private-key) |
+| **Databases**    | list, get, start, stop, restart                                                                          |
+| **Services**     | list, get, start, stop, restart, env vars (list, create, delete)                                         |
+| **Deployments**  | list, get, deploy, list by application                                                                   |
 
 ## Installation
 
@@ -94,121 +24,171 @@ Here are example prompts you can use with MCP-compatible AI assistants to intera
 
 - Node.js >= 18
 - A running Coolify instance
-- Coolify API access token
+- Coolify API access token (generate in Coolify Settings > API)
 
-### Setup in AI Tools
+### Claude Desktop
 
-#### Claude Desktop
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
 ```json
-"coolify": {
-    "command": "npx",
-    "args": [
-        "-y", "@masonator/coolify-mcp"
-    ],
-    "env": {
-        "COOLIFY_ACCESS_TOKEN": "0|your-secret-token",
+{
+  "mcpServers": {
+    "coolify": {
+      "command": "npx",
+      "args": ["-y", "@masonator/coolify-mcp"],
+      "env": {
+        "COOLIFY_ACCESS_TOKEN": "your-api-token",
         "COOLIFY_BASE_URL": "https://your-coolify-instance.com"
+      }
     }
+  }
 }
 ```
 
-#### Cursor
+### Claude Code
 
 ```bash
-env COOLIFY_ACCESS_TOKEN:0|your-secret-token COOLIFY_BASE_URL:https://your-coolify-instance.com npx -y @stumason/coolify-mcp
+claude mcp add coolify \
+  --env COOLIFY_BASE_URL="https://your-coolify-instance.com" \
+  --env COOLIFY_ACCESS_TOKEN="your-api-token" \
+  -- npx -y @masonator/coolify-mcp
 ```
 
-## Development
-
-### Local Setup
+### Cursor
 
 ```bash
-# Clone the repository
-git clone https://github.com/stumason/coolify-mcp.git
-cd coolify-mcp
+env COOLIFY_ACCESS_TOKEN=your-api-token COOLIFY_BASE_URL=https://your-coolify-instance.com npx -y @masonator/coolify-mcp
+```
 
-# Install dependencies
-npm install
+## Example Prompts
 
-# Build the project
-npm run build
+### Debugging & Monitoring
 
-# Run tests
-npm test
+```
+Show me all servers and their status
+What resources are running on server {uuid}?
+Get the logs for application {uuid}
+What environment variables are set for application {uuid}?
+Show me recent deployments for application {uuid}
 ```
 
-### Environment Variables
-
-```bash
-# Required
-COOLIFY_ACCESS_TOKEN=your_access_token_here
+### Application Management
 
-# Optional (defaults to http://localhost:3000)
-COOLIFY_BASE_URL=https://your.coolify.instance
+```
+Restart application {uuid}
+Stop the database {uuid}
+Start service {uuid}
+Deploy application {uuid} with force rebuild
+Update the DATABASE_URL env var for application {uuid}
 ```
 
-## API Reference
+### Project Setup
 
-### Resource Types
+```
+Create a new project called "my-app"
+Create a staging environment in project {uuid}
+Deploy my app from private GitHub repo org/repo on branch main
+```
 
-#### Application
+## Environment Variables
 
-```typescript
-interface Application {
-  uuid: string;
-  name: string;
-  // Additional properties based on your Coolify instance
-}
-```
+| Variable               | Required | Default                 | Description               |
+| ---------------------- | -------- | ----------------------- | ------------------------- |
+| `COOLIFY_ACCESS_TOKEN` | Yes      | -                       | Your Coolify API token    |
+| `COOLIFY_BASE_URL`     | No       | `http://localhost:3000` | Your Coolify instance URL |
 
-#### Service
-
-```typescript
-interface Service {
-  id: number;
-  uuid: string;
-  name: string;
-  type: ServiceType; // Various types like 'wordpress', 'mysql', etc.
-  status: 'running' | 'stopped' | 'error';
-  project_uuid: string;
-  environment_uuid: string;
-  server_uuid: string;
-  domains?: string[];
-}
-```
+## Development
 
-#### Database
-
-```typescript
-interface Database {
-  id: number;
-  uuid: string;
-  name: string;
-  type: 'postgresql' | 'mysql' | 'mongodb' | 'redis' | /* other types */;
-  status: 'running' | 'stopped' | 'error';
-  is_public: boolean;
-  public_port?: number;
-  // Additional configuration based on database type
-}
-```
+```bash
+# Clone and install
+git clone https://github.com/stumason/coolify-mcp.git
+cd coolify-mcp
+npm install
 
-#### Deployment
+# Build
+npm run build
 
-```typescript
-interface Deployment {
-  id: number;
-  uuid: string;
-  application_uuid: string;
-  status: string;
-  created_at: string;
-  updated_at: string;
-}
-```
+# Test
+npm test
+
+# Run locally
+COOLIFY_BASE_URL="https://your-coolify.com" \
+COOLIFY_ACCESS_TOKEN="your-token" \
+node dist/index.js
+```
+
+## Available Tools
+
+### Servers
+
+- `get_version` - Get Coolify API version
+- `list_servers` - List all servers
+- `get_server` - Get server details
+- `get_server_resources` - Get resources running on a server
+- `get_server_domains` - Get domains configured on a server
+- `validate_server` - Validate server connection
+
+### Projects
+
+- `list_projects` - List all projects
+- `get_project` - Get project details
+- `create_project` - Create a new project
+- `update_project` - Update a project
+- `delete_project` - Delete a project
+
+### Environments
+
+- `list_environments` - List environments in a project
+- `get_environment` - Get environment details
+- `create_environment` - Create environment in a project
+- `delete_environment` - Delete an environment
+
+### Applications
+
+- `list_applications` - List all applications
+- `get_application` - Get application details
+- `create_application_private_gh` - Create app from private GitHub repo (GitHub App)
+- `create_application_private_key` - Create app from private repo using deploy key
+- `update_application` - Update an application
+- `delete_application` - Delete an application
+- `start_application` - Start an application
+- `stop_application` - Stop an application
+- `restart_application` - Restart an application
+- `get_application_logs` - Get application logs
+- `list_application_envs` - List application environment variables
+- `create_application_env` - Create application environment variable
+- `update_application_env` - Update application environment variable
+- `delete_application_env` - Delete application environment variable
+
+### Databases
+
+- `list_databases` - List all databases
+- `get_database` - Get database details
+- `start_database` - Start a database
+- `stop_database` - Stop a database
+- `restart_database` - Restart a database
+
+### Services
+
+- `list_services` - List all services
+- `get_service` - Get service details
+- `start_service` - Start a service
+- `stop_service` - Stop a service
+- `restart_service` - Restart a service
+- `list_service_envs` - List service environment variables
+- `create_service_env` - Create service environment variable
+- `delete_service_env` - Delete service environment variable
+
+### Deployments
+
+- `list_deployments` - List running deployments
+- `get_deployment` - Get deployment details
+- `deploy` - Deploy by tag or UUID
+- `list_application_deployments` - List deployments for an application
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+Contributions welcome! Please open an issue first to discuss major changes.
 
 ## License
 
@@ -216,8 +196,5 @@ MIT
 
 ## Support
 
-For support, please:
-
-1. Check the [issues](https://github.com/stumason/coolify-mcp/issues) page
-2. Create a new issue if needed
-3. Join the Coolify community
+- [GitHub Issues](https://github.com/stumason/coolify-mcp/issues)
+- [Coolify Community](https://coolify.io/docs/contact)

package/dist/__tests__/coolify-client.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,286 @@
+import { jest, describe, it, expect, beforeEach } from '@jest/globals';
+import { CoolifyClient } from '../lib/coolify-client.js';
+// Helper to create mock response
+function mockResponse(data, ok = true, status = 200) {
+    return {
+        ok,
+        status,
+        statusText: ok ? 'OK' : 'Error',
+        text: async () => JSON.stringify(data),
+    };
+}
+const mockFetch = jest.fn();
+describe('CoolifyClient', () => {
+    let client;
+    const mockServers = [
+        {
+            id: 1,
+            uuid: 'test-uuid',
+            name: 'test-server',
+            ip: '192.168.1.1',
+            user: 'root',
+            port: 22,
+            created_at: '2024-01-01',
+            updated_at: '2024-01-01',
+        },
+    ];
+    const mockServerInfo = {
+        id: 1,
+        uuid: 'test-uuid',
+        name: 'test-server',
+        ip: '192.168.1.1',
+        user: 'root',
+        port: 22,
+        created_at: '2024-01-01',
+        updated_at: '2024-01-01',
+    };
+    const mockServerResources = [
+        {
+            id: 1,
+            uuid: 'resource-uuid',
+            name: 'test-app',
+            type: 'application',
+            status: 'running',
+            created_at: '2024-01-01',
+            updated_at: '2024-01-01',
+        },
+    ];
+    const mockService = {
+        id: 1,
+        uuid: 'test-uuid',
+        name: 'test-service',
+        type: 'code-server',
+        status: 'running',
+        created_at: '2024-01-01',
+        updated_at: '2024-01-01',
+    };
+    const errorResponse = {
+        message: 'Resource not found',
+    };
+    beforeEach(() => {
+        mockFetch.mockClear();
+        global.fetch = mockFetch;
+        client = new CoolifyClient({
+            baseUrl: 'http://localhost:3000',
+            accessToken: 'test-api-key',
+        });
+    });
+    describe('constructor', () => {
+        it('should throw error if baseUrl is missing', () => {
+            expect(() => new CoolifyClient({ baseUrl: '', accessToken: 'test' })).toThrow('Coolify base URL is required');
+        });
+        it('should throw error if accessToken is missing', () => {
+            expect(() => new CoolifyClient({ baseUrl: 'http://localhost', accessToken: '' })).toThrow('Coolify access token is required');
+        });
+        it('should strip trailing slash from baseUrl', () => {
+            const c = new CoolifyClient({
+                baseUrl: 'http://localhost:3000/',
+                accessToken: 'test',
+            });
+            mockFetch.mockResolvedValueOnce(mockResponse({ version: '1.0.0' }));
+            c.getVersion();
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/version', expect.any(Object));
+        });
+    });
+    describe('listServers', () => {
+        it('should return a list of servers', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse(mockServers));
+            const servers = await client.listServers();
+            expect(servers).toEqual(mockServers);
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/servers', expect.objectContaining({
+                headers: expect.objectContaining({
+                    'Content-Type': 'application/json',
+                    Authorization: 'Bearer test-api-key',
+                }),
+            }));
+        });
+        it('should handle errors', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse(errorResponse, false, 404));
+            await expect(client.listServers()).rejects.toThrow('Resource not found');
+        });
+    });
+    describe('getServer', () => {
+        it('should get server info', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse(mockServerInfo));
+            const result = await client.getServer('test-uuid');
+            expect(result).toEqual(mockServerInfo);
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/servers/test-uuid', expect.any(Object));
+        });
+        it('should handle errors', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse(errorResponse, false, 404));
+            await expect(client.getServer('test-uuid')).rejects.toThrow('Resource not found');
+        });
+    });
+    describe('getServerResources', () => {
+        it('should get server resources', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse(mockServerResources));
+            const result = await client.getServerResources('test-uuid');
+            expect(result).toEqual(mockServerResources);
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/servers/test-uuid/resources', expect.any(Object));
+        });
+        it('should handle errors', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse(errorResponse, false, 404));
+            await expect(client.getServerResources('test-uuid')).rejects.toThrow('Resource not found');
+        });
+    });
+    describe('listServices', () => {
+        it('should list services', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse([mockService]));
+            const result = await client.listServices();
+            expect(result).toEqual([mockService]);
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/services', expect.any(Object));
+        });
+    });
+    describe('getService', () => {
+        it('should get service info', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse(mockService));
+            const result = await client.getService('test-uuid');
+            expect(result).toEqual(mockService);
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/services/test-uuid', expect.any(Object));
+        });
+    });
+    describe('createService', () => {
+        it('should create a service', async () => {
+            const responseData = {
+                uuid: 'test-uuid',
+                domains: ['test.com'],
+            };
+            mockFetch.mockResolvedValueOnce(mockResponse(responseData));
+            const createData = {
+                name: 'test-service',
+                type: 'code-server',
+                project_uuid: 'project-uuid',
+                environment_uuid: 'env-uuid',
+                server_uuid: 'server-uuid',
+            };
+            const result = await client.createService(createData);
+            expect(result).toEqual(responseData);
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/services', expect.objectContaining({
+                method: 'POST',
+                body: JSON.stringify(createData),
+            }));
+        });
+    });
+    describe('deleteService', () => {
+        it('should delete a service', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Service deleted' }));
+            const result = await client.deleteService('test-uuid');
+            expect(result).toEqual({ message: 'Service deleted' });
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/services/test-uuid', expect.objectContaining({
+                method: 'DELETE',
+            }));
+        });
+        it('should delete a service with options', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Service deleted' }));
+            await client.deleteService('test-uuid', {
+                deleteVolumes: true,
+                dockerCleanup: true,
+            });
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/services/test-uuid?delete_volumes=true&docker_cleanup=true', expect.objectContaining({
+                method: 'DELETE',
+            }));
+        });
+    });
+    describe('applications', () => {
+        it('should list applications', async () => {
+            const mockApps = [{ id: 1, uuid: 'app-uuid', name: 'test-app' }];
+            mockFetch.mockResolvedValueOnce(mockResponse(mockApps));
+            const result = await client.listApplications();
+            expect(result).toEqual(mockApps);
+        });
+        it('should start an application', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Started', deployment_uuid: 'dep-uuid' }));
+            const result = await client.startApplication('app-uuid', {
+                force: true,
+            });
+            expect(result).toEqual({
+                message: 'Started',
+                deployment_uuid: 'dep-uuid',
+            });
+        });
+        it('should stop an application', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Stopped' }));
+            const result = await client.stopApplication('app-uuid');
+            expect(result).toEqual({ message: 'Stopped' });
+        });
+    });
+    describe('databases', () => {
+        it('should list databases', async () => {
+            const mockDbs = [{ id: 1, uuid: 'db-uuid', name: 'test-db' }];
+            mockFetch.mockResolvedValueOnce(mockResponse(mockDbs));
+            const result = await client.listDatabases();
+            expect(result).toEqual(mockDbs);
+        });
+        it('should start a database', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Started' }));
+            const result = await client.startDatabase('db-uuid');
+            expect(result).toEqual({ message: 'Started' });
+        });
+    });
+    describe('teams', () => {
+        it('should list teams', async () => {
+            const mockTeams = [{ id: 1, name: 'test-team', personal_team: false }];
+            mockFetch.mockResolvedValueOnce(mockResponse(mockTeams));
+            const result = await client.listTeams();
+            expect(result).toEqual(mockTeams);
+        });
+        it('should get current team', async () => {
+            const mockTeam = { id: 1, name: 'my-team', personal_team: true };
+            mockFetch.mockResolvedValueOnce(mockResponse(mockTeam));
+            const result = await client.getCurrentTeam();
+            expect(result).toEqual(mockTeam);
+        });
+    });
+    describe('deployments', () => {
+        it('should list deployments', async () => {
+            const mockDeps = [
+                {
+                    id: 1,
+                    uuid: 'dep-uuid',
+                    deployment_uuid: 'dep-123',
+                    status: 'finished',
+                },
+            ];
+            mockFetch.mockResolvedValueOnce(mockResponse(mockDeps));
+            const result = await client.listDeployments();
+            expect(result).toEqual(mockDeps);
+        });
+        it('should deploy by tag', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({ message: 'Deployed' }));
+            const result = await client.deployByTagOrUuid('my-tag', true);
+            expect(result).toEqual({ message: 'Deployed' });
+            expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/deploy?tag=my-tag&force=true', expect.any(Object));
+        });
+    });
+    describe('private keys', () => {
+        it('should list private keys', async () => {
+            const mockKeys = [{ id: 1, uuid: 'key-uuid', name: 'my-key' }];
+            mockFetch.mockResolvedValueOnce(mockResponse(mockKeys));
+            const result = await client.listPrivateKeys();
+            expect(result).toEqual(mockKeys);
+        });
+        it('should create a private key', async () => {
+            mockFetch.mockResolvedValueOnce(mockResponse({ uuid: 'new-key-uuid' }));
+            const result = await client.createPrivateKey({
+                name: 'new-key',
+                private_key: 'ssh-rsa AAAA...',
+            });
+            expect(result).toEqual({ uuid: 'new-key-uuid' });
+        });
+    });
+    describe('error handling', () => {
+        it('should handle network errors', async () => {
+            mockFetch.mockRejectedValueOnce(new TypeError('fetch failed'));
+            await expect(client.listServers()).rejects.toThrow('Failed to connect to Coolify server');
+        });
+        it('should handle empty responses', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 204,
+                text: async () => '',
+            });
+            const result = await client.deleteServer('test-uuid');
+            expect(result).toEqual({});
+        });
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};