funifier-mcp 0.2.24 → 0.2.26

package/skills/funifier-create-point/SKILL.md

@@ -48,35 +48,76 @@ If search returns insufficient results, read directly:
 
 ## Steps
 
-### 1. Understand the requirement
+### Rules — follow exactly, no exceptions
 
-Ask the user what they want to create or accomplish. Gather:
-- The name/title
-- The purpose and behavior
-- Any specific configuration or constraints
+**The single most important decision: which technique?**
 
-### 2. Search for relevant documentation
+| Point type | `techniques` | When to use |
+|---|---|---|
+| Normal (XP, score, karma) | `["GT01"]` | Progresso/ranking — jogador acumula, não transfere |
+| Trocável entre jogadores | `["GT75"]` | Jogadores podem transferir/enviar este ponto uns para os outros |
 
-Run the lexical search (command shown above) and read the returned files.
+Se jogadores podem trocar ou enviar este ponto entre si → **GT75**.
+Tudo o mais → **GT01**.
+Qualquer tipo de ponto pode ser usado na loja virtual — isso não influencia a escolha da técnica.
 
-### 3. Check existing resources (if MCP available)
+**_id format:** lowercase, no spaces (`xp`, `coin`, `karma`) — never `"Experience Points"` or `"XP Points"`.
 
-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.
+**Upsert:** POST with existing `_id` updates the point — never errors on duplicate.
 
-### 4. Design and confirm
+**Create points BEFORE challenges and leaderboards that reference them.**
 
-Based on the docs, outline the configuration to the user and confirm before saving.
+---
+
+### 1. Determine the type
+
+Ask (or infer from context): is this point spendable in a store?
+- Yes → `GT75`
+- No → `GT01`
+
+### 2. Check if it already exists
+
+```
+funifier_list type=point search=<name or _id>
+```
+
+If it exists and has the correct technique, stop.
+
+### 3. Build the payload
 
-### 5. Create or update
+Normal point (GT01):
+```json
+{
+  "_id": "xp",
+  "category": "Experience Points",
+  "shortName": "XP",
+  "techniques": ["GT01"]
+}
+```
+
+Exchangeable point (GT75):
+```json
+{
+  "_id": "coin",
+  "category": "Coins",
+  "shortName": "Coins",
+  "techniques": ["GT75"]
+}
+```
 
-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.
+### 4. Save
 
-### 6. Validate
+```
+funifier_save type=point payload=<json>
+```
+
+### 5. Validate
+
+```
+funifier_list type=point search=<_id>
+```
 
-Use `funifier_logs` (for triggers/schedulers) or `funifier_get` to confirm
-the resource was saved correctly and executed without errors.
+Do NOT use `funifier_logs` — that is only for triggers and schedulers.
 
 ## MCP
 
