StackWiz MCP Tool Reference¶

This document provides detailed documentation for all tools available in StackWiz MCP.

Available Tools¶

1. create_stack¶

Creates a new Docker service stack with automatic Traefik integration.

Parameters¶

Parameter	Type	Required	Default	Description
`name`	string	Yes	-	Stack identifier (lowercase, alphanumeric + hyphens)
`type`	string	No	"generic"	Stack type: "generic" or "pocketbase"
`domain`	string	No	Auto-generated	Full domain for the service
`image`	string	Yes*	-	Docker image (*required for generic type)
`port`	integer	Yes*	-	Container port (*required for generic type)
`create_dns`	boolean	No	false	Automatically create DNS record
`auto_start`	boolean	No	true	Start service after creation
`environment`	object	No	{}	Environment variables
`volumes`	array	No	[]	Volume mappings
`labels`	object	No	{}	Additional Docker labels
`networks`	array	No	["traefik_proxy"]	Docker networks
`restart_policy`	string	No	"unless-stopped"	Restart policy
`resources`	object	No	{}	Resource limits (memory, cpu)

Examples¶

Basic Generic Service:

{
  "name": "grafana",
  "type": "generic",
  "image": "grafana/grafana:latest",
  "port": 3000,
  "create_dns": true
}

Service with Environment Variables:

{
  "name": "postgres",
  "type": "generic",
  "image": "postgres:15",
  "port": 5432,
  "environment": {
    "POSTGRES_DB": "myapp",
    "POSTGRES_USER": "appuser",
    "POSTGRES_PASSWORD": "secure_password"
  },
  "volumes": [
    "./data:/var/lib/postgresql/data"
  ]
}

Pocketbase Application:

{
  "name": "todo-app",
  "type": "pocketbase",
  "create_dns": true,
  "environment": {
    "PB_ENCRYPTION_KEY": "your-encryption-key"
  }
}

Service with Resource Limits:

{
  "name": "redis",
  "type": "generic",
  "image": "redis:7-alpine",
  "port": 6379,
  "resources": {
    "memory": "512M",
    "cpus": "0.5"
  }
}

Response¶

{
  "success": true,
  "stack_name": "grafana",
  "path": "/srv/dockerdata/grafana",
  "url": "https://grafana.rbnk.uk",
  "status": "running",
  "message": "Stack created and started successfully"
}

2. list_stacks¶

Lists all Docker stacks in the infrastructure.

Parameters¶

Parameter	Type	Required	Default	Description
`filter`	string	No	""	Filter stacks by name (partial match)
`include_status`	boolean	No	true	Include container status
`sort_by`	string	No	"name"	Sort by: "name", "created", "status"
`include_resources`	boolean	No	false	Include resource usage
`format`	string	No	"detailed"	Output format: "detailed", "summary"

Examples¶

List All Stacks:

{
  "include_status": true
}

Filter and Sort:

{
  "filter": "app",
  "sort_by": "created",
  "include_resources": true
}

Response¶

{
  "stacks": [
    {
      "name": "grafana",
      "path": "/srv/dockerdata/grafana",
      "status": "running",
      "created": "2024-01-15T10:30:00Z",
      "services": [
        {
          "name": "grafana",
          "image": "grafana/grafana:latest",
          "status": "healthy",
          "ports": ["3000:3000"],
          "url": "https://grafana.rbnk.uk"
        }
      ],
      "resources": {
        "cpu_percent": "2.5",
        "memory_usage": "256MB",
        "memory_limit": "512MB"
      }
    }
  ],
  "total": 1
}

3. manage_stack¶

Performs operations on existing stacks.

Parameters¶

Parameter	Type	Required	Default	Description
`stack_name`	string	Yes	-	Name of the stack to manage
`action`	string	Yes	-	Action: "start", "stop", "restart", "remove", "logs"
`options`	object	No	{}	Additional options for the action

Action-Specific Options¶

For "logs" action: - follow: boolean (default: false) - Follow log output - tail: integer (default: 50) - Number of lines to show - since: string - Show logs since timestamp - service: string - Specific service to show logs for

For "remove" action: - force: boolean (default: false) - Force removal - remove_volumes: boolean (default: false) - Remove associated volumes

Examples¶

Start a Stack:

{
  "stack_name": "grafana",
  "action": "start"
}

View Logs:

{
  "stack_name": "postgres",
  "action": "logs",
  "options": {
    "tail": 100,
    "follow": true,
    "service": "postgres"
  }
}

Remove Stack:

{
  "stack_name": "test-app",
  "action": "remove",
  "options": {
    "force": true,
    "remove_volumes": true
  }
}

Response¶

{
  "success": true,
  "action": "restart",
  "stack_name": "grafana",
  "message": "Stack restarted successfully",
  "output": "Container grafana restarted"
}

4. create_dns_record¶

Creates DNS records in Cloudflare with automatic retry and rate limit handling.

Parameters¶

Parameter	Type	Required	Default	Description
`subdomain`	string	Yes	-	Subdomain to create (e.g., "api", "www")
`type`	string	No	"A"	Record type: A, AAAA, CNAME, TXT, MX
`value`	string	No	"AUTO"	Record value (AUTO for server IP)
`proxied`	boolean	No	true	Enable Cloudflare proxy
`priority`	integer	No*	-	*Required for MX records

Examples¶

Basic A Record:

{
  "subdomain": "api",
  "proxied": true
}

CNAME Record:

{
  "subdomain": "www",
  "type": "CNAME",
  "value": "rbnk.uk"
}

MX Record:

{
  "subdomain": "@",
  "type": "MX",
  "value": "mail.example.com",
  "priority": 10,
  "proxied": false
}

Response¶

{
  "success": true,
  "message": "DNS record created for api.rbnk.uk",
  "details": {
    "subdomain": "api",
    "full_domain": "api.rbnk.uk",
    "type": "A",
    "target": "157.180.63.15",
    "proxied": true,
    "record_id": "abc123..."
  }
}

5. list_dns_records¶

Lists DNS records from Cloudflare with optional filtering.

Parameters¶

Parameter	Type	Required	Default	Description
`filter`	string	No	""	Filter records by name (partial match)

Examples¶

List All Records:

{}

Filter by Subdomain:

{
  "filter": "api"
}

Response¶

