funifier-mcp 0.3.12 → 0.3.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "funifier-mcp",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "description": "Funifier AI toolkit — MCP server, API client, and Claude Code skills for the Funifier gamification platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/funifier/references/create-aggregate.md

@@ -63,6 +63,8 @@ If search returns insufficient results, read these directly:
 
 ## Steps
 
+> **Prepared aggregate** = pipeline MongoDB salvo na plataforma com `_id` e executado por ID via `POST /v3/find/<id>`, com parâmetros dinâmicos (`"$param:nome"`). Diferente do aggregate **ad-hoc** (`POST /v3/database/{collection}/aggregate`), usado para testar pipelines.
+
 ### Coleções principais
 
 | Coleção | Conteúdo chave |
@@ -148,3 +150,29 @@ funifier_save type=aggregate payload=<json>
 ```
 funifier_list type=aggregate search=<titulo>
 ```
+
+### 6. Executar o Prepared Aggregate
+
+**Endpoint correto:** `POST /v3/find/<id>` com os parâmetros no corpo JSON.
+
+> ⚠️ NÃO use `GET /v3/database/aggregate/{id}` — retorna null/405 silenciosamente, sem mensagem de erro. O endpoint de execução foge do padrão CRUD da plataforma.
+
+Via MCP (`params` é uma string JSON):
+```
+funifier_execute type=aggregate id=<id> params={"player":"abc"}
+```
+
+Via frontend:
+```js
+api.post('/v3/find/<id>', { player: 'abc' })
+```
+
+| Regra | Detalhe |
+|-------|---------|
+| Método HTTP | POST obrigatório |
+| Params | No corpo JSON — não na query string |
+| Substituição | Cada chave do corpo substitui `"$param:<chave>"` no pipeline diretamente |
+| `context` no Groovy | Só expõe o player autenticado — `context.get("outro")` retorna `null` |
+| Script vazio | Se o pipeline só usa `"$param:nome"`, o `script` pode ser `""` — não precisa de `prepare()` |
+
+Se o resultado vier vazio ou inesperado: `GET /v3/find/<id>/params` lista os params que o pipeline espera, e `POST /v3/prepared/aggregate/<id>/analyze` (mesmo corpo da execução) retorna outputs/exceções do script e o resultado de cada etapa do pipeline (`aggregate_step_N`) — veja `references/debug.md`.

package/skills/funifier/references/debug.md

@@ -34,7 +34,8 @@ If search returns insufficient results, read these directly:
 |---|---|
 | Trigger, Scheduler | `funifier_logs type=trigger id=<_id>` / `funifier_logs type=scheduler id=<_id>` |
 | Challenge, Level, Action | `funifier_get type=<type> id=<_id>` — verificar campos |
-| Aggregate | Testar via `POST /v3/database/<collection>/aggregate` |
+| Aggregate ad-hoc | Testar via `POST /v3/database/<collection>/aggregate` |
+| Prepared aggregate | `GET /v3/find/<id>/params` (params esperados) e `POST /v3/prepared/aggregate/<id>/analyze` (outputs/exceções do script + resultado de cada etapa do pipeline em `aggregate_step_N`) |
 | Frontend auth | Verificar role scope inclui `database` se usar `/v3/database` |
 
 ### Problemas comuns
@@ -49,6 +50,8 @@ If search returns insufficient results, read these directly:
 | `/v3/database` retorna vazio | Scope `database` ausente na role | Adicionar `database` ao scope via Security |
 | Filtro por data não encontra registros | Campo foi salvo como string ISO ou parâmetro ISO foi usado dentro de `$date` sem normalização | Salvar como `{ "$date": "<ISO UTC>" }`; em prepared aggregate converter ISO com `DateUtil.parse` no script |
 | Prepared aggregate com data absoluta falha/retorna vazio | `"$param:start"` dentro de `{ "$date": ... }` recebeu string ISO | Converter no `script` para `Date` e usar `"$gte":"$param:start"` diretamente |
+| Prepared aggregate retorna null/405 sem erro | Execução via `GET /v3/database/aggregate/{id}` — endpoint errado | Executar com `POST /v3/find/<id>`, params no corpo JSON |
+| Prepared aggregate retorna vazio | Nome de param divergente ou etapa do pipeline filtra tudo | `GET /v3/find/<id>/params` para conferir nomes; `POST /v3/prepared/aggregate/<id>/analyze` e achar a primeira `aggregate_step_N` vazia |
 
 ---
 

package/skills/funifier/references/help.md

@@ -28,7 +28,7 @@ If search returns insufficient results, read these directly:
 |---|---|
 | Criar trigger com Groovy | `references/create-trigger.md` |
 | Criar scheduler/cron job | `references/create-scheduler.md` |
-| Criar aggregate/relatório | `references/create-aggregate.md` |
+| Criar prepared aggregate (relatório/consulta salva) | `references/create-aggregate.md` |
 | Criar desafio/missão | `references/create-challenge.md` |
 | Criar ação rastreável | `references/create-action.md` |
 | Criar sistema de pontos | `references/create-point.md` |