---
title: Templates e exemplos
---

# Templates e exemplos

Modelos prontos para copiar. Consulte [O formato .adapp](./formato) e [Manifesto](./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](./manifesto#http-binding-v1)):

```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

<Passos>
<Passo>

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

</Passo>
<Passo>

**Empacotar:**

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

</Passo>
<Passo>

**Importar:**

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

</Passo>
<Passo>

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

</Passo>
</Passos>

## 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](./importar#seguranca-e-limites).

## Saiba mais

- [O formato .adapp](./formato) — estrutura do pacote e ciclo de vida.
- [Manifesto (manifest.json)](./manifesto) — referência completa dos campos.
- [Empacotar um .adapp](./empacotar) — como gerar o pacote com `mcp:pack-app`.
- [Importar um .adapp](./importar) — como publicar o pacote no catálogo global.