@masonator/coolify-mcp 0.1.0

package/README.md

@@ -0,0 +1,375 @@
+# 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.
+
+## Claude Desktop, Cursor, and other MCP compatible IDEs
+
+### Claude
+
+```json
+"coolify": {
+    "command": "npx",
+    "args": [
+        "-y", "@stumason/coolify-mcp"
+    ],
+    "env": {
+        "COOLIFY_ACCESS_TOKEN": "0|your-secret-token",
+        "COOLIFY_BASE_URL": "https://your-coolify-instance.com"
+    }
+},
+```
+
+### Cursor
+
+command:
+
+`env COOLIFY_ACCESS_TOKEN:0|your-secret-token COOLIFY_BASE_URL:https://your-coolify-instance.com npx -y @stumason/coolify-mcp`
+
+## Overview
+
+This MCP server provides a standardized interface for AI models to:
+
+- Query Coolify server information
+- Manage projects and environments
+- Handle deployments and resources
+- Monitor server status
+- And more...
+
+By implementing the [Model Context Protocol](https://modelcontextprotocol.io), this server allows AI assistants to understand and interact with your Coolify infrastructure in a secure and controlled manner.
+
+## Prerequisites
+
+- Node.js >= 18
+- A running Coolify instance
+- Coolify API access token
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/stumason/coolify-mcp.git
+cd coolify-mcp
+
+# Install dependencies
+npm install
+```
+
+## Configuration
+
+The server requires the following environment variables:
+
+```bash
+# Required
+COOLIFY_ACCESS_TOKEN=your_access_token_here
+
+# Optional (defaults to http://localhost:3000)
+COOLIFY_BASE_URL=https://your.coolify.instance
+```
+
+## Available Tools
+
+### Server Management
+
+#### list_servers
+
+Lists all Coolify servers in your instance.
+
+```typescript
+// Returns: ServerInfo[]
+await client.list_servers();
+```
+
+#### get_server
+
+Get detailed information about a specific server.
+
+```typescript
+// Returns: ServerInfo
+await client.get_server(uuid: string)
+```
+
+#### get_server_resources
+
+Get current resources (applications, databases, etc.) running on a server.
+
+```typescript
+// Returns: ServerResources[]
+await client.get_server_resources(uuid: string)
+```
+
+#### get_server_domains
+
+Get domains associated with a server.
+
+```typescript
+// Returns: ServerDomain[]
+await client.get_server_domains(uuid: string)
+```
+
+#### validate_server
+
+Validate the connection to a specific server.
+
+```typescript
+// Returns: ValidationResponse
+await client.validate_server(uuid: string)
+```
+
+### Project Management
+
+#### list_projects
+
+List all projects in your Coolify instance.
+
+```typescript
+// Returns: Project[]
+await client.list_projects();
+```
+
+#### get_project
+
+Get detailed information about a specific project.
+
+```typescript
+// Returns: Project
+await client.get_project(uuid: string)
+```
+
+#### create_project
+
+Create a new project.
+
+```typescript
+// Returns: { uuid: string }
+await client.create_project({
+  name: string,
+  description?: string
+})
+```
+
+#### update_project
+
+Update an existing project's details.
+
+```typescript
+// Returns: Project
+await client.update_project(uuid: string, {
+  name?: string,
+  description?: string
+})
+```
+
+#### delete_project
+
+Delete a project.
+
+```typescript
+// Returns: { message: string }
+await client.delete_project(uuid: string)
+```
+
+### Environment Management
+
+#### list_environments
+
+List all environments or environments for a specific project.
+
+```typescript
+// Returns: Environment[]
+await client.list_environments(project_uuid?: string)
+```
+
+#### get_environment
+
+Get detailed information about a specific environment.
+
+```typescript
+// Returns: Environment
+await client.get_environment(uuid: string)
+```
+
+#### get_project_environment
+
+Get a specific environment within a project.
+
+```typescript
+// Returns: Environment
+await client.get_project_environment(
+  project_uuid: string,
+  environment_name_or_uuid: string
+)
+```
+
+#### create_environment
+
+Create a new environment.
+
+```typescript
+// Returns: { uuid: string }
+await client.create_environment({
+  name: string,
+  project_uuid: string,
+  variables?: Record<string, string>
+})
+```
+
+#### update_environment_variables
+
+Update variables for a specific environment.
+
+```typescript
+// Returns: Environment
+await client.update_environment_variables(
+  uuid: string,
+  { variables: Record<string, string> }
+)
+```
+
+#### delete_environment
+
+Delete an environment.
+
+```typescript
+// Returns: { message: string }
+await client.delete_environment(uuid: string)
+```
+
+## Type Definitions
+
+### ServerInfo
+
+```typescript
+interface ServerInfo {
+  uuid: string;
+  name: string;
+  status: 'running' | 'stopped' | 'error';
+  version: string;
+  resources: {
+    cpu: number;
+    memory: number;
+    disk: number;
+  };
+}
+```
+
+### Environment
+
+```typescript
+interface Environment {
+  id: number;
+  uuid: string;
+  name: string;
+  project_uuid: string;
+  variables?: Record<string, string>;
+  created_at: string;
+  updated_at: string;
+}
+```
+
+### Project
+
+```typescript
+interface Project {
+  id: number;
+  uuid: string;
+  name: string;
+  description?: string;
+  environments?: Environment[];
+}
+```
+
+## Development
+
+```bash
+# Run in development mode
+npm run build -- --watch
+```
+
+### Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm test -- --watch
+
+# Run tests with coverage
+npm test -- --coverage
+```
+
+### Code Quality
+
+```bash
+# Run linter
+npm run lint
+
+# Fix linting issues
+npm run lint -- --fix
+
+# Format code
+npm run format
+```
+
+## Architecture
+
+The project follows a modular architecture:
+
+```
+src/
+├── lib/
+│   ├── coolify-client.ts    # Coolify API client
+│   └── mcp-server.ts        # MCP server implementation
+├── types/
+│   └── coolify.ts           # TypeScript type definitions
+└── index.ts                 # Entry point
+```
+
+### Key Components
+
+1. **CoolifyClient**: Handles communication with the Coolify API
+
+   - Authentication
+   - API request handling
+   - Error management
+
+2. **CoolifyMcpServer**: Implements the MCP server
+   - Resource management
+   - Tool implementations
+   - Client request handling
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Development Guidelines
+
+- Follow TypeScript best practices
+- Maintain test coverage
+- Update documentation as needed
+- Follow the established code style
+
+## CI/CD
+
+GitHub Actions workflows are configured to:
+
+- Run tests on Node.js 18.x and 20.x
+- Check code formatting
+- Verify build process
+- Run linting checks
+
+## License
+
+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

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

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

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

@@ -0,0 +1,325 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const coolify_client_js_1 = require("../lib/coolify-client.js");
+// Mock fetch globally
+const mockFetch = jest.fn();
+global.fetch = mockFetch;
+describe('CoolifyClient', () => {
+    let client;
+    beforeEach(() => {
+        client = new coolify_client_js_1.CoolifyClient({
+            baseUrl: 'http://test.coolify.io',
+            accessToken: 'test-token',
+        });
+        mockFetch.mockClear();
+        // Reset any global mock implementations
+        mockFetch.mockReset();
+    });
+    describe('listServers', () => {
+        const mockServers = [
+            {
+                uuid: 'test-id-1',
+                name: 'test-server-1',
+                status: 'running',
+                version: '1.0.0',
+                resources: {
+                    cpu: 50,
+                    memory: 60,
+                    disk: 70,
+                },
+            },
+            {
+                uuid: 'test-id-2',
+                name: 'test-server-2',
+                status: 'stopped',
+                version: '1.0.0',
+                resources: {
+                    cpu: 0,
+                    memory: 0,
+                    disk: 70,
+                },
+            },
+        ];
+        it('should fetch server list successfully', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockServers,
+            });
+            const result = await client.listServers();
+            expect(result).toEqual(mockServers);
+            expect(mockFetch).toHaveBeenCalledWith('http://test.coolify.io/api/v1/servers', expect.objectContaining({
+                headers: expect.objectContaining({
+                    Authorization: 'Bearer test-token',
+                    'Content-Type': 'application/json',
+                }),
+            }));
+        });
+        it('should handle error responses', async () => {
+            const errorResponse = {
+                error: 'Unauthorized',
+                status: 401,
+                message: 'Invalid token',
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: false,
+                json: async () => errorResponse,
+            });
+            await expect(client.listServers()).rejects.toThrow('Invalid token');
+        });
+    });
+    describe('getServer', () => {
+        const mockServerInfo = {
+            uuid: 'test-id',
+            name: 'test-server',
+            status: 'running',
+            version: '1.0.0',
+            resources: {
+                cpu: 50,
+                memory: 60,
+                disk: 70,
+            },
+        };
+        it('should fetch server info successfully', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockServerInfo,
+            });
+            const result = await client.getServer('test-id');
+            expect(result).toEqual(mockServerInfo);
+            expect(mockFetch).toHaveBeenCalledWith('http://test.coolify.io/api/v1/servers/test-id', expect.objectContaining({
+                headers: expect.objectContaining({
+                    Authorization: 'Bearer test-token',
+                    'Content-Type': 'application/json',
+                }),
+            }));
+        });
+        it('should handle error responses', async () => {
+            const errorResponse = {
+                error: 'Not Found',
+                status: 404,
+                message: 'Server not found',
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: false,
+                json: async () => errorResponse,
+            });
+            await expect(client.getServer('invalid-id')).rejects.toThrow('Server not found');
+        });
+    });
+    describe('getServerResources', () => {
+        const mockServerResources = [
+            {
+                id: 1,
+                uuid: 'test-id',
+                name: 'test-app',
+                type: 'application',
+                created_at: '2024-03-19T12:00:00Z',
+                updated_at: '2024-03-19T12:00:00Z',
+                status: 'running:healthy',
+            },
+        ];
+        it('should fetch server resources successfully', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockServerResources,
+            });
+            const result = await client.getServerResources('test-id');
+            expect(result).toEqual(mockServerResources);
+            expect(mockFetch).toHaveBeenCalledWith('http://test.coolify.io/api/v1/servers/test-id/resources', expect.objectContaining({
+                headers: expect.objectContaining({
+                    Authorization: 'Bearer test-token',
+                    'Content-Type': 'application/json',
+                }),
+            }));
+        });
+        it('should handle error responses', async () => {
+            const errorResponse = {
+                error: 'Server Error',
+                status: 500,
+                message: 'Internal server error',
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: false,
+                json: async () => errorResponse,
+            });
+            await expect(client.getServerResources('test-id')).rejects.toThrow('Internal server error');
+        });
+    });
+    test('getServer returns server info', async () => {
+        const mockResponse = {
+            uuid: 'test-uuid',
+            name: 'test-server',
+            status: 'running',
+            version: '1.0.0',
+            resources: {
+                cpu: 50,
+                memory: 60,
+                disk: 70,
+            },
+        };
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            json: () => Promise.resolve(mockResponse),
+        });
+        const server = await client.getServer('test-uuid');
+        expect(server).toEqual(mockResponse);
+        expect(mockFetch).toHaveBeenCalledWith('http://test.coolify.io/api/v1/servers/test-uuid', expect.objectContaining({
+            headers: {
+                Authorization: 'Bearer test-token',
+                'Content-Type': 'application/json',
+            },
+        }));
+    });
+    test('getServerResources returns server resources', async () => {
+        const mockResponse = [
+            {
+                id: 1,
+                uuid: 'test-uuid',
+                name: 'test-app',
+                type: 'application',
+                created_at: '2025-03-05T13:41:12.000Z',
+                updated_at: '2025-03-05T13:41:12.000Z',
+                status: 'running:healthy',
+            },
+        ];
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            json: () => Promise.resolve(mockResponse),
+        });
+        const resources = await client.getServerResources('test-uuid');
+        expect(resources).toEqual(mockResponse);
+        expect(mockFetch).toHaveBeenCalledWith('http://test.coolify.io/api/v1/servers/test-uuid/resources', expect.objectContaining({
+            headers: {
+                Authorization: 'Bearer test-token',
+                'Content-Type': 'application/json',
+            },
+        }));
+    });
+    describe('Environment Management', () => {
+        const mockEnvironment = {
+            id: 1,
+            uuid: 'env-test-id',
+            name: 'test-env',
+            project_uuid: 'project-test-id',
+            variables: { KEY: 'value' },
+            created_at: '2024-03-19T12:00:00Z',
+            updated_at: '2024-03-19T12:00:00Z',
+        };
+        beforeEach(() => {
+            mockFetch.mockClear();
+        });
+        describe('listEnvironments', () => {
+            it('should fetch all environments successfully', async () => {
+                mockFetch.mockResolvedValueOnce({
+                    ok: true,
+                    json: () => Promise.resolve([mockEnvironment]),
+                });
+                const result = await client.listEnvironments();
+                expect(result).toEqual([mockEnvironment]);
+                expect(mockFetch).toHaveBeenCalledWith('http://test.coolify.io/api/v1/environments', expect.objectContaining({
+                    headers: expect.objectContaining({
+                        Authorization: 'Bearer test-token',
+                        'Content-Type': 'application/json',
+                    }),
+                }));
+            });
+            it('should fetch environments by project UUID', async () => {
+                mockFetch.mockResolvedValueOnce({
+                    ok: true,
+                    json: () => Promise.resolve([mockEnvironment]),
+                });
+                const result = await client.listEnvironments('project-test-id');
+                expect(result).toEqual([mockEnvironment]);
+                expect(mockFetch).toHaveBeenCalledWith('http://test.coolify.io/api/v1/environments?project_uuid=project-test-id', expect.objectContaining({
+                    headers: expect.objectContaining({
+                        Authorization: 'Bearer test-token',
+                        'Content-Type': 'application/json',
+                    }),
+                }));
+            });
+        });
+        describe('getEnvironment', () => {
+            it('should fetch environment by UUID successfully', async () => {
+                mockFetch.mockResolvedValueOnce({
+                    ok: true,
+                    json: () => Promise.resolve(mockEnvironment),
+                });
+                const result = await client.getEnvironment('env-test-id');
+                expect(result).toEqual(mockEnvironment);
+                expect(mockFetch).toHaveBeenCalledWith('http://test.coolify.io/api/v1/environments/env-test-id', expect.objectContaining({
+                    headers: expect.objectContaining({
+                        Authorization: 'Bearer test-token',
+                        'Content-Type': 'application/json',
+                    }),
+                }));
+            });
+        });
+        describe('createEnvironment', () => {
+            it('should create environment successfully', async () => {
+                const createRequest = {
+                    name: 'test-env',
+                    project_uuid: 'project-test-id',
+                    variables: { KEY: 'value' },
+                };
+                const mockResponse = { uuid: 'env-test-id' };
+                mockFetch.mockResolvedValueOnce({
+                    ok: true,
+                    json: () => Promise.resolve(mockResponse),
+                });
+                const result = await client.createEnvironment(createRequest);
+                expect(result).toEqual(mockResponse);
+                expect(mockFetch).toHaveBeenCalledWith('http://test.coolify.io/api/v1/environments', expect.objectContaining({
+                    method: 'POST',
+                    body: JSON.stringify(createRequest),
+                    headers: expect.objectContaining({
+                        Authorization: 'Bearer test-token',
+                        'Content-Type': 'application/json',
+                    }),
+                }));
+            });
+        });
+        describe('updateEnvironmentVariables', () => {
+            it('should update environment variables successfully', async () => {
+                const updateRequest = {
+                    variables: { NEW_KEY: 'new-value' },
+                };
+                const mockUpdatedEnvironment = {
+                    ...mockEnvironment,
+                    variables: updateRequest.variables,
+                };
+                mockFetch.mockResolvedValueOnce({
+                    ok: true,
+                    json: () => Promise.resolve(mockUpdatedEnvironment),
+                });
+                const result = await client.updateEnvironmentVariables('env-test-id', updateRequest);
+                expect(result).toEqual(mockUpdatedEnvironment);
+                expect(mockFetch).toHaveBeenCalledWith('http://test.coolify.io/api/v1/environments/env-test-id/variables', expect.objectContaining({
+                    method: 'PUT',
+                    body: JSON.stringify(updateRequest),
+                    headers: expect.objectContaining({
+                        Authorization: 'Bearer test-token',
+                        'Content-Type': 'application/json',
+                    }),
+                }));
+            });
+        });
+        describe('deleteEnvironment', () => {
+            it('should delete environment successfully', async () => {
+                const mockResponse = { message: 'Environment deleted successfully' };
+                mockFetch.mockResolvedValueOnce({
+                    ok: true,
+                    json: () => Promise.resolve(mockResponse),
+                });
+                const result = await client.deleteEnvironment('env-test-id');
+                expect(result).toEqual(mockResponse);
+                expect(mockFetch).toHaveBeenCalledWith('http://test.coolify.io/api/v1/environments/env-test-id', expect.objectContaining({
+                    method: 'DELETE',
+                    headers: expect.objectContaining({
+                        Authorization: 'Bearer test-token',
+                        'Content-Type': 'application/json',
+                    }),
+                }));
+            });
+        });
+    });
+});

package/dist/__tests__/mcp-server.test.d.ts

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