funifier-mcp 0.3.20 → 0.3.22

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.20",
+  "version": "0.3.22",
   "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/SKILL.md

@@ -70,6 +70,7 @@ Then read a result with `funifier_read_doc path=<path>`.
 | Upload files to Funifier — images and documents for player avatars, challenge resources, and visual assets; use when adding media to the platform, not for CSV data import (use funifier-import-csv) or static frontend hosting (use funifier-implement-frontend) | `references/upload-file.md` |
 | Create, list, and drop MongoDB single-field indexes on Funifier collections via the REST API. Composite (multi-field) indexes are NOT supported by this endpoint — see Limitation section. | `references/manage-indexes.md` |
 | Cross-check a project's Funifier API calls against the live security document — scan code for usage, build an evidence-backed manifest, run the deterministic audit engine, and report missing scopes, excess tokens, and static danger findings; use when debugging 401s, auditing minimum privilege, or verifying permissions before deploying; audit is read-only and never changes any configuration | `references/audit-permissions.md` |
+| Use the server-side utility classes from com.funifier.engine.util in Groovy triggers, schedulers, and public endpoints — validates CPF, encrypts fields with AES/BCrypt/PGP, renders Mustache templates, evaluates inline expressions, computes object diffs/changelogs, converts JSON, generates Excel, makes HTTP calls, and handles files and pagination | `references/server-utils.md` |
 
 ## Documented Modules
 

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/help.md

@@ -79,9 +79,3 @@ Baseado na tabela acima, instrua o usuário a usar a skill específica.
 ### 4. Se não encontrar skill específica
 
 Consulte `funifier_read_doc path=index` e leia o módulo relevante diretamente.
-
-## Verified References
-
-| Claim | Status | Evidence |
-|-------|--------|----------|
-| Achievement is the core entity class representing all gamification rewards in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/achievement/Achievement.java:Achievement |

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

package/skills/funifier/references/server-utils.md

@@ -0,0 +1,94 @@
+# funifier-server-utils
+
+Use the server-side utility classes from com.funifier.engine.util in Groovy triggers, schedulers, and public endpoints — validates CPF, encrypts fields with AES/BCrypt/PGP, renders Mustache templates, evaluates inline expressions, computes object diffs/changelogs, converts JSON, generates Excel, makes HTTP calls, and handles files and pagination
+
+---
+
+## Formato do payload (obrigatório)
+
+Funifier armazena código como **strings JSON escapadas**. Ao montar o payload do `funifier_save`:
+
+- **Quebra de linha** → `\n` (nunca newline literal dentro da string)
+- **Aspas duplas** dentro do código → `\"`
+- **Backslash** → `\\` (regex `\b` vira `\\b`; dentro de Groovy com string-building pode exigir `\\\\b`)
+- **Tab** → `\t` (se usar)
+- **Pipelines de aggregate** vão como **string JSON** (não objeto aninhado) — serialize o array inteiro
+
+A regra prática: monte o objeto em JavaScript normalmente e passe por `JSON.stringify` — o MCP faz isso automaticamente quando você entrega o payload como JSON. **Nunca** cole código multilinha cru no meio do JSON.
+
+### Exemplo 1 — custom-page (html + angularjs script)
+
+```json
+{
+  "title": "Ciclos",
+  "slug": "studio/custom/ciclos",
+  "html": "<div class=\"row\">\n  <div class=\"col-md-12\">\n    <h2>Ciclos</h2>\n  </div>\n</div>\n",
+  "script": "$scope.all = [];\n$scope.loading = false;\n\n$scope.list = function () {\n  $scope.loading = true;\n};\n$scope.list();\n"
+}
+```
+
+### Exemplo 2 — aggregate preparado (pipeline JSON + script Groovy)
+
+```json
+{
+  "_id": "extrato",
+  "title": "Extrato de Pontos",
+  "collection": "extrato",
+  "aggregate": "[\n  {\n    \"$match\": { \"player\": \"$param:player\" }\n  },\n  {\n    \"$sort\": { \"time\": -1 }\n  }\n]",
+  "script": "void prepare(aggregations, params) {\n    if (context.get(\"player\") != null) {\n        params.put(\"player\", context.get(\"player\"));\n    } else {\n        params.put(\"player\", \"NAO_EXISTE\");\n    }\n}\n"
+}
+```
+
+Note que `aggregate` é uma **string** contendo JSON serializado (com `\n` e `\"` escapados), **não** um array nativo. Mesma regra vale para `script` em triggers/schedulers/aggregates e `html`/`script` em custom-pages.
+
+---
+
+## Before starting — find relevant docs
+
+Use the `funifier_search_docs` MCP tool to load only what you need:
+
+```
+funifier_search_docs "cpf cnpj validar validate cpf-util aes encrypt decrypt criptografar criptografia bcrypt hash senha password pgp pgpcrypt rsa asymmetric totp otp 2fa qrcode google-authenticator mustache template render handlebars expression inline formula avaliar diff changelog auditoria comparar compare json serialize deserialize jsonutil excel xlsx spreadsheet planilha relatorio currency moeda formatar format http get post requisicao external url read-url pagination paginar paginacao paginate file stream arquivo util helper utility server-side groovy"
+```
+
+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/server-utils`
+- `funifier_read_doc path=guides/triggers-guide`
+- `funifier_read_doc path=guides/java-managers`
+
+## Steps
+
+### 1. Understand the requirement
+
+Ask the user what they want to create or accomplish. Gather:
+- The name/title
+- The purpose and behavior
+- Any specific configuration or constraints
+
+### 2. Search for relevant documentation
+
+Run the lexical search (command shown above) and read the returned files.
+
+### 3. Check existing resources (if MCP available)
+
+Use `funifier_list` with the relevant type and a `search` parameter to see
+if a similar resource already exists. Never list all resources without a search term.
+
+### 4. Design and confirm
+
+Based on the docs, outline the configuration to the user and confirm before saving.
+
+### 5. Create or update
+
+Use `funifier_save` with the appropriate type and a JSON payload to create or
+update the resource. If MCP is unavailable, show the complete JSON for manual use.
+
+### 6. Validate
+
+Use `funifier_logs` (for triggers/schedulers) or `funifier_get` to confirm
+the resource was saved correctly and executed without errors.