Empacotar um .adapp

Pacotes .adapp são gerados pelo comando Artisan mcp:pack-app. Ele monta o manifest.json, calcula o checksum e grava o ZIP — você nunca escreve esses arquivos na mão.

Assinatura do comando

php artisan mcp:pack-app
    {catalog?}            # ID (UUID) ou name (slug) de um McpCatalog a empacotar
    {--openapi=}          # caminho do spec OpenAPI (.json ou .yaml/.yml) — modo alternativo
    {--out=}              # caminho de saída do .adapp
    {--endpoint=}         # endpoint HTTPS do servidor MCP
    {--name=}             # slug do pacote (OBRIGATÓRIO no modo --openapi)
    {--label=}            # label legível
    {--description=}      # descrição
    {--category=}         # categoria

Sem --out, o pacote é gravado em storage/app/adapp/.

Modo catálogo

Empacota um McpCatalog já existente (e o McpServer associado, se houver).

php artisan mcp:pack-app atende-direito --out=atende-direito.adapp

• Se o catálogo tiver um McpServer vinculado, o endpoint é lido de McpServer.config (chaves endpoint ou url).
• Se não houver server associado, informe --endpoint explicitamente.
• O manifest gerado leva tools[] + os arquivos tools/*.json a partir das tools já persistidas do servidor.

php artisan mcp:pack-app <uuid-do-catalogo> --endpoint=https://mcp.exemplo.com/v1

Modo OpenAPI

Empacota diretamente a partir de um spec OpenAPI, sem passar por um catálogo existente.

1. ·

   Tenha um spec OpenAPI válido (.json, .yaml ou .yml) com pelo menos um servidor em servers[], URL HTTPS e porta 443 — outras portas são rejeitadas.

2. ·

   Rode o comando informando --openapi, --name e --out (obrigatórios neste modo):

   php artisan mcp:pack-app --openapi=spec.json \
     --name=minha-api \
     --label="Minha API" \
     --out=minha-api.adapp

3. ·

   Se o spec não tiver servers[0].url utilizável, informe o endpoint manualmente:

   php artisan mcp:pack-app --openapi=spec.json \
     --name=minha-api --label="Minha API" --out=minha-api.adapp \
     --endpoint=https://api.exemplo.com

4. ·

   O comando gera manifest.json (com transport: openapi) + openapi.json dentro do ZIP. As tools não são materializadas no pacote — só serão derivadas no momento do import.

OpenAPI → tools

No import, o conversor deriva uma tool para cada combinação path + método HTTP:

• Nome da tool: usa operationId quando presente; senão o fallback é metodo_path (slug do path template, ex.: get_v1_test).
• inputSchema: montado a partir de parameters (path/query/header) + requestBody (application/json).
• required_secrets: derivados dos security schemes do spec, no formato { key, label, required }.
• http_binding: gerado automaticamente por tool (ver Manifesto → http_binding).

Resolução de $ref no spec é só local (#/components/...) — referências externas não são seguidas — com profundidade máxima de 10 níveis, como proteção anticiclo.

Regras de endpoint e porta

O(s) servidor(es) em servers[] do spec precisam respeitar:

• URL HTTPS obrigatória.
• Porta 443, OU qualquer porta ≥ 1024 que não esteja na blocklist.
• Portas < 1024 são bloqueadas.
• Blocklist explícita, independente da faixa: 8080, 8443, 9090, 9200, 5432, 6379, 11211.

Security schemes suportados

Suportado	Rejeitado (422)
apiKey (em header ou query)	oauth2
http com bearer	openIdConnect
http com basic	apiKey em cookie

Cada scheme suportado vira uma entrada em required_secrets ({ key, label, required }) e o credential_ref da tool aponta para ela (ex.: "required_secrets[0].key").

Ícone

Ícones não são baixados por URL — isso é uma decisão de segurança para evitar SSRF durante o empacotamento. Só arquivos locais com extensão png, jpg, jpeg ou webp são embarcados no pacote; caso contrário, manifest.icon fica null.

Próximos passos

• Importar um .adapp — como publicar o pacote gerado no catálogo global.
• Templates e exemplos — receita fim-a-fim (gerar → empacotar → importar).