DDEV MCP Server

Gestiona proyectos DDEV, permitiendo que aplicaciones LLM interactúen con entornos de desarrollo locales a través del protocolo MCP.

GitHub

Documentación

DDEV MCP Server

Resumen

Este proyecto proporciona un servidor de Model Context Protocol (MCP) que permite a los Modelos de Lenguaje de Gran Tamaño (LLMs) y asistentes de IA interactuar con entornos de desarrollo local DDEV.

Las características incluyen:

🗄️ Consultar bases de datos directamente - Ejecutar consultas SQL, inspeccionar esquemas y analizar datos en tus bases de datos MySQL/PostgreSQL de DDEV
🚀 Gestionar proyectos DDEV - Iniciar, detener, reiniciar proyectos y verificar su estado
🔧 Ejecutar comandos de desarrollo - Ejecutar Composer, acceder a registros, controlar Xdebug y ejecutar comandos de shell en contenedores
🛡️ Mantener la seguridad - La protección basada en listas blancas garantiza que solo se permitan operaciones seguras de forma predeterminada

Casos de uso:

Desarrollo de bases de datos: "Muéstrame todos los usuarios con pedidos pendientes" → El LLM consulta tu base de datos local directamente
Depuración: "Revisa los registros de errores de la última hora" → El LLM recupera y analiza los registros de servicios de DDEV
Gestión de proyectos: "Inicia mi proyecto de comercio electrónico y verifica si la base de datos está lista" → El LLM gestiona tu entorno DDEV
Análisis de esquemas: "¿Cuál es la relación entre las tablas de usuarios y pedidos?" → El LLM inspecciona la estructura real de tu base de datos
Flujo de trabajo de desarrollo: "Ejecuta las últimas migraciones y muéstrame el esquema actualizado" → El LLM ejecuta comandos y verifica resultados

Características

Herramientas

Operaciones de base de datos

ddev_db_backup - Crear instantáneas de base de datos
ddev_db_describe_table - Obtener estructura/esquema de tabla (PostgreSQL \d o MySQL DESCRIBE)
ddev_db_list_backups - Listar copias de seguridad disponibles de la base de datos
ddev_db_list_databases - Listar todas las bases de datos (PostgreSQL \l o MySQL SHOW DATABASES)
ddev_db_list_tables - Listar todas las tablas en la base de datos (detecta automáticamente el tipo de base de datos)
ddev_db_query - Ejecutar consultas SQL con informes de error detallados (soporta PostgreSQL, MySQL, MariaDB)
ddev_db_restore - Restaurar desde instantáneas de base de datos

Gestión de proyectos

ddev_list_projects - Listar todos los proyectos DDEV con su estado
ddev_project_status - Obtener el estado actual y la configuración de un proyecto DDEV
ddev_start_project - Iniciar un proyecto DDEV
ddev_stop_project - Detener un proyecto DDEV
ddev_restart_project - Reiniciar un proyecto DDEV

Operaciones de servicios DDEV

ddev_exec_command - Ejecutar comandos en el servicio web de DDEV
ddev_exec_service - Ejecutar comandos en servicios DDEV específicos (web, db, redis, etc.)
ddev_ssh - Acceso SSH e información de conexión
ddev_logs - Obtener registros de servicios

Herramientas de desarrollo

ddev_composer_command - Ejecutar comandos de Composer
ddev_xdebug - Controlar Xdebug (activar/desactivar/alternar/estado)
ddev_share - Compartir proyecto mediante túnel ngrok
ddev_mailpit - Acceder a Mailpit para pruebas de correo electrónico

Gestión de bases de datos

ddev_export_db - Exportar volcados de base de datos
ddev_import_db - Importar volcados de base de datos

🔒 Características de seguridad:

Modelo de seguridad de lista blanca: Solo se permiten operaciones de solo lectura explícitamente autorizadas (denegación predeterminada)
Protección integral: Bloquea cientos de operaciones potencialmente peligrosas de forma predeterminada
Protección de escritura: Toda modificación de datos está bloqueada de forma predeterminada a menos que se use --allow-write
Bloqueo de operaciones catastróficas: DROP DATABASE, SHUTDOWN y operaciones de archivos siempre están bloqueadas
Protección de configuración: Bloquea SET, FLUSH, GRANT y otros cambios de configuración

Recursos

ddev://current - Contexto actual del proyecto y configuración del servidor
ddev://config - Configuración DDEV actual del proyecto

Características de seguridad

🔒 Modelo de seguridad de lista blanca (denegación predeterminada) El servidor MCP utiliza un enfoque integral de lista blanca donde solo se permiten operaciones de solo lectura explícitamente autorizadas. Cualquier consulta que no coincida con la lista blanca se bloquea automáticamente.

✅ Operaciones permitidas (lista blanca)

