funifier-mcp 0.3.21 → 0.4.0

package/dist/mcp/tools/list-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"list-tools.js","sourceRoot":"","sources":["../../../src/mcp/tools/list-tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"list-tools.js","sourceRoot":"","sources":["../../../src/mcp/tools/list-tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "funifier-mcp",
-  "version": "0.3.21",
+  "version": "0.4.0",
   "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

@@ -59,6 +59,7 @@ 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=guides/explain-diagnostics`
 - `funifier_read_doc path=modules/database`
 
 ## Steps
@@ -191,10 +192,14 @@ O `mode=analyze` é uma **inspeção (dry-run)** — compila/roda o `script`, ap
 
 Diagnóstico: resultado de `mode=run` vazio **ou** recurso com `script` não-vazio → rode `mode=analyze` e leia `script_exceptions` (script quebrado) e `aggregate_step_3` (se um param virou `null`, o `$match` não casa nada — isso distingue "script quebrado" de "resultado legitimamente vazio").
 
-> ⚠️ NÃO execute via `GET /v3/database/aggregate/{id}` — retorna null/405 silenciosamente. A execução é `POST /v3/find/<id>` (corpo JSON, nunca query string). Via frontend: `api.post('/v3/find/<id>', { player: 'abc' })`.
+### 10. Validar performance (recomendado)
+
+O `aggregate_step_3` do `mode=analyze` é o pipeline **já resolvido** (com `$param` substituído) — é exatamente o que roda no Mongo, então é o que se deve explicar. Jogue-o no explain:
+
+```
+funifier_db_explain collection=<coll> pipeline=<aggregate_step_3> verbosity=queryPlanner
+```
 
-## Verified References
+O `queryPlanner` **não executa** a query — só revela `IXSCAN` vs `COLLSCAN` (barato: 1 execução de scheduler). Se der `COLLSCAN` no `$match`/`$sort` inicial, crie o índice (§7) e revalide. Use `verbosity=executionStats` só para os números reais de `totalDocsExamined` vs `nReturned`. Como os valores de `$param` mudam o filtro efetivo, valide com params **representativos**. Guia: `funifier_read_doc path=guides/explain-diagnostics`.
 
-| Claim | Status | Evidence |
-|-------|--------|----------|
-| DatabaseManager provides MongoDB connection and collection access for aggregate queries in Groovy scripts | ✓ verified | Class:src/main/java/com/funifier/engine/database/DatabaseManager.java:DatabaseManager |
+> ⚠️ NÃO execute via `GET /v3/database/aggregate/{id}` — retorna null/405 silenciosamente. A execução é `POST /v3/find/<id>` (corpo JSON, nunca query string). Via frontend: `api.post('/v3/find/<id>', { player: 'abc' })`.

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

@@ -113,11 +113,3 @@ Filtros combináveis em `$match`: `user`/`login` (ator), `type` (`studio`/`playe
 ### 6. Exclusão (cuidado)
 
 `funifier_delete type=audit id=<id>` remove a config **e todos os seus logs em cascata**. Confirme com o usuário antes.
-
-## Verified References
-
-| Claim | Status | Evidence |
-|-------|--------|----------|
-| Audit config fields are _id, title, active, entity, event, clean, type with event constants create/update/delete and type constants studio/player/all | ✓ verified | Class:src/main/java/com/funifier/engine/audit/Audit.java:Audit |
-| AuditManager.log only writes an AuditLog when an active Audit matches entity+event and the config type matches the operation origin | ✓ verified | Class:src/main/java/com/funifier/engine/audit/AuditManager.java:AuditManager |
-| clearExpiredLogs purges audit_log entries older than each config's clean retention and is invoked from AsyncProcessor | ✓ verified | Method:src/main/java/com/funifier/engine/audit/AuditManager.java:AuditManager.clearExpiredLogs#0 |

package/skills/funifier/references/create-custom-object.md

@@ -89,9 +89,3 @@ DELETE /v3/database/car__c?q=_id:'car001'
 ### 7. Usar em triggers
 
 Para executar trigger em eventos da coleção, use `entity: "car__c"` no payload do trigger.
-
-## Verified References
-
-| Claim | Status | Evidence |
-|-------|--------|----------|
-| DatabaseManager provides MongoDB connection for custom __c collection CRUD operations in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/database/DatabaseManager.java:DatabaseManager |

package/skills/funifier/references/date-handling.md

@@ -170,9 +170,3 @@ Não coloque o parâmetro convertido para `Date` dentro de `{ "$date": "$param:s
 - [ ] Em prepared aggregate, usar `"$param:nome"` exatamente como string.
 - [ ] Para data absoluta em prepared aggregate, converter no `script` com `DateUtil.parse`, validar `null`, e substituir o `Date` diretamente em `$gte`/`$lte`.
 - [ ] Testar aggregate direto antes de salvar como prepared aggregate.
-
-## Verified References
-
-| Claim | Status | Evidence |
-|-------|--------|----------|
-

package/skills/funifier/references/debug.md

@@ -9,7 +9,7 @@ Debug a Funifier resource — systematic diagnosis of triggers, schedulers, aggr
 Use the `funifier_search_docs` MCP tool to load only what you need:
 
 ```
-funifier_search_docs "debug error log exception timeout groovy stack trace fix"
+funifier_search_docs "debug error log exception timeout groovy stack trace fix explain slow index collscan"
 ```
 
 Then read the most relevant results with `funifier_read_doc path=<path>`.
@@ -24,6 +24,7 @@ If search returns insufficient results, read these directly:
 - `funifier_read_doc path=guides/trigger-examples`
 - `funifier_read_doc path=modules/scheduler`
 - `funifier_read_doc path=guides/aggregates`
+- `funifier_read_doc path=guides/explain-diagnostics`
 - `funifier_read_doc path=modules/public`
 
 ## Steps

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

@@ -83,9 +83,3 @@ Get the index name from `action=list`. The `_id_` index cannot be dropped.
 | Unique email | `{"email": 1}` (uniqueness enforced by MongoDB, not this API) |
 
 For a composite (e.g. `{player: 1, time: -1}` to back filter+sort in one plan), use the Groovy/trigger path shown in the Limitation section — not this tool.
-
-## Verified References
-
-| Claim | Status | Evidence |
-|-------|--------|----------|
-

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

@@ -20,6 +20,7 @@ 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=guides/explain-diagnostics`
 - `funifier_read_doc path=modules/database`
 
 ## Steps
@@ -61,6 +62,7 @@ A gramática de expressões de data Funifier (`{"$date": "-0M-"}` = início do m
 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. **Confirmar o plano real** (recomendado quando o passo 2 achou campo de `$match`/`$sort` sem índice, ou a coleção é grande): `funifier_db_explain collection=<coll> pipeline=<json> verbosity=queryPlanner`. O `queryPlanner` **não executa** a query — só revela `IXSCAN` vs `COLLSCAN` (barato: 1 execução de scheduler). Se o estágio vencedor for `COLLSCAN` sobre o `$match`/`$sort` inicial, crie o índice (passo 2) e revalide. Suba para `verbosity=executionStats` só quando quiser `totalDocsExamined` real (aí sim roda a query). Detalhes: `funifier_read_doc path=guides/explain-diagnostics`.
 
 ### 5. Executar
 
@@ -103,9 +105,3 @@ POST /v3/database/{collection}/aggregate?strict=true
 ```
 
 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 |
-|-------|--------|----------|
-