Cloud Manage MCP Server

🚀 雲管理 MCP 服務器

這是一個基於 MCP（模型上下文協議）的雲管理服務器，支持通過公網 IP 地址獲取雲服務器信息，為雲服務器管理提供便捷解決方案。

🚀 快速開始

依賴安裝

pip install -r requirements.txt

環境變量配置

創建 .env 文件並設置以下環境變量：

# DigitalOcean API Token
# 在 https://cloud.digitalocean.com/account/api/tokens 獲取
DIGITALOCEAN_TOKEN=your_digitalocean_api_token_here

# IPInfo API Token (可選，用於IP地址查詢)
# 在 https://ipinfo.io/account/token 獲取
IPINFO_API_TOKEN=your_ipinfo_api_token_here

# 刪除功能控制 (強烈不推薦啟用)
# ALLOW_DROPLET_DELETION=false  # 默認值，建議保持禁用

啟動服務器

python main.py

✨ 主要特性

• 雲服務提供商識別：支持通過公網 IP 地址識別雲服務提供商。
• Droplet 信息獲取：使用 pydo SDK 獲取 DigitalOcean droplet 詳細信息。
• Droplet 電源管理：支持開機、關機、重啟、優雅關機操作。
• 狀態監控：可獲取 droplet 當前狀態和資源使用情況。
• 操作歷史查看：能查看 droplet 操作歷史記錄。
• 批量管理：可列出所有 droplets，並按名稱查找。
• 監控數據獲取：獲取 CPU、內存、磁盤、網絡使用率（需啟用監控）。
• 刪除保護：具備多重安全機制，防止意外刪除重要服務器。
• 待實現功能：支持 AWS 功能待實現。

📦 安裝指南

依賴安裝

pip install -r requirements.txt

安裝 pydo SDK

pip install pydo

💻 使用示例

基礎用法

# 列出所有 droplets
result = list_droplets()
print(f"總共有 {result['total_droplets']} 個 droplets")

# 查找特定名稱的 droplet
result = find_droplet_by_name("web-server")
if result['found']:
    droplet = result['droplets'][0]
    droplet_id = droplet['id']

    # 獲取詳細狀態
    status = get_droplet_status(droplet_id)
    print(f"Droplet 狀態: {status['status']}")

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

        # 檢查操作狀態
        action_status = get_action_status(action_id)
        print(f"重啟操作狀態: {action_status['action']['status']}")

高級用法

刪除安全性檢查示例

# 檢查刪除策略
policy = get_droplet_deletion_policy()
print(f"刪除功能狀態: {policy['deletion_policy']['current_status']}")

# 檢查特定 droplet 的刪除安全性
safety_check = check_droplet_deletion_safety(droplet_id)
print(f"安全等級: {safety_check['safety_level']}")

# 查看安全檢查詳情
for check in safety_check['safety_checks']:
    print(f"{check['check']}: {check['status']} - {check['message']}")

# 嘗試刪除（會被安全機制阻止）
deletion_result = delete_droplet_with_protection(droplet_id, "CONFIRM_DELETE_DROPLET")
if deletion_result.get('error'):
    print(f"刪除被阻止: {deletion_result['error']}")

監控數據獲取示例

# 獲取監控數據
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} 監控數據可用")
        else:
            print(f"{metric_type} 暫無數據")
else:
    print("請先在 DigitalOcean 控制面板中啟用監控功能")

📚 詳細文檔

可用的 MCP 工具函數

基礎查詢功能

• get_dg_info(ipv4_address: str)：根據公網 IP 地址獲取對應的 DigitalOcean droplet 信息。
  • 參數：ipv4_address (str)：要查詢的公網 IP 地址。
• list_droplets()：列出賬戶下所有的 DigitalOcean droplets。
• find_droplet_by_name(name: str)：根據名稱查找 DigitalOcean droplet（支持模糊匹配）。
  • 參數：name (str)：droplet 名稱或部分名稱。
• get_droplet_status(droplet_id: int)：獲取指定 droplet 的當前狀態和詳細信息。
  • 參數：droplet_id (int)：droplet ID。

電源管理功能

• power_on_droplet(droplet_id: int)：開啟指定的 droplet。
• power_off_droplet(droplet_id: int)：強制關閉指定的 droplet（類似拔電源）。
• shutdown_droplet(droplet_id: int)：優雅關閉指定的 droplet（類似系統關機命令）。
• reboot_droplet(droplet_id: int)：重啟指定的 droplet。
  • 參數：droplet_id (int)：要操作的 droplet ID。