{
  "success": true,
  "records": [
    {
      "id": "abc123...",
      "type": "A",
      "name": "api.rbnk.uk",
      "content": "157.180.63.15",
      "proxied": true,
      "ttl": 1,
      "created_on": "2025-01-15T10:30:00Z",
      "modified_on": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

6. update_dns_proxy¶

Enables or disables Cloudflare proxy (orange/gray cloud) for a DNS record.

Parameters¶

Parameter	Type	Required	Default	Description
`subdomain`	string	Yes	-	Subdomain to update
`enable`	boolean	Yes	-	true=proxied (orange), false=DNS-only (gray)

Examples¶

Enable Proxy (Orange Cloud):

{
  "subdomain": "api",
  "enable": true
}

Disable Proxy (Gray Cloud - DNS Only):

{
  "subdomain": "api",
  "enable": false
}

Response¶

{
  "success": true,
  "message": "Cloudflare proxy enabled for api.rbnk.uk",
  "details": {
    "subdomain": "api",
    "full_domain": "api.rbnk.uk",
    "type": "A",
    "proxied": true,
    "record_id": "abc123..."
  }
}

Use Cases¶

Disable proxy when experiencing POST request timeouts (504 errors) on auth flows
Enable proxy for DDoS protection and CDN benefits
Only works on A, AAAA, and CNAME records (Cloudflare limitation)

7. delete_dns_record¶

Deletes DNS records from Cloudflare.

Parameters¶

Parameter	Type	Required	Default	Description
`subdomain`	string	Yes	-	Subdomain to delete

Examples¶

Delete a Record:

{
  "subdomain": "old-service"
}

Response¶

{
  "success": true,
  "message": "Deleted 1 DNS record(s) for old-service.rbnk.uk",
  "details": {
    "subdomain": "old-service",
    "full_domain": "old-service.rbnk.uk",
    "records_deleted": 1
  }
}

Notes¶

Deletes ALL record types for the specified subdomain
If multiple records exist (e.g., A and AAAA), all are deleted
Returns count of deleted records

8. validate_stack_config¶

Validates a stack configuration before creation.

Parameters¶

Parameter	Type	Required	Default	Description
`config`	object	Yes	-	Stack configuration to validate
`check_conflicts`	boolean	No	true	Check for port/domain conflicts
`check_image`	boolean	No	true	Verify Docker image exists
`strict`	boolean	No	false	Enable strict validation

Examples¶

Validate Configuration:

{
  "config": {
    "name": "webapp",
    "type": "generic",
    "image": "nginx:latest",
    "port": 80
  },
  "check_conflicts": true
}

Response¶

{
  "valid": true,
  "errors": [],
  "warnings": [
    "Port 80 is commonly used, consider using a different port"
  ],
  "suggestions": [
    "Consider adding environment variables for configuration",
    "Add volume mounts for persistent data"
  ]
}

Resources¶

StackWiz MCP also provides read-only resources:

Stack Resources¶

stack://list - List all stack names
stack://{name}/compose - Get docker-compose.yml content
stack://{name}/config - Get stack configuration
stack://{name}/status - Get detailed status

Template Resources¶

template://generic - Generic service template
template://pocketbase - Pocketbase stack template
template://list - List all available templates

Infrastructure Resources¶

infra://networks - List Docker networks
infra://domains - List configured domains
infra://images - List available Docker images
infra://volumes - List Docker volumes

Error Handling¶

All tools return consistent error responses:

{
  "success": false,
  "error": {
    "code": "STACK_EXISTS",
    "message": "Stack 'grafana' already exists",
    "details": "Use a different name or remove the existing stack",
    "suggestion": "Try 'grafana-dev' or run 'manage_stack' with action 'remove'"
  }
}

Common Error Codes¶

Code	Description	Common Causes
`STACK_EXISTS`	Stack name already in use	Duplicate stack name
`INVALID_NAME`	Invalid stack name	Special characters, uppercase
`PORT_CONFLICT`	Port already in use	Another service using port
`DOCKER_ERROR`	Docker operation failed	Docker daemon issues
`PERMISSION_DENIED`	Insufficient permissions	User not in docker group
`IMAGE_NOT_FOUND`	Docker image not found	Typo or private registry
`NETWORK_ERROR`	Network operation failed	Network doesn't exist
`DNS_ERROR`	DNS operation failed	Invalid credentials or zone not found
`DNS_RATE_LIMIT`	Cloudflare rate limit hit	Too many API requests (auto-retry enabled)
`DNS_NOT_FOUND`	DNS record not found	Record doesn't exist for subdomain
`VALIDATION_ERROR`	Configuration invalid	Missing required fields

Best Practices¶

1. Always Validate First¶

Before creating a stack, validate the configuration:

# Validate
result = validate_stack_config({
    "config": my_config,
    "check_conflicts": True
})

if result["valid"]:
    # Create stack
    create_stack(my_config)

2. Use Meaningful Names¶

Use descriptive names: analytics-api, not api
Include environment: redis-dev, redis-prod
Follow naming convention: lowercase, alphanumeric, hyphens

3. Handle Errors Gracefully¶

Always check the success field and handle errors:

result = create_stack(config)
if not result["success"]:
    print(f"Error: {result['error']['message']}")
    print(f"Suggestion: {result['error']['suggestion']}")

4. Resource Management¶

Set resource limits for production services
Monitor resource usage with list_stacks
Clean up unused stacks with manage_stack

5. Security Considerations¶

Always use strong passwords for databases
Enable Cloudflare proxy for public services
Use environment variables for sensitive data
Regularly update Docker images

Integration Examples¶

Python Script¶

import requests

# StackWiz MCP client example
class StackWizClient:
    def __init__(self, base_url="http://localhost:8765"):
        self.base_url = base_url

    def create_stack(self, config):
        response = requests.post(
            f"{self.base_url}/tools/create_stack",
            json=config
        )
        return response.json()

    def list_stacks(self, filter=""):
        response = requests.post(
            f"{self.base_url}/tools/list_stacks",
            json={"filter": filter}
        )
        return response.json()

# Usage
client = StackWizClient()
result = client.create_stack({
    "name": "my-app",
    "type": "generic",
    "image": "nginx:latest",
    "port": 80
})

Shell Script¶

#!/bin/bash

# Create a stack using curl
curl -X POST http://localhost:8765/tools/create_stack \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nginx-test",
    "type": "generic",
    "image": "nginx:latest",
    "port": 80,
    "create_dns": true
  }'

Next Steps¶

Examples - See real-world usage examples
Development Guide - Extend StackWiz MCP
Troubleshooting - Common issues and solutions