Atende Direito · Docs

Tema

Templates e exemplos ​

Modelos prontos para copiar. Consulte O formato .adapp e Manifesto para a explicação de cada campo.

Template 1 — pacote http ​

Árvore de arquivos:

text
test-app.adapp (ZIP)
├── manifest.json
└── tools/
    └── test_tool.json

manifest.json:

json
{
  "format": "adapp/v1",
  "checksum": "sha256:<64 hex — gerado pelo empacotador>",
  "name": "test-app",
  "label": "Test App",
  "description": "App de teste",
  "category": "test",
  "icon": null,
  "transport": "http",
  "endpoint": "https://mcp.exemplo.com/v1",
  "required_secrets": null,
  "tools": [
    { "name": "test_tool", "inputSchema": { "type": "object", "properties": {} } }
  ]
}

tools/test_tool.json:

json
{
  "name": "test_tool",
  "description": "Test tool",
  "inputSchema": { "type": "object", "properties": {} },
  "required_secrets": null
}

Variante com http_binding e secret ​

Quando a tool precisa de autenticação, o arquivo em tools/ também carrega required_secrets e um http_binding (ver Manifesto → http_binding):

json
{
  "name": "crawl",
  "description": "Extrai conteúdo de uma URL",
  "inputSchema": {
    "type": "object",
    "properties": {
      "start_url": { "type": "string" },
      "limit": { "type": "integer" }
    },
    "required": ["start_url"]
  },
  "required_secrets": [
    { "key": "FIRECRAWL_API_KEY", "label": "Chave de API do Firecrawl", "required": true }
  ],
  "http_binding": {
    "version": "v1",
    "method": "POST",
    "path": "/v1/crawl",
    "server": "https://api.exemplo.com",
    "params": { "start_url": "body", "limit": "query" },
    "auth": {
      "type": "apiKey",
      "in": "header",
      "name": "X-API-Key",
      "credential_ref": "required_secrets[0].key"
    }
  }
}

Template 2 — pacote openapi ​

Árvore de arquivos:

text
openapi-app.adapp (ZIP)
├── manifest.json
└── openapi.json

manifest.json:

json
{
  "format": "adapp/v1",
  "checksum": "sha256:<64 hex>",
  "name": "openapi-app",
  "label": "OpenAPI App",
  "description": "App OpenAPI de teste",
  "category": "test",
  "icon": null,
  "transport": "openapi",
  "endpoint": "https://api.exemplo.com",
  "required_secrets": null
}

openapi.json — spec mínimo que gera uma tool testGet:

json
{
  "openapi": "3.0.0",
  "info": { "title": "Test API", "version": "1.0.0" },
  "servers": [{ "url": "https://api.exemplo.com" }],
  "paths": {
    "/v1/test": {
      "get": { "operationId": "testGet", "summary": "Test endpoint" }
    }
  }
}

Receita fim-a-fim ​

  1. Gerar/ter o spec ou catálogo de origem. Um McpCatalog já cadastrado ou um spec OpenAPI válido com servers[] em HTTPS na porta 443.

  2. Empacotar:

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

  3. Importar:

    bash
    curl -X POST https://SEU_HOST/api/mcp/apps/import \
  -H "Authorization: Bearer $TOKEN" \
  -F "package=@minha-api.adapp"

  4. Preencher os required_secrets pendentes retornados na resposta do import, para que o servidor gerado fique pronto para uso.

Checklist de validação antes de importar ​

  • [ ] manifest.json tem format: "adapp/v1".
  • [ ] name é um slug válido (^[a-z0-9_-]{1,100}$).
  • [ ] transport é http, sse ou openapi (nunca stdio_curated).
  • [ ] endpoint é HTTPS e não aponta para IP privado/loopback/link-local.
  • [ ] Pacote gerado por mcp:pack-app — checksum nunca editado à mão.
  • [ ] Ícone (se houver) é PNG/JPG/JPEG/WEBP e tem no máximo 512 KB.
  • [ ] Arquivo final tem extensão .adapp e no máximo 20 MB.

Veja os detalhes de cada guard em Importar um .adapp → Segurança e limites.

Saiba mais ​