claude-plugins/wordpress/skills/mcp-happyfiles/SKILL.md

---
name: mcp-happyfiles
description: MCP dedicado multi-site (node stdio, ligação `happyfiles` em ~/.omp/agent/mcp.json) para gerir as pastas da media library organizadas pelo HappyFiles Pro em qualquer site do bundle Descomplicar® onde o plugin esteja activo — listar pastas com contagem e hierarquia, criar/renomear/apagar pastas, listar ficheiros de uma pasta ou sem pasta, mover ficheiros entre pastas. Apagar uma pasta NUNCA apaga ficheiros. Site é um parâmetro em cada tool, não uma ligação fixa. Usar quando "happyfiles mcp", "pastas media library", "organizar biblioteca de media", "mover ficheiros de pasta wordpress", "criar pasta happyfiles", "apagar pasta happyfiles", "ficheiros sem pasta", "uncategorized happyfiles".
layer: wiki
---

# /mcp-happyfiles — MCP dedicado multi-site ao HappyFiles Pro

Projecto em `/media/ealmeida/Dados/Dev/mcp-happyfiles/` (TypeScript, SDK MCP oficial, stdio). Sem
código PHP novo no WordPress — cada tool corre `wp eval` via `ssh server` sobre a **API nativa de
taxonomias do WordPress** (`get_terms`, `wp_insert_term`, `wp_update_term`, `wp_delete_term`,
`wp_set_object_terms`, `wp_delete_object_term_relationships`), nunca SQL directo. `site` é um
parâmetro em cada tool, não uma ligação fixa por site.

## Arquitectura de dados (confirmada no código-fonte do plugin em 19-08-2026)

O HappyFiles Pro **não tem tabelas próprias** para pastas de media library. Cada "pasta" é um termo
da taxonomia custom `happyfiles_category` (constante `HAPPYFILES_TAXONOMY`), registada só para o
post type `attachment`, **hierárquica** (usa `parent`/`term_id` nativos do WordPress). Cada
ficheiro (attachment) pertence a uma pasta através de uma relação normal
`wp_term_relationships` — exactamente como categorias/tags em posts.

- **Contagem de ficheiros por pasta** = `WP_Term->count`, mantida automaticamente pelo WordPress via
  `_update_generic_term_count` (callback registado pelo próprio plugin) sempre que
  `wp_set_object_terms`/`wp_delete_term` corre. Nunca precisa de ser recalculada manualmente.
- **Metadados extra por pasta** (termmeta, opcionais): `happyfiles_position` (inteiro, ordenação
  manual na UI) e `happyfiles_folder_color` (cor custom). Ambos ausentes por omissão.
- **"Sem pasta" (Uncategorized)** não é um termo real — é `tax_query` com `operator => NOT EXISTS`
  sobre `happyfiles_category`. O próprio `Data::get_folders()` do plugin usa a convenção
  `term_id = -1` para esta pseudo-pasta e `-2` para "Todos os ficheiros"; este MCP replica a mesma
  convenção internamente (`folderId: -1` nas tools de listagem de ficheiros).
- **Gotcha WP_Query confirmado ao vivo:** `tax_query` por omissão tem `include_children => true`
  (taxonomia hierárquica) — listar ficheiros de uma pasta-pai sem `include_children: false` devolve
  também os ficheiros de todas as subpastas (reproduzido: pasta "Clientes" mostrava 120 ficheiros em
  vez dos 7 directamente associados). Este MCP força sempre `include_children => false`, replicando
  o mesmo padrão que o próprio `Actions::delete_folder()` do plugin usa para não apagar relações de
  subpastas por engano.
- **`query_var` da taxonomia é `false`** (`public => false` na chamada `register_taxonomy`, confirmado
  via `get_taxonomy('happyfiles_category')->query_var`) — `wp post list --happyfiles_category=X`
  **não funciona**, nem via WP-CLI nem em pedidos normais; o próprio plugin nunca depende disto,
  constrói sempre `tax_query` explícito em PHP. Por isso este MCP também nunca usa esse atalho.
- **Apagar pasta nunca apaga ficheiros:** `Actions::delete_folder()` (e o `wp_delete_term()` nativo
  que ele chama) só remove a linha da taxonomia e as relações `wp_term_relationships` — os posts
  `attachment` continuam a existir, só passam a "Sem pasta". Confirmado no código-fonte
  (`includes/actions.php`) e testado ao vivo neste MCP (ver secção Verificação).