監控和歷史功能

• get_droplet_monitoring(droplet_id: int)：獲取 droplet 的監控數據，包括 CPU、內存、磁盤、網絡使用率。
  • 注意：需要在 droplet 上啟用監控功能。
• get_droplet_actions(droplet_id: int)：獲取指定 droplet 的操作歷史記錄。
• get_action_status(action_id: int)：查詢特定操作的狀態（在執行電源操作後可用於跟蹤進度）。
  • 參數：
    • droplet_id (int)：droplet ID。
    • action_id (int)：操作 ID。

刪除保護功能

• delete_droplet_with_protection(droplet_id: int, confirmation_code: str = "")：刪除 DigitalOcean droplet（帶嚴格安全保護）。
  • 注意：此功能具有多重安全限制，實際上被設計為阻止刪除操作。
  • 參數：
    • droplet_id (int)：要刪除的 droplet ID。
    • confirmation_code (str)：確認碼（必須為 "CONFIRM_DELETE_DROPLET"）。
• get_droplet_deletion_policy()：獲取當前的刪除策略和安全配置信息。
• check_droplet_deletion_safety(droplet_id: int)：檢查指定 droplet 的刪除安全性（不實際刪除）。
  • 參數：droplet_id (int)：要檢查的 droplet ID。

返回值說明

成功響應示例

• 刪除安全性檢查

{
    "cloud_provider": "digitalocean",
    "droplet_id": 123456789,
    "droplet_name": "web-server-01",
    "overall_safety": "BLOCKED",
    "safety_level": "刪除被阻止",
    "safety_checks": [
        {
            "check": "全局刪除策略",
            "status": "BLOCKED",
            "message": "刪除功能已被全局禁用"
        },
        {
            "check": "droplet狀態",
            "status": "WARNING",
            "message": "droplet正在運行 (active)，建議先關機"
        },
        {
            "check": "保護標籤",
            "status": "BLOCKED",
            "message": "發現保護標籤: production"
        }
    ],
    "warnings": [
        "此droplet帶有保護標籤，表明它可能是重要服務器"
    ],
    "summary": {
        "total_checks": 5,
        "blocked": 2,
        "warnings": 1,
        "passed": 2
    }
}

• 刪除策略信息

{
    "cloud_provider": "digitalocean",
    "deletion_policy": {
        "enabled": false,
        "protection_level": "MAXIMUM",
        "current_status": "所有刪除操作被禁用",
        "safety_checks": [
            "環境變量 ALLOW_DROPLET_DELETION 必須設置為 true",
            "必須提供正確的確認碼 'CONFIRM_DELETE_DROPLET'",
            "droplet 必須處於關機狀態",
            "droplet 不能帶有保護標籤",
            "多重確認機制"
        ],
        "protected_tags": ["production", "prod", "important", "critical", "backup"]
    },
    "security_info": {
        "philosophy": "安全第一，防止意外刪除重要服務器",
        "recommendation": "強烈建議通過DigitalOcean控制面板手動刪除droplet"
    }
}

• droplet 操作成功

{
    "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": "已成功提交 reboot 操作，操作ID: 987654321"
}

• droplet 狀態查詢

{
    "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"]
}

• 監控數據響應

{
    "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": "監控數據可能需要幾分鐘才能在新啟用監控的droplet上顯示。"
}

錯誤響應示例

• 刪除操作被阻止

{
    "cloud_provider": "digitalocean",
    "error": "刪除操作已被禁用。出於安全考慮，所有droplet刪除操作被限制。",
    "security_info": {
        "protection_level": "MAXIMUM",
        "reason": "防止意外刪除重要服務器",
        "how_to_enable": "設置環境變量 ALLOW_DROPLET_DELETION=true (不推薦)"
    }
}

• 一般錯誤

{
    "cloud_provider": "digitalocean",
    "error": "未找到ID為 123456789 的droplet"
}

測試功能

項目包含一個完整的測試腳本 test_dg_info.py，可以測試所有功能：

python test_dg_info.py

測試腳本包含以下測試模塊：

• 基本功能測試：列出 droplets、API 連接測試。
• Droplet 操作測試：狀態查詢、電源管理、操作歷史。
• 監控功能測試：監控數據獲取和可用性檢查。
• 刪除保護測試：安全策略檢查、刪除安全性評估。
• IP 查找測試：根據 IP 地址查找對應的 droplet。

