Cloud Manage MCP Server

🚀 Cloud Manage MCP Server

A cloud management server based on MCP (Model Context Protocol), supporting the retrieval of cloud server information via public IP addresses.

🚀 Quick Start

Dependency Installation

pip install -r requirements.txt

Environment Variable Configuration

Create a .env file and set the following environment variables:

# DigitalOcean API Token
# Obtain it at https://cloud.digitalocean.com/account/api/tokens
DIGITALOCEAN_TOKEN=your_digitalocean_api_token_here

# IPInfo API Token (Optional, for IP address queries)
# Obtain it at https://ipinfo.io/account/token
IPINFO_API_TOKEN=your_ipinfo_api_token_here

# Deletion function control (Highly not recommended to enable)
# ALLOW_DROPLET_DELETION=false  # Default value, recommended to keep disabled

Starting the Server

python main.py

✨ Features

• Identify Cloud Service Providers: Support identifying cloud service providers via public IP addresses.
• Retrieve Droplet Details: Use the pydo SDK to get detailed information about DigitalOcean droplets.
• Droplet Power Management: Power on, power off, restart, and gracefully shut down droplets.
• Status Monitoring: Obtain the current status and resource usage of droplets.
• Operation History: View the operation history of droplets.
• Batch Management: List all droplets and search by name.
• Monitoring Data: Get CPU, memory, disk, and network usage (monitoring needs to be enabled).
• Deletion Protection: Multiple security mechanisms to prevent accidental deletion of important servers.
• AWS Support (To be Implemented): Future support for AWS is planned.

🔒 Security Features

🛡️ Deletion Protection Mechanism

To prevent accidental deletion of important droplets, the system implements a strict five - layer security protection:

Protection Levels

1. Global Switch Protection: All deletion operations are disabled by default.
2. Confirmation Code Protection: A specific confirmation code is required to attempt deletion.
3. Status Check Protection: Deletion of running droplets is prohibited.
4. Tag Protection: Automatically identify and protect important droplets.
5. Final Security Check: Even if the previous checks are passed, actual deletion is still disabled.

Protected Tags

The system will automatically protect droplets with the following tags:

• production / prod
• important
• critical
• backup

Configuration Method

# By default, the deletion function is completely disabled.
# If you need to enable it (highly not recommended), set the environment variable:
export ALLOW_DROPLET_DELETION=true

⚠️ Important Note

Even if the deletion function is enabled, all actual deletion operations will still be blocked by the final security check. It is recommended to always manually delete droplets through the DigitalOcean control panel.

💻 Usage Examples

Basic Usage

# List all droplets
result = list_droplets()
print(f"Total number of droplets: {result['total_droplets']}")

# Find a droplet by a specific name
result = find_droplet_by_name("web-server")
if result['found']:
    droplet = result['droplets'][0]
    droplet_id = droplet['id']

    # Get detailed status
    status = get_droplet_status(droplet_id)
    print(f"Droplet status: {status['status']}")

    # Reboot the droplet
    if status['status'] == 'active':
        action_result = reboot_droplet(droplet_id)
        action_id = action_result['action']['id']

        # Check the operation status
        action_status = get_action_status(action_id)
        print(f"Reboot operation status: {action_status['action']['status']}")

Deletion Safety Check Example

# Check the deletion policy
policy = get_droplet_deletion_policy()
print(f"Deletion function status: {policy['deletion_policy']['current_status']}")

# Check the deletion safety of a specific droplet
safety_check = check_droplet_deletion_safety(droplet_id)
print(f"Safety level: {safety_check['safety_level']}")

# View the details of the safety check
for check in safety_check['safety_checks']:
    print(f"{check['check']}: {check['status']} - {check['message']}")

# Try to delete (will be blocked by the security mechanism)
deletion_result = delete_droplet_with_protection(droplet_id, "CONFIRM_DELETE_DROPLET")
if deletion_result.get('error'):
    print(f"Deletion blocked: {deletion_result['error']}")

Monitoring Data Retrieval Example

# Get monitoring data
monitoring_result = get_droplet_monitoring(droplet_id)
if monitoring_result['monitoring_enabled']:
    metrics = monitoring_result['metrics']

    for metric_type, data in metrics.items():
        if data['available']:
            print(f"{metric_type} monitoring data is available")
        else:
            print(f"No data available for {metric_type}")
else:
    print("Please enable the monitoring function in the DigitalOcean control panel first")

📚 Documentation

Available MCP Tool Functions

Basic Query Functions

• get_dg_info(ipv4_address: str): Retrieve information about the corresponding DigitalOcean droplet based on the public IP address.
  • Parameters:
    • ipv4_address (str): The public IP address to query.
• list_droplets(): List all DigitalOcean droplets under the account.
• find_droplet_by_name(name: str): Find a DigitalOcean droplet by name (supports fuzzy matching).
  • Parameters:
    • name (str): The name or partial name of the droplet.
