pdc-mcp — servidor MCP do PDC Deploy

Dá a qualquer agente MCP (Claude Code, Cursor, opencode…) o poder de operar o PDC Deploy: criar projetos e ambientes, deployar, acompanhar builds e diagnosticar falhas — com login seguro por código de dispositivo (o agente nunca vê sua senha) e segredos fora do chat por design: variáveis de ambiente são configuradas só no painel (o agente entrega o link).

Instalação

Requer Node 18+ (ou Bun). Não há download manual: o agente baixa e roda o servidor sob demanda via npx (ou bunx).

Claude Code

claude mcp add pdc -- npx -y pdc-mcp
# com Bun:
claude mcp add pdc -- bunx pdc-mcp

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "pdc": { "command": "npx", "args": ["-y", "pdc-mcp"] }
  }
}

opencode (~/.config/opencode/opencode.json)

{
  "mcp": {
    "pdc": {
      "type": "local",
      "command": ["npx", "-y", "pdc-mcp"],
      "enabled": true
    }
  }
}

Zero configuração: a URL institucional do PDC vai embutida como default e a URL do painel é auto-descoberta (GET /api/public/meta). Para desenvolvimento com backend local, passe o override PDC_API_URL (no Claude Code: claude mcp add pdc-dev -e PDC_API_URL=http://localhost:3334 -- npx -y pdc-mcp).

Alternativa: binário standalone (sem Node nem Bun)

Quem não quer Node/Bun pode baixar um executável único do seu sistema na última Release (pdc-mcp-linux-x64, -linux-arm64, -darwin-x64, -darwin-arm64, -windows-x64.exe). Linux/macOS: chmod +x e aponte o agente para o caminho absoluto (no macOS, se o Gatekeeper bloquear: xattr -d com.apple.quarantine <arquivo>).

Compilar do código (desenvolvimento)

bun install
bun run build           # bundle node-portável em packages/mcp/dist/index.js
bun run build:binaries  # binários de todos os SOs (usado pelo CI de release)

O pacote pdc-mcp no npm é o bundle node-portável (dist/index.js, com @pdc/core embutido — zero dependências em runtime). Uma Release com os binários standalone é gerada ao publicar uma tag v* (ver .github/workflows/release.yml).

Primeiro uso (login)

Peça algo como "liste meus projetos no PDC". Sem login, o agente mostra um link e um código (ex.: ABCD1234); abra o link, aprove no navegador (você já está logado no painel) e repita o pedido. O token fica em ~/.config/pdc/credentials.json (600), compartilhado com a futura CLI pdc.

Tools

| Tool | O quê | |---|---| | pdc_auth_status | Estado do login; inicia o device flow quando deslogado | | pdc_detect_context | Repo/branch/Dockerfile/porta do diretório local | | pdc_list_projects / pdc_get_project | Projetos e detalhe (ambientes, deploys, banco) | | pdc_list_repos / pdc_list_branches | Repos e branches do GitHub do usuário | | pdc_detect_framework | Framework/linguagem de um repo | | pdc_analyze_compose | Serviços do docker-compose, serviço público sugerido, avisos | | pdc_create_project | Cria projeto (produção nasce junto); devolve envEditorUrl | | pdc_create_environment | Adiciona dev/hml (branch própria, URL derivada, protegido) | | pdc_set_environment_branch | Troca a branch de deploy de um ambiente (valida que existe; prod exige confirmação) | | pdc_list_env_keys | NOMES das env vars + flag vazia (nunca valores) | | pdc_provision_database | Postgres gerenciado por ambiente (DATABASE_URL injetada) | | pdc_preflight | Checagem pré-deploy: build, compose, env vazias (ready) | | pdc_deploy | Dispara o deploy de um ambiente | | pdc_deployment_status | Status + timeline + logs de um deployment | | pdc_runtime_logs | Saúde/logs do container público (diagnóstico de crash) | | pdc_service_logs | Serviços da stack Compose (estado/health) + log por-serviço — pra achar quem travou um deploy compose (ex.: migrate/minio-init) | | pdc_restart / pdc_stop | Controle do app (com confirmação do usuário) |

Prompts guiados

Roteiros de ponta a ponta que o usuário invoca e o agente segue, encadeando as tools na ordem certa e confirmando cada passo:

| Prompt | O quê | |---|---| | deploy_repo | Deploy (projeto novo ou existente); pergunta para qual ambiente (prod/dev/hml) e segue até o deploy | | troubleshoot_deploy | Diagnóstico: identifica ambiente, checa build, runtime e env, explica a correção |

Segurança: valores de variáveis de ambiente não trafegam pelo MCP em nenhuma direção — configure-os no painel (o agente fornece o envEditorUrl). Excluir projeto/ambiente também é ação exclusiva do painel.

Troubleshooting

• "Usuário não autenticado" → chame pdc_auth_status (o agente faz isso sozinho; aprove no navegador).
• "GitHub não conectado" → entre no painel do PDC com GitHub (o token do GitHub fica no servidor, não na sua máquina).
• Rate limit (429) → aguarde o tempo indicado; o servidor protege o backend de polling agressivo.
• Logs administrativos do servidor saem no stderr (stdout é o protocolo).