@masonator/coolify-mcp 0.1.0 → 0.1.1

package/README.md

@@ -2,365 +2,213 @@
 
 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
+## Example Prompts
 
-### 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
+Here are example prompts you can use with MCP-compatible AI assistants to interact with your Coolify instance:
 
 ### Server Management
 
-#### list_servers
-
-Lists all Coolify servers in your instance.
-
-```typescript
-// Returns: ServerInfo[]
-await client.list_servers();
 ```
+# 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}?
 
-#### get_server
-
-Get detailed information about a specific server.
-
-```typescript
-// Returns: ServerInfo
-await client.get_server(uuid: string)
+# 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
 ```
 
-#### get_server_resources
-
-Get current resources (applications, databases, etc.) running on a server.
+### Project Management
 
-```typescript
-// Returns: ServerResources[]
-await client.get_server_resources(uuid: string)
 ```
+# 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}
 
-#### get_server_domains
-
-Get domains associated with a server.
-
-```typescript
-// Returns: ServerDomain[]
-await client.get_server_domains(uuid: string)
+# 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}?
 ```
 
-#### validate_server
-
-Validate the connection to a specific server.
+### Application and Service Management
 
-```typescript
-// Returns: ValidationResponse
-await client.validate_server(uuid: string)
 ```
+# Application Management
+- List all applications
+- Show me details of application {uuid}
+- Create a new application called "my-nodejs-app"
+- Delete application {uuid}
 
-### Project Management
-
-#### list_projects
-
-List all projects in your Coolify instance.
-
-```typescript
-// Returns: Project[]
-await client.list_projects();
+# 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
 ```
 
-#### get_project
-
-Get detailed information about a specific project.
+### Database Management
 
-```typescript
-// Returns: Project
-await client.get_project(uuid: string)
 ```
+# 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
 
-#### create_project
-
-Create a new project.
-
-```typescript
-// Returns: { uuid: string }
-await client.create_project({
-  name: string,
-  description?: string
-})
+# Database Types
+- Create a PostgreSQL database
+- Set up a Redis instance
+- Configure a MongoDB database
+- Initialize a MySQL database
 ```
 
-#### update_project
-
-Update an existing project's details.
+### Deployment Management
 
-```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)
+# 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}
 ```
 
-### Environment Management
-
-#### list_environments
+## Installation
 
-List all environments or environments for a specific project.
+### Prerequisites
 
-```typescript
-// Returns: Environment[]
-await client.list_environments(project_uuid?: string)
-```
+- Node.js >= 18
+- A running Coolify instance
+- Coolify API access token
 
-#### get_environment
+### Setup in AI Tools
 
-Get detailed information about a specific environment.
+#### Claude Desktop
 
-```typescript
-// Returns: Environment
-await client.get_environment(uuid: string)
+```json
+"coolify": {
+    "command": "npx",
+    "args": [
+        "-y", "@masonator/coolify-mcp"
+    ],
+    "env": {
+        "COOLIFY_ACCESS_TOKEN": "0|your-secret-token",
+        "COOLIFY_BASE_URL": "https://your-coolify-instance.com"
+    }
+}
 ```
 
-#### get_project_environment
-
-Get a specific environment within a project.
+#### Cursor
 
-```typescript
-// Returns: Environment
-await client.get_project_environment(
-  project_uuid: string,
-  environment_name_or_uuid: string
-)
+```bash
+env COOLIFY_ACCESS_TOKEN:0|your-secret-token COOLIFY_BASE_URL:https://your-coolify-instance.com npx -y @stumason/coolify-mcp
 ```
 
-#### create_environment
+## Development
 
-Create a new environment.
+### Local Setup
 
-```typescript
-// Returns: { uuid: string }
-await client.create_environment({
-  name: string,
-  project_uuid: string,
-  variables?: Record<string, string>
-})
-```
+```bash
+# Clone the repository
+git clone https://github.com/stumason/coolify-mcp.git
+cd coolify-mcp
 
-#### update_environment_variables
+# Install dependencies
+npm install
 
-Update variables for a specific environment.
+# Build the project
+npm run build
 
-```typescript
-// Returns: Environment
-await client.update_environment_variables(
-  uuid: string,
-  { variables: Record<string, string> }
-)
+# Run tests
+npm test
 ```
 
-#### delete_environment
+### Environment Variables
 
-Delete an environment.
+```bash
+# Required
+COOLIFY_ACCESS_TOKEN=your_access_token_here
 
-```typescript
-// Returns: { message: string }
-await client.delete_environment(uuid: string)
+# Optional (defaults to http://localhost:3000)
+COOLIFY_BASE_URL=https://your.coolify.instance
 ```
 
-## Type Definitions
+## API Reference
+
+### Resource Types
 
-### ServerInfo
+#### Application
 
 ```typescript
-interface ServerInfo {
+interface Application {
   uuid: string;
   name: string;
-  status: 'running' | 'stopped' | 'error';
-  version: string;
-  resources: {
-    cpu: number;
-    memory: number;
-    disk: number;
-  };
+  // Additional properties based on your Coolify instance
 }
 ```
 
-### Environment
+#### Service
 
 ```typescript
-interface Environment {
+interface Service {
   id: number;
   uuid: string;
   name: string;
+  type: ServiceType; // Various types like 'wordpress', 'mysql', etc.
+  status: 'running' | 'stopped' | 'error';
   project_uuid: string;
-  variables?: Record<string, string>;
-  created_at: string;
-  updated_at: string;
+  environment_uuid: string;
+  server_uuid: string;
+  domains?: string[];
 }
 ```
 
-### Project
+#### Database
 
 ```typescript
-interface Project {
+interface Database {
   id: number;
   uuid: string;
   name: string;
-  description?: string;
-  environments?: Environment[];
+  type: 'postgresql' | 'mysql' | 'mongodb' | 'redis' | /* other types */;
+  status: 'running' | 'stopped' | 'error';
+  is_public: boolean;
+  public_port?: number;
+  // Additional configuration based on database type
 }
 ```
 
-## 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:
+#### Deployment
 
-```
-src/
-├── lib/
-│   ├── coolify-client.ts    # Coolify API client
-│   └── mcp-server.ts        # MCP server implementation
-├── types/
-│   └── coolify.ts           # TypeScript type definitions
-└── index.ts                 # Entry point
+```typescript
+interface Deployment {
+  id: number;
+  uuid: string;
+  application_uuid: string;
+  status: string;
+  created_at: string;
+  updated_at: string;
+}
 ```
 
-### 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
+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.
 
 ## License