funifier-mcp 0.2.26 → 0.2.28

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

@@ -0,0 +1,95 @@
+# funifier-create-swap
+
+Create a Funifier swap — player-to-player trade offers for items or points with counter-proposal support; use when enabling peer trading or social exchange mechanics, not when a standard virtual good store purchase is sufficient
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "swap trade exchange offer counter-offer peer social marketplace" --skill funifier-create-swap
+```
+
+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/swap.md`
+
+## Steps
+
+### Swap flow
+
+```
+Seller creates offer (POST /v3/swap)
+  ↓
+Buyer acquires (POST /v3/swap/acquire)
+  ↓
+Seller receives (POST /v3/swap/receive)
+```
+
+**Counter-offer flow:**
+```
+Buyer creates counter-offer (POST /v3/swap/counter/offer)
+  ↓
+Seller accepts (POST /v3/swap/counter/offer/accept)
+  ↓
+Buyer receives (POST /v3/swap/counter/offer/receive)
+```
+
+**Dependências:** items (`type: 2`) e pontos (`type: 0`) devem existir.
+
+---
+
+## Steps
+
+### 1. Confirmar dependências
+
+```
+funifier_list type=virtual-good search=<item>
+funifier_list type=point search=<coin>
+```
+
+### 2. Criar oferta de troca (seller)
+
+Seller oferece 1 item em troca de 2 coins:
+```json
+{
+  "seller": "tom",
+  "rewards": [{ "total": 1, "type": 2, "item": "<item_id>" }],
+  "requires": [{ "total": 2, "type": 0, "item": "coin" }]
+}
+```
+
+```
+POST /v3/swap
+```
+
+### 3. Listar ofertas disponíveis
+
+```
+GET /v3/database/swap
+```
+
+### 4. Buyer adquire a oferta
+
+```
+POST /v3/swap/acquire   { "buyer": "jerry", "swap": "<swap_id>" }
+```
+
+### 5. Seller recebe pagamento
+
+```
+POST /v3/swap/receive   { "swap": "<swap_id>" }
+```
+
+### 6. (Opcional) Counter-offer
+
+```
+POST /v3/swap/counter/offer   { "swap": "<swap_id>", "buyer": "jerry", "offer": [{ "total": 1, "type": 0, "item": "coin" }] }
+POST /v3/swap/counter/offer/accept   { "offer": "<offer_id>" }
+```

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

@@ -1,32 +1,7 @@
----
-name: funifier-create-trigger
-description: Create a Funifier trigger — guided workflow from entity/event selection to Groovy code generation
----
-
 # funifier-create-trigger
 
 Create a Funifier trigger — guided workflow from entity/event selection to Groovy code generation
 
-## 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.
-
 ---
 
 ## Formato do payload (obrigatório)
