funifier-mcp 0.2.26 → 0.2.28

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

@@ -0,0 +1,106 @@
+# funifier-implement-frontend
+
+Implement frontend code that consumes the Funifier API — authentication, data fetching, aggregate consumption, and static hosting on Funifier subdomain
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "frontend api authentication fetch jwt token javascript react angular static hosting" --skill funifier-implement-frontend
+```
+
+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/auth.md`
+- `datasource-funifier-docs/knowledge/guides/aggregates.md`
+- `datasource-funifier-docs/knowledge/guides/database-access.md`
+- `datasource-funifier-docs/knowledge/modules/patterns.md`
+- `datasource-funifier-docs/knowledge/modules/action-log.md`
+- `datasource-funifier-docs/knowledge/modules/static-repo.md`
+
+## Steps
+
+### Regras críticas
+
+- **`grant_type` é obrigatório** e deve ser `"password"` — sem ele retorna `invalid_grant`
+- **Campo é `username`**, não `login` na chamada `/v3/auth/token`
+- **Senha do player no banco deve ser BCrypt** (`$2a$...`) — texto plano causa `"Invalid salt version"`
+- **Scope `database`** é obrigatório na role para usar `/v3/database` — sem ele escrita retorna 201 mas não persiste
+- **Header `Range: items=0-1000`** para listas sem paginação explícita
+
+### Auth flow
+
+```javascript
+// 1. Get Bearer token
+const resp = await fetch('/v3/auth/token', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    apiKey: 'YOUR_API_KEY',
+    grant_type: 'password',
+    username: 'player_id',
+    password: 'plain_password'
+  })
+});
+const { access_token } = await resp.json();
+
+// 2. Use in subsequent calls
+const headers = { Authorization: `Bearer ${access_token}` };
+```
+
+### Basic token (public/server-side)
+
+```javascript
+// No authentication needed — use for public reads or server-side actions
+const basicToken = 'Basic ' + btoa('API_KEY:APP_SECRET');
+// Public (no app): 'Basic ' + btoa('API_KEY:')
+```
+
+---
+
+## Steps
+
+### 1. Ler documentação de auth e padrões
+
+- `datasource-funifier-docs/knowledge/modules/auth.md`
+- `datasource-funifier-docs/knowledge/modules/patterns.md`
+- `datasource-funifier-docs/knowledge/guides/aggregates.md` (para relatórios)
+
+### 2. Implementar autenticação
+
+Use o auth flow acima. Armazene o token no localStorage ou contexto da aplicação.
+
+### 3. Registrar ações do jogador
+
+```javascript
+// Record a player action
+await fetch('/v3/action/log', {
+  method: 'POST',
+  headers: { ...headers, 'Content-Type': 'application/json' },
+  body: JSON.stringify({ actionId: 'watch_video', player: 'player_id' })
+});
+```
+
+### 4. Consumir dados via aggregate
+
+```javascript
+// Get player status
+const status = await fetch('/v3/player/player_id/status', { headers });
+// Get custom report via aggregate
+const report = await fetch('/v3/database/achievement/aggregate', {
+  method: 'POST',
+  headers: { ...headers, 'Content-Type': 'application/json' },
+  body: JSON.stringify([{"\$match": {"player": "player_id"}}, {"\$group": {"_id": "\$item", "total": {"\$sum": "\$total"}}}])
+});
+```
+
+### 5. Hospedar no Funifier (opcional)
+
+Para arquivos estáticos, leia `datasource-funifier-docs/knowledge/modules/static-repo.md`.

package/skills/funifier/references/import-csv.md

