# playwright-mcp-helm

**Repository Path**: xingchiang/playwright-mcp-helm

## Basic Information

- **Project Name**: playwright-mcp-helm
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-02
- **Last Updated**: 2026-02-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Playwright MCP Kubernetes Deployment

Enterprise-grade Kubernetes deployment for [Playwright MCP](https://github.com/microsoft/playwright-mcp) - Model Context Protocol server for browser automation.

## 📋 Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Architecture](#architecture)
- [Prerequisites](#prerequisites)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Deployment](#deployment)
- [Usage](#usage)
- [Monitoring](#monitoring)
- [Security](#security)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)

## 🎯 Overview

This repository provides a complete Kubernetes deployment solution for Playwright MCP, including:

- **Helm Chart**: Production-ready Helm chart for easy deployment
- **Docker Configuration**: Optimized Dockerfile with health checks
- **Auto-scaling**: HPA configuration for elastic scaling
- **Session Management**: Cookie-based session affinity for stateful connections
- **Monitoring**: Prometheus integration ready
- **Security**: Network policies and RBAC configuration

## ✨ Features

### Core Features
- ✅ **Helm-based Deployment**: Easy install, upgrade, and rollback
- ✅ **Horizontal Pod Autoscaling**: Automatically scale based on CPU/memory
- ✅ **Session Affinity**: Cookie-based sticky sessions for MCP connections
- ✅ **Health Checks**: Liveness, readiness, and startup probes
- ✅ **Resource Management**: CPU and memory limits/requests
- ✅ **Persistent Storage**: Optional PVC for screenshots and traces
- ✅ **Multiple Environments**: Dev, staging, and production configurations

### Advanced Features
- ✅ **Prometheus Monitoring**: ServiceMonitor integration
- ✅ **Network Policies**: Control pod-to-pod communication
- ✅ **Pod Disruption Budget**: Ensure availability during updates
- ✅ **TLS Support**: HTTPS ingress configuration
- ✅ **Rate Limiting**: Built-in rate limiting support

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────┐
│                     Client Layer                        │
│  (VS Code, Claude Desktop, Custom MCP Clients)          │
└────────────────────┬────────────────────────────────────┘
                     │ HTTP/SSE
                     ▼
┌─────────────────────────────────────────────────────────┐
│                  Kubernetes Ingress                     │
│              (Nginx + Session Affinity)                  │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                  Service (ClusterIP)                    │
│              playwright-mcp-service                      │
└────────────────────┬────────────────────────────────────┘
                     │
        ┌────────────┴────────────┐
        ▼                         ▼
┌──────────────┐          ┌──────────────┐
│   Pod 1      │          │   Pod 2      │
│  Port: 8931  │  ...     │  Port: 8931  │
│              │          │              │
│ Playwright   │          │ Playwright   │
│ MCP Server   │          │ MCP Server   │
└──────────────┘          └──────────────┘
        │                         │
        └────────────┬────────────┘
                     ▼
        ┌────────────────────────┐
        │   Shared Storage       │
        │ (Screenshots, Traces)  │
        └────────────────────────┘
```

## 📦 Prerequisites

### Required Software

- **Kubernetes**: v1.24+
- **Helm**: v3.0+
- **kubectl**: Compatible with your Kubernetes cluster
- **Ingress Controller**: Nginx Ingress Controller recommended

### Required Resources

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| Nodes | 2 | 3+ |
| CPU/Node | 2 cores | 4+ cores |
| Memory/Node | 4 GiB | 8+ GiB |
| Storage | 10 GiB | 20+ GiB |

## 🚀 Quick Start

### 1. Clone Repository

```bash
git clone https://your-repo/playwright-k8s.git
cd playwright-k8s
```

### 2. Configure Environment

```bash
# Copy environment template
cp .env.example .env

# Edit with your configuration
nano .env
```

### 3. Deploy to Development

```bash
# Using deployment script
./deploy.sh dev

# Or using Make
make deploy-dev
```

### 4. Verify Deployment

```bash
# Check pod status
kubectl get pods -n playwright-mcp-dev

# Check services
kubectl get svc -n playwright-mcp-dev

# Get ingress URL
kubectl get ingress -n playwright-mcp-dev
```

## ⚙️ Configuration

### Environment Values

#### Development (`values-dev.yaml`)
```yaml
replicaCount: 2
resources:
  requests:
    cpu: 250m
    memory: 256Mi
  limits:
    cpu: 500m
    memory: 512Mi

playwright:
  logLevel: debug
  headless: false  # Allow headed for debugging
```

#### Production (`values-prod.yaml`)
```yaml
replicaCount: 5
resources:
  requests:
    cpu: 1000m
    memory: 1Gi
  limits:
    cpu: 2000m
    memory: 2Gi

playwright:
  logLevel: info
  headless: true

autoscaling:
  minReplicas: 5
  maxReplicas: 50
```

### Key Configuration Options

| Option | Description | Default |
|--------|-------------|---------|
| `replicaCount` | Initial replica count | 3 |
| `image.repository` | Container image | `mcr.microsoft.com/playwright/mcp` |
| `image.tag` | Image tag | `latest` |
| `playwright.browser` | Browser type | `chromium` |
| `playwright.headless` | Headless mode | `true` |
| `playwright.logLevel` | Logging level | `info` |
| `autoscaling.enabled` | Enable HPA | `true` |
| `ingress.enabled` | Enable ingress | `true` |

## 📤 Deployment

### Using Deployment Script

```bash
# Deploy to specific environment
./deploy.sh dev
./deploy.sh staging
./deploy.sh prod

# With custom namespace
NAMESPACE=playwright-mcp-prod ./deploy.sh prod

# With custom ingress domain
INGRESS_DOMAIN=mcp.example.com ./deploy.sh prod
```

### Using Helm Directly

```bash
# Add namespace
kubectl create namespace playwright-mcp

# Deploy with Helm
helm install playwright-mcp ./helm-playwright-mcp \
  --namespace playwright-mcp \
  --values helm-playwright-mcp/values-prod.yaml \
  --set ingress.hosts[0].host=mcp.example.com \
  --wait
```

### Using Make

```bash
# Show all targets
make help

# Deploy to development
make deploy-dev

# Deploy to production
make deploy-prod

# Check status
make status

# View logs
make logs
```

### Upgrading Deployment

```bash
# Upgrade with Helm
helm upgrade playwright-mcp ./helm-playwright-mcp \
  --namespace playwright-mcp \
  --values helm-playwright-mcp/values-prod.yaml \
  --wait

# Or using deployment script
./deploy.sh prod
```

### Rolling Back

```bash
# Using Helm
helm rollback playwright-mcp -n playwright-mcp

# Using Make
make rollback

# View history
helm history playwright-mcp -n playwright-mcp
```

## 💻 Usage

### VS Code + GitHub Copilot

Configure in your VS Code `settings.json`:

```json
{
  "github.copilot.chat.mcp.servers": {
    "playwright": {
      "url": "http://playwright-mcp.example.com/mcp",
      "type": "http"
    }
  }
}
```

### Custom Node.js Client

```javascript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { HttpClientTransport } from '@modelcontextprotocol/sdk/client/http.js';

const transport = new HttpClientTransport({
  url: 'http://playwright-mcp.example.com/mcp'
});

const client = new Client({
  name: "my-mcp-client",
  version: "1.0.0"
});

await client.connect(transport);

// Navigate to URL
const result = await client.callTool({
  name: "browser_navigate",
  arguments: { url: "https://example.com" }
});

console.log(result);
```

### Example: UI Testing

```javascript
// Test login flow
await client.callTool({
  name: "browser_navigate",
  arguments: { url: "https://your-app.com/login" }
});

await client.callTool({
  name: "browser_fill_form",
  arguments: {
    fields: [
      { name: "email", type: "textbox", ref: "email-input", value: "test@example.com" },
      { name: "password", type: "textbox", ref: "password-input", value: "password123" }
    ]
  }
});

await client.callTool({
  name: "browser_click",
  arguments: { ref: "login-button" }
});
```

## 📊 Monitoring

### Prometheus Metrics

Deploy with ServiceMonitor enabled:

```yaml
# values-prod.yaml
serviceMonitor:
  enabled: true
  interval: 30s
  labels:
    release: prometheus
```

Access metrics at: `http://playwright-mcp.example.com/metrics`

### Grafana Dashboard

Import the provided dashboard to visualize:
- Pod CPU/Memory usage
- HPA scaling events
- Request latency
- Error rates
- Active sessions

### Logging

```bash
# View logs
kubectl logs -f deployment/playwright-mcp -n playwright-mcp

# View logs from all pods
kubectl logs -f -l app.kubernetes.io/name=playwright-mcp -n playwright-mcp

# View specific pod logs
POD_NAME=$(kubectl get pods -n playwright-mcp -l app.kubernetes.io/name=playwright-mcp -o jsonpath='{.items[0].metadata.name}')
kubectl logs -f $POD_NAME -n playwright-mcp
```

## 🔒 Security

### Network Policies

Enable network policies to control traffic:

```yaml
# values-prod.yaml
networkPolicy:
  enabled: true
```

### Pod Security

```yaml
# Applied by default
podSecurityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 1000

securityContext:
  allowPrivilegeEscalation: false
  capabilities:
    drop:
    - ALL
```

### TLS/HTTPS

Configure TLS for ingress:

```yaml
# values-prod.yaml
ingress:
  tls:
    - hosts:
      - playwright-mcp.example.com
      secretName: playwright-mcp-tls
```

### RBAC

Service accounts are created with minimal required permissions.

## 🐛 Troubleshooting

### Pods Not Starting

```bash
# Check pod status
kubectl describe pod playwright-mcp-xxx -n playwright-mcp

# Common issues:
# - Image pull errors: Check imagePullSecrets
# - Resource limits: Increase node resources or adjust resource requests
# - Health check failures: Adjust probe parameters
```

### Connection Issues

```bash
# Check service and endpoints
kubectl get svc playwright-mcp -n playwright-mcp
kubectl get endpoints playwright-mcp -n playwright-mcp

# Check ingress
kubectl describe ingress playwright-mcp -n playwright-mcp

# Test service locally
kubectl port-forward -n playwright-mcp deployment/playwright-mcp 8931:8931
curl http://localhost:8931/health
```

### Session Affinity Issues

```bash
# Verify ingress annotations
kubectl get ingress playwright-mcp -n playwright-mcp -o yaml | grep -A 5 affinity

# Should contain:
# nginx.ingress.kubernetes.io/affinity: "cookie"
# nginx.ingress.kubernetes.io/session-cookie-name: "playwright-session"
```

### Scaling Issues

```bash
# Check HPA status
kubectl get hpa -n playwright-mcp

# Describe HPA for more details
kubectl describe hpa playwright-mcp -n playwright-mcp

# Check resource usage
kubectl top pods -n playwright-mcp
```

## 🔧 Maintenance

### Backup Configuration

```bash
# Backup Helm values
helm get values playwright-mcp -n playwright-mcp > playwright-mcp-backup.yaml

# Backup persistent data (if enabled)
kubectl get pvc -n playwright-mcp
```

### Disaster Recovery

```bash
# Rollback to previous release
helm rollback playwright-mcp -n playwright-mcp

# Restore from backup
helm upgrade playwright-mcp ./helm-playwright-mcp \
  -n playwright-mcp \
  --values playwright-mcp-backup.yaml
```

### Upgrading Chart

```bash
# Pull latest changes
git pull origin main

# Upgrade deployment
helm upgrade playwright-mcp ./helm-playwright-mcp \
  --namespace playwright-mcp \
  --values helm-playwright-mcp/values-prod.yaml \
  --wait
```

## 🤝 Contributing

Contributions are welcome! Please follow these steps:

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

### Development Setup

```bash
# Clone repository
git clone https://github.com/your-org/playwright-k8s.git
cd playwright-k8s

# Run tests
make test

# Lint Helm chart
make lint

# Dry-run deployment
make dry-run
```

## 📝 License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Microsoft Playwright MCP](https://github.com/microsoft/playwright-mcp) - The underlying MCP server
- [Playwright](https://playwright.dev/) - Browser automation framework
- [Helm](https://helm.sh/) - Kubernetes package manager

## 📧 Support

For support and questions:
- GitHub Issues: [Create an issue](https://github.com/your-org/playwright-k8s/issues)
- Email: devops@example.com
- Documentation: [Full documentation](https://your-docs-site.com)

## 🔗 Links

- [Playwright MCP Official Repository](https://github.com/microsoft/playwright-mcp)
- [Playwright Documentation](https://playwright.dev/)
- [Kubernetes Documentation](https://kubernetes.io/docs/)
- [Helm Documentation](https://helm.sh/docs/)

---

Made with ❤️ by the DevOps Team