• get_droplet_status(droplet_id: int): Get the current status and detailed information of a specified droplet.
  • Parameters:
    • droplet_id (int): The ID of the droplet.

Power Management Functions

• power_on_droplet(droplet_id: int): Power on the specified droplet.
• power_off_droplet(droplet_id: int): Force - shut down the specified droplet (similar to pulling the power cord).
• shutdown_droplet(droplet_id: int): Gracefully shut down the specified droplet (similar to the system shutdown command).
• reboot_droplet(droplet_id: int): Reboot the specified droplet.
  • Parameters:
    • droplet_id (int): The ID of the droplet to operate on.

Monitoring and History Functions

• get_droplet_monitoring(droplet_id: int): Get the monitoring data of a droplet, including CPU, memory, disk, and network usage.
  • Note: The monitoring function needs to be enabled on the droplet.
• get_droplet_actions(droplet_id: int): Get the operation history of a specified droplet.
• get_action_status(action_id: int): Query the status of a specific operation (useful for tracking the progress after a power operation).
  • Parameters:
    • droplet_id (int): The ID of the droplet.
    • action_id (int): The ID of the operation.

Deletion Protection Functions

• delete_droplet_with_protection(droplet_id: int, confirmation_code: str = ""): Delete a DigitalOcean droplet (with strict security protection).
  • Note: This function has multiple security restrictions and is actually designed to block deletion operations.
  • Parameters:
    • droplet_id (int): The ID of the droplet to delete.
    • confirmation_code (str): The confirmation code (must be "CONFIRM_DELETE_DROPLET").
• get_droplet_deletion_policy(): Get the current deletion policy and security configuration information.
• check_droplet_deletion_safety(droplet_id: int): Check the deletion safety of a specified droplet (without actually deleting it).
  • Parameters:
    • droplet_id (int): The ID of the droplet to check.

Return Value Explanation

Successful Response Examples

• Deletion Safety Check:

{
    "cloud_provider": "digitalocean",
    "droplet_id": 123456789,
    "droplet_name": "web-server-01",
    "overall_safety": "BLOCKED",
    "safety_level": "Deletion blocked",
    "safety_checks": [
        {
            "check": "Global deletion policy",
            "status": "BLOCKED",
            "message": "The deletion function is globally disabled"
        },
        {
            "check": "Droplet status",
            "status": "WARNING",
            "message": "The droplet is running (active). It is recommended to shut it down first"
        },
        {
            "check": "Protected tags",
            "status": "BLOCKED",
            "message": "Protected tag found: production"
        }
    ],
    "warnings": [
        "This droplet has a protected tag, indicating that it may be an important server"
    ],
    "summary": {
        "total_checks": 5,
        "blocked": 2,
        "warnings": 1,
        "passed": 2
    }
}

• Deletion Policy Information:

{
    "cloud_provider": "digitalocean",
    "deletion_policy": {
        "enabled": false,
        "protection_level": "MAXIMUM",
        "current_status": "All deletion operations are disabled",
        "safety_checks": [
            "The environment variable ALLOW_DROPLET_DELETION must be set to true",
            "The correct confirmation code 'CONFIRM_DELETE_DROPLET' must be provided",
            "The droplet must be in the shutdown state",
            "The droplet cannot have protected tags",
            "Multiple confirmation mechanisms"
        ],
        "protected_tags": ["production", "prod", "important", "critical", "backup"]
    },
    "security_info": {
        "philosophy": "Safety first, prevent accidental deletion of important servers",
        "recommendation": "It is highly recommended to manually delete droplets through the DigitalOcean control panel"
    }
}

• Successful Droplet Operation:

{
    "cloud_provider": "digitalocean",
    "droplet_id": 123456789,
    "action": {
        "id": 987654321,
        "status": "in-progress",
        "type": "reboot",
        "started_at": "2024-01-01T12:00:00Z",
        "completed_at": null,
        "resource_id": 123456789,
        "resource_type": "droplet",
        "region": "New York 3"
    },
    "message": "The reboot operation has been successfully submitted. Operation ID: 987654321"
}

• Droplet Status Query:

{
    "cloud_provider": "digitalocean",
    "droplet_id": 123456789,
    "status": "active",
    "name": "web-server-01",
    "locked": false,
    "size_slug": "s-1vcpu-1gb",
    "memory": 1024,
    "vcpus": 1,
    "disk": 25,
    "region": {
        "name": "New York 3",
        "slug": "nyc3"
    },
    "image": {
        "name": "Ubuntu 20.04 x64",
        "distribution": "Ubuntu"
    },
    "created_at": "2024-01-01T10:00:00Z",
    "features": ["monitoring", "ipv6"],
    "tags": ["web", "production"]
}

• Monitoring Data Response:

