VPS MCP Server

# API Reference - MCP Server Portainer Esta documentação descreve todas as ferramentas (tools) disponíveis no MCP Server para gerenciamento do Portainer. ## Container Tools ### `list_containers` Lista todos os containers Docker. **Parâmetros:** - `all` (boolean, opcional): Se `true`, lista todos os containers incluindo parados. Padrão: `false` - `filters` (object, opcional): Filtros para aplicar (ex: `{"status": ["running"]}`) **Retorno:** ```json [ { "Id": "abc123...", "Names": ["/nginx"], "Image": "nginx:latest", "State": "running", "Status": "Up 2 hours", "Ports": [{"PrivatePort": 80, "PublicPort": 8080, "Type": "tcp"}] } ] ``` **Exemplo de uso:** ``` Liste todos os containers em execução ``` --- ### `get_container` Obtém detalhes completos de um container específico. **Parâmetros:** - `id` (string, obrigatório): ID ou nome do container **Retorno:** ```json { "Id": "abc123...", "Name": "/nginx", "State": { "Status": "running", "Running": true, "Paused": false, "StartedAt": "2025-12-21T10:00:00Z" }, "Config": { "Image": "nginx:latest", "Env": ["PATH=/usr/local/sbin:/usr/local/bin..."] }, "NetworkSettings": {...} } ``` **Exemplo de uso:** ``` Mostre os detalhes do container nginx ``` --- ### `start_container` Inicia um container parado. **Parâmetros:** - `id` (string, obrigatório): ID ou nome do container **Retorno:** ```json { "success": true, "message": "Container started successfully" } ``` **Exemplo de uso:** ``` Inicie o container nginx ``` --- ### `stop_container` Para um container em execução. **Parâmetros:** - `id` (string, obrigatório): ID ou nome do container - `timeout` (number, opcional): Tempo em segundos antes de forçar parada. Padrão: `10` **Retorno:** ```json { "success": true, "message": "Container stopped successfully" } ``` **Exemplo de uso:** ``` Pare o container nginx ``` --- ### `restart_container` Reinicia um container. **Parâmetros:** - `id` (string, obrigatório): ID ou nome do container - `timeout` (number, opcional): Tempo em segundos antes de forçar parada. Padrão: `10` **Retorno:** ```json { "success": true, "message": "Container restarted successfully" } ``` **Exemplo de uso:** ``` Reinicie o container nginx ``` --- ### `remove_container` Remove um container. **Parâmetros:** - `id` (string, obrigatório): ID ou nome do container - `force` (boolean, opcional): Força remoção mesmo se estiver rodando. Padrão: `false` - `volumes` (boolean, opcional): Remove volumes associados. Padrão: `false` **Retorno:** ```json { "success": true, "message": "Container removed successfully" } ``` **Exemplo de uso:** ``` Remova o container nginx-old forçadamente ``` --- ### `create_container` Cria um novo container. **Parâmetros:** - `name` (string, opcional): Nome do container - `image` (string, obrigatório): Imagem a usar (ex: `nginx:latest`) - `env` (array, opcional): Variáveis de ambiente (ex: `["VAR=value"]`) - `ports` (object, opcional): Mapeamento de portas (ex: `{"80/tcp": [{"HostPort": "8080"}]}`) - `volumes` (array, opcional): Volumes a montar - `network` (string, opcional): Network a conectar - `restart_policy` (string, opcional): Política de restart (`no`, `always`, `on-failure`, `unless-stopped`) **Retorno:** ```json { "Id": "def456...", "Warnings": [] } ``` **Exemplo de uso:** ``` Crie um container nginx na porta 8080 ``` --- ## Image Tools ### `list_images` Lista todas as imagens Docker. **Parâmetros:** - `all` (boolean, opcional): Incluir imagens intermediárias. Padrão: `false` **Retorno:** ```json [ { "Id": "sha256:abc123...", "RepoTags": ["nginx:latest"], "Size": 142000000, "Created": 1703174400 } ] ``` **Exemplo de uso:** ``` Liste todas as imagens Docker ``` --- ### `get_image` Obtém detalhes de uma imagem específica. **Parâmetros:** - `id` (string, obrigatório): ID ou nome da imagem **Retorno:** ```json { "Id": "sha256:abc123...", "RepoTags": ["nginx:latest"], "Size": 142000000, "Architecture": "amd64", "Os": "linux" } ``` **Exemplo de uso:** ``` Mostre detalhes da imagem nginx:latest ``` --- ### `pull_image` Faz pull de uma imagem do registry. **Parâmetros:** - `image` (string, obrigatório): Nome da imagem (ex: `nginx:alpine`) - `tag` (string, opcional): Tag específica. Padrão: `latest` **Retorno:** ```json { "success": true, "message": "Image pulled successfully", "status": "Download complete" } ``` **Exemplo de uso:** ``` Baixe a imagem postgres:15 ``` --- ### `remove_image` Remove uma imagem. **Parâmetros:** - `id` (string, obrigatório): ID ou nome da imagem - `force` (boolean, opcional): Força remoção mesmo se em uso. Padrão: `false` **Retorno:** ```json { "success": true, "message": "Image removed successfully" } ``` **Exemplo de uso:** ``` Remova a imagem nginx:old ``` --- ## Network Tools ### `list_networks` Lista todas as networks Docker. **Parâmetros:** Nenhum **Retorno:** ```json [ { "Id": "net123...", "Name": "bridge", "Driver": "bridge", "Scope": "local" } ] ``` **Exemplo de uso:** ``` Liste todas as networks ``` --- ### `create_network` Cria uma nova network. **Parâmetros:** - `name` (string, obrigatório): Nome da network - `driver` (string, opcional): Driver a usar (`bridge`, `overlay`, `host`). Padrão: `bridge` - `internal` (boolean, opcional): Network interna (sem acesso externo). Padrão: `false` - `subnet` (string, opcional): Subnet CIDR (ex: `172.20.0.0/16`) **Retorno:** ```json { "Id": "net456...", "Warning": "" } ``` **Exemplo de uso:** ``` Crie uma network chamada app-network ``` --- ### `remove_network` Remove uma network. **Parâmetros:** - `id` (string, obrigatório): ID ou nome da network **Retorno:** ```json { "success": true, "message": "Network removed successfully" } ``` **Exemplo de uso:** ``` Remova a network old-network ``` --- ## Volume Tools ### `list_volumes` Lista todos os volumes Docker. **Parâmetros:** Nenhum **Retorno:** ```json { "Volumes": [ { "Name": "my-volume", "Driver": "local", "Mountpoint": "/var/lib/docker/volumes/my-volume/_data" } ] } ``` **Exemplo de uso:** ``` Liste todos os volumes ``` --- ### `create_volume` Cria um novo volume. **Parâmetros:** - `name` (string, obrigatório): Nome do volume - `driver` (string, opcional): Driver a usar. Padrão: `local` - `labels` (object, opcional): Labels para o volume **Retorno:** ```json { "Name": "my-volume", "Driver": "local", "Mountpoint": "/var/lib/docker/volumes/my-volume/_data" } ``` **Exemplo de uso:** ``` Crie um volume chamado postgres-data ``` --- ### `remove_volume` Remove um volume. **Parâmetros:** - `name` (string, obrigatório): Nome do volume - `force` (boolean, opcional): Força remoção. Padrão: `false` **Retorno:** ```json { "success": true, "message": "Volume removed successfully" } ``` **Exemplo de uso:** ``` Remova o volume old-data ``` --- ## Tratamento de Erros Todas as tools retornam erros no seguinte formato: ```json { "error": true, "message": "Descrição do erro", "code": "ERROR_CODE", "details": {...} } ``` ### Códigos de Erro Comuns: - `UNAUTHORIZED`: Chave de API inválida ou expirada - `NOT_FOUND`: Recurso não encontrado - `CONFLICT`: Conflito (ex: nome já existe) - `SERVER_ERROR`: Erro interno do Portainer/Docker - `NETWORK_ERROR`: Erro de conexão com Portainer ## Notas de Segurança > [!WARNING] > Operações destrutivas (`remove_container`, `remove_image`, etc.) são irreversíveis. Use com cuidado. > [!CAUTION] > O parâmetro `force` em operações de remoção pode causar perda de dados se containers/volumes estiverem em uso.