# Bizfly Cloud MCP Server

A comprehensive Model Context Protocol (MCP) server implementation that connects to Bizfly Cloud to manage cloud resources. Built using the [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go) SDK.

## Features

- 🔧 **Complete Cloud Management**: Manage servers, volumes, load balancers, databases, Kubernetes clusters, and more
- 🔒 **Secure Authentication**: Uses environment variables for credentials
- 🐳 **Docker Support**: Ready-to-use Docker image for easy deployment
- 📦 **10 Services Supported**: Server, Volume, Load Balancer, Kubernetes, Database, DNS, CDN, KMS, Container Registry, AutoScaling, and Alert services
- ✅ **Fully Tested**: Comprehensive test suite with 196+ test cases
- 🚀 **MCP Protocol**: Compatible with Cursor and Claude Desktop
- 🌐 **Multi-Region Support**: Configurable region and API endpoints

## Prerequisites

### Local Development
-   Go 1.23 or later
-   Bizfly Cloud account credentials
-   Cursor or Claude Desktop installed

### Docker Deployment
-   Docker 20.10 or later
-   Docker Compose (optional)

## Setup

### Option 1: Docker (Recommended)

1. **Clone the repository:**
   ```bash
   git clone https://github.com/your-username/bizflycloud-mcp-server.git
   cd bizflycloud-mcp-server
   ```

2. **Build the Docker image:**
   ```bash
   docker build -t bizfly-mcp-server:latest .
   ```

3. **Run the container:**
   ```bash
   docker run -it --rm \
     -e BIZFLY_USERNAME=your_username \
     -e BIZFLY_PASSWORD=your_password \
     -e BIZFLY_REGION=HaNoi \
     bizfly-mcp-server:latest
   ```

4. **Using Docker Compose:**

   Create a `.env` file:
   ```bash
   BIZFLY_USERNAME=your_username
   BIZFLY_PASSWORD=your_password
   BIZFLY_REGION=HaNoi
   BIZFLY_API_URL=https://manage.bizflycloud.vn
   ```

   Run with docker-compose:
   ```bash
   docker-compose up
   ```

### Option 2: Local Development

1. **Clone the repository:**
   ```bash
   git clone https://github.com/your-username/bizflycloud-mcp-server.git
   cd bizflycloud-mcp-server
   ```

2. **Set up environment variables:**
   ```bash
   export BIZFLY_USERNAME=your_username
   export BIZFLY_PASSWORD=your_password
   export BIZFLY_REGION=HaNoi  # Optional, defaults to HaNoi
   export BIZFLY_API_URL=https://manage.bizflycloud.vn  # Optional, defaults to https://manage.bizflycloud.vn
   ```

3. **Install dependencies:**
   ```bash
   go mod download
   ```

4. **Build the server:**
   ```bash
   go build -o bizfly-mcp-server
   ```

## Running the Server

### For Cursor/Claude Desktop Integration

1. Build the server:

    ```bash
    go build -o bizfly-mcp-server
    ```

2. Configure your MCP client (Cursor or Claude Desktop) by adding the following to the configuration:

For Cursor:

```json
{
    "mcpServers": {
        "bizfly": {
            "command": "/absolute/path/to/bizfly-mcp-server",
            "env": {
                "BIZFLY_USERNAME": "your_username",
                "BIZFLY_PASSWORD": "your_password",
                "BIZFLY_REGION": "HaNoi"
            }
        }
    }
}
```

For Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
    "mcpServers": {
        "bizfly": {
            "command": "/absolute/path/to/bizfly-mcp-server",
            "env": {
                "BIZFLY_USERNAME": "your_username",
                "BIZFLY_PASSWORD": "your_password",
                "BIZFLY_REGION": "HaNoi"
            }
        }
    }
}
```

## Available Tools

The server provides comprehensive MCP tools for managing all Bizfly Cloud services. All tool names are prefixed with `bizflycloud_` for consistency.

### 🖥️ Server Management (`bizflycloud_*`)

-   `bizflycloud_list_servers` - List all Bizfly Cloud servers
-   `bizflycloud_get_server` - Get detailed information about a server
-   `bizflycloud_start_server` - Start a stopped server
-   `bizflycloud_stop_server` - Stop a running server
-   `bizflycloud_reboot_server` - Soft reboot a server
-   `bizflycloud_hard_reboot_server` - Hard reboot a server
-   `bizflycloud_delete_server` - Delete a server
-   `bizflycloud_resize_server` - Resize a server to a different flavor
-   `bizflycloud_list_flavors` - List available server flavors

### 💾 Volume Management (`bizflycloud_*`)

-   `bizflycloud_list_volumes` - List all volumes
-   `bizflycloud_get_volume` - Get detailed information about a volume
-   `bizflycloud_create_volume` - Create a new volume
-   `bizflycloud_delete_volume` - Delete a volume
-   `bizflycloud_resize_volume` - Resize a volume
-   `bizflycloud_attach_volume` - Attach a volume to a server
-   `bizflycloud_detach_volume` - Detach a volume from a server
-   `bizflycloud_list_snapshots` - List all volume snapshots
-   `bizflycloud_create_snapshot` - Create a volume snapshot
-   `bizflycloud_delete_snapshot` - Delete a volume snapshot

### ⚖️ Load Balancer Management (`bizflycloud_*`)

-   `bizflycloud_list_loadbalancers` - List all load balancers
-   `bizflycloud_get_loadbalancer` - Get detailed information about a load balancer
-   `bizflycloud_create_loadbalancer` - Create a new load balancer
-   `bizflycloud_update_loadbalancer` - Update load balancer properties
-   `bizflycloud_delete_loadbalancer` - Delete a load balancer

### ☸️ Kubernetes Management (`bizflycloud_*`)

-   `bizflycloud_list_kubernetes_clusters` - List all Kubernetes clusters
-   `bizflycloud_get_kubernetes_cluster` - Get detailed information about a cluster
-   `bizflycloud_create_kubernetes_cluster` - Create a new Kubernetes cluster
-   `bizflycloud_delete_kubernetes_cluster` - Delete a Kubernetes cluster
-   `bizflycloud_list_kubernetes_nodes` - List nodes in a cluster/pool
-   `bizflycloud_update_kubernetes_pool` - Update worker pool configuration
-   `bizflycloud_resize_kubernetes_pool` - Resize a worker pool
-   `bizflycloud_delete_kubernetes_pool` - Delete a worker pool

### 🗄️ Database Management (`bizflycloud_*`)

-   `bizflycloud_list_databases` - List all database instances
-   `bizflycloud_list_datastores` - List available database engines and versions
-   `bizflycloud_get_database` - Get detailed information about a database
-   `bizflycloud_create_database` - Create a new database instance
-   `bizflycloud_delete_database` - Delete a database instance
-   `bizflycloud_list_database_backups` - List backups for a database instance
-   `bizflycloud_create_database_backup` - Create a backup for a database instance

### 🌐 DNS Management (`bizflycloud_*`)

-   `bizflycloud_list_dns_zones` - List all DNS zones
-   `bizflycloud_get_dns_zone` - Get detailed information about a DNS zone
-   `bizflycloud_create_dns_zone` - Create a new DNS zone
-   `bizflycloud_delete_dns_zone` - Delete a DNS zone
-   `bizflycloud_create_dns_record` - Create a DNS record (A, AAAA, CNAME, MX, SRV, TXT, NS, PTR)
-   `bizflycloud_get_dns_record` - Get detailed information about a DNS record
-   `bizflycloud_delete_dns_record` - Delete a DNS record

### 🚀 CDN Management (`bizflycloud_*`)

-   `bizflycloud_list_cdn_domains` - List all CDN domains
-   `bizflycloud_get_cdn_domain` - Get detailed information about a CDN domain
-   `bizflycloud_create_cdn_domain` - Create a new CDN domain
-   `bizflycloud_update_cdn_domain` - Update CDN domain configuration
-   `bizflycloud_delete_cdn_domain` - Delete a CDN domain
-   `bizflycloud_delete_cdn_cache` - Delete CDN cache (all or specific files)

### 🔐 KMS (Key Management Service) (`bizflycloud_*`)

-   `bizflycloud_list_kms_certificates` - List all KMS certificates
-   `bizflycloud_get_kms_certificate` - Get detailed information about a certificate
-   `bizflycloud_create_kms_certificate` - Create a new KMS certificate container
-   `bizflycloud_delete_kms_certificate` - Delete a KMS certificate

### 📦 Container Registry Management (`bizflycloud_*`)

-   `bizflycloud_list_container_registries` - List all container registries/repositories
-   `bizflycloud_create_container_registry` - Create a new repository
-   `bizflycloud_update_container_registry` - Update repository settings (e.g., public/private)
-   `bizflycloud_delete_container_registry` - Delete a repository
-   `bizflycloud_list_container_registry_tags` - List tags in a repository
-   `bizflycloud_get_container_registry_tag` - Get detailed information about a tag
-   `bizflycloud_delete_container_registry_tag` - Delete a tag

### 📈 AutoScaling Management (`bizflycloud_*`)

-   `bizflycloud_list_autoscaling_groups` - List all auto scaling groups
-   `bizflycloud_get_autoscaling_group` - Get detailed information about an auto scaling group
-   `bizflycloud_create_autoscaling_group` - Create a new auto scaling group
-   `bizflycloud_delete_autoscaling_group` - Delete an auto scaling group

### 🚨 Alert/CloudWatcher Management (`bizflycloud_*`)

-   `bizflycloud_list_alarms` - List all alarms
-   `bizflycloud_get_alarm` - Get detailed information about an alarm
-   `bizflycloud_list_receivers` - List all notification receivers
-   `bizflycloud_get_receiver` - Get detailed information about a receiver

## Docker Configuration

### Using Docker Image with Cursor/Claude Desktop

For Cursor (`~/.cursor/mcp.json`):

```json
{
    "mcpServers": {
        "bizfly": {
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "-e", "BIZFLY_USERNAME",
                "-e", "BIZFLY_PASSWORD",
                "-e", "BIZFLY_REGION",
                "bizfly-mcp-server:latest"
            ],
            "env": {
                "BIZFLY_USERNAME": "your_username",
                "BIZFLY_PASSWORD": "your_password",
                "BIZFLY_REGION": "HaNoi"
            }
        }
    }
}
```

For Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
    "mcpServers": {
        "bizfly": {
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "-e", "BIZFLY_USERNAME",
                "-e", "BIZFLY_PASSWORD",
                "-e", "BIZFLY_REGION",
                "bizfly-mcp-server:latest"
            ],
            "env": {
                "BIZFLY_USERNAME": "your_username",
                "BIZFLY_PASSWORD": "your_password",
                "BIZFLY_REGION": "HaNoi"
            }
        }
    }
}
```

