DDEV MCP Server

Gerencie projetos DDEV, permitindo que aplicações LLM interajam com ambientes de desenvolvimento locais através do protocolo MCP.

GitHub

Documentação

DDEV MCP Server

Visão Geral

Este projeto fornece um servidor Model Context Protocol (MCP) que permite que Modelos de Linguagem de Grande Porte (LLMs) e assistentes de IA interajam com ambientes de desenvolvimento local DDEV.

Os recursos incluem:

🗄️ Consultar bancos de dados diretamente - Execute consultas SQL, inspecione esquemas e analise dados em seus bancos de dados MySQL/PostgreSQL do DDEV
🚀 Gerenciar projetos DDEV - Inicie, pare, reinicie projetos e verifique seu status
🔧 Executar comandos de desenvolvimento - Execute Composer, acesse logs, controle Xdebug e execute comandos shell em contêineres
🛡️ Manter segurança - A proteção baseada em lista de permissões garante que apenas operações seguras sejam permitidas por padrão

Casos de Uso:

Desenvolvimento de Banco de Dados: "Mostre-me todos os usuários com pedidos pendentes" → O LLM consulta seu banco de dados local diretamente
Depuração: "Verifique os logs de erro da última hora" → O LLM recupera e analisa os logs de serviço do DDEV
Gerenciamento de Projetos: "Inicie meu projeto de e-commerce e verifique se o banco de dados está pronto" → O LLM gerencia seu ambiente DDEV
Análise de Esquema: "Qual é a relação entre as tabelas de usuários e pedidos?" → O LLM inspeciona sua estrutura real de banco de dados
Fluxo de Trabalho de Desenvolvimento: "Execute as migrações mais recentes e mostre-me o esquema atualizado" → O LLM executa comandos e verifica resultados

Recursos

Ferramentas

Operações de Banco de Dados

ddev_db_backup - Criar snapshots de banco de dados
ddev_db_describe_table - Obter estrutura/esquema de tabela (PostgreSQL \d ou MySQL DESCRIBE)
ddev_db_list_backups - Listar backups de banco de dados disponíveis
ddev_db_list_databases - Listar todos os bancos de dados (PostgreSQL \l ou MySQL SHOW DATABASES)
ddev_db_list_tables - Listar todas as tabelas no banco de dados (detecta automaticamente o tipo de banco)
ddev_db_query - Executar consultas SQL com relatórios de erro detalhados (suporta PostgreSQL, MySQL, MariaDB)
ddev_db_restore - Restaurar a partir de snapshots de banco de dados

Gerenciamento de Projetos

ddev_list_projects - Listar todos os projetos DDEV com status
ddev_project_status - Obter status atual e configuração de um projeto DDEV
ddev_start_project - Iniciar um projeto DDEV
ddev_stop_project - Parar um projeto DDEV
ddev_restart_project - Reiniciar um projeto DDEV

Operações de Serviço DDEV

ddev_exec_command - Executar comandos no serviço web do DDEV
ddev_exec_service - Executar comandos em serviços DDEV específicos (web, db, redis, etc.)
ddev_ssh - Acesso SSH e informações de conexão
ddev_logs - Obter logs de serviço

Ferramentas de Desenvolvimento

ddev_composer_command - Executar comandos Composer
ddev_xdebug - Controlar Xdebug (ligar/desligar/alternar/status)
ddev_share - Compartilhar projeto via túnel ngrok
ddev_mailpit - Acessar Mailpit para testes de e-mail

Gerenciamento de Banco de Dados

ddev_export_db - Exportar dumps de banco de dados
ddev_import_db - Importar dumps de banco de dados

🔒 Recursos de Segurança:

Modelo de Segurança com Lista de Permissões: Apenas operações somente leitura explicitamente permitidas são autorizadas (negação por padrão)
Proteção Abrangente: Bloqueia centenas de operações potencialmente perigosas por padrão
Proteção de Escrita: Toda modificação de dados é bloqueada por padrão, a menos que --allow-write seja usado
Bloqueio de Operações Catastróficas: DROP DATABASE, SHUTDOWN, operações de arquivo sempre bloqueadas
Proteção de Configuração: Bloqueia SET, FLUSH, GRANT e outras alterações de configuração

Recursos

ddev://current - Contexto atual do projeto e configuração do servidor
ddev://config - Configuração DDEV atual do projeto

Recursos de Segurança

🔒 Modelo de Segurança com Lista de Permissões (Negação por Padrão) O servidor MCP usa uma abordagem abrangente de lista de permissões onde apenas operações somente leitura explicitamente permitidas são autorizadas. Qualquer consulta que não corresponda à lista de permissões é bloqueada automaticamente.

✅ Operações Permitidas (Lista de Permissões)

SELECT - Consultas de dados e junções
SHOW - Inspeção de banco de dados/tabelas (TABLES, DATABASES, COLUMNS, etc.)
DESCRIBE / DESC - Estrutura de tabela
EXPLAIN - Planos de execução de consultas
WITH ... SELECT - Expressões de Tabela Comum (somente leitura)
Meta-comandos PostgreSQL (\dt, \d, \l, etc.)
Consultas ao catálogo do sistema (INFORMATION_SCHEMA, pg_catalog)

🚫 Sempre Bloqueado (Mesmo com --allow-write)

DROP DATABASE / DROP SCHEMA - Exclusões catastróficas
SHUTDOWN, KILL - Controle do sistema
Acesso ao sistema de arquivos (LOAD_FILE, INTO OUTFILE)
Comandos shell (\!, COPY ... FROM PROGRAM)
Outras operações de nível de sistema

