# DDEV MCP Server

## Overview

This project provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables Large 
Language Models (LLMs) and AI assistants to interact with [DDEV](https://ddev.com/) local development environments.

Features include:

- 🗄️ **Query databases directly** - Execute SQL queries, inspect schemas, and analyze data in your DDEV MySQL/PostgreSQL databases
- 🚀 **Manage DDEV projects** - Start, stop, restart projects and check their status
- 🔧 **Execute development commands** - Run Composer, access logs, control Xdebug, and execute shell commands in containers
- 🛡️ **Maintain security** - Whitelist-based protection ensures only safe operations are allowed by default

**Use Cases:**
- **Database Development**: "Show me all users with pending orders" → LLM queries your local database directly
- **Debugging**: "Check the error logs for the last hour" → LLM retrieves and analyzes DDEV service logs
- **Project Management**: "Start my e-commerce project and check if the database is ready" → LLM manages your DDEV environment
- **Schema Analysis**: "What's the relationship between users and orders tables?" → LLM inspects your actual database structure
- **Development Workflow**: "Run the latest migrations and show me the updated schema" → LLM executes commands and verifies results

## Features

### Tools

#### Database Operations
- `ddev_db_backup` - Create database snapshots
- `ddev_db_describe_table` - Get table structure/schema (PostgreSQL \d or MySQL DESCRIBE)
- `ddev_db_list_backups` - List available database backups
- `ddev_db_list_databases` - List all databases (PostgreSQL \l or MySQL SHOW DATABASES)
- `ddev_db_list_tables` - List all tables in the database (auto-detects database type)
- `ddev_db_query` - Execute SQL queries with detailed error reporting (supports PostgreSQL, MySQL, MariaDB)
- `ddev_db_restore` - Restore from database snapshots

#### Project Management
- `ddev_list_projects` - List all DDEV projects with status
- `ddev_project_status` - Get current status and configuration of a DDEV project
- `ddev_start_project` - Start a DDEV project
- `ddev_stop_project` - Stop a DDEV project
- `ddev_restart_project` - Restart a DDEV project

#### DDEV Service Operations
- `ddev_exec_command` - Execute commands in DDEV web service
- `ddev_exec_service` - Execute commands in specific DDEV services (web, db, redis, etc.)
- `ddev_ssh` - SSH access and connection information
- `ddev_logs` - Get service logs

#### Development Tools
- `ddev_composer_command` - Run Composer commands
- `ddev_xdebug` - Control Xdebug (on/off/toggle/status)
- `ddev_share` - Share project via ngrok tunnel
- `ddev_mailpit` - Access Mailpit for email testing

#### Database Management
- `ddev_export_db` - Export database dumps
- `ddev_import_db` - Import database dumps

**🔒 Security Features:** 
- **Whitelist Security Model**: Only explicitly allowed read-only operations are permitted (default deny)
- **Comprehensive Protection**: Blocks hundreds of potentially dangerous operations by default
- **Write Protection**: All data modification blocked by default unless `--allow-write` is used
- **Catastrophic Operation Blocking**: DROP DATABASE, SHUTDOWN, file operations always blocked
- **Configuration Protection**: Blocks SET, FLUSH, GRANT, and other config changes

### Resources
- `ddev://current` - Current project context and server configuration
- `ddev://config` - Current project DDEV configuration

## Security Features

**🔒 Whitelist Security Model (Default Deny)**
The MCP server uses a comprehensive whitelist approach where only explicitly allowed read-only operations are permitted. 
Any query not matching the whitelist is automatically blocked.

### ✅ Allowed Operations (Whitelist)
- `SELECT` - Data queries and joins
- `SHOW` - Database/table inspection (TABLES, DATABASES, COLUMNS, etc.)
- `DESCRIBE` / `DESC` - Table structure
- `EXPLAIN` - Query execution plans
- `WITH ... SELECT` - Common Table Expressions (read-only)
- PostgreSQL meta-commands (`\dt`, `\d`, `\l`, etc.)
- System catalog queries (`INFORMATION_SCHEMA`, `pg_catalog`)

### 🚫 Always Blocked (Even with --allow-write)
- `DROP DATABASE` / `DROP SCHEMA` - Catastrophic deletions
- `SHUTDOWN`, `KILL` - System control
- File system access (`LOAD_FILE`, `INTO OUTFILE`)
- Shell commands (`\!`, `COPY ... FROM PROGRAM`)
- Other system-level operations

### Enabling Write Operations

To enable write operations, use the `--allow-write` flag:

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

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

**⚠️ Warning**: Only enable write operations when necessary and ensure you trust the LLM application accessing the server.

## Multi-Database Support

The MCP server automatically detects the database type from your DDEV configuration and uses the appropriate commands:

### PostgreSQL Projects
- Commands: `psql`, `\dt`, `\d table_name`, `\l`
- Detected from: `database.type: postgres` in `.ddev/config.yaml`

### MySQL/MariaDB Projects  
- Commands: `mysql`, `SHOW TABLES`, `DESCRIBE table_name`, `SHOW DATABASES`
- Detected from: `database.type: mysql` or `database.type: mariadb` in `.ddev/config.yaml`

### Automatic Detection
- Reads `.ddev/config.yaml` to determine database type
- Falls back to MySQL if no configuration found
- Database type is shown in command output for clarity

## Installation & Deployment

### Option 1: Download from GitHub Releases (Recommended)

Download the NPM package from the [latest release](https://github.com/AkibaAT/ddev-mcp/releases/latest) and install locally:

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

# Verify installation
ddev-mcp --help
```

### Option 2: NPM Installation (Currently Unavailable)

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

### Option 3: Build from Source

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

### Option 4: Quick Installation Script

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

This will:
- ✅ Check system requirements (Node.js 20+, DDEV)
- 📦 Install the server globally via npm
- 📋 Provide MCP client configuration

## MCP Client Configuration

### Basic Configuration

#### Global Installation
```json
{
  "mcpServers": {
    "ddev": {
      "command": "ddev-mcp"
    }
  }
}
```

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

### Advanced Configuration with Single Project Mode

**⚠️ Important:** When you configure single project mode, the MCP server becomes **limited to that single project only**. All tools will automatically target the configured project, project selection parameters (`project_name`) will be hidden from the interface, and the `ddev_list_projects` command will be disabled for security reasons (to prevent information disclosure about other projects on the system).

#### Single Project Mode (Recommended for dedicated development)
```json
{
  "mcpServers": {
    "ddev": {
      "command": "ddev-mcp",
      "args": ["--single-project", "project-id"]
    }
  }
}
```


**Use Case:** Perfect when working on a single project and you want a clean, dedicated interface without repetitive 
project parameters.

#### Enable Write Operations (Use with Caution)
```json
{
  "mcpServers": {
    "ddev-write": {
      "command": "ddev-mcp",
      "args": ["--allow-write", "--single-project", "development-site"]
    }
  }
}
```

#### Multi-Project Mode (Flexible for multiple projects)
```json
{
  "mcpServers": {
    "ddev": {
      "command": "ddev-mcp"
    }
  }
}
```

**Use Case:** When working with multiple DDEV projects, you can specify `project_name` or `project_path` for each command. 
All tools will show project selection parameters.

#### Multiple Dedicated Servers (Different projects and security levels)
```json
{
  "mcpServers": {
    "ddev-production": {
      "command": "ddev-mcp",
      "args": ["--single-project", "main-site"]
    },
    "ddev-development": {
      "command": "ddev-mcp",
      "args": ["--allow-write", "--single-project", "dev-site"]
    }
  }
}
```

**Use Case:** Separate MCP servers for different projects with different security levels (e.g., read-only for production, 
write-enabled for development).

### Configuration Summary

| Mode                 | Configuration                                   | Project Parameters | `ddev_list_projects`    | Use Case                                        |
|----------------------|-------------------------------------------------|--------------------|-------------------------|-------------------------------------------------|
| **Single Project**   | `--single-project name`                         | Hidden (automatic) | **Disabled** (security) | Dedicated development on one project            |
| **Multi-Project**    | No default args                                 | Visible (required) | **Available**           | Working across multiple projects                |
| **Multiple Servers** | Multiple servers with different single projects | Hidden per server  | **Disabled** per server | Different projects with different access levels |

### Configuration File Locations

Configuration file locations depend on your MCP client. Common examples:

- **Generic MCP Client**: `~/.config/mcp/config.json`
- **Application-specific**: Check your MCP client documentation for the correct path

## Project Context Features

**🎯 Intelligent Project Context**
When you configure single project mode, the MCP server provides rich contextual information to LLMs through the 
`ddev://current` resource.

### Current Project Information

The `ddev://current` resource provides real-time:
- **Project Details**: Name, status, database type, URL
- **Server Configuration**: Security mode, default settings  
- **Dynamic Status**: Current project state (updated when accessed)

**Example Response:**
```json
{
  "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
  }
}
```

## Usage Examples

### Project Targeting Options

The MCP server supports different project targeting modes depending on your configuration:

#### Single Project Mode (Single Project Configured)
```json5
// Clean interface - no project parameters needed or visible
{
  "name": "ddev_db_query",
  "arguments": {
    "query": "SELECT COUNT(*) FROM games;"
  }
}
```
**All commands automatically target the configured single project.**

#### Multi-Project Mode (No Single Project Restriction)
```json5
// Use Project Name
{
  "name": "ddev_db_query",
  "arguments": {
    "project_name": "project-id",
    "query": "SELECT COUNT(*) FROM users;"
  }
}
```

```json5
// Start a specific project
{
  "name": "ddev_start_project", 
  "arguments": {
    "project_name": "my-site"
  }
}
```
**Project parameters are visible and required for targeting specific projects.**

### Project Resolution (Multi-Project Mode Only)

When no single project restriction is configured, the server resolves projects in this order:

1. **Explicit `project_name`** - Uses the specified DDEV project name
2. **Current directory** - Fallback if no project name provided

**Note:** In single project mode, all commands automatically use the configured project.

## Testing & Debugging

### Test with MCP Inspector
```bash
# 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
```

### Verify Installation
```bash
# Check if globally installed
which ddev-mcp

# Test DDEV integration
ddev list --json-output
```

## Requirements

- Node.js 20+
- DDEV installed and accessible via PATH
- DDEV projects configured

## Development

### Building and Running

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

### Code Quality

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

### Testing

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