Dokku

Servidor MCP de Dokku

Servidor Model Context Protocol (MCP) para Dokku, escrito en Go.

Versión: v0.3.0

Este servidor expone las capacidades de gestión de Dokku a través del Protocolo de Contexto de Modelo (MCP) estandarizado, permitiendo que los Modelos de Lenguaje de Gran Tamaño (LLMs) interactúen con y gestionen una instancia de Dokku.

⚠️ Desarrollo temprano: Este proyecto se encuentra en sus primeras etapas. Se esperan cambios importantes y no se recomienda su uso en producción.

Pruébalo ahora — convierte tu instancia de Dokku en una PaaS gestionable por IA

Sigue la Instalación u obtén un binario precompilado para empezar en minutos con cursor, claude-code, goose y todas las herramientas de agentes que soporten mcp.

O make start si ya tienes go instalado localmente.

MCP Inspector Playground

Para una visita rápida al servidor sin configurar un cliente MCP completo, usa el objetivo de make dedicado:

make inspect

Compila el binario (si es necesario), lanza la CLI de MCP Inspector y la conecta al servidor en modo stdio. Inspector imprime una URL local: ábrela en tu navegador para explorar recursos, prompts y herramientas, o para realizar llamadas ad-hoc. Esta es una excelente manera de validar tu configuración antes de integrar Dokku MCP en Cursor, Claude, otros IDE o herramientas internas.

Conexión de Clientes MCP

El servidor puede usarse con cualquier cliente compatible con MCP.

Añade lo siguiente a tu zed, .cursor/mcp.json, windsurf, claude_desktop_config.json o .mcp.json:

{
  "mcpServers": {
    "dokku": {
      "command": "/home/user/dokku-mcp/build/dokku-mcp",
      "args": [],
      "env": {
        "DOKKU_MCP_SECURITY_BLACKLIST": "destroy,uninstall,remove",
        "DOKKU_MCP_SSH_HOST": "127.0.0.1",
        "DOKKU_MCP_SSH_KEY_PATH": "/home/user/.ssh/id_rsa",
        "DOKKU_MCP_SSH_PORT": "22",
        "DOKKU_MCP_SSH_USER": "dokku"
      }
    }
  }
}

Recuerda reemplazar la ruta command con la ruta absoluta al binario.

Características destacadas

• Núcleo: recursos de información del servidor y lista de plugins; herramienta opcional de registros del servidor.
• Apps: crear, desplegar (URL de Git + ref), escalar, configuración de entorno, estado; recurso de lista de apps; prompt de resolución de problemas.
• Despliegues: despliegues asíncronos con IDs y estado en segundo plano.

Hoja de ruta

Envía un issue para proponer una re-priorización

SIGUIENTE

• Registro a nivel de build: exponer la salida de compilación para invocaciones de despliegue.
• Registro a nivel de app: exponer registros de ejecución.
• Comunicación entre plugins: permitir la gestión de eventos entre plugins, Eventbus quizás Watermill.
• Gestión de usuarios: ssh-keys:add, límites y prompts.
• Plugins de servicios: plantillas de servicios, primera implementación con postgresql.

IDEAS

• Transacciones SSH / conexiones de larga duración: registros en streaming y operaciones interactivas.
• Aplicar lista de permitidos: aplicar el principio de mínimos privilegios con una lista de permitidos explícita en lugar de una lista de bloqueados.

Integraciones de Dokku

• Implementadas: apps:list, apps:info, apps:create, apps:destroy, apps:exists, apps:report, config:show, config:set, ps:scale, ps:report, logs, plugin:list, plugin:install, plugin:uninstall, plugin:enable, plugin:disable, plugin:update, version, proxy:report, proxy:set, scheduler:report, scheduler:set, git:report, git:set, ssh-keys:list, ssh-keys:remove, registry:logout, logs:set.
• Faltantes/parciales: ssh-keys:add, registry:login/listado del registro, enumeración de claves de configuración, plugin de Servicios, plugin SSL, sesiones de streaming/attach.

Contribuye — reporta problemas o propón funciones

Abre un issue o lee Contribución.

🪿 Obtén ayuda de Goose AI en los issues

