---

✨ Visão geral

adila-mcp é um sidecar fino (stdio, JSON-RPC 2.0) que expõe um conjunto de tools (deploy, leitura de projetos/services/deploys/builds/logs/métricas/uso/auditoria e 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 — npx baixa 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 no control plane: revogar a chave ou remover o usuário da org desativa o acesso imediatamente, 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 do usuá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 chave herdar um papel com permissão de escrita — os destrutivos ainda trazem destructiveHint 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 para mais 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 tool alimentam 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.
• .env está 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