CloudStack MCP Server

Integre-se ao Apache CloudStack para gerenciar recursos de nuvem diretamente do seu desktop.

Documentação

CloudStack MCP Server

Um servidor abrangente de Model Context Protocol (MCP) que fornece gerenciamento completo de infraestrutura CloudStack por meio de interações em linguagem natural com o Claude Desktop. Esta implementação oferece cobertura extensiva das APIs do CloudStack 4.20 com mais de 477 ferramentas MCP cobrindo mais de 735 métodos de API em 32 categorias.

Visão Geral

O CloudStack MCP Server permite o gerenciamento contínuo de infraestrutura em nuvem, conectando as APIs do CloudStack à interface de linguagem natural do Claude. Os usuários podem executar operações complexas de infraestrutura usando comandos conversacionais, eliminando a necessidade de aprender a sintaxe da API do CloudStack ou ferramentas de linha de comando.

Estatísticas Principais:

Cobertura Extensiva de API: Mais de 477 ferramentas MCP cobrindo mais de 735 métodos de API do CloudStack (93% de cobertura)
Categorias Abrangentes: 32 categorias de API do CloudStack implementadas, incluindo novos recursos de infraestrutura
Segurança Empresarial: 96 operações perigosas protegidas com sistema de confirmação
Interface em Linguagem Natural: Curva de aprendizado zero para gerenciamento de infraestrutura
Pronto para Produção: Confiabilidade de nível empresarial com controles de segurança abrangentes

Recursos

🏗️ Gerenciamento de Infraestrutura

Operações de Máquina Virtual: Gerenciamento completo do ciclo de vida, incluindo implantação, dimensionamento, migração e monitoramento
Gerenciamento de Armazenamento: Operações de volume, gerenciamento de snapshots, recursos de backup e restauração
Gerenciamento de Image Store: Gerenciamento completo de armazenamento backend com suporte a NFS, S3 e Swift
Gerenciamento de Pods: Operações de pods de infraestrutura, incluindo criação, dedicação e gerenciamento de faixas de IP
Administração de Rede: Gerenciamento de VPC, balanceamento de carga, regras de firewall e ACLs de rede
Grupos de Segurança: Gerenciamento de regras de entrada/saída e aplicação de políticas de segurança

👥 Gerenciamento de Identidade e Acesso

Administração de Contas: Gerenciamento do ciclo de vida do usuário com controle de acesso baseado em funções
Gerenciamento de Domínios: Estruturas hierárquicas de domínio e organização de recursos
Gerenciamento de Projetos: Espaços de colaboração multi-tenant com atribuições de usuários
Integração LDAP: Sincronização com serviços de diretório empresarial

🌐 Redes Avançadas

VPC e Redes: Configuração e gerenciamento de Virtual Private Cloud
Serviços VPN: Conectividade VPN site-to-site e de acesso remoto
Balanceamento de Carga: Configuração de balanceador de carga de aplicação com verificações de saúde
Gerenciamento de Certificados SSL: Ciclo de vida completo de certificados, incluindo emissão, upload, revogação e gerenciamento de provedores de CA

📊 Monitoramento e Análises

Métricas de Recursos: Monitoramento de desempenho da infraestrutura e planejamento de capacidade
Gerenciamento de Eventos: Rastreamento de eventos do sistema e configuração de alertas
Gerenciamento de Cotas: Aplicação de limites de recursos e integração com cobrança
Gerenciamento de AutoScale: Políticas automáticas de dimensionamento e limites de desempenho

🔧 Recursos Avançados

Gerenciamento de Templates e ISOs: Ciclo de vida de imagens com replicação entre zonas
Integração com Kubernetes: Gerenciamento de plataforma de orquestração de contêineres
Armazenamento de Objetos: Armazenamento compatível com S3 com políticas de ciclo de vida
Integração de Hardware: Gerenciamento de NetScaler, UCS e servidores bare metal
Tungsten Fabric SDN: Redes definidas por software com microssegmentação

🛡️ Segurança e Proteção Empresarial

