DDEV MCP

一个生产就绪的模型上下文协议（MCP）服务器，为AI助手提供全面的DDEV开发环境自动化。使用官方MCP SDK用TypeScript构建。

🚀 支持47+工具实现完整的DDEV自动化

支持所有DDEV项目类型，包括Drupal、WordPress、Laravel、Symfony、TYPO3、CakePHP、Magento等！

🎯 完整的DDEV开发自动化

此DDEV MCP服务器为任何Web项目提供全面的开发环境自动化：

• 环境管理：启动、停止、重启DDEV项目
• 数据库操作：导入/导出、快照、迁移
• CMS特定工作流：Drupal、WordPress、Laravel等

✨ 特性

🔧 环境管理

• 启动、停止、重启DDEV项目
• 获取项目状态和详细信息
• 访问容器日志并SSH进入服务

💾 数据库操作

• 使用各种格式导入/导出数据库
• 支持压缩的数据库文件
• 针对多数据库设置中的特定数据库

🌐 CMS与框架集成

• Drupal：执行Drush命令，管理模块和主题
• WordPress：WP-CLI命令，插件/主题管理，核心更新
• Laravel：Artisan命令，包管理
• Symfony：控制台命令，捆绑包管理
• TYPO3：TYPO3控制台命令，扩展管理
• Magento：Magento CLI，模块管理
• 等等：可扩展架构适用于任何DDEV支持的项目类型

🛡️ 企业级准备

• 全面的错误处理和日志记录
• 输入验证和清理
• 可配置的超时和安全措施
• 使用TypeScript确保类型安全
• 危险命令保护：内置的安全系统防止影响生产环境的命令

📦 安装

前提条件

• Node.js 20+（推荐使用Node.js 22+以获得最佳性能）
• 已安装并添加到PATH中的DDEV
• 团队贡献所需的TypeScript知识

快速设置

# 全局安装
npm install -g ddev-mcp

# 或直接使用npx运行
npx ddev-mcp --help

# 验证安装
ddev-mcp --version

Node.js版本要求

• 最低：Node.js 20.0.0+
• 推荐：Node.js 22.0.0+（以获得最佳性能和最新功能）
• 检查您的版本：node --version

开发设置

git clone <repository-url>
cd ddev-mcp
npm install
npm run build
npm run dev

⚙️ 配置

MCP客户端配置

添加到您的~/.cursor/mcp.json：

{
  "mcpServers": {
    "ddev": {
      "command": "npx",
      "args": ["ddev-mcp"]
    }
  }
}

无需额外配置！服务器会自动检测您的DDEV项目。

环境变量

# 可选：设置默认项目路径
export DDEV_PROJECT_PATH="/path/to/your/ddev/project"

# 可选：配置日志级别
export DDEV_MCP_LOG_LEVEL="DEBUG"

# 安全性：允许危险命令（默认：false）
export ALLOW_DANGEROUS_COMMANDS="true"

🛡️ 危险命令保护

DDEV MCP服务器内置了针对可能影响生产环境的危险命令的保护机制：

• Platform.sh命令如environment:redeploy、environment:delete默认被阻止
• 数据库操作可能会删除数据的操作受到保护
• 文件操作可能会删除重要文件的操作受到保护

启用危险命令

要允许危险命令（谨慎使用）：

export ALLOW_DANGEROUS_COMMANDS="true"

添加新的危险命令

贡献者可以轻松地在src/config/dangerous-commands.ts中添加危险命令模式。详情见DANGEROUS_COMMANDS.md。

简单目录处理

DDEV MCP服务器基于当前工作目录原则运行：

• 从调用MCP服务器的目录运行命令
• 无需复杂的目录检测或配置
• 用户通过导航到正确的目录来控制上下文

使用模式

# 导航到您的DDEV项目
cd /path/to/your/ddev/project

# 使用AI助手运行DDEV MCP命令
# MCP服务器将在当前目录运行DDEV命令

IDE集成

当与Cursor等IDE一起使用时：

• MCP服务器继承IDE的当前工作目录
• 命令在您当前打开的项目上下文中运行
• 您可以让AI更改目录（如果需要）

目录控制

如果您需要在不同的目录中运行命令：

• 让AI：“切换到/path/to/project目录并运行ddev状态”
• 或在支持的工具参数中指定项目路径

🚀 使用示例

基本DDEV操作

"使用DDEV MCP启动ddev项目环境"
"获取我的DDEV项目的状态并显示URL"
"使用新鲜容器重启DDEV"

数据库管理