@@ -208,11 +183,3 @@ funifier_logs type=trigger id=<_id>
 ```
 
 Confirme que não há erros de compilação ou execução. Se houver, leia o stack trace e corrija o script.
-
-## 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-virtual-good.md

@@ -0,0 +1,96 @@
+# funifier-create-virtual-good
+
+Create a Funifier virtual good — catalog items players can purchase with points
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "virtual good item catalog store purchase marketplace shop" --skill funifier-create-virtual-good
+```
+
+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/virtual-good.md`
+- `datasource-funifier-docs/knowledge/modules/point.md`
+
+## Steps
+
+### Regras críticas
+
+- Estrutura em dois níveis: **Catalog** (agrupa itens) → **Item** (produto individual)
+- `requires` define o preço: tipo de ponto (`type: 0`) + quantidade (`total`)
+- `amount: -1` = estoque ilimitado
+- Técnica obrigatória nos itens: `["GT08"]`
+- A moeda de compra (`requires[].item`) deve ser um ponto com técnica GT75 (trocável)
+
+---
+
+## Steps
+
+### 1. Confirmar que o ponto (moeda) existe
+
+```
+funifier_list type=point search=<coin_category>
+```
+
+### 2. Verificar se catálogo/item já existe
+
+```
+funifier_list type=virtual-good search=<nome>
+```
+
+### 3. Criar o Catálogo (se não existe)
+
+```json
+{
+  "_id": "gifts",
+  "catalog": "Gifts",
+  "extra": {},
+  "i18n": {}
+}
+```
+
+```
+POST /v3/virtualgoods/catalog
+```
+
+### 4. Criar o Item
+
+```json
+{
+  "catalogId": "gifts",
+  "name": "Electric Bike",
+  "description": "A great electric bike",
+  "amount": -1,
+  "active": true,
+  "techniques": ["GT08"],
+  "requires": [{ "total": 500, "type": 0, "item": "coin", "operation": 1 }],
+  "rewards": [],
+  "notifications": [],
+  "extra": {},
+  "i18n": {}
+}
+```
+
+```
+funifier_save type=virtual-good payload=<json>
+```
+
+### 5. Validar
+
+```
+GET /v3/virtualgoods/item
+```
+
+Para testar uma compra:
+```
+POST /v3/virtualgoods/purchase   { "player": "<id>", "item": "<item_id>", "total": 1 }
+```

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

@@ -0,0 +1,72 @@
+# funifier-create-webhook
+
+Create a Funifier webhook — push real-time event payloads to external endpoints (BI, CRM, Slack, Teams); use when external systems need event-driven data from Funifier, not when in-app live updates are needed (use websocket)
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "webhook integration external push event outbound realtime" --skill funifier-create-webhook
+```
+
+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/webhook.md`
+
+## Steps
+
+### Sobre Webhooks
+
+Webhooks enviam payloads HTTP para endpoints externos sempre que eventos ocorrem na gamificação (challenge completado, ponto creditado, etc.). Sem polling — push em tempo real.
+
+**Campos principais:**
+- `url`: endpoint externo que receberá o payload
+- `events`: lista dos eventos que disparam o webhook
+
+---
+
+## Steps
+
+### 1. Verificar se já existe
+
+```
+funifier_list type=webhook search=<descricao>
+```
+
+### 2. Ler a documentação do módulo
+
+```
+datasource-funifier-docs/knowledge/modules/webhook.md
+```
+
+### 3. Criar o webhook
+
+```json
+{
+  "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX",
+  "active": true,
+  "events": ["achievement"],
+  "extra": {}
+}
+```
+
+```
+funifier_save type=webhook payload=<json>
+```
+
+### 4. Verificar configuração
+
+```
+funifier_list type=webhook
+```
+
+### 5. Testar
+
+Dispare um evento (ex: log uma ação que gera conquista) e verifique se o endpoint externo recebeu o payload.

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

@@ -0,0 +1,71 @@
+# funifier-create-websocket
+
+Create a Funifier websocket configuration — real-time bidirectional communication for live competitions, instant player feedback, and chat; use for in-app live updates, not for pushing to external systems (use webhook)
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "websocket realtime live chat competition feedback socket bidirectional" --skill funifier-create-websocket
+```
+
+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/websocket.md`
+
+## Steps
+
+### Sobre WebSockets
+
+WebSockets permitem comunicação bidirecional em tempo real entre o frontend e o Funifier — sem recarregar a página. Útil para: atualizações de ranking ao vivo, chat durante competições, feedback instantâneo ao completar desafios.
+
+---
+
+## Steps
+
+### 1. Verificar se já existe uma configuração
+
+```
+funifier_list type=websocket
+```
+
+### 2. Ler a documentação do módulo
+
+```
+datasource-funifier-docs/knowledge/modules/websocket.md
+```
+
+### 3. Criar a configuração de WebSocket
+
+```json
+{
+  "title": "Live Competition Feed",
+  "description": "Real-time updates for active competition",
+  "active": true,
+  "events": ["achievement", "challenge"],
+  "extra": {}
+}
+```
+
+```
+funifier_save type=websocket payload=<json>
+```
+
+### 4. Integrar no frontend
+
+Para consumir via JavaScript, use a URL de WebSocket do Funifier e autentique com o Bearer token do jogador. Consulte `datasource-funifier-docs/knowledge/modules/websocket.md` para o protocolo de conexão específico da sua versão.
+
+### 5. Validar
+
+```
+funifier_list type=websocket
+```
+
+Conecte um cliente WebSocket e dispare um evento para confirmar que as mensagens chegam em tempo real.

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

@@ -0,0 +1,76 @@
+# funifier-create-widget
+
+Create a Funifier widget — embeddable visual components (rankings, challenge lists, player status, virtual stores) for integrating gamification displays into existing web systems like intranets, CRMs, or LMS platforms
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "widget embed visual ranking leaderboard component intranet integration display" --skill funifier-create-widget
+```
+
+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/widget.md`
+
+## Steps
+
+### Sobre Widgets
+
+Widgets são componentes visuais embutíveis que exibem dados de gamificação em sistemas externos (intranets, CRMs, LMS). Tipos comuns: ranking, lista de desafios, status do jogador, loja virtual.
+
+O Studio (`/studio/widget`) fornece um editor visual com preview e gera o código de embed.
+
+---
+
+## Steps
+
+### 1. Verificar se já existe
+
+```
+funifier_list type=widget search=<nome>
+```
+
+### 2. Ler a documentação do módulo
+
+```
+datasource-funifier-docs/knowledge/modules/widget.md
+```
+
+### 3. Criar o widget no Studio
+
+Use `/studio/widget` para:
+- Selecionar o tipo de widget (ranking, challenge list, player status, store)
+- Configurar os dados a exibir (qual leaderboard, quais challenges, etc.)
+- Personalizar estilo visual (cores, fontes, dimensões)
+- Obter o código de embed (`iframe` ou snippet JS)
+
+### 4. Criar via API
+
+```json
+{
+  "title": "Top Players Widget",
+  "active": true,
+  "extra": {}
+}
+```
+
+```
+funifier_save type=widget payload=<json>
+```
+
+### 5. Embed e validar
+
+Cole o código de embed na página destino (intranet, LMS, etc.) e verifique que o widget exibe os dados corretos.
+
+```
+funifier_list type=widget
+GET /v3/widget/<_id>
+```

package/skills/funifier/references/debug.md

@@ -0,0 +1,87 @@
+# funifier-debug
+
+Debug a Funifier resource — systematic diagnosis of triggers, schedulers, aggregates, and other Funifier components
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "debug error log exception timeout groovy stack trace fix" --skill funifier-debug
+```
+
+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/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`
+
+## Steps
+
+### Onde encontrar erros
+
+| Tipo de recurso | Ferramenta |
+|---|---|
+| Trigger, Scheduler | `funifier_logs type=trigger id=<_id>` / `funifier_logs type=scheduler id=<_id>` |
+| Challenge, Level, Action | `funifier_get type=<type> id=<_id>` — verificar campos |
+| Aggregate | Testar via `POST /v3/database/<collection>/aggregate` |
+| Frontend auth | Verificar role scope inclui `database` se usar `/v3/database` |
+
+### Problemas comuns
+
+| Sintoma | Causa provável | Fix |
+|---|---|---|
+| Trigger não executa | `active: false` ou entidade/evento errado | Verificar campos com `funifier_get` |
+| Script compila mas não faz nada | Condição de guarda nunca satisfeita | Adicionar `println` para rastrear |
+| `$` em GString não funciona | Groovy interpreta como variável | Use `String.valueOf((char)0x24)` |
+| Challenge não avança | Action não existe ou operator/total errado | `funifier_list type=action search=<id>` |
+| Compra falha sem erro | Saldo insuficiente ou `requires` errado | Checar ponto do jogador: `GET /v3/player/<id>/status` |
+| `/v3/database` retorna vazio | Scope `database` ausente na role | Adicionar `database` ao scope via Security |
+
+---
+
+## Steps
+
+### 1. Identificar o tipo de recurso com problema
+
+Perguntar: trigger? scheduler? challenge? aggregate? frontend?
+
+### 2. Ler os logs (triggers/schedulers)
+
+```
+funifier_logs type=trigger id=<_id>
+```
+
+Procure: exception name, stack trace, linha do erro.
+
+### 3. Verificar a configuração atual
+
+```
+funifier_get type=<type> id=<_id>
+```
+
+Compare com o que a documentação exige.
+
+### 4. Isolar o problema
+
+- Para scripts Groovy: reduza ao mínimo que reproduz o erro
+- Para challenges: verifique se action e point existem
+- Para frontend: verifique token, scope, e headers
+
+### 5. Ler a documentação primária do módulo
+
+Leia o arquivo de doc específico para o módulo com problema:
+- Trigger → `datasource-funifier-docs/knowledge/modules/trigger.md` + guides
+- Scheduler → `datasource-funifier-docs/knowledge/modules/scheduler.md`
+- Aggregate → `datasource-funifier-docs/knowledge/guides/aggregates.md`
+- Security/Auth → `datasource-funifier-docs/knowledge/modules/security.md`

package/skills/funifier/references/help.md

@@ -0,0 +1,81 @@
+# funifier-help
+
+Get help with Funifier — routes to the right documentation or skill based on your question
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "help documentation guide module question how what funifier" --skill funifier-help
+```
+
+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/index.md`
+
+## Steps
+
+### Mapa de skills por objetivo
+
+| Quero... | Leia o arquivo |
+|---|---|
+| Criar trigger com Groovy | `references/create-trigger.md` |
+| Criar scheduler/cron job | `references/create-scheduler.md` |
+| Criar aggregate/relatório | `references/create-aggregate.md` |
+| Criar desafio/missão | `references/create-challenge.md` |
+| Criar ação rastreável | `references/create-action.md` |
+| Criar sistema de pontos | `references/create-point.md` |
+| Criar ranking | `references/create-leaderboard.md` |
+| Criar níveis de progressão | `references/create-level.md` |
+| Criar quiz/avaliação | `references/create-quiz.md` |
+| Criar loja virtual | `references/create-virtual-good.md` |
+| Criar página no Studio | `references/create-custom-page.md` |
+| Integrar frontend | `references/implement-frontend.md` |
+| Depurar erro | `references/debug.md` |
+| Cadastrar jogador | `references/manage-player.md` |
+| Criar equipe | `references/manage-team.md` |
+| Criar competição temporária | `references/create-competition.md` |
+| Criar trilha de aprendizagem | `references/create-folder.md` |
+| Criar sorteio | `references/create-lottery.md` |
+| Criar caixa surpresa/roda | `references/create-mystery.md` |
+| Criar história interativa | `references/create-story.md` |
+| Criar palavra cruzada | `references/create-crossword.md` |
+| Configurar notificação | `references/create-notification.md` |
+| Configurar última milha | `references/create-lastmile.md` |
+| Integrar webhook externo | `references/create-webhook.md` |
+| Comunicação em tempo real | `references/create-websocket.md` |
+| Criar widget embutível | `references/create-widget.md` |
+| Trocar itens entre jogadores | `references/create-swap.md` |
+| Criar coleção customizada | `references/create-custom-object.md` |
+| Configurar segurança/tokens | `references/configure-security.md` |
+| Importar/exportar CSV | `references/import-csv.md` |
+| Fazer upload de arquivo | `references/upload-file.md` |
+
+---
+
+## Steps
+
+### 1. Entender o objetivo do usuário
+
+Perguntar: o que você está tentando fazer na gamificação?
+
+### 2. Consultar a documentação de índice
+
+```
+datasource-funifier-docs/knowledge/index.md
+```
+
+### 3. Redirecionar para a skill correta
+
+Baseado na tabela acima, instrua o usuário a usar a skill específica.
+
+### 4. Se não encontrar skill específica
+
+Consulte `datasource-funifier-docs/knowledge/index.md` e leia o módulo relevante diretamente.