mcp-warden-magento/README.md

A Model Context Protocol (MCP) server for Magento 2 operations within Warden environments

# 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)

```bash
# 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**

```bash
pnpm install
```

2. **Build the project**

```bash
pnpm run build
```

3. **Test with MCP Inspector**

```bash
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):

```bash
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:

```bash
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:**

```json
{
  "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**

```json
{
  "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:**

```json
{
  "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`:

```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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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:

```bash
# 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