Habilitando Operações de Escrita

Para habilitar operações de escrita, use o sinalizador --allow-write:

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

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

⚠️

Aviso**: Habilite operações de escrita apenas quando necessário e garanta que você confia no aplicativo LLM que acessa o servidor.

Suporte a Múltiplos Bancos de Dados

O servidor MCP detecta automaticamente o tipo de banco de dados a partir da sua configuração DDEV e usa os comandos apropriados:

Projetos PostgreSQL

Comandos: psql, \dt, \d table_name, \l
Detectado a partir de: database.type: postgres em .ddev/config.yaml

Projetos MySQL/MariaDB

Comandos: mysql, SHOW TABLES, DESCRIBE table_name, SHOW DATABASES
Detectado a partir de: database.type: mysql ou database.type: mariadb em .ddev/config.yaml

Detecção Automática

Lê .ddev/config.yaml para determinar o tipo de banco de dados
Usa MySQL como fallback se nenhuma configuração for encontrada
O tipo de banco de dados é exibido na saída do comando para maior clareza

Instalação & Implantação

Baixe o pacote NPM da última versão e instale localmente:

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

# Verify installation
ddev-mcp --help

Opção 2: Instalação via NPM (Atualmente Indisponível)

# 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 .

Opção 3: Compilar a partir do Código Fonte

# 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 .

Opção 4: Script de Instalação Rápida

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

Isso irá:

✅ Verificar requisitos do sistema (Node.js 20+, DDEV)
📦 Instalar o servidor globalmente via npm
📋 Fornecer configuração do cliente MCP

Configuração do Cliente MCP

Configuração Básica

Instalação Global

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

Instalação Local

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

Configuração Avançada com Modo de Projeto Único

⚠️

Importante:** Ao configurar o modo de projeto único, o servidor MCP fica limitado a esse único projeto apenas. Todas as ferramentas terão como alvo automático o projeto configurado, os parâmetros de seleção de projeto (project_name) ficarão ocultos da interface, e o comando ddev_list_projects será desabilitado por motivos de segurança (para evitar divulgação de informações sobre outros projetos no sistema).

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

Caso de Uso: Perfeito quando você trabalha em um único projeto e deseja uma interface limpa e dedicada, sem parâmetros repetitivos de projeto.

Habilitar Operações de Escrita (Use com Cautela)

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

Modo Multi-Projeto (Flexível para múltiplos projetos)

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

Caso de Uso: Ao trabalhar com múltiplos projetos DDEV, você pode especificar project_name ou project_path para cada comando. Todas as ferramentas mostrarão parâmetros de seleção de projeto.

Múltiplos Servidores Dedicados (Diferentes projetos e níveis de segurança)

{
  "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 projetos com diferentes níveis de segurança (por exemplo, somente leitura para produção, escrita habilitada para desenvolvimento).

Resumo de Configuração

Modo	Configuração	Parâmetros de Projeto	`ddev_list_projects`	Caso de Uso
Projeto Único	`--single-project name`	Ocultos (automáticos)	Desabilitado (segurança)	Desenvolvimento dedicado em um projeto
Multi-Projeto	Sem argumentos padrão	Visíveis (obrigatórios)	Disponível	Trabalho em múltiplos projetos
Múltiplos Servidores	Múltiplos servidores com diferentes projetos únicos	Ocultos por servidor	Desabilitado por servidor	Diferentes projetos com diferentes níveis de acesso

Locais dos Arquivos de Configuração

Os locais dos arquivos de configuração dependem do seu cliente MCP. Exemplos comuns:

Cliente MCP Genérico: ~/.config/mcp/config.json
Específico do aplicativo: Consulte a documentação do seu cliente MCP para o caminho correto

Recursos de Contexto do Projeto

🎯 Contexto Inteligente do Projeto Ao configurar o modo de projeto único, o servidor MCP fornece informações contextuais ricas aos LLMs através do recurso ddev://current.

Informações Atuais do Projeto

O recurso ddev://current fornece em tempo real:

Detalhes do Projeto: Nome, status, tipo de banco de dados, URL
Configuração do Servidor: Modo de segurança, configurações padrão
Status Dinâmico: Estado atual do projeto (atualizado quando acessado)

Exemplo de Resposta:

{
  "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
  }
}

Exemplos de Uso

Opções de Segmentação de Projeto

O servidor MCP suporta diferentes modos de segmentação de projeto dependendo da sua configuração:

Modo de Projeto Único (Projeto Único Configurado)

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

Todos os comandos têm como alvo automático o projeto único configurado.

Modo Multi-Projeto (Sem Restrição de Projeto Ú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"
  }
}

Os parâmetros de projeto são visíveis e obrigatórios para segmentar projetos específicos.

Resolução de Projeto (Somente Modo Multi-Projeto)

Quando nenhuma restrição de projeto único está configurada, o servidor resolve projetos nesta ordem:

project_name explícito - Usa o nome do projeto DDEV especificado
Diretório atual - Fallback se nenhum nome de projeto for fornecido

Nota: No modo de projeto único, todos os comandos usam automaticamente o projeto configurado.

Testes & Depuração

Testar com 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 Instalação

# Check if globally installed
which ddev-mcp

# Test DDEV integration
ddev list --json-output

Requisitos

Node.js 20+
DDEV instalado e acessível via PATH
Projetos DDEV configurados

Desenvolvimento

Compilação e Execução

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

Qualidade de 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)

Testes

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