"使用DDEV MCP导入最新的生产数据库备份"
"将当前数据库导出为backup-$(date).sql.gz"
"从/path/to/dump.sql导入数据库到我的项目"

CMS特定开发

# Drupal
"使用DDEV MCP运行drush cr清除Drupal缓存"
"执行drush cex通过DDEV导出配置"

# WordPress
"使用DDEV MCP安装并激活Akismet插件"
"通过DDEV将WordPress核心更新到最新版本"

# Laravel
"使用DDEV MCP运行php artisan migrate"
"通过DDEV执行artisan cache:clear"

# Symfony
"使用DDEV MCP运行symfony console cache:clear"
"通过DDEV执行doctrine:migrations:migrate"

高级工作流程

"DDEV MCP：启动带有最新数据库的新鲜开发环境"
"DDEV MCP：启用调试模式并清除缓存以便调试"
"DDEV MCP：导入测试数据进行测试"

# 插件特定的工作流程
"DDEV MCP：清除Redis缓存并检查内存使用情况"
"DDEV MCP：创建新的Solr核心用于测试，然后查询索引内容"
"DDEV MCP：安装Playwright浏览器进行测试"

# 目录导航工作流程
"DDEV MCP：转到我在~/Projects/mysite的WordPress项目并启动它"
"DDEV MCP：导航到/home/user/drupal-site目录并检查项目状态"
"DDEV MCP：转到正确的项目文件夹并运行数据库导入"

🛠️ 可用工具

核心DDEV工具

工具	描述	关键参数
ddev_start	启动DDEV环境	projectPath, skipHooks
ddev_stop	停止DDEV环境	projectPath
ddev_restart	重启DDEV环境	projectPath
ddev_status	获取项目状态	projectPath
ddev_describe	获取详细的项目信息	projectPath
ddev_list	列出所有DDEV项目	-

数据库操作

工具	描述	关键参数
ddev_import_db	导入数据库	projectPath, src, targetDb
ddev_export_db	导出数据库	projectPath, file, compressionType
ddev_snapshot	管理数据库快照	projectPath, action, name

配置与项目管理

工具	描述	关键参数
ddev_config	配置DDEV项目	projectName, projectType, docroot, phpVersion
ddev_delete	删除项目	projectPath, projectName, omitSnapshot, yes
ddev_clean	清理DDEV项	projectPath, all, dryRun

服务管理

工具	描述	关键参数
ddev_logs	获取服务日志	projectPath, service, tail
ddev_ssh	进入容器SSH	projectPath, command, service
ddev_exec	在容器中执行命令	projectPath, command, service, workdir

文件操作

工具	描述	关键参数
ddev_import_files	导入文件目录	projectPath, src, extractPath

开发工具

工具	描述	关键参数
ddev_composer	执行Composer命令	projectPath, command, args
ddev_drush	执行Drush命令（Drupal）	projectPath, command, args
ddev_debug	运行调试命令	projectPath, command

共享与网络

工具	描述	关键参数
ddev_share	通过ngrok共享项目	projectPath, ngrokArgs
ddev_hostname	管理主机文件条目	projectPath, action, hostname

全局操作

工具	描述	关键参数
ddev_poweroff	停止所有DDEV项目	timeout
ddev_version	获取DDEV版本信息	timeout

目录导航

工具	描述	关键参数
ddev_go_to_project_directory	导航到DDEV项目目录	path, verify

插件和服务特定工具

Redis操作

工具	描述	关键参数
ddev_redis_cli	执行Redis CLI命令	projectPath, command
ddev_redis_info	获取Redis服务器信息	projectPath, section

Solr搜索引擎

工具	描述	关键参数
ddev_solr_admin	Solr管理操作	projectPath, action, core, configSet
ddev_solr_query	执行Solr搜索查询	projectPath, core, query, rows, fields

浏览器测试

工具	描述	关键参数
ddev_playwright	运行Playwright命令	projectPath, action, testFilter, browser, headed
ddev_playwright_install	安装Playwright浏览器	projectPath, browser, withDeps

CMS特定工具

Drupal工具

工具	描述	关键参数
ddev_drush	执行Drush命令	projectPath, command, args
ddev_composer	执行Composer命令	projectPath, command, args

WordPress工具

工具	描述	关键参数
ddev_wp_cli	执行WP-CLI命令	projectPath, command, args
ddev_wp_site_info	获取WordPress站点信息	projectPath

WordPress插件管理

工具	描述	关键参数
ddev_wp_plugin_install	安装WordPress插件	projectPath, plugin, activate
ddev_wp_plugin_toggle	激活/停用插件	projectPath, plugin, action
ddev_wp_plugin_list	列出WordPress插件	projectPath, status
ddev_wp_plugin_manage	综合插件管理	projectPath, action, plugin, version