¿Necesitas ayuda con el proyecto dokku-mcp? ¡Goose AI está disponible para ayudarte! Simplemente etiqueta tus issues o pull requests de GitHub con la etiqueta :goose, y Goose AI será notificado automáticamente para ayudar con el desarrollo, depuración, implementación de funciones y otras tareas relacionadas con el proyecto.

Ejemplo de Goose AI en acción Otro ejemplo

Tabla de contenidos

• Instalación
• Configuración
• Desarrollo Local de Dokku
• Conexión de Clientes MCP
• Desarrollo
  • Configuración de Desarrollo
  • Comandos de Makefile
  • Pruebas
• Arquitectura
• Estructura del Proyecto
• Contribución
• Licencia

Instalación

Binarios Precompilados

Descarga la última versión para tu plataforma:

# Linux (amd64; also available: arm64, arm)
curl -L -o dokku-mcp https://github.com/dokku-mcp/dokku-mcp/releases/latest/download/dokku-mcp-linux-amd64
chmod +x dokku-mcp
sudo mv dokku-mcp /usr/local/bin/

# macOS (amd64; also available: arm64)
curl -L -o dokku-mcp https://github.com/dokku-mcp/dokku-mcp/releases/latest/download/dokku-mcp-darwin-amd64
chmod +x dokku-mcp
sudo mv dokku-mcp /usr/local/bin/

Los archivos comprimidos (dokku-mcp-<os>-<arch>.tar.gz) también se publican con cada versión.

Verificar la Instalación

dokku-mcp --version

Compilar desde el Código Fuente

Si prefieres compilar desde el código fuente:

1. Requisitos previos:

   • Go (versión 1.25 o posterior)

2. Clonar y compilar:

   git clone https://github.com/dokku-mcp/dokku-mcp.git
   cd dokku-mcp
   make build
   

Configuración

El servidor se puede configurar de dos maneras: usando un archivo config.yaml o mediante variables de entorno.

Archivo de Configuración

Crea un archivo de configuración en una de las siguientes ubicaciones:

• A nivel de sistema: /etc/dokku-mcp/config.yaml
• Específico del usuario: ~/.dokku-mcp/config.yaml
• Local: config.yaml en el mismo directorio que el binario.

Aquí tienes un ejemplo mínimo de config.yaml:

ssh:
  host: "your-dokku-host.com"
  user: "dokku"
  # key_path: "/path/to/your/ssh/private/key" # Optional, uses ssh-agent if empty

log_level: "info"

Para obtener una lista completa de las opciones disponibles, consulta el archivo config.yaml.example.

Variables de Entorno

Todas las opciones de configuración se pueden sobrescribir con variables de entorno con el prefijo DOKKU_MCP_. Por ejemplo:

export DOKKU_MCP_SSH_HOST="your-dokku-host.com"
export DOKKU_MCP_SSH_USER="dokku"
export DOKKU_MCP_LOG_LEVEL="debug"

Ejecutar el Servidor

Una vez configurado, puedes ejecutar el servidor:

dokku-mcp

El servidor se iniciará y estará listo para aceptar conexiones de un cliente MCP.

Desarrollo Local de Dokku

Para desarrollo y pruebas sin necesidad de una instancia remota de Dokku, puedes ejecutar un servidor Dokku local usando Docker.

Requisitos previos:

• Docker y Docker Compose
• Make

1. Configurar el contenedor Dokku local:

   Este comando descargará las imágenes de Docker necesarias y configurará la instancia local de Dokku. Solo necesita ejecutarse una vez.

   make setup-dokku
   
   make dokku-start
   

2. Detener el contenedor Dokku local:

   make dokku-stop
   

Cuando el contenedor Dokku local esté en ejecución, el servidor MCP (con la configuración predeterminada) debería poder conectarse a él. Puedes ejecutar pruebas de integración contra esta instancia local.

Modos de Transporte

El servidor soporta dos modos de transporte para clientes:

• stdio (predeterminado): Entrada/salida estándar para comunicación directa entre procesos.
• sse (Server-Sent Events): Transporte basado en HTTP para clientes web.

  DOKKU_MCP_TRANSPORT_TYPE=sse dokku-mcp
  

