Hetzner MCP Connection

MCP para conectar Mistral Work a los servicios VPS de Hetzner

Este proyecto implementa un Model Context Protocol (MCP) que permite a agentes de IA como Mistral Work interactuar con los servicios VPS de Hetzner Cloud de manera natural en español, así como automatizar tareas complejas.

🎯 Características Principales

• ✅ Interacción en Lenguaje Natural: Conversación en español con el VPS
• ✅ Gestión Completa de Servidores: Crear, modificar, eliminar servidores
• ✅ Redes y Firewalls: Configuración de redes, firewalls y balanceadores
• ✅ Almacenamiento: Gestión de volúmenes y backups
• ✅ Automatización: Scripts y workflows predefinidos
• ✅ Principios NUPP/OMIMO: Diseño Open, Minimalist, Modular
• ✅ API REST Completa: Integración con toda la API de Hetzner Cloud

📋 Principios NUPP Aplicados

Este proyecto sigue los 6 Principios Casi Universales de Proyectos (NUPP) de OMIMO:

1. Enfócate en el Valor - Cada función entrega valor real al usuario
2. Mantén las Cosas Simple - Diseño minimalista y fácil de usar
3. Adapta el Enfoque - Modular para diferentes necesidades
4. Enfócate en los Cuellos de Botella - Optimización de operaciones críticas
5. Sé Transparente - Código abierto y documentación clara
6. Usa el Sentido Común - Soluciones prácticas y efectivas

🚀 Instalación

Requisitos Previos

• Python 3.10 o superior
• Cuenta en Hetzner Cloud
• API Token de Hetzner Cloud

Instalación

# Clonar el repositorio
git clone https://github.com/AI-Foundry-Col/hetzner-mcp-connection.git
cd hetzner-mcp-connection

# Crear entorno virtual
python -m venv venv
source venv/bin/activate  # En Windows: venv\Scripts\activate

# Instalar dependencias
pip install -e ".[dev]"

# Configurar variables de entorno
cp .env.example .env
# Editar .env con tu API token

Configuración Inicial

Crea un archivo .env en la raíz del proyecto:

# Token de API de Hetzner Cloud
HETZNER_API_TOKEN=tu_token_aqui

# Configuración opcional
HETZNER_API_URL=https://api.hetzner.cloud/v1
REQUEST_TIMEOUT=30
MAX_RETRIES=3

# Configuración de logging
LOG_LEVEL=INFO

🛠️ Uso

CLI Principal

# Ver ayuda general
hetzner-mcp --help

# Listar servidores
hetzner-mcp servers list

# Crear un servidor
hetzner-mcp servers create --name mi-servidor --type cx21 --location nbg1 --image ubuntu-22.04

# Interacción en lenguaje natural
hetzner-mcp chat "Crear un servidor con 4GB RAM en Frankfurt"

Ejemplos de Commands

# Gestión de servidores
hetzner-mcp servers list
hetzner-mcp servers create --name web-server --type cx31 --location hel1 --image ubuntu-22.04
hetzner-mcp servers start 12345
hetzner-mcp servers stop 12345
hetzner-mcp servers reboot 12345
hetzner-mcp servers delete 12345

# Gestión de redes
hetzner-mcp networks list
hetzner-mcp networks create --name mi-red --ip-range 10.0.0.0/16

# Gestión de firewalls
hetzner-mcp firewalls list
hetzner-mcp firewalls create --name mi-firewall --rules '{"in": "ACCEPT", "out": "ACCEPT"}'

# Gestión de volúmenes
hetzner-mcp volumes list
hetzner-mcp volumes create --name mi-volumen --size 100 --location nbg1

# Automatización
hetzner-mcp automation deploy --config deploy_config.yaml
hetzner-mcp automation backup --server-id 12345

Modo Chat (Lenguaje Natural)

# Iniciar modo interactivo
hetzner-mcp chat

# O usar comandos directos
hetzner-mcp chat "¿Qué servidores tengo actualmente?"
hetzner-mcp chat "Crear un servidor con Ubuntu 22.04 en Nuremberg"
hetzner-mcp chat "Apagar todos los servidores con etiqueta 'test'"
hetzner-mcp chat "Hacer backup de todos mis servidores de producción"

📚 Documentación

• Guía de Uso
• Referencia de la API
• Ejemplos Avanzados
• Automatización
• Solución de Problemas

🏗️ Arquitectura

hetzner-mcp-connection/
├── src/
│   └── hetzner_mcp/
│       ├── __init__.py
│       ├── cli.py              # Interfaz de línea de comandos
│       ├── config.py           # Configuración
│       ├── core/
│       │   ├── __init__.py
│       │   ├── client.py        # Cliente HTTP base
│       │   ├── exceptions.py    # Excepciones personalizadas
│       │   └── models.py        # Modelos Pydantic
│       ├── servers/
│       │   ├── __init__.py
│       │   ├── server.py        # Gestión de servidores
│       │   └── actions.py       # Acciones de servidores
│       ├── networking/
│       │   ├── __init__.py
│       │   ├── networks.py      # Gestión de redes
│       │   ├── firewalls.py     # Gestión de firewalls
│       │   └── load_balancers.py # Balanceadores
│       ├── storage/
│       │   ├── __init__.py
│       │   ├── volumes.py       # Gestión de volúmenes
│       │   └── backups.py       # Gestión de backups
│       ├── automation/
│       │   ├── __init__.py
│       │   ├── workflows.py     # Workflows de automatización
│       │   └── scripts.py       # Scripts predefinidos
│       └── utils/
│           ├── __init__.py
│           ├── helpers.py       # Funciones utilitarias
│           └── natural_language.py # Procesamiento de lenguaje natural
├── tests/
│   ├── __init__.py
│   ├── test_client.py
│   ├── test_servers.py
│   └── test_automation.py
├── docs/
│   ├── usage.md
│   ├── api-reference.md
│   └── automation.md
├── examples/
│   ├── basic_usage.py
│   ├── automation_script.py
│   └── chat_example.py
├── pyproject.toml
├── README.md
└── .env.example

