cpanel4agents - MCP Server para Gestión de Servidores

Servidor MCP (Model Context Protocol) seguro para gestionar servidores compartidos desde tu editor de código.

🆕 v1.1.0 - Ahora con 32 herramientas MCP incluyendo Code Execution para reducir tokens hasta 98.7%. Basado en Code Execution with MCP de Anthropic.

📦 Instalación

Opción 1: Paquete NPM (Recomendado para producción)

npm install -g cpanel4agents
cpanel4agents install   # Genera token JWT
cpanel4agents start     # Inicia servidor

Opción 2: Instalador automático

curl -fsSL https://raw.githubusercontent.com/iberi22/cpanel4agents/main/install.sh | bash

Opción 3: Docker (Desarrollo local)

git clone https://github.com/iberi22/cpanel4agents.git
cd cpanel4agents
npm install
npm run build
npm run docker:up

📦 ¿Qué incluye?

Herramientas Disponibles (32 tools)

🗄️ MySQL (8 tools)

• mysql_query - SELECT/SHOW queries
• mysql_execute - INSERT/UPDATE/DELETE con parámetros
• mysql_tables - Listar tablas de base de datos
• mysql_describe - Estructura de tabla
• mysql_create_table - Crear tabla con schema
• mysql_drop_table - Eliminar tabla
• mysql_create_db - Crear base de datos
• mysql_drop_db - Eliminar base de datos

💾 Redis (15 tools)

• redis_get/set/del - Operaciones key-value
• redis_keys - Buscar keys por patrón
• redis_expire/ttl - Gestión de TTL
• redis_hset/hget/hgetall/hdel - Operaciones hash
• redis_lpush/rpop/lrange/llen - Operaciones lista
• redis_dbsize/info/flushdb - Administración

📦 Backup & System (5 tools)

• system_scan - Escanea servicios y puertos
• backup_database - Backup de MySQL
• backup_directory - Backup de directorios
• backup_list - Lista de backups
• manage_service_* - Gestión de servicios (dinámico)

🚀 Code Execution (3 tools)

Implementa Code Execution with MCP de Anthropic - Reduce uso de tokens hasta 98.7%

• execute_code - Ejecutar JavaScript en sandbox con APIs
• search_tools - Buscar herramientas con disclosure progresivo
• get_tool_tree - Ver árbol jerárquico de herramientas

Stack Tecnológico

• Node.js 18+ - Runtime
• TypeScript - Lenguaje
• Express - HTTP Server
• MySQL 8.0 - Base de datos
• Redis - Cache
• Docker - Contenedores
• MCP SDK - Protocolo

🏗️ Arquitectura

Hexagonal Architecture (Ports & Adapters)

src/
├── domain/          # Lógica de negocio
├── application/     # Casos de uso
├── infrastructure/  # Adaptadores (DB, Cache, etc.)
└── interface/       # Puntos de entrada (HTTP, MCP, CLI)

📚 Documentación

• 📖 Guía de Instalación
• 🔧 Configuración MCP
• 🧪 Guía de Testing
• 🚀 Code Execution with MCP - Token optimization
• 📋 Especificaciones
• 🗓️ Plan de Tareas

🧪 Testing

# Test completo (health, auth, SSE, tools)
npm run test:mcp

# Test de conexión continua
npm run test:connection

# Tests unitarios (próximamente)
npm test

🐳 Comandos Docker

# Iniciar servicios
npm run docker:up

# Ver logs en tiempo real
npm run docker:logs

# Detener servicios
npm run docker:down

# Reconstruir contenedores
docker-compose up -d --build

🔐 Seguridad

• ✅ Autenticación JWT obligatoria
• ✅ Tokens con expiración de 1 año
• ✅ HTTPS recomendado en producción
• ✅ Variables de entorno para secretos
• ✅ .gitignore configurado para credenciales

Nunca commitees:

• .env
• .secure_token
• Contraseñas o API keys

🌐 Despliegue en Producción

Opción A: NPM Global (Más limpio)

# En tu servidor
npm install -g cpanel4agents
cpanel4agents install
cpanel4agents start

Opción B: Instalador automático

ssh [email protected]
curl -fsSL https://raw.githubusercontent.com/iberi22/cpanel4agents/main/install.sh | bash

Mantener corriendo con PM2

cd ~/cpanel4agents
pm2 start ecosystem.config.js
pm2 save
pm2 startup

Configurar cliente MCP (tu máquina local)

En tu proyecto, crea .vscode/mcp.json:

{
  "servers": {
    "cpanel4agents": {
      "url": "http://TU_IP_SERVIDOR:3000/sse",
      "headers": {
        "Authorization": "Bearer TU_TOKEN_JWT"
      }
    }
  }
}

🤖 Para Agentes de IA

• Lee primero: docs/specs/project_specs.md
• Tareas pendientes: docs/planning/task.md
• Reglas del proyecto: AGENTS.md
• Workflows: .agent/workflows/

🐛 Troubleshooting

Servidor no inicia

docker-compose logs cpanel4agents

Error 401 en MCP

# Obtener token actual del contenedor
docker exec cpanel4agents-cpanel4agents-1 cat /app/.secure_token

# O si instalaste con npm:
cat ~/.cpanel4agents/.secure_token

Puerto 3000 ocupado

Edita docker-compose.yml o usa variable de entorno PORT=3001.

📄 Licencia

ISC License

Hecho con ❤️ para desarrolladores que gestionan servidores

Docker

docker-compose up --build

🧪 Testing

npm test

🏗️ Architecture

Built with Hexagonal Architecture (Ports & Adapters) to ensure separation of concerns and testability.

• Domain: Core business logic and interfaces.
• Infrastructure: Adapters for external systems (File System, PM2, MySQL, Redis).
• Application: Use cases and services.
• Interface: HTTP/SSE Server and CLI.

License

ISC