# Coolify MCP Server

A Model Context Protocol (MCP) server that exposes Coolify API functionality as safe, structured tools for AI agents. This enables AI-driven app marketplaces where users can deploy applications on Coolify with a single click.

## 🚀 Features

- **Project Management**: List, create, and manage Coolify projects
- **Application Lifecycle**: Create, update, delete, and manage applications
- **Deployment Control**: Deploy applications and monitor their status
- **Template Marketplace**: Pre-configured templates for popular applications
- **Safety Guardrails**: Quota checking, name conflict detection, and resource limits
- **Comprehensive Logging**: Full audit trail of all AI operations

## 📋 Prerequisites

- Node.js 18+
- A running Coolify instance
- Coolify API token with appropriate permissions
- Docker (for running the MCP server)

## 🛠️ Installation

### Option 1: Clone and Build

```bash
git clone https://github.com/your-org/coolify-mcp-server.git
cd coolify-mcp-server
npm install
npm run build
```

### Option 2: Docker (Recommended)

```bash
docker pull ghcr.io/your-org/coolify-mcp-server:latest
```

## ⚙️ Configuration

Create a `.env` file based on `.env.example`:

```env
# Required
COOLIFY_API_URL=https://your-coolify-instance.com
COOLIFY_API_TOKEN=your-api-token-here

# Optional
COOLIFY_DEFAULT_TEAM_ID=
COOLIFY_MAX_APPS_PER_PROJECT=10
LOG_LEVEL=info
```

### Getting Your Coolify API Token

1. Log into your Coolify instance
2. Go to Settings → API Tokens
3. Create a new token with permissions for:
   - Projects: Read/Write
   - Applications: Read/Write/Delete
   - Deployments: Read/Write

## 🏃 Running the Server

### Development

```bash
npm run dev
```

### Production

```bash
npm run build
npm start
```

### Docker

```bash
docker run \
  -e COOLIFY_API_URL=https://coolify.example.com \
  -e COOLIFY_API_TOKEN=your-token \
  -e COOLIFY_MAX_APPS_PER_PROJECT=20 \
  ghcr.io/your-org/coolify-mcp-server:latest
```

## 🔧 MCP Client Configuration

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "coolify": {
      "command": "node",
      "args": ["/path/to/coolify-mcp-server/dist/index.js"],
      "env": {
        "COOLIFY_API_URL": "https://your-coolify-instance.com",
        "COOLIFY_API_TOKEN": "your-api-token",
        "COOLIFY_MAX_APPS_PER_PROJECT": "10"
      }
    }
  }
}
```

## 📚 Available Tools

### Projects
- `coolify.list_projects` - List all projects
- `coolify.create_project` - Create a new project

### Applications
- `coolify.list_apps` - List applications in a project
- `coolify.get_app` - Get application details
- `coolify.create_app` - Create a new application
- `coolify.update_app` - Update an application
- `coolify.delete_app` - Delete an application

### Deployments
- `coolify.deploy_app` - Deploy an application
- `coolify.get_deployment_status` - Check deployment status
- `coolify.get_deployment_logs` - Get deployment logs

### Templates
- `coolify.deploy_template` - Deploy from a pre-configured template
- `coolify.list_templates` - List available templates

### Safety
- `coolify.check_quota` - Check project quota
- `coolify.check_name_conflicts` - Check if application name is available

## 🎯 Quick Start Examples

### Deploy Plausible Analytics

```javascript
// First, check if the name is available
await checkNameConflicts({
  projectId: "proj-123",
  name: "plausible-analytics"
});

// Deploy the template
const result = await deployTemplate({
  templateName: "plausible",
  projectId: "proj-123",
  appName: "plausible-analytics",
  environment: {
    BASE_URL: "https://analytics.example.com",
    SECRET_KEY_BASE: "your-secret-key",
    POSTGRES_URL: "postgresql://..."
  }
});
```

### Deploy Custom Application

```javascript
// Create a new application
const app = await createApp({
  projectId: "proj-123",
  name: "my-react-app",
  type: "dockerfile",
  gitRepository: {
    url: "https://github.com/user/react-app.git",
    branch: "main"
  },
  environment: {
    NODE_ENV: "production"
  },
  ports: [3000]
});

// Deploy it
const deployment = await deployApp({ id: app.id });
```

## 📦 Available Templates

| Template | Description | Type | Services |
|----------|-------------|------|----------|
| plausible | Privacy-friendly analytics | Docker Image | PostgreSQL |
| strapi | Headless CMS | Git | PostgreSQL, MySQL |
| saleor | E-commerce platform | Docker Image | PostgreSQL, Redis |
| n8n | Workflow automation | Docker Image | PostgreSQL, Redis |
| uptime-kuma | Monitoring tool | Docker Image | - |
| gitlab | Git repository manager | Docker Image | PostgreSQL, Redis |
| rocketchat | Communication platform | Docker Image | MongoDB |
| bookstack | Documentation platform | Docker Image | MySQL, PostgreSQL |

See [examples/tool-calls.md](./examples/tool-calls.md) for detailed examples.

## 🔒 Security

- API tokens are stored server-side and never exposed to AI agents
- All inputs are validated with strict schemas
- Project-level isolation prevents cross-project access
- Built-in quota and rate limiting
- Comprehensive audit logging

See [docs/SECURITY.md](./docs/SECURITY.md) for detailed security considerations.

## 📝 API Reference

The MCP server exposes the following endpoints through the Model Context Protocol:

### Response Format

All responses follow this structure:

```json
{
  "success": true,
  "data": { ... }
}
```

Or for errors:

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  }
}
```

### Error Codes

- `UNAUTHORIZED` - Invalid API token
- `FORBIDDEN` - Insufficient permissions
- `NOT_FOUND` - Resource doesn't exist
- `CONFLICT` - Resource conflict (e.g., duplicate name)
- `VALIDATION_ERROR` - Invalid input data
- `RATE_LIMIT` - Too many requests
- `QUOTA_EXCEEDED` - Project quota exceeded
- `NETWORK_ERROR` - Failed to connect to Coolify
- `UNKNOWN_ERROR` - Unexpected error

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Commit your changes: `git commit -m 'Add amazing feature'`
4. Push to the branch: `git push origin feature/amazing-feature`
5. Open a Pull Request

### Development Setup

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- 📖 [Documentation](./docs/)
- 🐛 [Issue Tracker](https://github.com/your-org/coolify-mcp-server/issues)
- 💬 [Discussions](https://github.com/your-org/coolify-mcp-server/discussions)

## 🙏 Acknowledgments

- [Coolify](https://coolify.io) - The amazing self-hosting platform
- [Model Context Protocol](https://modelcontextprotocol.io) - The protocol that makes this possible
- All contributors and users of this project

---

Built with ❤️ by the community