API 說明

pydo SDK 集成

本項目使用官方的 pydo SDK 來與 DigitalOcean API 交互：

1. 安裝 pydo：pip install pydo。
2. 配置 API Token：設置 DIGITALOCEAN_TOKEN 環境變量。
3. 調用 API：使用 client.droplets.list() 獲取所有 droplets。

工作原理

1. 初始化 pydo 客戶端，使用配置的 API token。
2. 調用 client.droplets.list() 獲取賬戶下所有 droplets。
3. 遍歷每個 droplet 的網絡配置。
4. 查找匹配指定公網 IP 地址的 droplet。
5. 返回找到的 droplet 的詳細信息。

🔧 技術細節

安全特性

🛡️ 刪除保護機制

為了防止意外刪除重要的 droplet，本系統實現了嚴格的五層安全保護：

保護層級

1. 全局開關保護：默認禁用所有刪除操作。
2. 確認碼保護：需要特定確認碼才能嘗試刪除。
3. 狀態檢查保護：禁止刪除運行中的 droplet。
4. 標籤保護：自動識別並保護重要 droplet。
5. 最終安全檢查：即使通過前面檢查，實際刪除仍被禁用。

保護標籤

系統會自動保護帶有以下標籤的 droplet：

• production / prod
• important
• critical
• backup

配置方法

# 默認情況下，刪除功能完全禁用
# 如需啟用（強烈不推薦），設置環境變量：
export ALLOW_DROPLET_DELETION=true

⚠️ 重要提醒：即使啟用刪除功能，所有實際刪除操作仍會被最終安全檢查阻止。建議始終通過 DigitalOcean 控制面板手動刪除 droplet。

錯誤處理

• 自動檢測 pydo SDK 是否已安裝。
• 驗證 DIGITALOCEAN_TOKEN 環境變量是否配置。
• 捕獲 API 調用異常並返回友好的錯誤信息。
• 提供詳細的調試信息。

注意事項

安全相關

⚠️ 重要提示

• 刪除保護：

• 默認禁用所有刪除操作以防止意外刪除。
• 多重安全檢查機制保護重要服務器。
• 即使配置允許刪除，實際刪除仍被最終安全檢查阻止。
• 強烈建議通過 DigitalOcean 控制面板手動刪除。

• API 權限：確保您的 DigitalOcean API token 具有適當的權限：

• 讀取 droplets 的權限。
• 執行 droplet 操作的權限（開關機、重啟等）。
• 訪問監控數據的權限。

• 監控功能限制：

• 需要在 droplet 上啟用監控功能（在創建時或後續在控制面板中啟用）。
• 監控數據可能需要幾分鐘才能顯示。
• 免費 monitoring 功能每 5 分鐘收集一次數據點。

• API 調用限制：

• DigitalOcean API 有頻率限制（每小時 5,000 次請求）。
• 電源操作是異步的，需要查詢操作狀態來確認完成。

• 安全考慮：

• 請妥善保管您的 API token。
• 建議使用環境變量存儲敏感信息。
• 在生產環境中限制 API token 的權限範圍。
• 避免在自動化腳本中啟用刪除功能。

操作狀態說明

droplet 可能的狀態包括：

• new：新創建，正在初始化。
• active：運行中。
• off：已關機。
• archive：已歸檔（長期關閉）。

操作狀態包括：

• in-progress：執行中。
• completed：已完成。
• errored：執行失敗。

刪除安全等級：

• BLOCKED：刪除被阻止（有嚴重安全問題）。
• WARNING：需要謹慎考慮（有潛在風險）。
• CAUTION：可以刪除但需確認（仍有限制）。

最佳實踐

💡 使用建議

• 安全操作：

• 避免啟用刪除功能，始終通過控制面板手動刪除。
• 定期使用 check_droplet_deletion_safety() 評估服務器安全性。
• 為重要服務器添加保護標籤。

• 批量操作：使用 list_droplets() 獲取所有 droplets，然後根據需要過濾和操作。
• 狀態檢查：在執行電源操作前，先檢查 droplet 當前狀態。
• 操作跟蹤：保存操作 ID，用於後續狀態查詢。
• 錯誤處理：始終檢查返回結果中的 error 字段。
• 監控啟用：在創建 droplet 時啟用監控功能，以便後續獲取使用數據。