🚀 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 gerencie deploys conversando: "faz deploy da branch main do acme/api", "mostra os logs de build do service web", "como está meu uso do plano esse mês?".

npm node MCP license

✨ 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.