Configuración de CORS

Para el transporte SSE, CORS se gestiona por defecto con Access-Control-Allow-Origin: *. Para despliegues remotos, puedes habilitar middleware CORS personalizado:

transport:
  type: sse
  cors:
    enabled: true
    allowed_origins:
      - "https://app.example.com"
      - "*.example.com"

Consulta docs/CORS.md para opciones de configuración detalladas y mejores prácticas de seguridad.

Desarrollo

Esta sección es para desarrolladores que quieran contribuir al proyecto o modificar el código fuente.

Configuración de Desarrollo

1. Requisitos previos:

   • Go (versión 1.25 o posterior)
   • Docker y Docker Compose
   • Make

2. Clonar el repositorio:

   git clone https://github.com/dokku-mcp/dokku-mcp.git
   cd dokku-mcp
   

3. Instalar herramientas de desarrollo:

   Este comando instala todas las herramientas de Go necesarias para desarrollo, linting y pruebas.

   make install-tools
   

4. Configurar el entorno de desarrollo:

   Este comando configura hooks de Git para garantizar la calidad del código antes de los commits.

   make setup-dev
   

5. Compilar y ejecutar desde el código fuente:

   # This command builds the binary and starts the server.
   make start
   

Comandos de Makefile

El proyecto utiliza un Makefile para automatizar tareas comunes.

• make help: Mostrar todos los comandos disponibles.
• make check: Ejecutar todas las verificaciones de calidad del código (linting, formato, complejidad).
• make build: Compilar el binario del servidor.
• make clean: Limpiar los artefactos de compilación.

Pruebas

• Ejecutar todas las pruebas:

  make test
  

  Esto ejecuta todas las pruebas unitarias y de integración y genera un informe de cobertura HTML en coverage.html.

• Ejecutar pruebas de integración contra Dokku local: Asegúrate de que tu contenedor Dokku local esté en ejecución (make dokku-start).

  make test-integration-local
  

Arquitectura

El servidor sigue los principios de Diseño Dirigido por el Dominio (DDD), con una clara separación entre:

• Capa de Dominio (internal/domain): Lógica de negocio central, entidades e interfaces de repositorio.
• Capa de Aplicación (internal/application): Orquestación y coordinación de casos de uso.
• Capa de Infraestructura (internal/infrastructure): Implementaciones de interfaces, como el cliente de Dokku, bases de datos y servicios externos.

Cuenta con una arquitectura basada en plugins ubicada en internal/server-plugins, donde cada plugin encapsula un conjunto específico de funciones de Dokku (p. ej., app, core, deployment).

Para más detalles, consulta la documentación en el directorio docs/.

Estructura del Proyecto

dokku-mcp/
├── cmd/                    # Entry points for the application
│   └── server/             # Server main command
├── internal/               # Private application code
│   ├── server/             # MCP server and adapter
│   ├── server-plugin/      # Plugin system infrastructure
│   ├── server-plugins/     # Actual plugin implementations (app, core, etc.)
│   ├── dokku-api/          # Dokku CLI client and API
│   └── shared/             # Shared domain types and services
├── pkg/                    # Reusable packages (config, logger, etc.)
├── docs/                   # Project documentation
└── scripts/                # Helper scripts

Contribución

¡Las contribuciones son bienvenidas! Consulta Contribución para obtener una guía detallada sobre cómo contribuir.

Licencia

Este proyecto está bajo la Licencia Apache 2.0 - consulta el archivo LICENSE para más detalles.

Copyright [Alex Galey]

Licenciado bajo la Licencia Apache, Versión 2.0 (la "Licencia"); no puedes usar este archivo excepto en cumplimiento con la Licencia. Puedes obtener una copia de la Licencia en

http://www.apache.org/licenses/LICENSE-2.0

Salvo que lo exija la ley aplicable o se acuerde por escrito, el software distribuido bajo la Licencia se distribuye "TAL CUAL", SIN GARANTÍAS NI CONDICIONES DE NINGÚN TIPO, ya sean expresas o implícitas. Consulta la Licencia para conocer el lenguaje específico que rige los permisos y las limitaciones bajo la Licencia.