Warden Magento MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with safe, structured access to Magento 2 operations within Warden environments. Each server instance is bound to a specific Warden project, eliminating confusion when working with multiple environments.

✨ Features

• 🎯 Project-specific servers: Each instance serves one Warden environment
• 🔧 Comprehensive Magento tools: Cache management, setup, deployment, indexing
• 🐳 Warden integration: Direct container execution via warden env exec
• 🏷️ Clear identification: All responses show which project was targeted
• 📊 Production logging: Winston-based logging with file rotation
• 🔒 Safe execution: Structured inputs only, no arbitrary shell access

🚀 Quick Start

Option 1: Install from npm (Recommended)

# Install globally
npm install -g mcp-warden-magento

# Or use directly with npx
npx mcp-warden-magento --warden-root /Users/yourname/Documents/GitLab/warden-envs

Option 2: Build from source

1. Install dependencies

pnpm install

2. Build the project

pnpm run build

3. Test with MCP Inspector

npx @modelcontextprotocol/inspector mcp-warden-magento --warden-root /Users/yourname/Documents/GitLab/warden-envs

Development Mode

For development with auto-reload (local terminal use only):

pnpm run dev --warden-root /Users/yourname/Documents/GitLab/warden-envs

Note: pnpm run dev outputs startup messages that break MCP Inspector's stdio protocol. Use the built version (node dist/index.js) for MCP Inspector and client configurations.

📋 Requirements

• Node.js ≥ 18
• Warden installed and services running (brew install wardenenv/warden/warden && warden svc up)
• Warden Magento 2 projects initialized (warden env-init) and started (warden env start)

⚠️ Important: Zod Compatibility

This project requires Zod 3.x for MCP SDK compatibility. If you encounter keyValidator._parse is not a function errors:

pnpm remove zod && pnpm add zod@^3.23.8
pnpm run build

🎯 Primary Supported Clients

1. Cursor IDE (Recommended)

Installation:

1. Open Cursor settings: Cmd/Ctrl + ,
2. Search for "MCP" or go to Extensions → MCP
3. Add server configurations to your workspace or user settings

Configuration Example:

{
  "mcp.servers": {
    "warden-magento": {
      "command": "npx",
      "args": ["mcp-warden-magento", "--warden-root", "/Users/yourname/Documents/GitLab/warden-envs"]
    },
    "warden-anotherwarden": {
      "command": "npx",
      "args": [
        "mcp-warden-magento",
        "--warden-root",
        "/Users/yourname/Documents/GitLab/anotherwarden/warden-envs-anotherwarden"
      ]
    }
  }
}

Alternative: Using global installation

{
  "mcp.servers": {
    "warden-magento": {
      "command": "mcp-warden-magento",
      "args": ["--warden-root", "/Users/yourname/Documents/GitLab/warden-envs"]
    }
  }
}

Usage in Cursor:

• Use @warden-magento to target the magento project
• Use @warden-anotherwarden to target the anotherwarden project
• Example: "Hey @warden-magento, clear the config cache"

2. Claude Desktop

Installation:

1. Locate your Claude Desktop config: ~/Library/Application Support/Claude/claude_desktop_config.json
2. Add MCP server entries

Configuration Example:

{
  "mcpServers": {
    "warden-magento": {
      "command": "npx",
      "args": ["mcp-warden-magento", "--warden-root", "/Users/yourname/Documents/GitLab/warden-envs"]
    },
    "warden-anotherwarden": {
      "command": "npx",
      "args": [
        "mcp-warden-magento",
        "--warden-root",
        "/Users/yourname/Documents/GitLab/anotherwarden/warden-envs-anotherwarden"
      ]
    }
  }
}

Usage in Claude Desktop:

• Restart Claude Desktop after configuration changes
• Claude will automatically detect available tools from both servers
• All responses include project identification: [magento2 @ magento2.test]

3. Claude Code (VS Code Extension)

Installation:

1. Install the Claude Code extension from VS Code marketplace
2. Configure MCP servers in VS Code settings

Configuration Example: Add to your VS Code settings.json:

{
  "claude-code.mcpServers": {
    "warden-magento": {
      "command": "npx",
      "args": ["mcp-warden-magento", "--warden-root", "/Users/yourname/Documents/GitLab/warden-envs"]
    },
    "warden-anotherwarden": {
      "command": "npx",
      "args": [
        "mcp-warden-magento",
        "--warden-root",
        "/Users/yourname/Documents/GitLab/anotherwarden/warden-envs-anotherwarden"
      ]
    }
  }
}

Usage in Claude Code:

• Use Claude Code commands to interact with Magento environments
• Each server appears as a separate MCP connection
• Project identification helps distinguish between environments

🛠️ Available Tools

Magento Operations

• magento.cacheClean — Clean Magento cache types
• magento.cacheFlush — Flush Magento cache storage
• magento.setupUpgrade — Run setup:upgrade + cache clean
• magento.diCompile — Compile dependency injection
• magento.staticDeploy — Deploy static content
• magento.indexerReindex — Reindex all indexers
• magento.modeShow / magento.modeSet — Show/set deploy mode
• magento.configSet / magento.configShow — Manage configuration

Warden Operations