SELECT - Consultas de datos y uniones
SHOW - Inspección de bases de datos/tablas (TABLES, DATABASES, COLUMNS, etc.)
DESCRIBE / DESC - Estructura de tablas
EXPLAIN - Planes de ejecución de consultas
WITH ... SELECT - Expresiones de tabla comunes (solo lectura)
Meta-comandos de PostgreSQL (\dt, \d, \l, etc.)
Consultas al catálogo del sistema (INFORMATION_SCHEMA, pg_catalog)

🚫 Siempre bloqueado (incluso con --allow-write)

DROP DATABASE / DROP SCHEMA - Eliminaciones catastróficas
SHUTDOWN, KILL - Control del sistema
Acceso al sistema de archivos (LOAD_FILE, INTO OUTFILE)
Comandos de shell (\!, COPY ... FROM PROGRAM)
Otras operaciones a nivel de sistema

Habilitar operaciones de escritura

Para habilitar operaciones de escritura, usa la bandera --allow-write:

# Enable write operations
ddev-mcp --allow-write

# Enable write operations with single project mode
ddev-mcp --allow-write --single-project my-project

⚠️

Advertencia**: Solo habilita operaciones de escritura cuando sea necesario y asegúrate de confiar en la aplicación LLM que accede al servidor.

Soporte de múltiples bases de datos

El servidor MCP detecta automáticamente el tipo de base de datos desde tu configuración DDEV y usa los comandos apropiados:

Proyectos PostgreSQL

Comandos: psql, \dt, \d table_name, \l
Detectado desde: database.type: postgres en .ddev/config.yaml

Proyectos MySQL/MariaDB

Comandos: mysql, SHOW TABLES, DESCRIBE table_name, SHOW DATABASES
Detectado desde: database.type: mysql o database.type: mariadb en .ddev/config.yaml

Detección automática

Lee .ddev/config.yaml para determinar el tipo de base de datos
Usa MySQL como alternativa si no se encuentra configuración
El tipo de base de datos se muestra en la salida del comando para mayor claridad

Instalación e implementación

Descarga el paquete NPM desde la última versión e instálalo localmente:

# Download the .tgz file from releases, then:
npm install -g ./ddev-mcp-0.8.0.tgz

# Verify installation
ddev-mcp --help

Opción 2: Instalación mediante NPM (actualmente no disponible)

# NPM publishing is currently disabled
# Use Option 1 (GitHub Releases) instead
npm install -g ddev-mcp  # This will not work currently

# Or install directly from the downloaded package
tar -xzf ddev-mcp-1.0.0.tgz
cd package
npm install -g .

Opción 3: Compilar desde el código fuente

# Clone the repository
git clone https://github.com/AkibaAT/ddev-mcp.git
cd ddev-mcp

# Install dependencies and build
npm install
npm run build

# Install globally (optional)
npm install -g .

Opción 4: Script de instalación rápida

# Clone and install
git clone https://github.com/AkibaAT/ddev-mcp.git
cd ddev-mcp
chmod +x install.sh
./install.sh

Esto hará lo siguiente:

✅ Verificar los requisitos del sistema (Node.js 20+, DDEV)
📦 Instalar el servidor globalmente mediante npm
📋 Proporcionar la configuración del cliente MCP

Configuración del cliente MCP

Configuración básica

Instalación global

{
  "mcpServers": {
    "ddev": {
      "command": "ddev-mcp"
    }
  }
}

Instalación local

{
  "mcpServers": {
    "ddev": {
      "command": "node",
      "args": ["/absolute/path/to/ddev-mcp/dist/index.js"]
    }
  }
}

Configuración avanzada con modo de proyecto único

⚠️

Importante:** Cuando configuras el modo de proyecto único, el servidor MCP se limita a ese único proyecto solamente. Todas las herramientas apuntarán automáticamente al proyecto configurado, los parámetros de selección de proyecto (project_name) se ocultarán de la interfaz y el comando ddev_list_projects se deshabilitará por razones de seguridad (para evitar la divulgación de información sobre otros proyectos en el sistema).

{
  "mcpServers": {
    "ddev": {
      "command": "ddev-mcp",
      "args": ["--single-project", "project-id"]
    }
  }
}

Caso de uso: Perfecto cuando trabajas en un solo proyecto y deseas una interfaz limpia y dedicada sin parámetros de proyecto repetitivos.

Habilitar operaciones de escritura (usar con precaución)

{
  "mcpServers": {
    "ddev-write": {
      "command": "ddev-mcp",
      "args": ["--allow-write", "--single-project", "development-site"]
    }
  }
}

Modo multiproyecto (flexible para múltiples proyectos)

{
  "mcpServers": {
    "ddev": {
      "command": "ddev-mcp"
    }
  }
}