WordPress主题管理

工具	描述	关键参数
ddev_wp_theme_install	安装WordPress主题	projectPath, theme, activate
ddev_wp_theme_activate	激活WordPress主题	projectPath, theme
ddev_wp_theme_manage	综合主题管理	projectPath, action, theme, version

WordPress用户与维护

工具	描述	关键参数
ddev_wp_user_manage	用户操作（创建、更新、删除、列出）	projectPath, action, user, userLogin, role
ddev_wp_core_update	更新WordPress核心	projectPath, version, force
ddev_wp_rewrite_flush	刷新重写规则	projectPath
ddev_wp_search_replace	数据库搜索/替换	projectPath, oldUrl, newUrl
ddev_wp_maintenance	缓存、计划任务和维护操作	projectPath, action, enable

可扩展架构：可以通过添加Laravel（Artisan）、Symfony（Console）、TYPO3、Magento和其他DDEV支持的框架的工具来轻松扩展。

🧪 开发与测试

构建和测试

# 构建TypeScript
npm run build

# 运行测试
npm test

# 开发模式热重载
npm run dev

# 清理构建工件
npm run clean

代码质量

• TypeScript：完全类型安全和IntelliSense支持
• ESLint：代码质量和一致性
• Jest：全面的测试覆盖率
• 日志：结构化日志记录，具有可配置的日志级别

🔧 架构

项目结构

src/
├── server/          # MCP服务器实现
│   ├── index.ts     # 主服务器类
│   └── tools.ts     # 工具定义和验证
├── ddev/            # DDEV操作
│   └── operations.ts # 核心DDEV命令实现
├── utils/           # 工具
│   ├── logger.ts    # 结构化日志记录
│   └── command.ts   # 安全命令执行
├── types/           # TypeScript定义
│   └── index.ts     # 类型定义
└── index.ts         # CLI入口点

支持的DDEV项目类型

基于DDEV CMS快速入门，此MCP服务器支持：

内容管理系统：

• Backdrop, Drupal, WordPress, TYPO3, Joomla, ProcessWire

电子商务平台：

• Magento 2, OpenMage, Shopware

PHP框架：

• Laravel, Symfony, CakePHP, Pimcore, Sulu

其他平台：

• Craft CMS, ExpressionEngine, Grav, Statamic, Silverstripe CMS, Moodle

等等！ 该架构支持通过通用命令和可扩展的CMS特定集成支持任何DDEV项目类型。

设计原则

1. 经过验证的架构：强大的错误处理和可靠的模式
2. 官方MCP SDK：使用@modelcontextprotocol/sdk以确保可靠性
3. 类型安全：完整的TypeScript实现
4. 安全性：输入验证和命令清理
5. 可观测性：全面的日志记录和错误报告

🤝 贡献

该项目旨在团队协作，采用熟悉的JavaScript/TypeScript模式：

1. 分叉和克隆：标准GitHub工作流程
2. 安装依赖：npm install
3. 进行更改：遵循现有模式
4. 测试：npm test和手动测试
5. 提交PR：附带清晰描述

编码标准

• 启用TypeScript严格模式
• 使用ESLint配置以保持一致性
• 全面的错误处理
• 新功能的单元测试
• 文档更新

📚 集成示例

开发工作流程示例

# 早晨启动例行程序
"DDEV MCP：启动开发环境并导入最新的生产数据"

# 特性开发
"DDEV MCP：启用新特性并清除缓存"

# 虫调查
"DDEV MCP：启用Xdebug并跟踪错误日志"

# 部署准备
"DDEV MCP：运行数据库更新并构建资产"

🔒 安全注意事项

Platform.sh集成安全性

ddev_platform工具包含内置的安全措施，以防止意外执行潜在破坏性的命令：

• 所需确认：所有Platform.sh命令都需要通过confirmExecution: true显式用户确认
• 生产保护：没有确认的情况下，会影响生产环境的命令被阻止
• 明确警告：详细的错误消息解释为什么命令被阻止

示例：

# 这将因安全警告而被阻止
"DDEV MCP：运行platform environment:redeploy"

# 这将执行（带有显式确认）
"DDEV MCP：运行platform environment:list with confirmExecution: true"

一般安全最佳实践

• 审查命令：始终在执行前审查DDEV命令
• 使用干跑模式：许多工具支持dryRun模式以进行安全测试
• 先备份：在执行破坏性操作之前导出数据库