{
    "cloud_provider": "digitalocean",
    "droplet_id": 123456789,
    "monitoring_enabled": true,
    "metrics": {
        "cpu": {
            "available": true,
            "data": [...]
        },
        "memory": {
            "available": true,
            "data": [...]
        },
        "disk": {
            "available": false,
            "data": []
        },
        "network": {
            "available": true,
            "data": [...]
        }
    },
    "note": "Monitoring data may take a few minutes to appear on newly enabled droplets."
}

Error Response Examples

• Deletion Operation Blocked:

{
    "cloud_provider": "digitalocean",
    "error": "The deletion operation is disabled. For security reasons, all droplet deletion operations are restricted.",
    "security_info": {
        "protection_level": "MAXIMUM",
        "reason": "Prevent accidental deletion of important servers",
        "how_to_enable": "Set the environment variable ALLOW_DROPLET_DELETION=true (not recommended)"
    }
}

• General Error:

{
    "cloud_provider": "digitalocean",
    "error": "Droplet with ID 123456789 not found"
}

API Explanation

pydo SDK Integration

This project uses the official pydo SDK to interact with the DigitalOcean API:

1. Install pydo: pip install pydo
2. Configure the API Token: Set the DIGITALOCEAN_TOKEN environment variable.
3. Call the API: Use client.droplets.list() to get all droplets.

Working Principle

1. Initialize the pydo client with the configured API token.
2. Call client.droplets.list() to get all droplets under the account.
3. Iterate through the network configuration of each droplet.
4. Find the droplet that matches the specified public IP address.
5. Return the detailed information of the found droplet.

🔧 Technical Details

Testing Function

The project includes a complete test script test_dg_info.py that can test all functions:

python test_dg_info.py

The test script includes the following test modules:

• Basic Function Testing: List droplets, test API connection.
• Droplet Operation Testing: Query status, power management, operation history.
• Monitoring Function Testing: Retrieve monitoring data and check availability.
• Deletion Protection Testing: Check security policies, evaluate deletion safety.
• IP Search Testing: Find the corresponding droplet based on the IP address.

Precautions

Security - Related

1. Deletion Protection:
   • All deletion operations are disabled by default to prevent accidental deletion.
   • Multiple security check mechanisms protect important servers.
   • Even if deletion is configured to be allowed, actual deletion is still blocked by the final security check.
   • It is highly recommended to manually delete through the DigitalOcean control panel.
2. API Permissions: Ensure that your DigitalOcean API token has the appropriate permissions:
   • Permission to read droplets.
   • Permission to perform droplet operations (power on/off, reboot, etc.).
   • Permission to access monitoring data.
3. Monitoring Function Limitations:
   • The monitoring function needs to be enabled on the droplet (either at creation or later in the control panel).
   • Monitoring data may take a few minutes to appear.
   • The free monitoring function collects data points every 5 minutes.
4. API Call Limitations:
   • The DigitalOcean API has a rate limit (5,000 requests per hour).
   • Power operations are asynchronous, and the operation status needs to be queried to confirm completion.
5. Security Considerations:
   • Keep your API token safe.
   • It is recommended to use environment variables to store sensitive information.
   • Limit the permission scope of the API token in the production environment.
   • Avoid enabling the deletion function in automated scripts.

Operation Status Explanation

• Possible Droplet States:
  • new: Newly created, initializing.
  • active: Running.
  • off: Shut down.
  • archive: Archived (long - term shutdown).
• Operation States:
  • in - progress: In execution.
  • completed: Completed.
  • errored: Execution failed.
• Deletion Safety Levels:
  • BLOCKED: Deletion is blocked (severe security issues).
  • WARNING: Requires careful consideration (potential risks).
  • CAUTION: Can be deleted but needs confirmation (still restricted).

Best Practices

1. Safe Operations:
   • Avoid enabling the deletion function and always manually delete through the control panel.
   • Regularly use check_droplet_deletion_safety() to evaluate server safety.
   • Add protected tags to important servers.
2. Batch Operations: Use list_droplets() to get all droplets and then filter and operate as needed.
3. Status Check: Check the current status of the droplet before performing power operations.
4. Operation Tracking: Save the operation ID for subsequent status queries.
5. Error Handling: Always check the error field in the return result.
6. Monitoring Enablement: Enable the monitoring function when creating a droplet to obtain usage data later.

Error Handling

• Automatically detect if the pydo SDK is installed.
• Verify if the DIGITALOCEAN_TOKEN environment variable is configured.
• Capture API call exceptions and return friendly error messages.
• Provide detailed debugging information.

Precautions

1. Ensure that your DigitalOcean API token has the permission to read droplets.
2. The API has a call frequency limit, so use it reasonably.
3. This function will list all droplets under the account, so ensure the security of the token.

Extended Features

• Support filtering droplets by tags.
• Support paginated queries for a large number of droplets.
• Cache query results to improve performance.
• Support other cloud service providers (AWS, GCP, etc.).