warden-mcp-server

Warden Magento MCP Server

A comprehensive Model Context Protocol (MCP) server that provides seamless integration between AI assistants and Warden + Magento 2 development environments. This server enables AI assistants to interact directly with your Warden-managed Magento projects, automating common development tasks and providing intelligent assistance for complex workflows.

Features

This MCP server transforms your AI assistant into a powerful development companion for Warden + Magento 2 projects by providing:

• 🚀 Project Initialization: Create new Warden projects with customizable Magento 2 environments
• 🔧 Environment Management: Start/stop projects and services with intelligent state management
• 🗄️ Database Operations: Execute SQL queries directly in containerized databases
• 🐘 PHP Development Tools: Run PHP scripts in properly configured containerized environments
• 🛠️ Magento CLI Integration: Execute Magento commands seamlessly within containers
• 🧪 Unit Testing Support: Run PHPUnit tests with automatic configuration detection
• 📦 Composer Integration: Manage dependencies within containers with full command support
• 📊 Environment Monitoring: List and monitor running Warden environments

Installation

1. Clone or download this repository
2. Install dependencies:

npm install

3. Configure your MCP client (see Configuration section below)

Configuration

MCP Client Configuration

Add the following configuration to your MCP client settings:

{
  "mcpServers": {
    "warden-magento": {
      "command": "node",
      "args": ["/absolute/path/to/warden-mcp-server/server.js"],
      "env": {}
    }
  }
}

Important: Replace /absolute/path/to/warden-mcp-server/server.js with the actual absolute path to the server.js file on your system.

For Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "warden-magento": {
      "command": "node",
      "args": ["/Users/your-username/path/to/warden-mcp-server/server.js"]
    }
  }
}

For Zed Editor

Add to your Zed settings:

{
  "assistant": {
    "version": "2",
    "provider": {
      "name": "anthropic",
      "model": "claude-3-5-sonnet-20241022"
    }
  },
  "context_servers": {
    "warden-magento": {
      "command": "node",
      "args": ["/Users/your-username/path/to/warden-mcp-server/server.js"]
    }
  }
}

Usage

Once configured, your AI assistant can automatically use these tools to help with Warden + Magento development tasks. Simply describe what you want to accomplish, and the AI will use the appropriate tools.

Available Tools

Environment Management

warden_list_environments

Lists all running Warden environments with their directories and status information.

Parameters: None

Use Cases:

• Check which environments are currently running
• Get project paths for other operations
• Monitor environment status

---

warden_start_project

Starts a Warden project environment, bringing up all configured containers.

Parameters:

• project_path (required): Path to the project directory

Use Cases:

• Start development environment
• Resume work on a project
• Bring up services after system restart

---

warden_stop_project

Stops a Warden project environment, shutting down all project containers.

Parameters:

• project_path (required): Path to the project directory

Use Cases:

• Clean shutdown of development environment
• Free up system resources
• Prepare for system maintenance

---

warden_start_svc

Starts Warden system services (shared infrastructure like DNS, proxy, etc.).

Parameters:

• project_path (required): Path to the project directory

Use Cases:

• Initialize Warden infrastructure
• Start shared services after system reboot
• Prepare environment for project startup

---

warden_stop_svc

Stops Warden system services.

Parameters:

• project_path (required): Path to the project directory

Use Cases:

• Clean shutdown of Warden infrastructure
• Troubleshoot service conflicts
• System maintenance

---

Project Initialization

warden_init_project

Initializes a new Warden project with a fully configured Magento 2 environment.

Parameters:

• project_path (required): Path where the project should be initialized
• project_name (required): Name for the Warden environment
• environment_type (optional): Environment type (default: "magento2")
• php_version (optional): PHP version (default: "8.3")
• mysql_distribution (optional): MySQL distribution (default: "mariadb")
• mysql_version (optional): MySQL version (default: "10.6")
• node_version (optional): Node.js version (default: "20")
• composer_version (optional): Composer version (default: "2")
• opensearch_version (optional): OpenSearch version (default: "2.12")
• redis_version (optional): Redis version (default: "7.2")
• enable_redis (optional): Enable Redis (default: true)
• enable_opensearch (optional): Enable OpenSearch (default: true)
• enable_varnish (optional): Enable Varnish (default: true)
• enable_rabbitmq (optional): Enable RabbitMQ (default: true)
• enable_xdebug (optional): Enable Xdebug (default: true)

Use Cases:

• Set up new Magento 2 development environment
• Create project with specific PHP/MySQL versions
• Configure environment for specific requirements
• Initialize project with custom service stack

---

Database Operations

warden_db_query

Executes SQL queries directly in the Warden database container.

Parameters:

• project_path (required): Path to the project directory
• query (required): SQL query to execute
• database (optional): Database name (default: "magento")

Use Cases:

• Execute database queries for debugging
• Retrieve data for analysis
• Perform database maintenance tasks
• Check database schema or data

---

PHP Development

warden_php_script

Runs PHP scripts inside the php-fpm container with proper environment setup.

Parameters:

• project_path (required): Path to the project directory
• script_path (required): Path to the PHP script relative to project root
• args (optional): Additional arguments to pass to the script

Use Cases:

• Execute custom PHP scripts
• Run data migration scripts
• Test PHP functionality
• Execute maintenance scripts

---

Magento CLI

warden_magento_cli

Executes Magento CLI commands inside the php-fpm container.

Parameters:

• project_path (required): Path to the project directory
• command (required): Magento CLI command (without 'bin/magento' prefix)
• args (optional): Additional arguments for the command

Use Cases:

• Run cache operations (cache:clean, cache:flush)
• Execute setup commands (setup:upgrade, setup:di:compile)
• Manage configuration (config:set, config:show)
• Run indexing operations (indexer:reindex)
• Module management (module:enable, module:disable)

---

Testing

warden_run_unit_tests

Runs PHPUnit tests inside the php-fpm container with automatic configuration detection.

Parameters:

• project_path (required): Path to the project directory
• config_file (optional): PHPUnit configuration file (auto-detects phpunit.xml.dist or phpunit.xml)
• test_path (optional): Path to specific test file or directory
• extra_args (optional): Additional PHPUnit arguments

Use Cases:

• Run unit tests for modules
• Execute specific test suites
• Run tests with custom configuration
• Validate code changes with automated testing

---

Dependency Management

warden_composer

Executes Composer commands inside the php-fpm container.

Parameters:

• project_path (required): Path to the project directory
• command (required): Composer command to execute

Common Commands:

• install - Install dependencies
• update - Update dependencies
• require package/name - Add new dependency
• remove package/name - Remove dependency
• require-commerce - Install Adobe Commerce (if applicable)
• dump-autoload - Regenerate autoloader

Use Cases:

• Install project dependencies
• Add new packages to project
• Update existing dependencies
• Manage autoloading
• Install Adobe Commerce components

---

Prerequisites

• Warden: Must be installed and configured on your system
• Docker: Required for Warden to function
• Node.js: Version 18.0.0 or higher
• MCP Client: Compatible MCP client (Claude Desktop, Zed, etc.)

Troubleshooting

For issues specific to this MCP server, check:

• Server logs when running npm start
• MCP client logs for connection issues
• Docker container logs: warden env logs
• MCP Server inspector: https://github.com/modelcontextprotocol/inspector

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Related Projects

• Warden - The Docker-based development environment
• Model Context Protocol - The protocol specification
• Magento 2 - The e-commerce platform