Cloud Manage MCP Server

🚀 Cloud Manage MCP Server

このサーバーは、MCP (Model Context Protocol) をベースにしたクラウド管理サーバーで、公開 IP アドレスを通じてクラウドサーバーの情報を取得することができます。

✨ 主な機能

• 公開 IP アドレスを通じてクラウドサービスプロバイダーを識別することができます。
• pydo SDK を使用して、DigitalOcean droplet の詳細情報を取得します。
• Droplet 電源管理: 起動、シャットダウン、再起動、グレースフルシャットダウンが可能です。
• 状態監視: droplet の現在の状態とリソース使用状況を取得します。
• 操作履歴: droplet の操作履歴を確認できます。
• 一括管理: すべての droplets をリストし、名前で検索することができます。
• 監視データ: CPU、メモリ、ディスク、ネットワークの使用率を取得します（監視を有効にする必要があります）。
• 削除保護: 重要なサーバーの誤削除を防ぐための多重セキュリティ機能が備わっています。
• AWS のサポート（未実装）

🛡️ セキュリティ機能

🛡️ 削除保護メカニズム

重要な droplet の誤削除を防止するため、本システムでは厳格な 5 層のセキュリティ保護を実装しています。

保護レベル

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 で監視機能を有効にする必要があります（作成時または後でコントロールパネルで有効にします）。
   • 監視データが表示されるまで数分かかる場合があります。
   • 無料の監視機能は 5 分ごとにデータポイントを収集します。
4. API 呼び出し制限:
   • DigitalOcean API には呼び出し頻度制限があります（1 時間に 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 など）をサポートします。