Cloud Manage MCP Server
这是一个基于 MCP (Model Context Protocol) 的云管理服务器，支持通过公网 IP 地址获取云服务器信息。
功能特性
- 支持通过公网 IP 地址识别云服务提供商
- 使用 pydo SDK 获取 DigitalOcean droplet 详细信息
- Droplet 电源管理: 开机、关机、重启、优雅关机
- 状态监控: 获取 droplet 当前状态和资源使用情况
- 操作历史: 查看 droplet 操作历史记录
- 批量管理: 列出所有 droplets，按名称查找
- 监控数据: 获取 CPU、内存、磁盘、网络使用率（需启用监控）
- 删除保护: 多重安全机制防止意外删除重要服务器
- 支持 AWS（待实现）
安全特性
🛡️ 删除保护机制
为了防止意外删除重要的 droplet，本系统实现了严格的五层安全保护：
保护层级
- 全局开关保护: 默认禁用所有删除操作
- 确认码保护: 需要特定确认码才能尝试删除
- 状态检查保护: 禁止删除运行中的 droplet
- 标签保护: 自动识别并保护重要 droplet
- 最终安全检查: 即使通过前面检查，实际删除仍被禁用
保护标签
系统会自动保护带有以下标签的 droplet：
production / prodimportantcriticalbackup
配置方法
# 默认情况下，删除功能完全禁用
# 如需启用（强烈不推荐），设置环境变量：
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 IDaction_id (int): 操作 ID
删除保护功能
delete_droplet_with_protection(droplet_id: int, confirmation_code: str = "")
删除 DigitalOcean droplet（带严格安全保护）。
注意: 此功能具有多重安全限制，实际上被设计为阻止删除操作。
参数:
droplet_id (int): 要删除的 droplet IDconfirmation_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，可以测试所有功能：
测试脚本包含以下测试模块：
- 基本功能测试: 列出 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 时启用监控功能，以便后续获取使用数据
依赖安装
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 # 默认值，建议保持禁用
使用方法
启动服务器
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 等）