金大哥 - cloud_manage_mcp

article

README

🚀 云管理 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 当前状态和资源使用情况。
操作历史查看：查看 droplet 操作历史记录。
批量管理：列出所有 droplets，并可按名称查找。
监控数据获取：获取 CPU、内存、磁盘、网络使用率（需启用监控）。
删除保护：具备多重安全机制，防止意外删除重要服务器。
AWS 支持（待实现）：未来将支持 AWS 云服务。

📦 安装指南

依赖安装

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  # 默认值，建议保持禁用

💻 使用示例

基础用法

# 列出所有 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。

注意事项

安全相关

删除保护：

默认禁用所有删除操作以防止意外删除。
多重安全检查机制保护重要服务器。
即使配置允许删除，实际删除仍被最终安全检查阻止。
强烈建议通过 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 时启用监控功能，以便后续获取使用数据。

API 说明

pydo SDK 集成

本项目使用官方的 pydo SDK 来与 DigitalOcean API 交互：

安装 pydo：pip install pydo。
配置 API Token：设置 DIGITALOCEAN_TOKEN 环境变量。
调用 API：使用 client.droplets.list() 获取所有 droplets。

工作原理

初始化 pydo 客户端，使用配置的 API token。
调用 client.droplets.list() 获取账户下所有 droplets。
遍历每个 droplet 的网络配置。
查找匹配指定公网 IP 地址的 droplet。
返回找到的 droplet 的详细信息。

错误处理

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

注意事项

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

扩展功能

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

🔧 技术细节

🛡️ 删除保护机制

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

保护层级

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

保护标签

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

production / prod
important
critical
backup

配置方法

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

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

cloud_manage_mcp_server

README

🚀 云管理 MCP 服务器

🚀 快速开始

依赖安装

环境变量配置

启动服务器

✨ 主要特性

📦 安装指南

依赖安装

环境变量配置

💻 使用示例

基础用法

高级用法

删除安全性检查示例

监控数据获取示例

📚 详细文档

可用的 MCP 工具函数

基础查询功能

电源管理功能

监控和历史功能

删除保护功能

返回值说明

成功响应示例

错误响应示例

测试功能

注意事项

安全相关

操作状态说明

最佳实践

API 说明

pydo SDK 集成

工作原理

错误处理

注意事项

扩展功能

🔧 技术细节

🛡️ 删除保护机制

保护层级

保护标签

配置方法

运行方式说明

托管运行

本地运行 / 其它方式