Cloudstack MCP Server

🚀 CloudStack MCP Server

このサーバーは、MCP (Model Context Protocol) を介してApache CloudStack APIとの統合を実現し、AIアシスタントや自動化ツールとのシームレスな連携を可能にする高性能なMCPサーバーです。CloudStackインフラストラクチャの管理に必要な包括的なツールを提供します。

✨ 主な機能

• 🔧 完全なVMライフサイクル管理：仮想マシンのデプロイ、起動、停止、再起動、破棄を行うことができます。
• 🏗️ インフラストラクチャの探索：ゾーン、テンプレート、サービスオファリングを一覧表示できます。
• 🔐 安全な認証：CloudStack APIの資格情報を使用したHMAC - SHA1署名付きのリクエストをサポートします。
• ⚡ 高性能：適切なエラーハンドリングを備えた効率的なTypeScript実装です。
• 🛡️ 型安全性：包括的なインターフェースを持つ完全なTypeScriptサポートがあります。
• 📊 豊富な情報：CPU、メモリ、ネットワーク、ステータスを含む詳細なVMメタデータを提供します。
• 🖥️ コマンドラインインターフェース：CloudStackを対話的に管理するための直接的なCLIアクセスが可能です。
• 🤖 MCP統合：MCPプロトコルを介してAIアシスタントとシームレスに統合できます。

🚀 クイックスタート

📦 インストール

1. リポジトリをクローンし、依存関係をインストールする：

   git clone <repository-url>
   cd cloudstack-mcp-server
   npm install
   

2. 環境変数を設定する： プロジェクトのルートに.envファイルを作成します。

   CLOUDSTACK_API_URL=https://your-cloudstack-server/client/api
   CLOUDSTACK_API_KEY=your-api-key
   CLOUDSTACK_SECRET_KEY=your-secret-key
   CLOUDSTACK_TIMEOUT=30000
   

3. プロジェクトをビルドする：

   npm run build
   

4. サーバーを起動する：

   # 開発モード (MCPサーバー)
   npm run dev
   
   # 本番モード (MCPサーバー)
   npm start
   
   # CLIモード
   npm run cli -- --help
   

MCPクライアントの統合

MCPクライアントの設定 (例: Claude Desktop) に追加します。

{
  "mcpServers": {
    "cloudstack": {
      "command": "node",
      "args": ["/path/to/cloudstack-mcp-server/build/index.js"],
      "env": {
        "CLOUDSTACK_API_URL": "https://your-cloudstack-server/client/api",
        "CLOUDSTACK_API_KEY": "your-api-key",
        "CLOUDSTACK_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

コマンドラインインターフェース

直接コマンドラインからアクセスするには、組み込みのCLIを使用します。

# グローバルにインストールする (オプション)
npm link

# CLIを使用する
cloudstack-cli list-vms --state Running
cloudstack-cli deploy-vm --service-offering-id 1 --template-id 2 --zone-id 3
cloudstack-cli get-vm --id 12345-67890-abcdef

# 利用可能なすべてのコマンドを表示する
cloudstack-cli --help

詳細なCLIドキュメントはCLI.mdを参照してください。

💻 使用例

仮想マシンの一覧表示

{
  "tool": "list_virtual_machines",
  "arguments": {
    "state": "Running",
    "zoneid": "1746ef10-8fa6-40c1-9c82-c3956bf75db8"
  }
}

新しい仮想マシンのデプロイ

{
  "tool": "deploy_virtual_machine",
  "arguments": {
    "serviceofferingid": "c6f99499-7f59-4138-9427-a09db13af2bc",
    "templateid": "7d4a7bb5-2409-4c8f-8537-6bbdc8a4e5c1",
    "zoneid": "1746ef10-8fa6-40c1-9c82-c3956bf75db8",
    "name": "my-new-vm",
    "displayname": "My New VM"
  }
}

📚 ドキュメント

利用可能なツール (45個のツール)

🖥️ 仮想マシン管理 (7個のツール)

⚙️ VMの高度な操作 (4個のツール)

💾 ストレージ管理 (7個のツール)

🌐 ネットワーキング (7個のツール)

📊 モニタリングと分析 (5個のツール)

👥 アカウントとユーザー管理 (4個のツール)

🏗️ インフラストラクチャの探索 (2個のツール)

🔧 システム管理 (5個のツール)

🔐 セキュリティとコンプライアンス (4個のツール)

プロジェクト構造

├── src/
│   ├── index.ts              # MCPサーバーのエントリーポイント
│   ├── server.ts             # メインのMCPサーバー実装
│   ├── cli.ts                # コマンドラインインターフェース
│   └── cloudstack-client.ts  # CloudStack APIクライアント
├── build/                    # コンパイルされたJavaScript出力
├── CLI.md                   # CLIドキュメント
├── package.json             # 依存関係とスクリプト
├── tsconfig.json            # TypeScriptの設定
└── .env                     # 環境変数 (リポジトリに含まれない)

アーキテクチャの概要

• src/index.ts：環境変数を読み込み、サーバーを起動するMCPサーバーのエントリーポイントです。
• src/server.ts：45以上のツールハンドラー、エラー管理、およびCloudStack統合を備えた包括的なMCPサーバーの実装です。
• src/cli.ts：MCPサーバーとのJSON - RPC通信を介してCloudStackを直接管理するためのコマンドラインインターフェースです。
• src/cloudstack-client.ts：HMAC - SHA1認証、型安全なインターフェース、および包括的なエラーハンドリングを備えた堅牢なCloudStack APIクライアントです。

設定

必須の環境変数

オプションの環境変数

開発

ビルドコマンド

# TypeScriptをJavaScriptにビルドする
npm run build

# ホットリロードで開発モードでMCPサーバーを実行する
npm run dev

# 開発モードでCLIを実行する
npm run dev:cli -- list-vms --help

# コンパイルされたMCPサーバーを実行する
npm start

# コンパイルされたCLIを実行する
npm run cli -- list-vms --help

# 型チェックのみを行う
npx tsc --noEmit

コード品質

• TypeScript：厳格モードを有効にした完全な型安全性があります。
• エラーハンドリング：MCPエラータイプを用いた包括的なエラーハンドリングが行われます。
• Async/Await：全体で最新の非同期パターンが使用されています。
• モジュール設計：関心事の明確な分離が行われています。

セキュリティ

• HMAC - SHA1署名：すべてのAPIリクエストは暗号学的に署名されます。
• 資格情報の保存なし：資格情報は環境変数からのみ読み取られます。
• リクエストの検証：すべてのツールパラメータに対する入力検証が行われます。
• エラーのサニタイズ：エラーメッセージから機密情報がフィルタリングされます。

互換性

• CloudStack：CloudStack 4.11以上と互換性があります。
• Node.js：Node.js 18以上が必要です。
• MCPプロトコル：MCP SDK 0.5.0以上を実装しています。
• TypeScript：TypeScript 5.0以上で構築されています。

📄 ライセンス

MIT - 詳細はLICENSEファイルを参照してください。