## Example Usage

You can interact with the server through natural language queries in Cursor or Claude Desktop:

### Server Management
-   "Show me all my Bizfly Cloud servers"
-   "Start server server-123"
-   "Reboot the server named production-web"
-   "List available server flavors"

### Volume Management
-   "List all volumes in my Bizfly Cloud account"
-   "Create a 100GB volume named data-storage"
-   "Attach volume vol-123 to server server-456"
-   "Show me all snapshots"

### Load Balancer
-   "List all load balancers"
-   "Create a new load balancer for my web servers"

### Kubernetes
-   "List all Kubernetes clusters"
-   "Show me the nodes in cluster cluster-123"
-   "Resize the worker pool to 5 nodes"

### Database
-   "Show me all databases"
-   "Create a MySQL 8.0 database"
-   "List backups for database db-123"

### DNS
-   "List all DNS zones"
-   "Create an A record for www.example.com pointing to 1.2.3.4"
-   "Show me all records in zone example.com"

### CDN
-   "List all CDN domains"
-   "Create a CDN domain for example.com"
-   "Clear CDN cache for domain cdn-123"

### Container Registry
-   "List all container repositories"
-   "Create a public repository named my-app"
-   "Show me all tags in repository my-app"

### AutoScaling & Alerts
-   "List all auto scaling groups"
-   "Show me all alarms"
-   "List notification receivers"

## MCP Implementation Details

This server uses the [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go) SDK to implement the Model Context Protocol:

1. **Standard I/O Transport**: Uses stdin/stdout for communication with MCP clients
2. **Tool Definitions**: Clear tool descriptions and parameters
3. **Error Handling**: Proper error reporting in MCP format
4. **Text Formatting**: Human-readable output for resource listings

## Environment Variables

The server uses environment variables for configuration:

### Required Variables
-   `BIZFLY_USERNAME`: Your Bizfly Cloud username
-   `BIZFLY_PASSWORD`: Your Bizfly Cloud password

### Optional Variables
-   `BIZFLY_REGION`: Region name (defaults to "HaNoi")
  - Available regions: `HaNoi`, `HoChiMinh`, etc.
-   `BIZFLY_API_URL`: API endpoint URL (defaults to "https://manage.bizflycloud.vn")

### Security Best Practices

⚠️ **Important**: Keep your credentials secure and never commit them to version control.

1. **For Docker**: Use `.env` files or Docker secrets
   ```bash
   # .env file (add to .gitignore)
   BIZFLY_USERNAME=your_username
   BIZFLY_PASSWORD=your_password
   ```

2. **For Local Development**: Use environment variables or a `.env` file loader
   ```bash
   export BIZFLY_USERNAME=your_username
   export BIZFLY_PASSWORD=your_password
   ```

3. **For Production**: Consider using:
   - Docker secrets
   - Kubernetes secrets
   - HashiCorp Vault
   - AWS Secrets Manager / Azure Key Vault / GCP Secret Manager

## Testing

The project includes comprehensive test coverage with 196+ test cases:

```bash
# Run all tests
go test ./...

# Run tests with verbose output
go test -v ./...

# Run a specific test
go test -v ./... -run TestServerToolsRegistration

# Run tests with coverage
go test -cover ./...
```

See [TEST_COVERAGE.md](TEST_COVERAGE.md) for detailed test coverage information.

## Docker Commands

### Build the Image
```bash
docker build -t bizfly-mcp-server:latest .
```

### Run Container
```bash
docker run -it --rm \
  -e BIZFLY_USERNAME=your_username \
  -e BIZFLY_PASSWORD=your_password \
  -e BIZFLY_REGION=HaNoi \
  bizfly-mcp-server:latest
```

### Build for Specific Platform
```bash
# For ARM64 (Apple Silicon)
docker build --platform linux/arm64 -t bizfly-mcp-server:arm64 .

# For AMD64
docker build --platform linux/amd64 -t bizfly-mcp-server:amd64 .
```

### Using Docker Compose
```bash
# Start the container
docker-compose up

# Start in detached mode
docker-compose up -d

# Stop the container
docker-compose down

# View logs
docker-compose logs -f
```

## MCP Features

1. **Standard I/O Transport**: Uses stdin/stdout for seamless integration with Cursor/Claude Desktop
2. **Standardized Response Format**: All responses follow the MCP format with context, type, data, and root fields
3. **Resource Organization**: Resources are organized under root paths
4. **Type Safety**: Strong typing for all resources
5. **Error Handling**: Standardized error responses in MCP format
6. **Comprehensive Tool Coverage**: 80+ tools covering 10 Bizfly Cloud services
7. **Security**: Non-root user in Docker container, secure credential handling

## Development

### Project Structure
```
.
├── main.go                    # Entry point
├── server_tools.go           # Server management tools
├── volume_tools.go           # Volume management tools
├── loadbalancer_tools.go     # Load balancer tools
├── kubernetes_tools.go       # Kubernetes management tools
├── database_tools.go          # Database management tools
├── dns_tools.go              # DNS service tools
├── cdn_tools.go              # CDN service tools
├── kms_tools.go              # KMS service tools
├── container_registry_tools.go # Container registry tools
├── autoscaling_tools.go      # AutoScaling tools
├── alert_tools.go            # Alert/CloudWatcher tools
├── *_test.go                 # Test files
├── test_helpers.go           # Test utilities
├── Dockerfile                # Docker image definition
├── docker-compose.yml        # Docker Compose configuration
└── README.md                 # This file
```

### Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new features
5. Ensure all tests pass: `go test ./...`
6. Submit a pull request

## License

[Add your license here]

## Support

For issues, questions, or contributions, please open an issue on GitHub.