@@ -0,0 +1,75 @@
+# funifier-import-csv
+
+Import or export Funifier platform data via CSV — bulk player import, performance export, and cross-system data migration; use when loading or extracting large datasets, not for individual record CRUD or media file uploads (use funifier-upload-file)
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "csv import export bulk data migration player dataset" --skill funifier-import-csv
+```
+
+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/csv-data.md`
+
+## Steps
+
+### Sobre CSV Import/Export
+
+O módulo CSV permite importar dados em massa (jogadores, ações, etc.) e exportar relatórios de desempenho em formato CSV.
+
+**API:** `POST /v3/csv` para importar, `GET /v3/csv` para exportar.
+
+---
+
+## Steps
+
+### 1. Ler a documentação do módulo
+
+```
+datasource-funifier-docs/knowledge/modules/csv-data.md
+```
+
+### 2. Preparar o arquivo CSV
+
+Para import de jogadores, o formato mínimo é:
+```
+_id,name,email
+tom,Tom Cat,tom@company.com
+jerry,Jerry Mouse,jerry@company.com
+```
+
+Verifique o formato exato aceito pelo Funifier na documentação do módulo.
+
+### 3. Importar
+
+```
+POST /v3/csv
+Content-Type: multipart/form-data
+Authorization: Bearer <token>
+file: <arquivo.csv>
+```
+
+### 4. Exportar dados
+
+```
+GET /v3/csv
+Authorization: Bearer <token>
+```
+
+Adicione parâmetros de filtro conforme suportado pelo módulo (ver documentação).
+
+### 5. Validar
+
+Após import, verifique se os registros foram criados:
+```
+funifier_list type=player search=<nome_importado>
+```

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

@@ -0,0 +1,82 @@
+# funifier-manage-player
+
+Register and manage Funifier players — CRUD workflow for participant onboarding, team assignment, extra-field management, and status queries; use at the start of every project to set up participants
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "player user register onboarding participant status extra profile" --skill funifier-manage-player
+```
+
+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/player.md`
+
+## Steps
+
+### Rules — follow exactly, no exceptions
+
+**`_id` is the login** — lowercase, no spaces: `tom`, `jerry`, `john_doe`.
+**Upsert:** POST with existing `_id` updates the player — never errors on duplicate.
+**Password:** stored as BCrypt hash in `password` field — plain text causes `"Invalid salt version"` on login.
+**Teams:** assign via `teams` array in the player payload OR after creation with `GET /v3/team/:id/member/add/:player`.
+**Extra fields:** put any custom data (department, role, region) inside the `extra` object.
+
+---
+
+### 1. Check if player already exists
+
+```
+funifier_list type=player search=<name or _id>
+```
+
+### 2. Build the payload
+
+Minimal player:
+```json
+{
+  "_id": "tom",
+  "name": "Tom",
+  "email": "tom@company.com"
+}
+```
+
+Full player with teams and extra:
+```json
+{
+  "_id": "tom",
+  "name": "Tom",
+  "email": "tom@company.com",
+  "teams": ["sales"],
+  "extra": { "department": "Sales", "region": "BR" }
+}
+```
+
+### 3. Save
+
+```
+funifier_save type=player payload=<json>
+```
+
+### 4. Verify
+
+```
+funifier_get type=player id=<_id>
+GET /v3/player/<_id>/status
+```
+
+`/status` returns points, level, challenges completed.
+
+### 5. Add to team (if needed, separately)
+
+```
+GET /v3/team/<team_id>/member/add/<player_id>
+```

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