Caso de uso: Cuando trabajas con múltiples proyectos DDEV, puedes especificar project_name o project_path para cada comando. Todas las herramientas mostrarán parámetros de selección de proyecto.

Múltiples servidores dedicados (diferentes proyectos y niveles de seguridad)

{
  "mcpServers": {
    "ddev-production": {
      "command": "ddev-mcp",
      "args": ["--single-project", "main-site"]
    },
    "ddev-development": {
      "command": "ddev-mcp",
      "args": ["--allow-write", "--single-project", "dev-site"]
    }
  }
}

Caso de uso: Servidores MCP separados para diferentes proyectos con diferentes niveles de seguridad (por ejemplo, solo lectura para producción, escritura habilitada para desarrollo).

Resumen de configuración

Modo	Configuración	Parámetros de proyecto	`ddev_list_projects`	Caso de uso
Proyecto único	`--single-project name`	Ocultos (automáticos)	Deshabilitado (seguridad)	Desarrollo dedicado en un proyecto
Multiproyecto	Sin argumentos predeterminados	Visibles (obligatorios)	Disponible	Trabajo en múltiples proyectos
Múltiples servidores	Múltiples servidores con diferentes proyectos únicos	Ocultos por servidor	Deshabilitado por servidor	Diferentes proyectos con diferentes niveles de acceso

Ubicaciones de archivos de configuración

Las ubicaciones de los archivos de configuración dependen de tu cliente MCP. Ejemplos comunes:

Cliente MCP genérico: ~/.config/mcp/config.json
Específico de la aplicación: Consulta la documentación de tu cliente MCP para conocer la ruta correcta

Características de contexto del proyecto

🎯 Contexto inteligente del proyecto Cuando configuras el modo de proyecto único, el servidor MCP proporciona información contextual enriquecida a los LLM a través del recurso ddev://current.

Información actual del proyecto

El recurso ddev://current proporciona en tiempo real:

Detalles del proyecto: Nombre, estado, tipo de base de datos, URL
Configuración del servidor: Modo de seguridad, configuración predeterminada
Estado dinámico: Estado actual del proyecto (actualizado al acceder)

Respuesta de ejemplo:

{
  "project": {
    "name": "project-id",
    "status": "running", 
    "dbType": "postgres",
    "url": "https://project-id.ddev.site",
    "description": "DDEV project 'project-id' (running) using postgres database"
  },
  "serverConfig": {
    "securityMode": "read-only",
    "allowWriteOperations": false
  }
}

Ejemplos de uso

Opciones de selección de proyecto

El servidor MCP admite diferentes modos de selección de proyecto según tu configuración:

Modo de proyecto único (proyecto único configurado)

// Clean interface - no project parameters needed or visible
{
  "name": "ddev_db_query",
  "arguments": {
    "query": "SELECT COUNT(*) FROM games;"
  }
}

Todos los comandos apuntan automáticamente al proyecto único configurado.

Modo multiproyecto (sin restricción de proyecto único)

// Use Project Name
{
  "name": "ddev_db_query",
  "arguments": {
    "project_name": "project-id",
    "query": "SELECT COUNT(*) FROM users;"
  }
}

// Start a specific project
{
  "name": "ddev_start_project", 
  "arguments": {
    "project_name": "my-site"
  }
}

Los parámetros de proyecto son visibles y obligatorios para seleccionar proyectos específicos.

Resolución de proyectos (solo modo multiproyecto)

Cuando no se configura una restricción de proyecto único, el servidor resuelve los proyectos en este orden:

project_name explícito - Usa el nombre del proyecto DDEV especificado
Directorio actual - Alternativa si no se proporciona un nombre de proyecto

Nota: En el modo de proyecto único, todos los comandos usan automáticamente el proyecto configurado.

Pruebas y depuración

Probar con MCP Inspector

# Global installation
npx @modelcontextprotocol/inspector ddev-mcp

# Local installation
npx @modelcontextprotocol/inspector node dist/index.js

# Development mode
npx @modelcontextprotocol/inspector node --loader ts-node/esm index.ts

Verificar la instalación

# Check if globally installed
which ddev-mcp

# Test DDEV integration
ddev list --json-output

Requisitos

Node.js 20+
DDEV instalado y accesible mediante PATH
Proyectos DDEV configurados

Desarrollo

Compilación y ejecución

npm run dev         # Run with ts-node
npm run build       # Build TypeScript
npm run start       # Run built version

Calidad del código

npm run lint        # Run ESLint
npm run lint:fix    # Fix auto-fixable ESLint issues
npm run lint:check  # Run ESLint with strict checking (CI)

Pruebas

npm run test        # Run tests
npm run test:watch  # Run tests in watch mode
npm run test:ci     # Run tests for CI (with coverage)