• warden.exec — Execute commands in containers
• warden.varnishFlush — Clear Varnish cache
• warden.redisFlushAll — Flush Redis (use with caution)
• warden.logsTail — View recent container logs
• warden.showEnv — Display sanitized environment variables
• warden.projectInfo — Show current project information

🏗️ Multi-Project Setup

Your GitLab Layout

~/Documents/GitLab/
├──
│   ├── warden-envs/          # ← Point --warden-root here
│   ├── app/
│   └── ...
└── anotherwarden/
    ├── warden-envs-anotherwarden/  # ← Point --warden-root here
    ├── app/
    └── ...

Running Multiple Servers

# Terminal 1: magento server
npx mcp-warden-magento --warden-root /Users/yourname/Documents/GitLab/warden-envs

# Terminal 2: anotherwarden server
npx mcp-warden-magento --warden-root /Users/yourname/Documents/GitLab/anotherwarden/warden-envs-anotherwarden

# Or if installed globally:
mcp-warden-magento --warden-root /Users/yourname/Documents/GitLab/warden-envs

Benefits

• ✅ Clear server names: warden-magento-magento vs warden-magento-anotherwarden
• ✅ No parameter confusion: No need to specify project in every tool call
• ✅ Concurrent usage: Run operations on both projects simultaneously
• ✅ Project identification: All responses prefixed with [project/env @ domain]

📊 Logging

Log Levels & Environment Configuration

• Development (NODE_ENV=development): Debug-level console logging with colors (disabled automatically in MCP stdio mode)
• Production (NODE_ENV=production): Warning-level file logging with rotation

File Logging (Production)

When NODE_ENV=production or LOG_TO_FILE=true:

• logs/mcp-warden-magento.log — All logs (JSON format, 5MB rotation)
• logs/mcp-warden-magento-error.log — Error logs only

Environment Variables

• NODE_ENV — Set to production for production logging
• LOG_TO_FILE — Set to true to enable file logging in any environment
• LOG_DIR — Custom log directory (defaults to ./logs)
• MCP_STDIO_MODE — When true, disables console logging to protect MCP stdio transport

Examples

# Development with debug logging
NODE_ENV=development npx mcp-warden-magento --warden-root /path/to/warden/env

# Production with file logging
NODE_ENV=production npx mcp-warden-magento --warden-root /path/to/warden/env

# Force file logging in development
LOG_TO_FILE=true npx mcp-warden-magento --warden-root /path/to/warden/env

🔧 Development

Scripts

• pnpm run build — Compile TypeScript to dist/
• pnpm run dev — Run with tsx (development only)
• pnpm run lint — Check code style
• pnpm run format — Format code with Prettier

Testing

# Test with MCP Inspector
npx @modelcontextprotocol/inspector mcp-warden-magento --warden-root /path/to/warden/env

# Test specific tools
# In Inspector UI, try: magento.cacheClean with { "types": ["config"] }
# Or: warden.projectInfo (no parameters needed)

Automated Tests

• Unit tests (Vitest): pnpm run test:unit
• E2E tests (Playwright): pnpm run test:e2e

Notes:

• Unit tests cover env parsing/redaction, output cleaning, and input validation.
• E2E scaffolding is in place (Playwright) and ready to extend with a stubbed warden binary and an MCP stdio client.

🔒 Security

• Structured inputs only: All tools use Zod validation, no arbitrary shell execution
• Container isolation: Commands run inside Warden containers via warden env exec
• Environment validation: Server validates Warden project structure on startup
• Smart timeouts: Commands have execution timeouts (5 minutes default, 15 minutes for long operations like DI compile)
• Sanitized output: Environment variables are redacted in logs and responses

🚨 Troubleshooting

Common Issues

"keyValidator._parse is not a function"

• Install Zod 3.x: pnpm remove zod && pnpm add zod@^3.23.8

"WARDEN_ENV_NAME missing"

• Ensure you're pointing to the correct warden environment folder
• Run warden env-init in your Magento project if needed

"Command not found: warden"

• Install Warden?
• Start services: warden svc up

MCP client can't connect

• Ensure absolute paths in client configuration
• Check that the built dist/index.js file exists
• Verify Node.js ≥ 18 is installed

"Request timed out" for DI compile or static deploy

• These operations can take 10-20 minutes on large projects
• MCP Inspector: Increase timeout in Configuration → MCP_SERVER_REQUEST_TIMEOUT to 1200000 (20 minutes)
• Cursor/Claude: The server automatically extends timeouts for long operations (20 minutes for DI compile)
• If still timing out, the operation may be stuck - check Magento logs

Debug Mode

NODE_ENV=development LOG_TO_FILE=true npx mcp-warden-magento --warden-root /path/to/env
# Check logs/mcp-warden-magento.log for detailed information

📦 Publishing to npm

For maintainers:

# Test the package locally
pnpm run publish:dry

# Publish to npm (requires npm login)
npm publish

# Or publish with pnpm
pnpm publish

The prepublishOnly script will automatically run tests, linting, and build before publishing.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

For questions or issues, please open a GitHub issue with:

• Your client configuration
• Server logs (with sensitive data redacted)
• Steps to reproduce the problem