funifier-mcp 0.3.18 → 0.3.20

package/skills/funifier/references/manage-player.md

@@ -80,3 +80,10 @@ GET /v3/player/<_id>/status
 ```
 GET /v3/team/<team_id>/member/add/<player_id>
 ```
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| Player is the entity class with _id, name, email, teams, extra fields in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/player/Player.java:Player |
+| PlayerManager handles player CRUD, authentication, and status queries in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/player/PlayerManager.java:PlayerManager |

package/skills/funifier/references/manage-team.md

@@ -74,3 +74,9 @@ GET /v3/team/sales/status
 ```
 GET /v3/team/sales/member/remove/tom
 ```
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+| Team is the entity class for player groups with _id, name, members, owner fields in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/team/Team.java:Team |

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

@@ -0,0 +1,111 @@
+# funifier-query-aggregate
+
+Run an ad-hoc MongoDB aggregate (one-off query) on a Funifier collection via POST /v3/database/{collection}/aggregate — for reports and exploration, without saving a resource
+
+---
+
+## Before starting — find relevant docs
+
+Use the `funifier_search_docs` MCP tool to load only what you need:
+
+```
+funifier_search_docs "aggregate mongodb pipeline query report ad-hoc consulta"
+```
+
+Then read the most relevant results with `funifier_read_doc path=<path>`.
+
+## Primary docs for this skill
+
+If search returns insufficient results, read these directly:
+
+- `funifier_read_doc path=guides/aggregates`
+- `funifier_read_doc path=guides/database-access`
+- `funifier_read_doc path=modules/database`
+
+## Steps
+
+> **Aggregate ad-hoc** = uma consulta **pontual** executada direto numa coleção via `POST /v3/database/{collection}/aggregate`, com o pipeline no corpo. Sem `_id`, sem salvar, sem `$param`, sem `script`. Use para relatórios e exploração. Se você precisa de um pipeline **salvo, parametrizado e reutilizável** (dashboards, `POST /v3/find/<id>`), use a skill `funifier-create-aggregate` (prepared aggregate).
+
+### 1. Definir a consulta
+
+- Qual coleção tem os dados? (ver tabela abaixo)
+- Qual o filtro (`$match`), agrupamento (`$group`), ordenação (`$sort`) e limite (`$limit`)?
+- Precisa juntar coleções? (`$lookup` — ver relações abaixo)
+
+### Coleções principais e relações (para `$lookup`)
+
+| Coleção | Relação-chave |
+|---|---|
+| `player` | `_id` é a ponta de `userId`/`player` — `name`, `teams`, `extra` |
+| `action_log` | `userId` → `player._id`; `actionId` → `action._id` — `attributes`, `time` |
+| `achievement` | `player` → `player._id`; `item` → coleção do `type` (0=Point, 1=Challenge, 2=VirtualGood, 3=Level) |
+| `challenge` | `_id` referenciado por `achievement.item` (type 1) |
+| `catalog_item` | `_id` referenciado por `achievement.item` (type 2) |
+| `point_category` | `_id` referenciado por `achievement.item` (type 0) |
+
+> Em `achievement`, junte por `$player`/`$item` — **não** por `_id` (senão o `$lookup` volta vazio). Campos completos das coleções: `funifier_read_doc path=guides/java-entities`.
+
+### 2. Operadores suportados
+
+`$match`, `$group`, `$sort`, `$limit`, `$lookup`, `$project`, `$unwind`, `$addFields`, `$count`.
+
+### 3. Filtros por data
+
+A gramática de expressões de data Funifier (`{"$date": "-0M-"}` = início do mês, `-0M+` = fim, `-1d-`, ISO-8601, millis) é detalhada em `aggregates.md` §4 (**dono único** das expressões `$date`) — leia com `funifier_read_doc path=guides/aggregates`. Não reescreva a gramática aqui.
+
+> ⚠️ **Use `?strict=true`** no endpoint ad-hoc ao filtrar por data: sem ele, `Date` degrada para número e o `$match` por data falha. Exemplo: `{ "$match": { "time": { "$gte": {"$date": "-0M-"}, "$lte": {"$date": "-0M+"} } } }`.
+
+### 4. Antes de executar: índices e forma da query
+
+1. Liste os campos que dirigem o plano: filtros de `$match`, campos de `$sort`, e `localField`/`foreignField` de cada `$lookup` (atenção ao `foreignField` na coleção `from`).
+2. Cheque/crie índices: `funifier_index action=list collection=<coll>` para cada coleção tocada; crie os single-field faltantes com `funifier_index action=create`. Índice **composto** (ex.: `{player:1,time:-1}`) → o endpoint REST é single-field apenas; use o caminho Groovy `createIndex(...append...)` (ver skill `funifier-manage-indexes`). Não duplique a mecânica de índice aqui.
+3. Boas práticas: `$match` o mais cedo possível · reduza documentos com `$project`/`$match` **antes** do `$lookup` · `$sort` seguido imediatamente de `$limit` · cuidado com explosão de documentos do `$unwind` · garanta o `$lookup.foreignField` indexado.
+4. ⚠️ **Ad-hoc NÃO usa `allowDiskUse`** — um `$match`/`$sort` sem índice em coleção grande tende a ser lento ou falhar. (Prepared aggregate usa `allowDiskUse(true)`; ad-hoc não.)
+
+### 5. Executar
+
+Via MCP:
+```
+funifier_database action=aggregate collection=<coll> pipeline=<json-array>
+```
+
+Via API REST:
+```
+POST /v3/database/{collection}/aggregate?strict=true
+<json-array do pipeline no corpo>
+```
+
+> O GET de listagem (`GET /v3/database/{collection}`) **não ordena** — para ordenar, use sempre `$sort` num aggregate.
+
+### Exemplos
+
+**Top 10 jogadores com mais XP no mês atual** (coleção `achievement`):
+```json
+[
+  {"$match": {"type": 0, "item": "xp", "time": {"$gte": {"$date": "-0M-"}, "$lte": {"$date": "-0M+"}}}},
+  {"$group": {"_id": "$player", "total": {"$sum": "$total"}}},
+  {"$sort": {"total": -1}},
+  {"$lookup": {"from": "player", "localField": "_id", "foreignField": "_id", "as": "p"}},
+  {"$unwind": "$p"},
+  {"$project": {"_id": 1, "player": "$p.name", "total": 1}},
+  {"$limit": 10}
+]
+```
+
+**Jogadores distintos que executaram ações ontem** (coleção `action_log`):
+```json
+[
+  {"$match": {"time": {"$gte": {"$date": "-1d-"}, "$lte": {"$date": "-1d+"}}}},
+  {"$group": {"_id": "$userId"}},
+  {"$lookup": {"from": "player", "localField": "_id", "foreignField": "_id", "as": "p"}},
+  {"$project": {"_id": 1, "playerName": {"$first": "$p.name"}}}
+]
+```
+
+Mais exemplos prontos (médias, distintos, top-N por período) em `aggregates.md` §6 — `funifier_read_doc path=guides/aggregates`.
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+

package/skills/funifier/references/upload-file.md

@@ -89,3 +89,9 @@ funifier_save type=player payload=<json>
 ```
 DELETE /v3/upload/<upload_id>
 ```
+
+## Verified References
+
+| Claim | Status | Evidence |
+|-------|--------|----------|
+