- **Uma pasta por ficheiro por omissão:** `wp_set_object_terms($id, [$folderId], $taxonomy, false)`
  com `append=false` **substitui** a pasta anterior — é o comportamento por omissão do HappyFiles
  Pro (`happyfiles_multiple_folders` = false). Este MCP replica exactamente essa semântica em
  `happyfiles_move_files`.

## Sites conhecidos

Chamar `happyfiles_list_sites` para a lista actual. Confirmados HappyFiles Pro 1.8.3 activo ao vivo
em 19-08-2026: `descomplicar` (produção, `/home/ealmeida/public_html` — 66 pastas reais em uso,
1218 attachments, 893 sem pasta), `emanuelalmeida` (`emanuelalmeida.pt`), `starter`
(`starter.descomplicar.pt`). Também aceita um path absoluto directamente
(`/home/ealmeida/<site>`) para sites fora desta lista, sem exigir rebuild do MCP.

## Tools (9)

| Tool | Read-only | Uso |
|---|---|---|
| `happyfiles_list_sites` | sim | Aliases conhecidos, path WP, nota de estado |
| `happyfiles_get_status` | sim | Plugin instalado/activo + versão |
| `happyfiles_list_folders` | sim | Todas as pastas: id, nome, slug, `parent`, `count`, `position`, `color`, mais `all_files_count`/`uncategorized_count` |
| `happyfiles_create_folder` | não | Nova pasta, `parentId` opcional para subpasta |
| `happyfiles_rename_folder` | não | Novo nome + slug recalculado |
| `happyfiles_delete_folder` | não | **Nunca apaga ficheiros.** `deleteSubfolders:true` apaga em cascata; por omissão as subpastas sobem para o pai (comportamento nativo `wp_delete_term`) |
| `happyfiles_list_files_in_folder` | sim | Ficheiros **directamente** numa pasta (não inclui subpastas), paginado |
| `happyfiles_list_uncategorized_files` | sim | Ficheiros sem nenhuma pasta atribuída, paginado |
| `happyfiles_move_files` | não | 1+ ficheiros para uma pasta (substitui a pasta anterior) ou `folderId: null` para desassociar (Sem pasta) |

Todas as tools exigem `site` como primeiro parâmetro.

## Segurança

Nenhuma escrita usa SQL directo nem classes internas do plugin (não são autoload-seguras fora do
wp-admin) — só as funções nativas de taxonomia do WordPress, as mesmas que os handlers AJAX do
próprio HappyFiles Pro chamam (`includes/actions.php`, `includes/ajax.php`), pelo que os hooks
(`created_term`, `edited_term`, `delete_term`, `set_object_terms`) disparam sempre. O corpo PHP
corrido por `wp eval` é sempre um template estático sem texto do utilizador interpolado; nomes de
pasta e IDs de ficheiros viajam em JSON codificado em base64 pelo **STDIN** do processo remoto
(`php://stdin` dentro do PHP, `stream_get_contents(STDIN)`), nunca na linha de comando — evita por
completo ter de escapar aspas/unicode num nome de pasta para a shell remota.

## Verificação

Construído e testado ponta-a-ponta contra produção e staging em 19-08-2026:

- **Leituras cruzadas independentes** (`descomplicar`, produção): `happyfiles_list_folders` devolveu
  66 pastas, `all_files_count: 1218` e `uncategorized_count: 893` — confirmados byte-a-byte via
  `wp eval`/`wp post list --format=count` directos fora do MCP. `happyfiles_list_files_in_folder`
  na pasta "Clientes" (id 42) devolveu `total: 7` depois de corrigido o gotcha `include_children`
  (tinha devolvido 120 antes da correcção); confirmado via `wp post term list <id>
  happyfiles_category` em vários ficheiros individuais devolvidos.
- **Ciclo de escrita completo em `starter`** (site vazio de pastas, 7 attachments — sandbox seguro):
  `happyfiles_create_folder` → `happyfiles_rename_folder` → `happyfiles_move_files` (ficheiro 19
  para a pasta nova, confirmado via `wp post term list` directo) → `happyfiles_list_files_in_folder`
  (1 item) / `happyfiles_list_uncategorized_files` (6 itens, confirmado) → `happyfiles_move_files`
  de volta a `null` (confirmado `wp post term list` vazio de novo) → `happyfiles_delete_folder` →
  estado final confirmado idêntico ao inicial (`wp term list` vazio, `wp post list --format=count`
  ainda 7, `wp post get 19` com o título original intacto).

## Skills relacionadas

Nenhuma skill de conhecimento dedicada ao HappyFiles Pro existe neste bundle — esta skill é a única
documentação (arquitectura de dados + tools). Ver `wp-cli` para o padrão geral de gestão via
WP-CLI no servidor CWP.