Confirmação de Ações Perigosas: Sistema de confirmação à prova de falhas protegendo 96 operações destrutivas
Detecção Inteligente de Operações: Identificação automática de operações de exclusão, destruição, purga, dimensionamento e reinicialização
Avisos Contextuais Detalhados: Descrições detalhadas de operações com níveis de gravidade e avaliação de impacto
Requisitos de Confirmação: Confirmação digitada obrigatória para operações críticas (por exemplo, "destruir permanentemente")
Proteção de Infraestrutura: Proteções críticas para exclusão de image store e operações de gerenciamento de pods
Controles de Ambiente: Bypasses inteligentes para desenvolvimento, mantendo a segurança em produção
Auditoria Abrangente: Trilhas completas de auditoria de segurança com rastreamento de correlação e relatórios de conformidade
Categorias de Operação: Proteção em operações de VM, Armazenamento, Rede, VPC, Kubernetes, Infraestrutura e Certificados
Gerenciamento de Memória: Rastreamento eficiente com limpeza automática e políticas de timeout configuráveis

Cobertura de Testes e Garantia de Qualidade

Framework de Testes de Nível Empresarial (v2.3.0+)

Suíte de Testes Completa: 12 arquivos de teste de integração cobrindo todas as operações empresariais
Mais de 350 Casos de Teste: Testes sistemáticos em VM, Armazenamento, Rede, Conta, Kubernetes, Balanceador de Carga, VPN, Template/ISO, Administração do Sistema, Segurança/Conformidade, Monitoramento/Análises e Operações de Integração Empresarial
Framework Avançado de Mocks: Classe TestFramework personalizada com mais de 50 mocks de métodos de cliente CloudStack
Tratamento Completo de Erros: Testes para erros de API, timeouts de rede, problemas de permissão e restrições de recursos
Cobertura de Operações CRUD: Padrões Create, Read, Update, Delete para todos os tipos de recursos
Testes de Casos Extremos: Validação abrangente de condições de erro e cenários de limite

Estrutura de Testes

tests/
├── helpers/TestFramework.ts             # Comprehensive mocking and utilities
├── integration/
│   ├── vm-operations.test.ts            # 25+ VM lifecycle tests
│   ├── storage-operations.test.ts       # 20+ Storage and snapshot tests
│   ├── network-operations.test.ts       # 25+ Network and security tests
│   ├── account-management.test.ts       # 20+ User and domain tests
│   ├── kubernetes-operations.test.ts    # 14+ K8s cluster tests
│   ├── load-balancer-operations.test.ts # 18+ Load balancer tests
│   ├── vpn-operations.test.ts           # 14+ VPN and gateway tests
│   ├── template-iso-operations.test.ts  # 16+ Template and ISO tests
│   ├── system-administration.test.ts    # 20+ System admin tests
│   ├── security-compliance.test.ts      # 18+ Security and compliance tests
│   ├── monitoring-analytics.test.ts     # 15+ Monitoring and analytics tests
│   └── enterprise-integration.test.ts   # 12+ Enterprise integration tests
└── unit/cloudstack/client.test.ts       # CloudStack client tests

Métricas de Qualidade

Cobertura de Testes: Mais de 350 casos de teste em 12 categorias principais de operações
Cenários de Erro: Mais de 80 testes de tratamento de erros e casos extremos
Cobertura de Mocks: Todos os métodos de API do CloudStack sistematicamente mockados com mais de 65 métodos de cliente da Fase 3
Operações Empresariais: Cobertura completa de Administração do Sistema, Segurança/Conformidade, Monitoramento/Análises e Integração Empresarial
Pronto para CI/CD: Integração completa com Jest e relatórios de cobertura

Instalação

Pré-requisitos

Node.js: Versão 18.0 ou superior
Claude Desktop: Versão mais recente com suporte a MCP
Acesso ao CloudStack: Credenciais de API válidas com permissões apropriadas

Passo 1: Clonar e Compilar

# Clone the repository
git clone https://github.com/mozg31337/cloudstack-mcp-server.git
cd cloudstack-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Passo 2: Configurar a Conexão com o CloudStack

🔒 Configuração Segura com Variáveis de Ambiente (Recomendado)

Por segurança, use variáveis de ambiente em vez de credenciais codificadas:

# Copy the example environment file
cp .env.example .env

# Edit .env with your CloudStack credentials
# The .env file is automatically excluded from git

Edite .env com suas credenciais reais:

# Production CloudStack Environment
CLOUDSTACK_PROD_NAME="Production CloudStack"
CLOUDSTACK_PROD_API_URL="https://your-cloudstack.example.com/client/api"
CLOUDSTACK_PROD_API_KEY="your-production-api-key"
CLOUDSTACK_PROD_SECRET_KEY="your-production-secret-key"

