# Cloudflare MCP Tools Usage Guide

## 🚀 Quick Start

### 1. Configure Environment

```bash
# Copy and edit the environment file
cp .env.example .env

# Edit with your Cloudflare credentials
nano .env
```

**Required Credentials:**
- `CLOUDFLARE_API_TOKEN`: API token with Zone:Read, Zone:Write permissions
- `CLOUDFLARE_ACCOUNT_ID`: Your Cloudflare account ID

### 2. Load Environment

```bash
# Source the environment
source .env

# Set Python path for MCP servers
export PYTHONPATH="/Users/sovereign/work-core"
```

## 🔧 Available MCP Tools

### Cloudflare Safe MCP (`cloudflare.mcp.cloudflare_safe`)

**Tools for managing Cloudflare infrastructure:**

#### 1. Take Snapshot of Current State
```bash
python3 -c "
from cloudflare.mcp.cloudflare_safe.server import CloudflareServer
import os

# Set environment
os.environ['CLOUDFLARE_API_TOKEN'] = 'your_token'
os.environ['CLOUDFLARE_ACCOUNT_ID'] = 'your_account_id'

server = CloudflareServer()
result = server.cf_snapshot(scopes=['zones', 'tunnels', 'access_apps'])
print('Snapshot ID:', result['data']['snapshot_id'])
print('Summary:', result['summary'])
"
```

#### 2. List DNS Zones
```bash
python3 -c "
from cloudflare.mcp.cloudflare_safe.server import CloudflareServer
import os

os.environ['CLOUDFLARE_API_TOKEN'] = 'your_token'
os.environ['CLOUDFLARE_ACCOUNT_ID'] = 'your_account_id'

server = CloudflareServer()
result = server.cf_snapshot(scopes=['zones'])
zones = result['data']['counts']['zones']
print(f'Found {zones} DNS zones')
"
```

#### 3. Check Tunnel Status
```bash
python3 -c "
from cloudflare.mcp.cloudflare_safe.server import CloudflareServer
import os

os.environ['CLOUDFLARE_API_TOKEN'] = 'your_token'
os.environ['CLOUDFLARE_ACCOUNT_ID'] = 'your_account_id'

server = CloudflareServer()
result = server.cf_tunnel_status()
print('Tunnel status:', result)
"
```

### WAF Intelligence MCP (`cloudflare.mcp.waf_intelligence.mcp_server`)

**Tools for security analysis and rule generation:**

#### 1. Analyze WAF Configuration
```bash
python3 -m cloudflare.mcp.waf_intelligence.mcp_server --file terraform/waf.tf --format text
```

#### 2. Generate Security Rules
```bash
python3 -c "
from cloudflare.mcp.waf_intelligence.orchestrator import WAFIntelligence

waf_intel = WAFIntelligence()
analysis = waf_intel.analyze_and_recommend('terraform/waf.tf')
print('Security recommendations:', analysis)
"
```

## 🌐 Setting Up Domains

### 1. Configure DNS Records via Terraform

**Example DNS Configuration:**

```hcl
# terraform/dns.tf
resource "cloudflare_zone" "domains" {
  for_each = toset(["vaultmesh.org", "offsec.global"])
  
  zone = each.key
  plan = "free"
}

resource "cloudflare_record" "root_a" {
  for_each = cloudflare_zone.domains
  
  zone_id = each.value.id
  name    = "@"
  value   = "192.168.1.100"  # Your server IP
  type    = "A"
  proxied = true
}
```

### 2. Apply DNS Configuration

```bash
# Initialize Terraform
terraform init

# Plan changes
terraform plan

# Apply DNS configuration
terraform apply
```

## 🛡️ Configuring WAF Security

### 1. Basic WAF Rules