@@ -84,3 +125,4 @@ If Funifier MCP tools are available (`funifier_list`, `funifier_save`, `funifier
 - Use MCP for live server data
 - Use docs for correct patterns and syntax
 - Never learn patterns from existing live resources — docs are authoritative
+- **For any new Funifier task, check `/funifier-index` first** — there may be a skill with the correct enums, examples, and workflow already defined

package/skills/funifier-create-quiz/SKILL.md

@@ -84,3 +84,4 @@ If Funifier MCP tools are available (`funifier_list`, `funifier_save`, `funifier
 - Use MCP for live server data
 - Use docs for correct patterns and syntax
 - Never learn patterns from existing live resources — docs are authoritative
+- **For any new Funifier task, check `/funifier-index` first** — there may be a skill with the correct enums, examples, and workflow already defined

package/skills/funifier-create-scheduler/SKILL.md

@@ -124,3 +124,4 @@ If Funifier MCP tools are available (`funifier_list`, `funifier_save`, `funifier
 - Use MCP for live server data
 - Use docs for correct patterns and syntax
 - Never learn patterns from existing live resources — docs are authoritative
+- **For any new Funifier task, check `/funifier-index` first** — there may be a skill with the correct enums, examples, and workflow already defined

package/skills/funifier-create-trigger/SKILL.md

@@ -73,7 +73,7 @@ Note que `aggregate` é uma **string** contendo JSON serializado (com `\n` e `\"
 Run lexical search to load only what you need:
 
 ```bash
-npx funifier-mcp search "trigger event groovy java before_create after_win entity script" --skill funifier-create-trigger
+npx funifier-mcp search "trigger event groovy java before_create after_win entity script achievement_type context_extra bulk csv after_bulk before_bulk" --skill funifier-create-trigger
 ```
 
 Read only files returned with score > 0.5 (this threshold is printed in the search output).
@@ -86,38 +86,128 @@ If search returns insufficient results, read directly:
 - `datasource-funifier-docs/knowledge/guides/triggers-guide.md`
 - `datasource-funifier-docs/knowledge/guides/java-entities.md`
 - `datasource-funifier-docs/knowledge/guides/java-managers.md`
+- `datasource-funifier-docs/knowledge/guides/trigger-examples.md`
 
 ## Steps
 
-### 1. Understand the requirement
+## ⚠ Regra crítica: triggers não impedem persistência via throw
 
-Ask the user what they want to create or accomplish. Gather:
-- The name/title
-- The purpose and behavior
-- Any specific configuration or constraints
+O Funifier **sempre salva o documento** antes de executar o trigger.
 
-### 2. Search for relevant documentation
+- `before_create` → enriquecimento apenas (normalizar, preencher defaults)
+- Rejeitar criação → usar `after_create`: validar → se inválido:
+  ```java
+  database.delete(entity._id, "collection__c");
+  entity.clear();
+  entity.put("message", "motivo");
+  return;
+  ```
+- Para lógica complexa, use `BusinessException` interna (capturada dentro do trigger, não propaga para a plataforma).
 
-Run the lexical search (command shown above) and read the returned files.
+---
+
+## Referência rápida — constantes e campos
+
+| Constante | Valor | Uso |
+|-----------|-------|-----|
+| `Achievement.TYPE_POINT` | `0` | Ponto acumulado |
+| `Achievement.TYPE_CHALLENGE` | `1` | Desafio completado |
+| `Achievement.TYPE_VIRTUAL_GOOD` | `2` | Item de catálogo |
+| `Achievement.TYPE_LEVEL` | `3` | Nível alcançado |
+
+**ActionLog** (entity em triggers de `action`):
+`entity.actionId`, `entity.userId`, `entity.attributes` (Map), `entity.time`, `entity.id`
+
+**Player** (entity em triggers de `player`):
+`entity._id`, `entity.name`, `entity.email`, `entity.extra` (Map), `entity.teams`
 
-### 3. Check existing resources (if MCP available)
+**context.extra** (disponível em `before_win` / `before_create` / `after_create`):
+- `context.extra.parentAchievement.id` / `.type` / `.item` / `.player`
+- `context.extra.parentActionLog.id` / `.actionId` / `.userId` / `.attributes`
+- `context.extra.originActionLog` — action log raiz da cadeia
 
-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
+## Leituras obrigatórias (não condicionais — leia antes de escrever qualquer Groovy)
 
-Based on the docs, outline the configuration to the user and confirm before saving.
+- `datasource-funifier-docs/knowledge/guides/java-entities.md`
+- `datasource-funifier-docs/knowledge/guides/java-managers.md`
+- `datasource-funifier-docs/knowledge/guides/trigger-examples.md`
+
+---
 
-### 5. Create or update
+## Steps
+
+### 1. Entender o requisito
+
+Perguntar (ou inferir do contexto):
+- Nome/descrição da trigger
+- Qual entidade e evento? (ver tabela abaixo)
+- Qual comportamento esperado?
+
+**Combinações mais comuns:**
+
+| entity | event | Quando usar |
+|--------|-------|-------------|
+| `action` | `before_win` | Reagir a uma ação antes de registrar a conquista |
+| `action` | `after_win` | Efeito colateral após ação (ex: creditar pontos para outro jogador) |
+| `achievement` | `before_create` | Enriquecer conquista com dados de origem (`context.extra`) |
+| `player` | `after_create` | Inicializar campos customizados ao criar jogador |
+| `player` | `before_update` | Normalizar campos antes de salvar atualização |
+| `custom__c` | `before_create` | Normalizar/enriquecer documento customizado |
+| `custom__c` | `after_create` | Validar e rejeitar se inválido (delete + message) |
+| `custom__c` | `after_bulk` | Processar import em lote (entity é uma List) |
+
+### 2. Verificar se já existe
+
+```
+funifier_list type=trigger search=<nome>
+```
 
-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.
+Se existir e estiver correto, parar — não recriar.
 
-### 6. Validate
+### 3. Ler documentação obrigatória
+
+Leia os três arquivos listados acima antes de escrever qualquer código.
+Use também `datasource-funifier-docs/knowledge/guides/trigger-examples.md` para encontrar o padrão mais próximo do requisito.
+
+### 4. Escrever o script Groovy
+
+- Use os exemplos de `trigger-examples.md` como base
+- Prefira funções auxiliares para lógica reutilizável
+- Use `println` para debug (aparece nos logs)
+- Sempre verifique nulos antes de acessar campos
+
+### 5. Montar e salvar o payload
+
+O campo `script` deve ser uma string JSON escapada. Exemplo completo:
+
+```json
+{
+  "name": "Update Task Status",
+  "entity": "action",
+  "event": "before_win",
+  "active": true,
+  "script": "void trigger(event, entity, player, database) {\n    String taskId = entity.attributes.get(\"taskId\");\n    if (taskId != null) {\n        HashMap<String, Object> task = manager.getJongoConnection().getCollection(\"task__c\").findOne(\"{_id:#}\", taskId).as(HashMap.class);\n        if (task != null) {\n            task.put(\"status\", \"done\");\n            manager.getJongoConnection().getCollection(\"task__c\").save(task);\n        }\n    }\n}\n"
+}
+```
+
+Regras de escape no campo `script`:
+- Quebra de linha → `\n`
+- Aspas duplas → `\"`
+- Nunca cole código multilinha cru no JSON
+
+```
+funifier_save type=trigger payload=<json>
+```
+
+### 6. Validar via logs
+
+```
+funifier_logs type=trigger id=<_id>
+```
 
-Use `funifier_logs` (for triggers/schedulers) or `funifier_get` to confirm
-the resource was saved correctly and executed without errors.
+Confirme que não há erros de compilação ou execução. Se houver, leia o stack trace e corrija o script.
 
 ## MCP
 
@@ -125,3 +215,4 @@ If Funifier MCP tools are available (`funifier_list`, `funifier_save`, `funifier
 - Use MCP for live server data
 - Use docs for correct patterns and syntax
 - Never learn patterns from existing live resources — docs are authoritative
+- **For any new Funifier task, check `/funifier-index` first** — there may be a skill with the correct enums, examples, and workflow already defined

package/skills/funifier-create-virtual-good/SKILL.md

@@ -84,3 +84,4 @@ If Funifier MCP tools are available (`funifier_list`, `funifier_save`, `funifier
 - Use MCP for live server data
 - Use docs for correct patterns and syntax
 - Never learn patterns from existing live resources — docs are authoritative
+- **For any new Funifier task, check `/funifier-index` first** — there may be a skill with the correct enums, examples, and workflow already defined

package/skills/funifier-debug/SKILL.md

@@ -46,6 +46,7 @@ If search returns insufficient results, read directly:
 - `datasource-funifier-docs/knowledge/guides/java-libraries.md`
 - `datasource-funifier-docs/knowledge/modules/trigger.md`
 - `datasource-funifier-docs/knowledge/guides/triggers-guide.md`
+- `datasource-funifier-docs/knowledge/guides/trigger-examples.md`
 - `datasource-funifier-docs/knowledge/modules/scheduler.md`
 - `datasource-funifier-docs/knowledge/guides/aggregates.md`
 - `datasource-funifier-docs/knowledge/modules/public.md`
@@ -88,3 +89,4 @@ If Funifier MCP tools are available (`funifier_list`, `funifier_save`, `funifier
 - Use MCP for live server data
 - Use docs for correct patterns and syntax
 - Never learn patterns from existing live resources — docs are authoritative
+- **For any new Funifier task, check `/funifier-index` first** — there may be a skill with the correct enums, examples, and workflow already defined

package/skills/funifier-help/SKILL.md

@@ -83,3 +83,4 @@ If Funifier MCP tools are available (`funifier_list`, `funifier_save`, `funifier
 - Use MCP for live server data
 - Use docs for correct patterns and syntax
 - Never learn patterns from existing live resources — docs are authoritative
+- **For any new Funifier task, check `/funifier-index` first** — there may be a skill with the correct enums, examples, and workflow already defined

package/skills/funifier-implement-frontend/SKILL.md

@@ -87,3 +87,4 @@ If Funifier MCP tools are available (`funifier_list`, `funifier_save`, `funifier
 - Use MCP for live server data
 - Use docs for correct patterns and syntax
 - Never learn patterns from existing live resources — docs are authoritative
+- **For any new Funifier task, check `/funifier-index` first** — there may be a skill with the correct enums, examples, and workflow already defined

package/skills/funifier-index/SKILL.md

@@ -1,10 +1,18 @@
 ---
 name: funifier-index
-description: Entry point for all Funifier skills — routes to the right skill for any intent
+description: >
+  REQUIRED before any funifier_* MCP tool call — check this index first to find the matching skill.
+  Routes to the right skill for creating actions, challenges, points, leaderboards, triggers, schedulers, aggregates, quizzes, virtual goods, custom pages, and frontend implementation.
 ---
 
 # Funifier Index
 
+## ⚠ Rule
+
+**Before using any `funifier_*` MCP tool, check this list first.**
+If a skill matches the task, invoke it — skills contain the correct field values, enum tables, and examples that prevent common errors.
+Only proceed directly with MCP tools when no skill matches.
+
 ## Usage
 
 1. Identify what the user wants to do