mcp-server-coolify: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in the coolify-mcp-server repository.

Repository Overview

This is an MCP (Model Context Protocol) server that provides comprehensive integration with the Coolify API. It enables AI assistants to manage infrastructure, applications, databases, and services through Coolify's self-hosted PaaS platform.

Current Status: ✅ Production ready with comprehensive API coverage and robust error handling. Tested Version: Coolify 4.0.0-beta.418

Architecture

The codebase follows a layered architecture pattern:

src/
├── index.ts          # MCP server entry point and tool registration
├── services/         # API client layer (CoolifyClient)
├── tools/           # MCP tool implementations (CoolifyTools)
├── types/           # TypeScript interfaces for API types
└── prompts/         # Pre-configured workflow prompts

Key Components

1. Service Layer (services/coolify-client.ts)

   • Handles all HTTP communication with Coolify API
   • Manages authentication and error handling
   • Returns strongly-typed responses
   • Throws structured errors with context

2. Tool Layer (tools/coolify-tools.ts)

   • Wraps service methods with MCP-specific logic
   • Validates inputs using Zod schemas
   • Formats responses for MCP consumption
   • Handles error transformation

3. Type Definitions (types/coolify.ts)

   • Comprehensive TypeScript interfaces for all API entities
   • Request/response types for each endpoint
   • Error types with proper structure

4. Prompts (prompts/index.ts)

   • Pre-configured workflows for common tasks
   • Template-based approach for complex operations
   • Guides users through multi-step processes

Development Guidelines

Running the Server

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
npm start

# Development mode with watch
npm run watch

# Test with MCP Inspector
npm run inspector