```hcl
# terraform/waf.tf
resource "cloudflare_ruleset" "security_rules" {
  for_each = cloudflare_zone.domains
  
  zone_id = each.value.id
  name    = "Security Rules"
  kind    = "zone"
  phase   = "http_request_firewall_custom"

  # Block admin access from untrusted IPs
  rules {
    action      = "block"
    expression  = "(http.request.uri.path contains '/admin') and not (ip.src in {192.168.1.1 10.0.0.1})"
    description = "Block admin access from untrusted IPs"
    enabled     = true
  }
}
```

### 2. Enable Managed WAF

```hcl
resource "cloudflare_ruleset" "managed_waf" {
  for_each = cloudflare_zone.domains
  
  zone_id = each.value.id
  name    = "Managed WAF"
  kind    = "zone"
  phase   = "http_request_firewall_managed"

  # Cloudflare Managed Ruleset
  rules {
    action = "execute"
    action_parameters {
      id = "efb7b8c949ac4650a09736fc376e9aee"
    }
    expression  = "true"
    description = "Execute Cloudflare Managed Ruleset"
    enabled     = true
  }
}
```

## 🌉 Setting Up Cloudflare Tunnels

### 1. Configure Tunnels

```hcl
# terraform/tunnels.tf
resource "cloudflare_tunnel" "vaultmesh" {
  account_id = local.account_id
  name       = "vaultmesh-tunnel"
  secret     = var.tunnel_secret_vaultmesh
}

resource "cloudflare_tunnel_config" "vaultmesh" {
  account_id = local.account_id
  tunnel_id  = cloudflare_tunnel.vaultmesh.id

  config {
    # API endpoint
    ingress_rule {
      hostname = "api.vaultmesh.org"
      service  = "http://localhost:8080"
    }
    
    # Dashboard
    ingress_rule {
      hostname = "dash.vaultmesh.org"
      service  = "http://localhost:3000"
    }
  }
}
```

### 2. Generate Tunnel Secrets

```bash
# Generate secure tunnel secrets
openssl rand -base64 32

# Add to your .env file
TUNNEL_SECRET_VAULTMESH="generated_secret_here"
```

## 🔍 Monitoring and Validation

### 1. Check Current State

```bash
# Use the invariant checker to validate configuration
python3 scripts/invariant_checker_py.py
```

### 2. Monitor Tunnel Health

```bash
# Check tunnel status via MCP
python3 -c "
from cloudflare.mcp.cloudflare_safe.server import CloudflareServer
import os

os.environ.update({
    'CLOUDFLARE_API_TOKEN': 'your_token',
    'CLOUDFLARE_ACCOUNT_ID': 'your_account_id'
})

server = CloudflareServer()
status = server.cf_tunnel_status()
print('Tunnel health:', status)
"
```

## 🚨 Common Operations

### Adding New Domain

1. **Add to Terraform zones list**
2. **Run `terraform apply`**
3. **Verify DNS propagation**
4. **Configure WAF rules**

### Updating Security Rules

1. **Modify `terraform/waf.tf`**
2. **Run `terraform plan` to preview**
3. **Apply with `terraform apply`**
4. **Validate with WAF Intelligence MCP**

### Tunnel Management

1. **Generate new tunnel secret**
2. **Update Terraform configuration**
3. **Apply changes**
4. **Verify connectivity**

## 📊 Best Practices

### Security
- Use least-privilege API tokens
- Enable 2FA on Cloudflare account
- Regular security audits with WAF Intelligence
- Monitor access logs

### Operations
- Test changes in staging first
- Use Terraform for all infrastructure changes
- Regular backups of Terraform state
- Monitor tunnel health

### Monitoring
- Set up Cloudflare analytics
- Monitor WAF rule effectiveness
- Track DNS resolution times
- Alert on security events

## 🆘 Troubleshooting

### Common Issues

**API Token Errors**
```bash
# Verify token permissions
curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
     -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```

**Tunnel Connectivity**
```bash
# Check cloudflared service status
cloudflared tunnel list
```

**DNS Issues**
```bash
# Verify DNS resolution
dig yourdomain.com
```

This guide provides the foundation for managing your Cloudflare infrastructure using the MCP tools. Start with basic DNS setup, then progressively add WAF rules and tunnels as needed.