Cloud Manage MCP Server

这是一个基于 MCP (Model Context Protocol) 的云管理服务器，支持通过公网 IP 地址获取云服务器信息。

功能特性

• 支持通过公网 IP 地址识别云服务提供商
• 使用 pydo SDK 获取 DigitalOcean droplet 详细信息
• Droplet 电源管理: 开机、关机、重启、优雅关机
• 状态监控: 获取 droplet 当前状态和资源使用情况
• 操作历史: 查看 droplet 操作历史记录
• 批量管理: 列出所有 droplets，按名称查找
• 监控数据: 获取 CPU、内存、磁盘、网络使用率（需启用监控）
• 删除保护: 多重安全机制防止意外删除重要服务器
• 支持 AWS（待实现）

安全特性

🛡️ 删除保护机制

为了防止意外删除重要的 droplet，本系统实现了严格的五层安全保护：

保护层级

1. 全局开关保护: 默认禁用所有删除操作
2. 确认码保护: 需要特定确认码才能尝试删除
3. 状态检查保护: 禁止删除运行中的 droplet
4. 标签保护: 自动识别并保护重要 droplet
5. 最终安全检查: 即使通过前面检查，实际删除仍被禁用

保护标签

系统会自动保护带有以下标签的 droplet：

• production / prod
• important
• critical
• backup

配置方法

# 默认情况下，删除功能完全禁用
# 如需启用（强烈不推荐），设置环境变量：
export ALLOW_DROPLET_DELETION=true

⚠️ 重要提醒: 即使启用删除功能，所有实际删除操作仍会被最终安全检查阻止。建议始终通过 DigitalOcean 控制面板手动删除 droplet。

可用的 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

使用示例

基本操作示例

# 列出所有 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 控制面板中启用监控功能")

返回值说明

成功响应示例

删除安全性检查

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

注意事项

安全相关

1. 删除保护:

   • 默认禁用所有删除操作以防止意外删除
   • 多重安全检查机制保护重要服务器
   • 即使配置允许删除，实际删除仍被最终安全检查阻止
   • 强烈建议通过 DigitalOcean 控制面板手动删除

2. API 权限: 确保您的 DigitalOcean API token 具有适当的权限：

   • 读取 droplets 的权限
   • 执行 droplet 操作的权限（开关机、重启等）
   • 访问监控数据的权限

3. 监控功能限制:

   • 需要在 droplet 上启用监控功能（在创建时或后续在控制面板中启用）
   • 监控数据可能需要几分钟才能显示
   • 免费 monitoring 功能每 5 分钟收集一次数据点

4. API 调用限制:

   • DigitalOcean API 有频率限制（每小时 5,000 次请求）
   • 电源操作是异步的，需要查询操作状态来确认完成

5. 安全考虑:

   • 请妥善保管您的 API token
   • 建议使用环境变量存储敏感信息
   • 在生产环境中限制 API token 的权限范围
   • 避免在自动化脚本中启用删除功能

操作状态说明

droplet 可能的状态包括：

• new: 新创建，正在初始化
• active: 运行中
• off: 已关机
• archive: 已归档（长期关闭）

操作状态包括：

• in-progress: 执行中
• completed: 已完成
• errored: 执行失败

删除安全等级：

• BLOCKED: 删除被阻止（有严重安全问题）
• WARNING: 需要谨慎考虑（有潜在风险）
• CAUTION: 可以删除但需确认（仍有限制）

最佳实践

1. 安全操作:

   • 避免启用删除功能，始终通过控制面板手动删除
   • 定期使用 check_droplet_deletion_safety() 评估服务器安全性
   • 为重要服务器添加保护标签

2. 批量操作: 使用 list_droplets() 获取所有 droplets，然后根据需要过滤和操作

3. 状态检查: 在执行电源操作前，先检查 droplet 当前状态

4. 操作跟踪: 保存操作 ID，用于后续状态查询

5. 错误处理: 始终检查返回结果中的 error 字段

6. 监控启用: 在创建 droplet 时启用监控功能，以便后续获取使用数据

依赖安装

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

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 的详细信息

错误处理

• 自动检测 pydo SDK 是否已安装
• 验证 DIGITALOCEAN_TOKEN 环境变量是否配置
• 捕获 API 调用异常并返回友好的错误信息
• 提供详细的调试信息

注意事项

1. 确保您的 DigitalOcean API token 具有读取 droplets 的权限
2. API 有调用频率限制，请合理使用
3. 该功能会列出账户下所有 droplets，请确保 token 的安全性

扩展功能

• 支持按标签过滤 droplets
• 支持分页查询大量 droplets
• 缓存查询结果以提高性能
• 支持其他云服务提供商（AWS、GCP 等）