@@ -0,0 +1,76 @@
+# funifier-manage-team
+
+Create and manage Funifier teams — group players for collective challenges, team rankings, and collaborative goals; use when organizing players into competing or collaborating groups, not when only individual player setup is needed
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "team group department member collective ranking collaboration squad" --skill funifier-manage-team
+```
+
+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/team.md`
+
+## Steps
+
+### Rules — follow exactly, no exceptions
+
+**Members are added via a separate endpoint** — not included in the create payload.
+**Upsert:** POST with existing `_id` updates the team.
+**`owner`:** optional player `_id` — team captain/admin.
+
+---
+
+### 1. Check if team already exists
+
+```
+funifier_list type=team search=<name>
+```
+
+### 2. Create the team
+
+```json
+{
+  "_id": "sales",
+  "name": "Sales Team",
+  "description": "The sales department",
+  "extra": { "region": "BR" },
+  "owner": "john"
+}
+```
+
+```
+funifier_save type=team payload=<json>
+```
+
+### 3. Add members
+
+```
+GET /v3/team/sales/member/add/tom
+GET /v3/team/sales/member/add/jerry
+```
+
+### 4. Verify
+
+```
+funifier_list type=team search=<name>
+GET /v3/team/sales/memberids
+GET /v3/team/sales/status
+```
+
+`/status` returns aggregated points and challenges for the team.
+
+### 5. Remove a member (if needed)
+
+```
+GET /v3/team/sales/member/remove/tom
+```

package/skills/funifier/references/upload-file.md

@@ -0,0 +1,91 @@
+# funifier-upload-file
+
+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)
+
+---
+
+## Before starting — find relevant docs
+
+Run lexical search to load only what you need:
+
+```bash
+npx funifier-mcp search "upload image file avatar media asset s3 multipart" --skill funifier-upload-file
+```
+
+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/upload.md`
+
+## Steps
+
+### Regras críticas
+
+- **Campo `extra` é obrigatório** no FormData — sem ele: `"Field extra is required"`
+- **`Content-Type` não definido manualmente** — deixe o FormData/browser gerar com boundary correto
+- Dois endpoints: `/v3/upload/image` (imagens) e `/v3/upload/file` (qualquer tipo)
+- A URL retornada em `response.uploads[0].url` é pública no S3/Azure/Google Cloud
+- Upload dispara triggers `BEFORE_CREATE` e `AFTER_CREATE` na entidade `UPLOAD`
+
+---
+
+## Steps
+
+### 1. Verificar uploads existentes (se necessário)
+
+```
+GET /v3/upload
+Authorization: Bearer <token>
+```
+
+### 2. Upload de imagem
+
+```javascript
+const formData = new FormData();
+formData.append('file', imageFile);
+formData.append('extra', JSON.stringify({ session: 'images' }));
+
+const resp = await fetch('/v3/upload/image', {
+  method: 'POST',
+  headers: { Authorization: `Bearer ${token}` },
+  body: formData
+});
+const { uploads } = await resp.json();
+const imageUrl = uploads[0].url;
+```
+
+### 3. Upload de arquivo genérico
+
+```bash
+curl -X POST "{server}/v3/upload/file" \
+  -H "Authorization: Bearer {token}" \
+  -F 'file=@./documento.pdf;type=application/pdf' \
+  -F 'extra={"session":"docs"}'
+```
+
+### 4. Usar a URL no recurso destino
+
+Para avatar do jogador:
+```json
+{
+  "_id": "tom",
+  "image": {
+    "small": { "url": "<imageUrl>" },
+    "medium": { "url": "<imageUrl>" },
+    "original": { "url": "<imageUrl>" }
+  }
+}
+```
+
+```
+funifier_save type=player payload=<json>
+```
+
+### 5. Deletar upload (se necessário)
+
+```
+DELETE /v3/upload/<upload_id>
+```

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

@@ -1,127 +0,0 @@
----
-name: funifier-create-aggregate
-description: Create a Funifier prepared aggregate — guided workflow for building MongoDB aggregate pipelines for reports and dashboards
----
-
-# funifier-create-aggregate
-
-Create a Funifier prepared aggregate — guided workflow for building MongoDB aggregate pipelines for reports and dashboards
-
-## 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)
-
-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
-
-### 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.
-
-## 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-create-challenge/SKILL.md

@@ -1,88 +0,0 @@
----
-name: funifier-create-challenge
-description: Create a Funifier challenge — missions with action rules and point rewards
----
-
-# funifier-create-challenge
-
-Create a Funifier challenge — missions with action rules and point rewards
-
-## 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
-
-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
-
-### 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.
-
-## 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