# EasyPanel MCP Server

[![Quality](https://github.com/dannymaaz/easypanel-mcp/actions/workflows/quality.yml/badge.svg)](https://github.com/dannymaaz/easypanel-mcp/actions/workflows/quality.yml)
[![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
[![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-green?logo=anthropic&logoColor=white)](https://modelcontextprotocol.io/)
[![EasyPanel Compatible](https://img.shields.io/badge/EasyPanel-Compatible-orange?logo=docker&logoColor=white)](https://easypanel.io/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)](#instalación-y-configuración)

[Documentación](https://dannymaaz.github.io/easypanel-mcp/) · [Inicio rápido](#instalación-y-configuración) · [Reportar un problema](https://github.com/dannymaaz/easypanel-mcp/issues)

Servidor de **Model Context Protocol (MCP)** para **EasyPanel**. Este conector permite a clientes de inteligencia artificial y entornos de automatización gestionar infraestructura, desplegar servicios, configurar redes y monitorear recursos mediante la API tRPC de EasyPanel en lenguaje natural.

---

## Descripción General

Este servidor implementa el estándar abierto **Model Context Protocol (MCP)** y utiliza la línea estable v2 del SDK oficial de Python. Permite a agentes de IA interactuar con una instancia de EasyPanel desde un cliente configurado, automatizando tareas complejas de administración de servidores, despliegues y diagnósticos.

### Características Principales

*   **Gestión Completa de Servicios:** Listado, inspección, creación, actualización, detención y reinicio de aplicaciones y bases de datos.
*   **Manejo Inteligente de Recursos:** Detección automática y ruteo de namespaces tRPC según el tipo de servicio (`app`, `postgres`, `redis`, `mysql`, `mongodb`, `mariadb`).
*   **Auto-Scaling Automatizado:** Escalado vertical de CPU y memoria basado en métricas y límites definidos.
*   **Análisis y Debugging:** Recuperación de logs estructurados e información de despliegue para auditoría y diagnóstico de fallos en tiempo real.
*   **Descubrimiento de Redes:** Análisis automático de topologías de comunicación interna y pública de Docker.
*   **Soporte Multicliente:** Transporte local `stdio`, transporte remoto moderno **Streamable HTTP** y compatibilidad explícita con **SSE**.

---

## Instalación y Configuración

### 1. Clonar el repositorio
```bash
git clone https://github.com/dannymaaz/easypanel-mcp
cd easypanel-mcp
```

### 2. Configurar el entorno virtual e instalar
Recomendamos usar un entorno virtual para aislar las dependencias e instalar el proyecto en modo editable. Esto utiliza `pyproject.toml`, instala las dependencias compatibles y registra el comando `easypanel-mcp`.

**En Windows (PowerShell):**
```powershell
python -m venv venv
.\venv\Scripts\Activate.ps1
python -m pip install -e .
```

**En macOS / Linux:**
```bash
python3 -m venv venv
source venv/bin/activate
python -m pip install -e .
```

`requirements.txt` se mantiene disponible para instalaciones tradicionales, pero la instalación mediante `pyproject.toml` es la recomendada para desarrollo y para clientes MCP locales.

### 3. Configurar variables de entorno
Crea un archivo `.env` en la raíz del proyecto basándote en el ejemplo provisto:
```bash
cp .env.example .env
```

Edita el archivo `.env` configurando los accesos a tu EasyPanel:
```env
# URL de acceso a tu instancia (ej. https://panel.tudominio.com)
EASYPANEL_URL=https://tu-easypanel.com

# Token de API o credenciales en formato email:password
EASYPANEL_API_KEY=tu_api_key_aqui

# Parámetros adicionales
EASYPANEL_TIMEOUT=30
EASYPANEL_VERIFY_SSL=true

# Configuración del servidor MCP
MCP_HOST=127.0.0.1
MCP_PORT=8080
MCP_LOG_LEVEL=INFO
```

### 4. Verificar el arranque
Con el entorno virtual activo puedes iniciar el servidor mediante el entrypoint instalado:

```bash
easypanel-mcp
```

También se mantiene soportada la ejecución directa por ruta absoluta a `src/server.py`. El servidor resuelve sus imports relativos al repositorio, por lo que los clientes MCP no necesitan configurar `PYTHONPATH` ni arrancar desde la raíz del proyecto.

---

## Configuración en Clientes MCP

### 1. Antigravity IDE
Para integrar el servidor en **Antigravity**, añade la ruta del script en la configuración del gestor de plugins de MCP.

Asegúrate de apuntar al ejecutable de Python de tu entorno virtual (`venv`) para que localice las dependencias instaladas:

```json
{
  "mcpServers": {
    "easypanel-mcp": {
      "command": "C:\\ruta\\a\\easypanel-mcp\\venv\\Scripts\\python.exe",
      "args": ["C:\\ruta\\a\\easypanel-mcp\\src\\server.py"],
      "env": {
        "EASYPANEL_URL": "https://tu-easypanel.com",
        "EASYPANEL_API_KEY": "tu_api_key"
      }
    }
  }
}
```

### 2. Cursor / VS Code (Extensiones Cline & Roo Code)
En editores compatibles con OpenCode o extensiones de agentes inteligentes:

1.  Abre el panel de configuración de la extensión (ej. en **Roo Code**, ve a *Settings* > *MCP Servers*).
2.  Añade una nueva configuración de servidor:
    *   **Name:** `easypanel`
    *   **Type:** `command`
    *   **Command:** `python` (o la ruta al ejecutable de tu `venv`)
    *   **Args:** `["/ruta/absoluta/a/easypanel-mcp/src/server.py"]`
    *   **Environment Variables:**
        *   `EASYPANEL_URL`: `https://tu-easypanel.com`
        *   `EASYPANEL_API_KEY`: `tu_api_key`

### 3. Claude Desktop
Añade el servidor al archivo de configuración de Claude Desktop (`claude_desktop_config.json`):

**En Windows:** `%APPDATA%\Claude\claude_desktop_config.json`  
**En macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "easypanel-mcp": {
      "command": "python",
      "args": ["/ruta/absoluta/a/easypanel-mcp/src/server.py"],
      "env": {
        "EASYPANEL_URL": "https://tu-easypanel.com",
        "EASYPANEL_API_KEY": "tu_api_key"
      }
    }
  }
}
```

### 4. n8n y clientes remotos (Streamable HTTP)
Para desplegar el servidor como servicio MCP remoto, inicia el transporte **Streamable HTTP**:

```bash
easypanel-mcp http
```

También puedes utilizar:

```bash
python src/server.py http
```

El endpoint MCP queda disponible en:

```text
http://127.0.0.1:8080/mcp
```

Configura ese endpoint en un cliente compatible con MCP, por ejemplo un nodo MCP Client/MCP Client Tool de n8n. El cliente MCP se encarga de la negociación del protocolo, descubrimiento de tools y llamadas JSON-RPC.

Si necesitas mantener una integración antigua basada en Server-Sent Events, SSE continúa disponible de forma explícita:

```bash
easypanel-mcp sse
```

---

## Ejemplos Prácticos de Uso

Una vez conectado, puedes interactuar directamente con tu agente haciéndole peticiones de infraestructura basadas en la vida real:

### Despliegue de Aplicaciones
> **Usuario:** "Despliega un servicio frontend usando la imagen nginx:alpine en el proyecto principal."  
> **IA (Interno):** Invoca `create_service(name="frontend", project_id="principal", image="nginx:alpine")` y posteriormente `deploy_service`.  
> **IA (Respuesta):** *"He creado y desplegado el servicio 'frontend' exitosamente en tu proyecto. Está listo para recibir configuración de dominio."*

### Diagnóstico de Caídas
> **Usuario:** "¿Por qué el servicio backend está fallando?"  
> **IA (Interno):** Invoca `get_service_logs(service_id="backend")`.  
> **IA (Respuesta):** *"El servicio backend reporta un estado 'crashed' debido al siguiente error en consola: 'ConnectionRefusedError: No se pudo establecer conexión con redis-cache en el puerto 6379'. ¿Deseas que verifique si el contenedor de Redis está detenido?"*

### Monitoreo y Escalado
> **Usuario:** "Verifica las estadísticas del sistema y escala el servicio backend si el uso de CPU es alto."  
> **IA (Interno):** Invoca `get_system_stats()` seguido de `scale_service(service_id="backend", cpu=2, memory=4096)`.

---

## Herramientas Disponibles

| Categoría | Herramienta | Parámetros | Descripción |
| :--- | :--- | :--- | :--- |
| **Servicios** | `list_services` | `project_id` (opcional) | Lista todos los servicios y sus estados. |
| | `get_service` | `service_id` (requerido) | Obtiene la configuración detallada de un servicio. |
| | `create_service` | `name`, `project_id`, `image`, `config` | Crea un nuevo servicio (soporta apps y DBs). |
| | `update_service` | `service_id`, `config` | Modifica configuraciones de entorno, puertos y recursos. |
| | `delete_service` | `service_id` | Remueve un servicio de EasyPanel. |
| | `restart_service` | `service_id` | Reinicia de inmediato el contenedor de la aplicación. |
| | `get_service_logs` | `service_id`, `lines` (opcional) | Obtiene los últimos logs de consola del contenedor. |
| **Despliegues** | `list_deployments`| `project_id` (opcional) | Lista el historial de despliegues. |
| | `create_deployment`| `project_id`, `service_id`, `image` | Lanza un nuevo despliegue actualizando la imagen. |
| **Redes** | `list_networks` | - | Descubre la topología de red Docker pública/interna. |
| **Proyectos** | `list_projects` | - | Lista los proyectos creados en la instancia. |
| | `create_project` | `name`, `description` (opcional) | Crea un nuevo proyecto organizador. |
| **Monitoreo** | `get_system_stats`| - | Obtiene estadísticas en tiempo real de CPU, RAM y disco. |
| **Escalado** | `scale_service` | `service_id`, `cpu`, `memory` | Escala verticalmente los recursos asignados. |
| | `auto_scale_service`| `service_id`, `cpu_threshold`, `memory_threshold` | Escala dinámicamente según la carga actual. |
| **Seguridad** | `list_domains` | - | Lista los dominios asignados en la instancia. |
| | `get_public_key` | - | Obtiene la clave SSH pública para despliegues Git. |

---

## Seguridad

- Guarda `EASYPANEL_API_KEY` únicamente en variables de entorno o gestores de secretos; nunca la publiques ni la confirmes en Git.
- Usa una cuenta o token con los permisos mínimos necesarios para las tareas que vayas a ejecutar.
- Revisa las acciones destructivas propuestas por el agente antes de ejecutarlas.
- Para reportar una vulnerabilidad, consulta [SECURITY.md](SECURITY.md) y evita publicar credenciales o detalles sensibles en issues públicos.

---

## Verificación del Entorno

Para verificar la conectividad de la API y el estado de la configuración sin arrancar el servidor MCP completo, puedes ejecutar la suite de pruebas unitarias:

```bash
python -m pytest tests/test_basic.py -v
```

---

## Autor

*   **Danny Maaz** - [LinkedIn](https://linkedin.com/in/dannymaaz) • [GitHub](https://github.com/dannymaaz)

---

## Licencia

Este proyecto está bajo la Licencia MIT. Consulta el archivo [LICENSE](LICENSE) para más detalles.