# Development CloudStack Environment
CLOUDSTACK_DEV_NAME="Development CloudStack"
CLOUDSTACK_DEV_API_URL="https://dev-cloudstack.example.com/client/api"
CLOUDSTACK_DEV_API_KEY="your-dev-api-key"
CLOUDSTACK_DEV_SECRET_KEY="your-dev-secret-key"

# Default environment to use
CLOUDSTACK_DEFAULT_ENVIRONMENT="default"

Alternativa: Configuração Baseada em Arquivo

Se você preferir configuração baseada em arquivo (não recomendado para produção):

# Copy example configuration
cp config/cloudstack.example.json config/cloudstack.json

Edite config/cloudstack.json com valores de exemplo (as credenciais reais devem estar nas variáveis de ambiente):

{
  "defaultEnvironment": "default",
  "environments": {
    "default": {
      "name": "Production CloudStack",
      "apiUrl": "https://your-cloudstack.example.com/client/api",
      "apiKey": "your-api-key-here",
      "secretKey": "your-secret-key-here",
      "timeout": 30000,
      "retries": 3
    }
  },
  "logging": {
    "level": "info",
    "file": "logs/cloudstack-mcp.log"
  }
}

Passo 3: Integração com Claude Desktop

Adicione o servidor MCP à configuração do seu Claude Desktop:

macOS/Linux: ~/.config/claude/claude_desktop_config.json Windows: %APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "cloudstack": {
      "command": "node",
      "args": ["/absolute/path/to/cloudstack-mcp-server/dist/server.js"],
      "env": {
        "CLOUDSTACK_CONFIG": "/absolute/path/to/config/cloudstack.json"
      }
    }
  }
}

Passo 4: Verificar a Instalação

Reinicie o Claude Desktop
Inicie uma nova conversa
Teste a conexão com: "Liste minhas máquinas virtuais do CloudStack"

Configuração

Variáveis de Ambiente

O servidor suporta configuração abrangente por meio de variáveis de ambiente para gerenciamento seguro de credenciais:

Ambiente de Produção:

CLOUDSTACK_PROD_NAME="Production CloudStack"
CLOUDSTACK_PROD_API_URL="https://cloudstack.example.com/client/api"
CLOUDSTACK_PROD_API_KEY="your-production-api-key"
CLOUDSTACK_PROD_SECRET_KEY="your-production-secret-key"
CLOUDSTACK_PROD_TIMEOUT=30000
CLOUDSTACK_PROD_RETRIES=3

Ambiente de Desenvolvimento:

CLOUDSTACK_DEV_NAME="Development CloudStack"
CLOUDSTACK_DEV_API_URL="https://dev-cloudstack.example.com/client/api"
CLOUDSTACK_DEV_API_KEY="your-dev-api-key"
CLOUDSTACK_DEV_SECRET_KEY="your-dev-secret-key"
CLOUDSTACK_DEV_TIMEOUT=30000
CLOUDSTACK_DEV_RETRIES=3

Controle de Configuração:

# Default environment to use ("default" for production, "dev" for development)
CLOUDSTACK_DEFAULT_ENVIRONMENT="default"

# Logging configuration
CLOUDSTACK_LOG_LEVEL=info
CLOUDSTACK_LOG_FILE=logs/cloudstack-mcp.log

# Legacy configuration file path (optional)
CLOUDSTACK_CONFIG=/path/to/cloudstack.json

# Network settings
CLOUDSTACK_TIMEOUT=30000
CLOUDSTACK_RETRIES=3

Múltiplos Ambientes

Configure múltiplos ambientes CloudStack para diferentes casos de uso:

{
  "defaultEnvironment": "production",
  "environments": {
    "production": { "..." },
    "development": { "..." },
    "testing": { "..." }
  }
}

Alterne entre ambientes no Claude especificando: "Liste as VMs no ambiente de desenvolvimento"

Exemplos de Uso

Descoberta de Infraestrutura

"List all virtual machines in zone-east"
"Show me running VMs with their IP addresses"
"What storage volumes are available?"
"Display network configuration for my VPC"
"List all image store backends"
"Show pods in my zone"

Gerenciamento de Máquinas Virtuais

"Deploy a new Ubuntu 20.04 server with 4GB RAM"
"Start virtual machine vm-12345"
"Create a snapshot of my database server"
"Resize VM memory to 8GB"

Operações de Rede

