funifier-mcp 0.2.26 → 0.2.28

package/skills/{funifier-create-action/SKILL.md → funifier/references/create-action.md}

@@ -1,32 +1,7 @@
----
-name: funifier-create-action
-description: Create a Funifier action — define trackable player behaviors with attributes
----
-
 # funifier-create-action
 
 Create a Funifier action — define trackable player behaviors with attributes
 
-## Persona e Qualidade de Código
-
-A partir de agora, atue como um **desenvolvedor de software sênior altamente experiente**, especializado em **geração de código limpo, legível e de fácil manutenção**. Suas soluções devem seguir rigorosamente as **boas práticas da indústria**, **padrões de projeto** e **arquiteturas modernas**, sempre **evitando overengineering**.
-
-### Ao lidar com qualquer código — seja refatorando ou criando do zero — siga este processo:
-
-1. **Analise cuidadosamente o problema ou o código existente.**
-2. **Raciocine passo a passo** antes de escrever qualquer linha de código.
-3. **Identifique problemas (em caso de refatoração) ou requisitos (em caso de código novo).**
-4. **Defina prioridades e estratégias com base em princípios sólidos de engenharia.**
-5. **Justifique tecnicamente cada decisão**, com base em fundamentos como:
-   - **SOLID**
-   - **DRY (Don't Repeat Yourself)**
-   - **KISS (Keep It Simple, Stupid)**
-   - **YAGNI (You Aren't Gonna Need It)**
-
-Só então prossiga com a implementação.
-
-> **Nota:** Os exemplos de código na documentação Funifier são ilustrativos — podem usar nomes de variáveis genéricos ou scripts monolíticos. Sempre melhore-os: use nomes descritivos, extraia métodos especializados para lógicas complexas e mantenha cada função com responsabilidade única.
-
 ---
 
 ## Before starting — find relevant docs
@@ -116,11 +91,3 @@ funifier_list type=action search=<_id>
 ```
 
 Do NOT use `funifier_logs` — that is only for triggers and schedulers.
-
-## MCP
-
-If Funifier MCP tools are available (`funifier_list`, `funifier_save`, `funifier_get`, `funifier_logs`):
-- 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/references/create-aggregate.md

@@ -0,0 +1,144 @@
+# funifier-create-aggregate
+
+Create a Funifier prepared aggregate — guided workflow for building MongoDB aggregate pipelines for reports and dashboards
+
+---
+
+## 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
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "aggregate mongodb pipeline report dashboard query prepared" --skill funifier-create-aggregate
+```
+
+Read only files returned with score > 0.5 (this threshold is printed in the search output).
+
+## Primary docs for this skill
+
+If search returns insufficient results, read directly:
+
+- `datasource-funifier-docs/knowledge/guides/aggregates.md`
+- `datasource-funifier-docs/knowledge/guides/database-access.md`
+- `datasource-funifier-docs/knowledge/modules/database.md`
+
+## Steps
+
+### Coleções principais
+
+| Coleção | Conteúdo chave |
+|---|---|
+| `achievement` | Conquistas — `type`: 0=Point, 1=Challenge, 2=VirtualGood, 3=Level |
+| `action_log` | Ações executadas — `actionId`, `userId`, `attributes`, `time` |
+| `player` | Jogadores — `_id`, `name`, `teams`, `extra` |
+| `challenge` | Desafios — `_id`, `challenge`, `rules`, `points` |
+| `point_category` | Tipos de ponto — `_id`, `category`, `shortName` |
+| `catalog_item` | Loja virtual — `_id`, `catalogId`, `name`, `requires` |
+
+### Expressões de data Funifier
+
+| Expressão | Significado |
+|---|---|
+| `{"$date": "-0d-"}` | Início do dia atual |
+| `{"$date": "-0M-"}` | Início do mês atual |
+| `{"$date": "-0M+"}` | Fim do mês atual |
+| `{"$date": "-0y-"}` | Início do ano atual |
+| `{"$date": "-1d-"}` | Início do dia anterior |
+
+---
+
+## Steps
+
+### 1. Identificar a necessidade
+
+- Qual collection tem os dados? (ver tabela acima)
+- Qual o filtro? (período, jogador, tipo de conquista)
+- Qual o agrupamento? (por jogador, por dia, por equipe)
+- Qual ordenação e limite?
+
+### 2. Verificar se já existe
+
+```
+funifier_list type=aggregate search=<titulo>
+```
+
+### 3. Construir e testar o pipeline
+
+Top 10 jogadores com mais pontos no mês:
+```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}
+]
+```
+
+Testar diretamente antes de registrar:
+```
+POST /v3/database/achievement/aggregate
+```
+
+### 4. Registrar como Prepared Aggregate
+
+```json
+{
+  "_id": "top_players_month",
+  "title": "Top Players Month",
+  "collection": "achievement",
+  "aggregate": "[{\"\$match\":{\"type\":0,\"item\":\"xp\"}},{\"\$group\":{\"_id\":\"\$player\",\"total\":{\"\$sum\":\"\$total\"}}},{\"\$sort\":{\"total\":-1}},{\"\$limit\":10}]",
+  "script": ""
+}
+```
+
+```
+funifier_save type=aggregate payload=<json>
+```
+
+### 5. Validar
+
+```
+funifier_list type=aggregate search=<titulo>
+```

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

@@ -0,0 +1,116 @@
+# funifier-create-challenge
+
+Create a Funifier challenge — missions with action rules and point rewards
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "challenge mission reward rules action points gamification" --skill funifier-create-challenge
+```
+
+Read only files returned with score > 0.5 (this threshold is printed in the search output).
+
+## Primary docs for this skill
+
+If search returns insufficient results, read directly:
+
+- `datasource-funifier-docs/knowledge/modules/challenge.md`
+- `datasource-funifier-docs/knowledge/modules/action.md`
+- `datasource-funifier-docs/knowledge/modules/point.md`
+
+## Steps
+
+### Regras críticas
+
+- **Dependências**: Actions e Points devem existir **antes** de criar o challenge
+- `techniques` é **obrigatório** — use `["GT35"]` (Quest List) na maioria dos casos
+- `range` é necessário quando há mais de uma rule
+
+### Referência rápida
+
+| Campo | Enum | Significado |
+|---|---|---|
+| `range` | `0` | Complete All (todas as rules) |
+| `range` | `1` | Complete Any (qualquer rule) |
+| `range` | `2` | Complete All in Order |
+| `rules[].operator` | `5` | >= (padrão — N ou mais vezes) |
+| `rules[].operator` | `1` | = (exatamente N vezes) |
+| `limitTimeScale` | `5` | Day | `6` = Week | `7` = Month |
+| `limitPerType` | `0` | Player | `1` = Team | `2` = Global |
+
+---
+
+## Steps
+
+### 1. Confirmar dependências
+
+```
+funifier_list type=action search=<actionId>
+funifier_list type=point search=<category>
+```
+
+### 2. Verificar se já existe
+
+```
+funifier_list type=challenge search=<nome>
+```
+
+### 3. Construir o payload
+
+Challenge simples:
+```json
+{
+  "challenge": "Watch Video",
+  "description": "Watch a video to earn 10 xp",
+  "techniques": ["GT35"],
+  "rules": [{ "actionId": "watch_video", "operator": 5, "total": 1 }],
+  "points": [{ "total": 10, "category": "xp", "operation": 0 }]
+}
+```
+
+Com filtro de atributo:
+```json
+{
+  "challenge": "Sell 10 Books",
+  "techniques": ["GT35"],
+  "rules": [{
+    "actionId": "sell",
+    "operator": 5,
+    "total": 10,
+    "filters": [{ "param": "product", "operator": 1, "value": "book" }]
+  }],
+  "points": [{ "total": 25, "category": "xp", "operation": 0 }]
+}
+```
+
+Com limite de frequência (1x por dia):
+```json
+{
+  "challenge": "Daily Check-in",
+  "techniques": ["GT35"],
+  "rules": [{ "actionId": "checkin", "operator": 5, "total": 1 }],
+  "points": [{ "total": 5, "category": "xp", "operation": 0 }],
+  "limitTotal": 1,
+  "limitPerType": 0,
+  "limitTimeAmount": 1,
+  "limitTimeScale": 5
+}
+```
+
+### 4. Salvar
+
+```
+funifier_save type=challenge payload=<json>
+```
+
+### 5. Validar
+
+```
+funifier_get type=challenge id=<_id>
+```
+
+Não use `funifier_logs` — isso é só para triggers e schedulers.

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

@@ -0,0 +1,98 @@
+# funifier-create-competition
+
+Create a Funifier competition — timed ranking contests with player enrollment, position-based rewards, and execution; use when you need player sign-up, prizes by finish position, or a scheduled end date, not when an always-on leaderboard is enough
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "competition contest ranking tournament enrollment rewards position gt26" --skill funifier-create-competition
+```
+
+Read only files returned with score > 0.5 (this threshold is printed in the search output).
+
+## Primary docs for this skill
+
+If search returns insufficient results, read directly:
+
+- `datasource-funifier-docs/knowledge/modules/competition.md`
+
+## Steps
+
+### Rules — follow exactly, no exceptions
+
+**Technique:** always `["GT26"]`.
+**`operation.type`:**
+- `1` = Count actions
+- `3` = Sum achievements (points) — most common
+
+**`period.expression`:** Funifier date syntax, e.g. `"-0M-;+1M+"` = current month.
+**Rewards by position:** use `extra.position_start` and `extra.position_ends` on each reward.
+**Execution:** automatic (`autoExecute: true`) or manual (`GET /v3/competition/:id/execute`).
+
+---
+
+### 1. Check dependencies
+
+```
+funifier_list type=point search=<metric>
+funifier_list type=action search=<metric>
+```
+
+### 2. Check if competition already exists
+
+```
+funifier_list type=competition search=<title>
+```
+
+### 3. Build the payload
+
+```json
+{
+  "title": "Sales Race",
+  "description": "Top sellers of the month",
+  "period": { "expression": "-0M-;+1M+" },
+  "maxWinners": 3,
+  "maxPlayers": 100,
+  "minScore": 0,
+  "operation": {
+    "type": 3,
+    "achievement_type": 0,
+    "item": "xp",
+    "sort": -1,
+    "sub": false,
+    "filters": []
+  },
+  "rewards": [
+    { "total": 200, "type": 0, "item": "xp", "operation": 0, "extra": { "position_start": 1, "position_ends": 1 }, "restrict": false, "perPlayer": false },
+    { "total": 100, "type": 0, "item": "xp", "operation": 0, "extra": { "position_start": 2, "position_ends": 3 }, "restrict": false, "perPlayer": false }
+  ],
+  "notifications": [],
+  "active": true,
+  "teamCompetition": false,
+  "autoExecute": true,
+  "techniques": ["GT26"]
+}
+```
+
+### 4. Save
+
+```
+funifier_save type=competition payload=<json>
+```
+
+### 5. Enroll players
+
+```
+POST /v3/competition/join   { "competition": "<_id>", "player": "<player_id>" }
+```
+
+### 6. Check leaderboard and execute
+
+```
+POST /v3/competition/leader/aggregate?id=<_id>
+GET /v3/competition/<_id>/execute   (manual execution only)
+```