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.

When working with Magento code with this tool enabled, good AI models will call the appropriate tools after edits. The AI knows when to clear cache, run di:compile, and run static:deploy better than most developers. This saves considerable time and eliminates context switching. It also makes accessing logs easier, which is normally a minor pain to do manually.

✨ 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