VPS MCP Server

# Arquitetura do MCP Server para Portainer ## Visão Geral O MCP Server atua como uma ponte entre modelos de IA (como Claude) e a API do Portainer, permitindo gerenciamento de containers Docker através de linguagem natural. ## Diagrama de Componentes ```mermaid graph TB subgraph "Cliente MCP" A[Claude Desktop / Cliente MCP] end subgraph "MCP Server" B[index.ts - MCP Server] C[PortainerClient] D[Container Tools] E[Image Tools] F[Network Tools] G[Volume Tools] end subgraph "Portainer" H[Portainer API] I[Docker Engine] end A <-->|MCP Protocol via stdio| B B --> D B --> E B --> F B --> G D --> C E --> C F --> C G --> C C <-->|HTTP + API Key| H H <--> I ``` ## Fluxo de Comunicação ### 1. Inicialização 1. MCP Server carrega configurações do `.env` 2. Inicializa `PortainerClient` com URL e API Key 3. Registra todas as tools disponíveis 4. Aguarda conexões via stdio ### 2. Execução de Tool 1. Cliente MCP envia requisição `tools/call` com nome da tool e parâmetros 2. MCP Server roteia para o handler apropriado (ex: `container-tools.ts`) 3. Handler valida parâmetros e chama método do `PortainerClient` 4. `PortainerClient` faz requisição HTTP à API do Portainer 5. Resposta é formatada e retornada ao cliente MCP ### 3. Autenticação - Todas as requisições à API do Portainer incluem header `X-API-Key` - A chave é configurada via variável de ambiente `PORTAINER_API_KEY` ## Estrutura de Diretórios ``` MCP-SERVER/ ├── src/ │ ├── index.ts # Entry point do MCP Server │ ├── config.ts # Configurações │ ├── portainer-client.ts # Cliente da API Portainer │ └── tools/ │ ├── container-tools.ts │ ├── image-tools.ts │ ├── network-tools.ts │ └── volume-tools.ts ├── docs/ │ ├── ARCHITECTURE.md # Este arquivo │ ├── API_REFERENCE.md # Referência das tools │ └── SETUP.md # Guia de setup ├── scripts/ │ ├── build.sh │ └── dev.sh ├── package.json ├── tsconfig.json ├── .env.example └── README.md ``` ## Tecnologias Utilizadas - **TypeScript**: Linguagem principal - **@modelcontextprotocol/sdk**: SDK oficial do MCP - **axios**: Cliente HTTP para API do Portainer - **dotenv**: Gerenciamento de variáveis de ambiente ## Segurança - API Key armazenada em variável de ambiente (não commitada) - Validação de parâmetros antes de chamadas à API - Tratamento de erros para evitar exposição de informações sensíveis ## Extensibilidade Novas ferramentas podem ser adicionadas criando novos arquivos em `src/tools/` e registrando-as no `index.ts`. Exemplos de extensões futuras: - Gerenciamento de Stacks - Gerenciamento de Secrets e Configs - Logs de containers em tempo real - Estatísticas e métricas