"Create a load balancer for web servers"
"Add firewall rule allowing HTTP traffic"
"Configure VPN access for remote users"
"Set up network ACL for database tier"

Gerenciamento de Segurança

"Create security group for web applications"
"Allow SSH access from corporate network"
"Upload SSL certificate for HTTPS load balancer"
"Issue a Let's Encrypt certificate for my domain"
"List available certificate authorities"
"Configure two-factor authentication"

Gerenciamento de Infraestrutura

"Add a new NFS image store backend"
"Create a pod for my zone with IP range 192.168.1.10-100"
"Add S3 bucket as image store with my AWS credentials"
"Dedicate pod to specific domain"
"Update pod IP range configuration"

Desenvolvimento

Configuração de Desenvolvimento Local

# Development mode with hot reload
npm run dev

# Run test suite
npm test

# Test with coverage report
npm run test:coverage

# Code linting
npm run lint

# Type checking
npm run typecheck

Estrutura do Projeto

src/
├── server.ts              # MCP server implementation with 477+ tools
├── cloudstack/
│   ├── client.ts          # CloudStack API client with 735+ methods
│   ├── auth.ts            # HMAC signature authentication
│   └── types.ts           # TypeScript type definitions
├── utils/
│   ├── config.ts          # Configuration management
│   └── logger.ts          # Structured logging
├── security/              # Enterprise security framework
├── tests/                 # Comprehensive test suite
└── config/                # Configuration templates

Cobertura da API

Status Completo da Implementação

Categoria	Métodos de API	Ferramentas MCP	Cobertura
Máquina Virtual	72	80	100%
Armazenamento e Volumes	105	28	100%
Redes	85	59	100%
Balanceador de Carga	34	30	100%
Segurança	22	19	100%
Gerenciamento de Contas	16	17	100%
Templates e ISOs	35	25	100%
AutoScale	21	21	100%
Image Store	20	6	100%
Gerenciamento de Pods	9	5	100%
Gerenciamento de Certificados	10	4	100%
Total	735+	477+	93%

Para análise detalhada da cobertura da API, consulte a Documentação de Cobertura da API.

Roadmap Futuro

Melhorias de Alta Prioridade

Arquitetura: Organização modular de ferramentas e implementação de carregamento preguiçoso
Desempenho: Pooling de conexões e estratégias inteligentes de cache
Testes: Cobertura de testes aprimorada e suíte de testes de integração
Segurança: Rotação de chaves de API e controle de acesso baseado em funções

Recursos de Prioridade Média

Monitoramento: Verificações de saúde, coleta de métricas e registro de auditoria
Empresarial: Isolamento multi-tenant e automação de backup
Desenvolvimento: Tipos TypeScript abrangentes e documentação

Melhorias Futuras

CloudStack 5.x: Compatibilidade com a API quando disponível
Interface do Usuário: Painel web e ferramentas de CLI
Integração com IA: Otimização de recursos e gerenciamento de custos
Tempo Real: Streaming de eventos e atualizações ao vivo

Veja o roadmap completo em nossa lista de tarefas de desenvolvimento.

Contribuindo

Aceitamos contribuições para melhorar o CloudStack MCP Server:

Faça um fork do repositório e crie um branch de recurso
Implemente as alterações com testes apropriados
Execute as verificações de qualidade: npm run lint && npm test
Envie um pull request com descrição detalhada

Diretrizes de Desenvolvimento

Siga as melhores práticas de TypeScript
Mantenha a cobertura de testes acima de 90%
Inclua documentação para novos recursos
Use mensagens de commit convencionais

Considerações de Segurança

Credenciais de API: Armazene com segurança e rotacione regularmente
Acesso à Rede: Use HTTPS para todas as comunicações com o CloudStack
Permissões: Siga o princípio do menor privilégio
Registro de Auditoria: Ative para ambientes de produção

Licença

Este projeto é licenciado sob a Licença Internacional Creative Commons Atribuição-NãoComercial-CompartilhaIgual 4.0. Consulte LICENSE para detalhes.

Uso Comercial: Entre em contato com os mantenedores para opções de licenciamento comercial.

Suporte

Problemas: Reporte bugs via GitHub Issues
Documentação: Consulte o diretório docs/ para guias detalhados
Comunidade: Participe das discussões em nosso repositório

Nota: Este aplicativo usa técnicas de desenvolvimento assistido por IA. Embora tenha sido extensivamente testado, revise e valide a funcionalidade para seu ambiente específico antes da implantação em produção.