🚀 adila-mcp
Servidor MCP da Adila — opere sua plataforma por linguagem natural.
Conecte Claude, Cursor ou qualquer cliente de IA ao seu control plane e gerenciedeploys conversando: "faz deploy da branch main do acme/api", "mostra os logsde build do service web", "como está meu uso do plano esse mês?".
✨ Visão geral
adila-mcp é um sidecar fino (stdio, JSON-RPC 2.0) que expõe um conjunto detools (deploy, leitura de projetos/services/deploys/builds/logs/métricas/uso/auditoriae mutação de infraestrutura) para clientes de IA. Ele não contém lógica de negócio:apenas traduz o protocolo MCP em chamadas HTTP autenticadas ao control plane da Adila.
- 🪶 Zero dependências de runtime — bundle único, roda em Node 18+ ou Bun.
- 🔐 Autorização ao vivo — a chave resolve usuário/org a cada chamada; revogar tem efeito imediato.
- ⚡ Sem instalação manual —
npxbaixa e executa sob demanda. - 🤖 Plug-and-play — funciona com Claude Desktop, Claude Code, Cursor e afins.
🧭 Arquitetura
┌──────────────┐ stdio (JSON-RPC) ┌───────────┐ HTTPS (Bearer) ┌──────────────────┐
│ Cliente de IA│ ───────────────────▶ │ adila-mcp │ ─────────────────▶ │ /api/* control │
│ (Claude…) │ ◀─────────────────── │ (sidecar) │ ◀───────────────── │ plane │
└──────────────┘ resultado MCP └───────────┘ deploy + dados └──────────────────┘
A chave de API resolve o usuário/organização ao vivo a cada chamada nocontrol plane: revogar a chave ou remover o usuário da org desativa o acessoimediatamente, e a chave nunca concede mais que o papel atual do usuário.
🚀 Início rápido
1. Gere uma chave
No dashboard, vá em Integrações → Servidor MCP → Gerar chave. A chave(adila_sk_...) é exibida uma única vez — copie e guarde com segurança.
2. Configure o cliente
Adicione ao arquivo de MCP servers do seu cliente (ex.: claude_desktop_config.json):
{
"mcpServers": {
"adila": {
"command": "npx",
"args": ["-y", "adila-mcp"],
"env": {
"ADILA_API_URL": "https://api-dash.adila.co",
"ADILA_API_KEY": "adila_sk_xxxxxxxx"
}
}
}
}
💡 Quem usa Bun pode trocar por
"command": "bunx","args": ["adila-mcp"].
3. Converse
Reinicie o cliente e peça um deploy em linguagem natural. Pronto. 🎉
⚙️ Variáveis de ambiente
| Variável | Obrigatória | Descrição |
|---|---|---|
ADILA_API_URL |
✅ | URL base do control plane (ex.: https://api-dash.adila.co). |
ADILA_API_KEY |
✅ | Chave de API no formato adila_sk_.... |
🛠️ Tools
Todos os tools são escopados pela organização da chave e respeitam o papel dousuário no control plane. Cada tool anuncia suas annotations MCP:os de leitura vêm com readOnlyHint, e os de mutação só funcionam se a chaveherdar um papel com permissão de escrita — os destrutivos ainda trazemdestructiveHint para o cliente poder pedir confirmação antes de executar.
Deploy
| Tool | O que faz | Argumentos principais |
|---|---|---|
deploy |
Dispara build do repositório + deploy automático de um service. | serviceId ou repo, branch?, commitSha? |
Leitura (read-only)
| Tool | O que faz | Argumentos principais |
|---|---|---|
list_projects |
Lista os projetos da organização. | limit? |
list_services |
Lista os services de um projeto, agrupados por ambiente. | projectId |
get_service |
Detalha um service (tipo, status, repositório, start, imagem). | serviceId |
list_deployments |
Histórico de deploys de um service (status, branch/commit, URL). | serviceId, limit? |
get_deployment |
Detalha um deploy (imagem, réplicas, erro, timestamps). | deploymentId |
list_builds |
Histórico de builds (construção da imagem) de um service. | serviceId, limit? |
get_logs |
Lê logs de deploy (runtime) ou build do deploy atual. |
serviceId, type?, limit?, filter?, since? |
get_metrics |
Métricas de uso (CPU, memória, disco, uptime) dos recursos. | serviceId, limit? |
list_resources |
Recursos gerenciados (Postgres, Redis…) de um service. | serviceId |
get_resource |
Detalha um recurso gerenciado (provedor, status, região). | resourceId |
list_audit_logs |
Trilha de auditoria da org (quem fez o quê), com filtros. | limit?, action?, targetType?, actorUserId?, from?, to? |
get_usage |
Consumo vs. cota do plano por dimensão, com excedentes. | — |
get_project_usage |
Uso (RAM/disco) de um projeto, por recurso. | projectId |
Mutação de infraestrutura
| Tool | O que faz | Argumentos principais |
|---|---|---|
create_service |
Cria um service num ambiente. | environmentId, name, type, … |
update_service |
Atualiza a configuração de um service. | serviceId, campos opcionais |
delete_service ⚠️ |
Exclui um service (irreversível). | serviceId |
create_resource |
Provisiona um recurso gerenciado (assíncrono). | serviceId, region? |
delete_resource ⚠️ |
Desprovisiona um recurso e seus dados (irreversível). | resourceId |
create_environment |
Cria um ambiente num projeto. | projectId, name, type, … |
update_environment |
Atualiza um ambiente. | environmentId, campos opcionais |
delete_environment ⚠️ |
Exclui um ambiente e tudo dentro dele (irreversível). | environmentId |
deploy
Informe exatamente um entre serviceId e repo. Quando repo mapeia paramais de um service, o control plane responde pedindo o serviceId específico.
{ "serviceId": "svc_abc123" }
{ "repo": "acme/api", "branch": "main" }
Fluxo típico de descoberta
list_projects → list_services (com o projectId) → list_deployments /get_logs (com o serviceId) → deploy. Os IDs retornados por um toolalimentam os argumentos do próximo.
🔐 Segurança
- A chave de API só trafega no header
Authorization: Bearer ...— nunca é logada. - O stdout é reservado ao protocolo MCP; todo log vai para o stderr.
.envestá no.gitignore; não versione a chave.- Revogue chaves comprometidas no dashboard — o efeito é imediato.
💻 Desenvolvimento
bun install
# Execução direta (debug)
ADILA_API_URL=... ADILA_API_KEY=... bun run src/index.ts
bunx tsc --noEmit # type-check
bun run build # gera dist/index.js (bundle Node)
📦 Publicação (npm)
O bin aponta para dist/index.js; prepublishOnly roda o build automaticamente.
npm login
npm publish --access public # ou --dry-run para ensaiar
Depois de publicado, npx -y adila-mcp passa a funcionar em qualquer máquina.
📄 Licença
MIT © Adila
