RollDev MCP Server

A Model Context Protocol (MCP) server for RollDev + Magento 2 development environments. This server enables Claude and other LLMs to interact with RollDev projects, manage environments, execute commands, and initialize new Magento 2 projects seamlessly.

Features

Environment Management

• Environment Control: List, start, and stop RollDev project environments
• Service Management: Control RollDev system services (database, Redis, OpenSearch, etc.)
• Project Initialization: Create new Magento 2 projects with automatic configuration

Development Tools

• Database Operations: Execute SQL queries directly in project databases
• PHP Script Execution: Run PHP scripts within project containers
• Magento CLI Access: Execute Magento commands through roll magento
• Composer Integration: Run Composer commands in project environments

Reliability Features

• Command Timeouts: All commands have appropriate timeouts to prevent hanging (5-15 min depending on operation)
• Output File Redirection: Option to save command output to log files for later investigation

Prerequisites

• RollDev installed and configured
• Node.js 18+
• Active RollDev project environments (for some operations)

Installation

Option 1: Using NPM (Recommended)

{
  "mcpServers": {
    "rolldev": {
      "command": "npx",
      "args": [
        "-y",
        "@disrex/rolldev-mcp-server"
      ]
    }
  }
}

Add this configuration to your Claude for Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Option 2: Manual Setup

1. Clone this repository:

git clone https://github.com/dockergiant/rolldev-mcp-server.git
cd rolldev-mcp-server

2. Install dependencies:

npm install

3. Add to Claude configuration:

{
  "mcpServers": {
    "rolldev": {
      "command": "node",
      "args": ["/path/to/rolldev-mcp-server/server.js"]
    }
  }
}

Available Tools

rolldev_list_environments

Lists all running RollDev environments with structured information including project names, paths, URLs, Docker networks, and container counts.

rolldev_start_project

Starts a RollDev project environment.

• project_path: Path to the project directory

rolldev_stop_project

Stops a RollDev project environment.

• project_path: Path to the project directory

rolldev_start_svc

Starts RollDev system services.

• project_path: Path to the project directory

rolldev_stop_svc

Stops RollDev system services.

• project_path: Path to the project directory

rolldev_db_query

Executes SQL queries in project databases.

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

rolldev_php_script

Runs PHP scripts inside project containers.

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

rolldev_magento_cli

Executes Magento CLI commands (5 minute timeout).

• project_path: Path to the project directory
• command: Magento command (without 'bin/magento' prefix)
• args: Additional arguments (optional)
• save_output_to_file: Save full output to a log file (optional, default: false)

rolldev_composer

Runs Composer commands in project environments (10 minute timeout).

• project_path: Path to the project directory
• command: Composer command (e.g., "install", "update", "require symfony/console")
• save_output_to_file: Save full output to a log file (optional, default: false)

rolldev_magento2_init

Initializes new Magento 2 projects with automatic configuration (15 minute timeout).

• project_name: Project name (lowercase, letters, numbers, hyphens only)
• magento_version: Magento version (optional, defaults to "2.4.x")
• target_directory: Target directory (optional, defaults to current directory)

Roll Inspector tools (read-only)

These tools read from Roll Inspector (https://inspector.<TRAEFIK_DOMAIN>) and never change the environment. Each takes project_path, reads ROLL_ENV_NAME, TRAEFIK_DOMAIN and ROLL_INSPECTOR the way roll does (${ROLL_HOME_DIR:-~/.roll}/.env.roll, then .env there, then the nearest project .env.roll, each overriding the one before), and accepts save_output_to_file like the tools above. Output is compact text plus a JSON block. Anything over 60,000 characters is cut off with a hint to use save_output_to_file.

Tool	Returns
rolldev_inspector_overview	Service health, warnings and their copyable fixes
rolldev_inspector_traces	Trace list with cost split per category. Filters: route, min_ms, sort, limit
rolldev_inspector_trace	Analysis of one trace id: cost per category, hot spans, repeated (N+1) calls, slowest calls. Raw spans only with include_spans, capped at 200 by self time
rolldev_inspector_hotspots	Slowest routes, most expensive operations and repeated calls across all stored traces. limit sets the rows per section
rolldev_inspector_request	Timeline entry for a url (or xid): Varnish result and the PHP, cache and search lanes. limit returns more matches, newest first
rolldev_inspector_service	section health (default) or info of kind varnish, redis, search or rabbitmq

Connection details:

• The tool connects with node:https and trusts roll's root CA from ${ROLL_SSL_DIR}/rootca/certs/ca.cert.pem. ROLL_SSL_DIR defaults to ${ROLL_HOME_DIR}/ssl and ROLL_HOME_DIR to ~/.roll, as in bin/roll. Set either variable in the MCP server's environment to override.
• Requests time out after 10 seconds.
• With ROLL_INSPECTOR unset or 0, the tool answers with the fix: set ROLL_INSPECTOR=1 in .env.roll and run roll env up.
• It reports a stopped Inspector container (roll env up), certificate problems (roll sign-certificate <domain>), an unresolvable host and a 403 from the gate in plain words.
• rolldev_inspector_trace and rolldev_inspector_hotspots need an Inspector image with the analysis and hotspots endpoints. Older images get a message to update.

Trace and hotspot answers need the project's .env.roll to have ROLL_INSPECTOR=1 and ROLL_INSPECTOR_TRACE=1. Varnish HITs have no trace, so rolldev_inspector_request finds nothing for them. User docs: roll-docker-stack/docs/inspector/api-and-extensions.md.

The logic lives in inspector.cjs, and test/inspector.test.js runs it against a fake transport.

Examples

Here are some example interactions you can try with Claude after setting up the RollDev MCP server:

Basic Environment Management

1. "Can you list all my RollDev environments?"
2. "Start the project at /path/to/my-magento-project"
3. "Stop the services for my current project"

Database Operations

4. "Run the query 'SELECT * FROM admin_user LIMIT 5' in my project"
5. "Show me all enabled modules in the database"
6. "Check the current configuration values for my store"

Magento Development

7. "Execute 'cache:flush' Magento command in my project"
8. "Run 'setup:upgrade' on my Magento installation"
9. "List all available Magento CLI commands"

Project Initialization

10. "Initialize a new Magento 2.4.7 project called 'my-store'"
11. "Create a Magento project with the latest version in /Users/dev/projects"

Composer Operations

12. "Install dependencies with Composer in my project"
13. "Require the symfony/console package in my project"

Output File Redirection

14. "Run setup:upgrade and save the output to a file for investigation"
15. "Execute composer install with output saved to a log file"

Roll Inspector

These prompts only read; no Inspector tool purges, flushes or switches anything. 16. "Why is /category-1.html slow? Check the Inspector trace" 17. "Show the Inspector hotspots for this project" 18. "Which routes in this project repeat the same SQL query (N+1)?" 19. "Is RabbitMQ healthy? Ask Inspector for the overview" 20. "Was the last request to /checkout/cart a Varnish MISS, and why?"

Development

# Start in development mode with debugging
npm run dev

# Run tests
npm test

Testing

You can test the server using the MCP Inspector:

npx @modelcontextprotocol/inspector node server.js

Contributing

1. Fork the repository from dockergiant/rolldev-mcp-server
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions:

1. Check the GitHub Issues section
2. Consult the MCP documentation at modelcontextprotocol.io
3. Open a new issue with detailed reproduction steps

---

Sponsored by