Cloudstack MCP Server

🚀 CloudStack MCP 服務器

CloudStack MCP 服務器是一個高性能的 MCP（模型上下文協議）服務器，專為 Apache CloudStack API 集成而設計。該服務器提供了一套全面的工具，可通過 MCP 協議管理 CloudStack 基礎設施，實現與 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。

✨ 主要特性

• 🔧 完整的虛擬機生命週期管理：可部署、啟動、停止、重啟和銷燬虛擬機。
• 🏗️ 基礎設施發現：可列出區域、模板和服務套餐。
• 🔐 安全認證：使用 CloudStack API 憑證對 HMAC - SHA1 簽名的請求進行認證。
• ⚡ 高性能：採用高效的 TypeScript 實現，並具備完善的錯誤處理機制。
• 🛡️ 類型安全：全面支持 TypeScript，擁有完善的接口。
• 📊 豐富信息：提供詳細的虛擬機元數據，包括 CPU、內存、網絡和狀態等。
• 🖥️ 命令行界面：可直接通過 CLI 對 CloudStack 進行交互式管理。
• 🤖 MCP 集成：通過 MCP 協議與 AI 助手實現無縫集成。

📦 安裝指南

安裝步驟已在快速開始部分的“安裝”小節中詳細介紹，此處不再贅述。

💻 使用示例

基礎用法

列出虛擬機

{
  "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 個工具）

⚙️ 虛擬機高級操作（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：全面的 MCP 服務器實現，包含 45 個以上的工具處理程序、錯誤管理和 CloudStack 集成。
• src/cli.ts：命令行界面，通過 JSON - RPC 與 MCP 服務器通信，實現對 CloudStack 的直接管理。
• src/cloudstack-client.ts：強大的 CloudStack API 客戶端，具備 HMAC - SHA1 認證、類型安全的接口和完善的錯誤處理。

配置

必需的環境變量

可選的環境變量

開發

構建命令

# 將 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 錯誤類型。
• 異步/等待：全程採用現代異步模式。
• 模塊化設計：清晰的關注點分離。

安全

• HMAC - SHA1 簽名：所有 API 請求均經過加密簽名處理。
• 無憑證存儲：僅從環境變量中讀取憑證。
• 請求驗證：對所有工具參數進行輸入驗證。
• 錯誤清理：從錯誤消息中過濾敏感信息。

兼容性

• CloudStack：與 CloudStack 4.11 及以上版本兼容。
• Node.js：需要 Node.js 18 及以上版本。
• MCP 協議：實現了 MCP SDK 0.5.0 及以上版本。
• TypeScript：基於 TypeScript 5.0 及以上版本構建。

🔧 技術細節

本項目採用高效的 TypeScript 實現，具備完善的錯誤處理機制和類型安全保障。通過 HMAC - SHA1 簽名對 API 請求進行安全認證，確保通信的安全性。在架構上，各個模塊職責明確，如 src/index.ts 作為入口點負責啟動服務器，src/server.ts 實現核心的 MCP 服務器功能，src/cli.ts 提供命令行操作的接口，src/cloudstack-client.ts 則負責與 CloudStack API 進行交互。

📄 許可證

本項目採用 MIT 許可證，詳細信息請參閱 LICENSE 文件。