🔧 API de Hetzner Cloud Cubierta

Servidores (Servers)

• ✅ Listar servidores
• ✅ Crear servidor
• ✅ Modificar servidor
• ✅ Eliminar servidor
• ✅ Iniciar/Parar/Reiniciar
• ✅ Acciones avanzadas (rescue, rebuild, etc.)

Redes (Networks)

• ✅ Listar redes
• ✅ Crear red
• ✅ Modificar red
• ✅ Eliminar red
• ✅ Conectar/Desconectar servidores

Firewalls

• ✅ Listar firewalls
• ✅ Crear firewall
• ✅ Modificar firewall
• ✅ Eliminar firewall
• ✅ Aplicar a recursos

Balanceadores de Carga (Load Balancers)

• ✅ Listar balanceadores
• ✅ Crear balanceador
• ✅ Modificar balanceador
• ✅ Eliminar balanceador

Almacenamiento (Storage)

• ✅ Listar volúmenes
• ✅ Crear volumen
• ✅ Modificar volumen
• ✅ Eliminar volumen
• ✅ Conectar/Desconectar volúmenes

Imágenes (Images)

• ✅ Listar imágenes
• ✅ Crear snapshot
• ✅ Modificar imagen
• ✅ Eliminar imagen

SSH Keys

• ✅ Listar claves SSH
• ✅ Crear clave SSH
• ✅ Eliminar clave SSH

🤖 Integración con Mistral Work

Este MCP está diseñado para integrarse con Mistral Work y otros agentes de IA. La interfaz de lenguaje natural permite:

1. Consultas en Español: "¿Cuántos servidores tengo en Frankfurt?"
2. Acciones Complejas: "Crear un cluster de 3 servidores con balanceador"
3. Automatización Inteligente: "Hacer backup de todos los servidores y notificar por email"
4. Análisis: "¿Cuál es mi servidor más costoso?"

Ejemplo de Integración

from hetzner_mcp import HetznerClient
from hetzner_mcp.natural_language import NaturalLanguageProcessor

# Inicializar cliente
client = HetznerClient()

# Procesador de lenguaje natural
nlp = NaturalLanguageProcessor(client)

# Procesar comando en español
response = nlp.process("Crear un servidor con Ubuntu 22.04 y 4GB RAM en Nuremberg")
print(response)

📊 Ejemplos de Automatización

1. Despliegue Automático

# deploy_config.yaml
server:
  name: production-web
  type: cx31
  location: hel1
  image: ubuntu-22.04
  ssh_keys: [my-ssh-key]
  labels:
    environment: production
    role: web

volume:
  name: production-data
  size: 100
  location: hel1

firewall:
  name: production-firewall
  rules:
    in: ACCEPT
    out: ACCEPT

2. Backup Automático

from hetzner_mcp.automation import BackupWorkflow

# Crear workflow de backup
backup_workflow = BackupWorkflow(client)
backup_workflow.run_all_servers()

3. Escalado Automático

from hetzner_mcp.automation import ScaleWorkflow

# Escalar servidores basados en métricas
scale_workflow = ScaleWorkflow(client)
scale_workflow.scale_based_on_cpu(threshold=80)

🔒 Seguridad

• Token de API: Nunca se almacena en el código, solo en variables de entorno
• Validación de Entrada: Todos los inputs son validados con Pydantic
• Manejo de Errores: Excepciones claras y manejo de rate limiting
• Logging Seguro: Información sensible se mascara en los logs

📈 Contribución

Las contribuciones son bienvenidas. Por favor sigue estos pasos:

1. Fork el repositorio
2. Crea una rama (git checkout -b feature/nueva-funcionalidad)
3. Haz commit de tus cambios (git commit -m 'Añadir nueva funcionalidad')
4. Push a la rama (git push origin feature/nueva-funcionalidad)
5. Abre un Pull Request

Estándares de Código

• Formato: Black
• Linter: Ruff
• Tipado: MyPy
• Tests: Pytest
• Cobertura: 80% mínimo

# Ejecutar tests
pytest

# Formatear código
black src/ tests/

# Verificar linting
ruff check src/ tests/

# Verificar tipos
mypy src/

📄 Licencia

Este proyecto está licenciado bajo la MIT License. Ver el archivo LICENSE para más detalles.

🙏 Agradecimientos

• Hetzner Cloud por su excelente API
• OMIMO por los principios NUPP
• Mistral AI por la inspiración

📞 Soporte

• Issues: GitHub Issues
• Discusión: GitHub Discussions
• Email: contact@aifoundry.col

---

Hecho con ❤️ por AI Foundry Col

Open, Minimalist, Modular - Siguiendo los principios NUPP de OMIMO