emcp-tools-mapping/docs/INDEX.md

# EMCP Tools — Mapeamento completo e blueprint de réplica

Índice e síntese de 13 documentos (~7 810 linhas), produzidos 19-08-2026 por leitura directa do
código-fonte `emcp-tools` v3.12.1 (build Free, `msrbuilds/elementor-mcp`, GPL-2.0-or-later),
instalado em `emanuelalmeida.pt` (`/home/ealmeida/emanuelalmeida.pt/wp-content/plugins/emcp-tools/`),
mais dois docs adicionais (11, WooCommerce; 12, Widget Builder) fundamentados noutro código real
quando o EMCP Pro correspondente está ausente. Cruzado com `skill://emcp-tools` (auditoria de
postura de segurança viva nos 3 sites do ecossistema: `descomplicar.pt`, `emanuelalmeida.pt`,
`starter.descomplicar.pt`).

**Objectivo desta série:** especificação funcional completa, ao nível de "o que este código faz e
porquê", para servir de base a uma réplica própria — seja fork (GPL permite) seja reescrita limpa.
Nenhum documento é resumo de superfície; cada um lê o código-fonte real, cita comentários do autor
quando revelam decisões não óbvias, e termina numa secção "Blueprint para réplica" com veredicto
copiar-1:1 / simplificar / deixar de fora.

---

## 1. Mapa dos documentos

| Doc | Assunto | Linhas | Abilities (aprox.) | Dependência |
|---|---|---|---|---|
| [00-ARQUITECTURA](00-ARQUITECTURA.md) | Bootstrap, ability registrar, dispatcher compact mode, `register_mcp_server`, guarda Free⇄Pro | 277 | n/a (estrutural) | — (fundação de tudo) |
| [01-ELEMENTOR-CLASSICO](01-ELEMENTOR-CLASSICO.md) | Páginas, layout, widgets (catálogo), templates, global settings/classes, custom code, SVG, composite | 632 | ~35 | Elementor activo |
| [02-ATOMIC-V4-GUTENBERG](02-ATOMIC-V4-GUTENBERG.md) | Elementor Atomic v4 (`$$type` props, widgets, flexbox/div-block) + Gutenberg nativo (sempre-on) | 515 | ~25 | Elementor 4.0+ atomic (widgets/layout) · nenhuma (Gutenberg) |
| [03-WORDPRESS-CORE-TEMAS](03-WORDPRESS-CORE-TEMAS.md) | Posts/media/settings/plugins/temas/users/menus + integrações de tema (Astra/Spectra/Kadence) | 494 | ~30 | Nenhuma (core puro) |
| [04-THEMER](04-THEMER.md) | CPT header/footer/single/archive/search/404, sistema de condições, render pipeline, Themer PHP | 687 | ~13 | Módulo `themer` (free, on por omissão) |
| [05-REDIRECTS-SEARCH-LEDGER](05-REDIRECTS-SEARCH-LEDGER.md) | Redirects 301/302, broken-links, **change ledger unificado** (rollback), content-mirror | 727 | ~14 | Módulo `redirects` (redirects) · nenhuma (ledger) |
| [06-SANDBOX-CUSTOM-CODE](06-SANDBOX-CUSTOM-CODE.md) | PHP snippets com aprovação humana, export/import de artefactos, Widget Builder (Pro, ausente) | 336 | ~20 | Nenhuma (snippets free) |
| [07-SYSTEM-OPS](07-SYSTEM-OPS.md) | Filesystem, base de dados directa, WP-CLI, Security Scanner, Performance Analyzer | 629 | ~15 | Nenhuma — **maior risco do plugin** |
| [08-INTEGRACOES-TERCEIROS](08-INTEGRACOES-TERCEIROS.md) | ACF, Meta Box, formulários (CF7 free), SEO (SlimSEO free) | 457 | ~30 (free) | Plugin de terceiros instalado |
| [09-STOCK-IMAGES-CLOUD-OAUTH](09-STOCK-IMAGES-CLOUD-OAUTH.md) | Unsplash/Pexels/Pixabay, EMCP Cloud (ligação/sync), servidor OAuth para MCP remoto | 654 | ~17 | Nenhuma |
| [10-MODULOS-E-INVENTARIO-PRO](10-MODULOS-E-INVENTARIO-PRO.md) | Sistema de módulos (toggles), Image Optimization, SVG Support, **inventário definitivo das 30 classes Pro-only** | 661 | n/a + 30 ausentes | — (estrutural + auditoria) |
| [11-WOOCOMMERCE-BLUEPRINT](11-WOOCOMMERCE-BLUEPRINT.md) | **Não é auditoria EMCP** — blueprint de abilities WooCommerce (produtos/encomendas/clientes/cupões/analytics/webhooks) fundamentado no WooCommerce real, para preencher o gap `EMCP_Tools_Woo_Integration` (Pro, código ausente). Exclui SEO/Yoast por pedido. | 878 | ~35 propostas | WooCommerce activo |
| [12-WIDGET-BUILDER-BLUEPRINT](12-WIDGET-BUILDER-BLUEPRINT.md) | **Não é auditoria EMCP** — blueprint de gerador spec→widget-Elementor-PHP (marca `[REAL]`/`[DESENHO PRÓPRIO]` em cada afirmação), fundamentado na API pública `Widget_Base`/`Controls_Manager` do Elementor real + no `EMCP_Tools_Widget_Store`/`Widget_Loader` já Free/reais (doc 06). Recomenda "zero tool de activação via MCP", ecoando Themer PHP/Sandbox. | 651 | 8 propostas | Elementor activo |

Total: **~7 810 linhas de documentação**, ~165 abilities EMCP confirmadas + ~35 WooCommerce + 8
Widget Builder propostas (docs 11-12, não implementadas no EMCP — blueprints próprios) sobre
**~128 465 linhas de PHP** do plugin `emcp-tools` (`~50k` das quais são o SDK Freemius bundled,
irrelevante para réplica).

---

## 2. O achado mais importante de toda a série

**A peça MCP não é do fornecedor do plugin — é do próprio WordPress core team.** O EMCP Tools
depende de `wordpress/mcp-adapter` + `wordpress/php-mcp-schema`, dois pacotes Composer oficiais
`make.wordpress.org/ai`, GPL-2.0-or-later, e da Abilities API nativa do WordPress 6.9+/7.0
(`wp_register_ability()`). **Não há protocolo nenhum para reimplementar.** O trabalho real de uma
réplica é 100% aplicação: registar as nossas próprias abilities com o nosso prefixo, e chamar
`$mcp_adapter->create_server()` com o nosso `server_id`. Ver `00-ARQUITECTURA.md` §0.

Consequência prática: a pergunta "construir um MCP para WordPress do zero" tem uma resposta muito
mais barata do que pareceria — `composer require wordpress/mcp-adapter` dá a máquina toda
(JSON-RPC, sessão, transporte HTTP/stdio). O valor real deste plugin (e desta documentação) está
no **catálogo de ~165 abilities bem desenhadas** por cima dessa máquina, não na máquina em si.

---

## 3. Os 5 subsistemas de maior valor para copiar quase verbatim

Ordenados por relação esforço-de-reescrita ÷ risco-de-reintroduzir-bugs-já-corrigidos (o critério
mais citado em todos os 10 documentos de subsistema):

1. **`EMCP_Tools_Atomic_Props`** (doc 02, 973 linhas) — o sistema `$$type` do Elementor 4.0+.
   Sete issues numeradas do próprio autor (#36, #56, #74, #97, #101, #102, #111) já corrigidas;
   `is_atomic_supported()` usa introspecção de tipos registados, nunca `version_compare()`
   (o Elementor reporta versão 3.x com atomic já activo como experiment). Reescrever do zero
   arrisca reproduzir literalmente 2 anos de bugs de produção documentados.
2. **O change ledger unificado** (doc 05 §4: `Change_Log` + `Change_Recorder` + `Change_Blobs`) —
   é o mecanismo de rollback partilhado por **praticamente todos os outros subsistemas**
   (Elementor, Gutenberg, filesystem, DB, ACF, redirects, posts). Onze tipos de rollback
   diferentes (`elementor-data`, `file-backup`, `db-before-image`, `post-fields`, `user-create`,
   etc.), cada um com o seu applier. Construir isto PRIMEIRO numa réplica poupa reimplementar
   undo ad-hoc em cada subsistema individual — é exactamente o padrão que `08-INTEGRACOES-TERCEIROS.md`
   recomenda generalizar ainda mais (a base SEO já o faz com zero código extra por integração).
3. **`EMCP_Tools_Filesystem_Guard`/`Database_Guard`/`WPCLI_Validator`** (doc 07) — os três guards
   de maior superfície de segurança do plugin. `resolve_path()` (confinamento a `ABSPATH`,
   comparação de prefixo correcta), `is_read_only_sql()` (scanner char-a-char anti-ReDoS, com dois
   bugs de "quase-passou" já documentados nos comentários — o truque `/*!` do MySQL e o regex de
   `LOAD_FILE(` sem `\b` a fechar), e o tokenizador consciente de aspas do WP-CLI validator.
4. **`EMCP_Tools_Block_Tree`** (doc 02, ~330 linhas) — transformações puras sobre
   `parse_blocks()`/`serialize_blocks()`, endereçamento por PATH de índices. Três guards de
   segurança em `move()` (auto-referência, alvo-dentro-da-subárvore, correcção de deslocamento de
   índice) e a reconstrução de `innerContent` em `inner_content_for()` são precisamente o tipo de
   lógica subtil que se parte silenciosamente ao reescrever sem os mesmos casos de teste.
5. **O sistema de condições do Themer** (doc 04 §4) — Schema/Matcher-Registry/Conditions/Context/
   Resolver com algoritmo de desempate de 3 níveis, mais o índice cacheado (com o bug histórico de
   ordem save/priority-99 já corrigido e um mecanismo de heal one-time para sites já afectados). É
   o núcleo mais reutilizável fora do domínio Elementor — qualquer sistema de "mostra X só quando Y"
   pode reaproveitar a mesma arquitectura.

---

## 4. Padrões arquitecturais que atravessam todo o plugin

Encontrados de forma independente em múltiplos documentos — não são acidente, são a assinatura de
um autor disciplinado:

- **Kill switch por módulo + `is_enabled()` estático** (doc 10 §1.2) — porque
  `wp_abilities_api_init` corre ANTES de `init:5`, as MCP tools de um módulo nunca podem depender
  de `$module->is_active()` (a instância só existe depois); todo módulo com abilities associadas
  expõe um helper estático que lê a option directamente. Ver Redirect/Cloud/Themer/Agent-Skills.
- **Construção lazy de motores pesados/frágeis** (doc 07 §4, issue #100) — o Security Scanner só
  instancia os 4 audits na primeira `scan()` real, nunca no registo da ability (que corre em TODO
  pedido admin/REST). O mesmo princípio aparece em `register_all()` do registrador global
  (doc 00 §3), envolto em `try/catch`.
- **Argv array, nunca string interpolada** — a regra de ouro para qualquer invocação de processo
  externo (`WPCLI_Runner::run_shell`, `WPCLI_Jobs::spawn`). Citada explicitamente como "a regra
  arquitectural mais importante" do doc 07.
- **Fragmentação de assinaturas próprias** (doc 07 §4.1) — o scanner de malware fragmenta as
  suas próprias regras de detecção em tokens concatenados em runtime, para não ser confundido com
  malware por scanners do host (Imunify360, Wordfence). O achado mais inesperado de toda a série.
- **Zero tool MCP de "attach" para código PHP executável** (doc 04 §11) — o Themer PHP tem
  deliberadamente nenhuma ability que torne um template PHP activo; só um humano no dropdown da
  metabox pode fazê-lo. Combinado com manifest-only lookup + path containment guard + tamper guard
  sha256 + shutdown fatal-recovery handler, é o modelo de segurança de 4 camadas mais valioso
  documentado para "código gerado por IA que corre no servidor".
- **Snapshot-before-write como contrato universal, não por-ability** (doc 05 §4.4, doc 08) — o
  Recorder é uma fachada fina; cada write-site decide o que capturar, mas o mecanismo de
  persistência/rollback é sempre o mesmo. A base SEO (doc 08) prova que isto pode ser tão genérico
  a ponto de dar rollback automático a integrações que nunca escrevem uma linha de código de undo.
- **Guarda Free⇄Pro single-instance** (doc 00 §7) — Free e Pro são o mesmo código-fonte em duas
  pastas de plugin; a guarda impede fatal de redeclaração se ambas activarem por engano. Não
  relevante para réplica (housekeeping de distribuição), mas explica a estrutura de ficheiros.

---

## 5. Sequência de construção recomendada para uma réplica

Ordem por dependência real (não por número de documento) — cada fase assume as anteriores feitas:

### Fase 0 — Fundação (sem isto, nada mais tem rollback nem é seguro)
1. Wrapper de registo (`emcp_tools_register_ability()` equivalente — doc 00 §5): `sanitize()` +
   `normalize_result()` no mínimo; `strictify()` só se formos alvo de clientes OpenAI-strict.
2. `register_mcp_server()` + dispatcher de compact tool mode (doc 00 §3-4) — ~250 linhas triviais,
   não vale a pena simplificar mais.
3. Change ledger unificado (doc 05 §4) — `Change_Log`/`Change_Recorder`/`Change_Blobs`, mesmo que
   inicialmente só com 2-3 tipos de rollback (`post-fields`, `option`, `file-backup`) e expansível
   depois.
4. Os 3 guards de maior risco (doc 07): `Filesystem_Guard::resolve_path()`,
   `Database_Guard::is_read_only_sql()`, `WPCLI_Validator`.

### Fase 1 — Conteúdo WordPress puro (sem dependência de Elementor)
5. `03-WORDPRESS-CORE-TEMAS`: posts/media/settings/users/menus/taxonomias. É a base útil mesmo
   sem nenhuma outra fase — um site sem Elementor já ganha valor MCP real aqui.
6. Gutenberg (doc 02 §3 + `Block_Tree`) — também sem dependência de Elementor, sempre-on.

### Fase 2 — Elementor (o núcleo de "construir páginas")
7. `01-ELEMENTOR-CLASSICO`: `Element_Factory`, `Elementor_Data` (com os ~14 gotchas numerados do
   próprio código — copiar a lógica de save/verify/fallback tal-e-qual), páginas/layout/widgets
   catalog-backed/templates.
8. `02-ATOMIC-V4-GUTENBERG` (parte atomic): `Atomic_Props` (copiar quase inteiro),
   `Atomic_Widget_Map`, `Atomic_Styles`.

### Fase 3 — Camadas de produto sobre o conteúdo
9. Sistema de módulos (doc 10 §1.1-1.2) — a máquina de toggles + `apply_defaults()` com seeding
   por-módulo.
10. `04-THEMER` — sistema de condições primeiro (é o mais reutilizável), depois CPT/render/blocos.
11. `05-REDIRECTS-SEARCH-LEDGER` (parte redirects) — 301/302 + broken-links + shadow warning.

### Fase 4 — Superfície de risco elevado, opt-in
12. `07-SYSTEM-OPS` restante: WP-CLI runner (**simplificável** — se o deployment for sempre
    SSH+STDIO como este ecossistema, `is_cli_context()` é sempre verdadeiro e todo o caminho shell
    + jobs detached pode ser cortado), Security Scanner, Performance Analyzer (ambos activos por
    omissão, só leitura — bom ROI inicial).
13. `06-SANDBOX-CUSTOM-CODE` — PHP snippets com aprovação humana; **replicar o padrão de
    aprovação, não pular directo para execução automática**.
14. Image Optimization + SVG Support (doc 10 §1.4-1.5) — os dois módulos opt-in mais bem
    desenhados de toda a árvore Free, sem dependência Pro nenhuma.

### Fase 5 — Integrações e periferia (valor incremental, não bloqueante)
15. `08-INTEGRACOES-TERCEIROS` — ACF/Meta Box/CF7/SlimSEO, só se esses plugins fizerem parte do
    stack alvo.
16. `09-STOCK-IMAGES-CLOUD-OAUTH` — Unsplash/Pexels/Pixabay + EMCP Cloud + OAuth (só se for
    preciso MCP remoto autenticado; Application Password/cookie admin cobre o caso local).

### Explicitamente fora de âmbito (doc 10 §2)
As **30 classes Pro-only** (WooCommerce completo, 8 integrações de formulários adicionais, 6 de
SEO adicionais, 2 packs de widgets Elementor de terceiros, Ultimate Addons, Brand/System Kit MCP,
SEO/A11y toolkit, Widget/Block Builder MCP, Skill/Memory/Migrate) representam **~18% do catálogo
total** e simplesmente não se constroem numa réplica 100% free/aberta — o mecanismo de gate
(`class_exists()` + ficheiro fisicamente ausente da árvore) só é replicável se quisermos a mesma
separação de monetização.

---

## 6. Tabela de risco consolidada

| Categoria | Activo por omissão? | Nº de tools destrutivas | Mecanismo de defesa principal |
|---|---|---|---|
| Filesystem (doc 07 §1) | **Não** (write/edit/delete) | 3 | `resolve_path()` confinamento a ABSPATH + backup automático |
| Base de dados directa (doc 07 §2) | **Não** (insert/update/delete) | 3 | `is_read_only_sql()` + `valid_table()` contra `SHOW TABLES` + before-image |
| WP-CLI (doc 07 §3) | **Não** (as 4, incl. as 2 readonly) | 2 (run/dispatch) | Blocklist comando/subcomando/flag + argv array nunca shell string |
| Security Scanner (doc 07 §4) | **Sim** — só leitura | 0 | — |
| Performance Analyzer (doc 07 §5) | **Sim** — só leitura | 0 | — |
| Themer PHP (doc 04 §11) | Módulo on, mas **zero tool de attach** | 0 (nenhuma torna código executável) | Aprovação humana obrigatória no dropdown da metabox |
| Sandbox PHP Snippets (doc 06) | Módulo on, execução gated | 0 (activação sempre humana) | Aprovação humana + manifest hash-verificado |
| Elementor/Gutenberg escrita (docs 01-02) | Sim | Várias (delete-*, remove-*) | Change ledger com rollback via `rollback-change` |
| Base de dados via ACF/Meta Box (doc 08) | Depende do plugin instalado | Poucas | Snapshot before-image (ACF); **gap identificado**: Meta Box sem registo algum |

**Gap de segurança mais citado nesta série** (doc 08 §Blueprint): Meta Box não tem nenhum
mecanismo de snapshot/rollback, ao contrário de ACF (`record_acf_fields`) e da base SEO
(`recordable_meta_keys()` automático). Uma réplica que use o padrão de "declarar meta keys
recordáveis" generalizado (em vez de cada integração implementar o seu próprio undo ad-hoc) fecha
este gap de origem.

---

## 7. Como usar esta documentação

- **Fork/rebranding rápido**: ler `00-ARQUITECTURA.md` §0 e §7 primeiro (namespace, guarda
  Free⇄Pro, licenciamento GPL), depois usar os docs 01-10 como mapa de onde cada coisa vive no
  código real para renomear/remover Freemius/ajustar prefixo de abilities.
- **Reescrita limpa**: seguir a sequência da secção 5 acima; cada documento de subsistema tem uma
  secção "Blueprint para réplica" com veredicto explícito copiar/simplificar/omitir por peça, e uma
  secção "Fonte" com os ficheiros exactos lidos (para re-verificar contra o código original em
  caso de dúvida).
- **Apenas auditoria/entendimento** (sem construir nada): `skill://emcp-tools` continua a ser a
  referência operacional para a instalação viva nos 3 sites Descomplicar (deny-list, módulos
  activos, postura de segurança); esta série documenta o CÓDIGO, não a CONFIGURAÇÃO de nenhum
  site específico.

---

## Metodologia

Cada um dos 10 documentos de subsistema foi produzido por um subagente `code-explorer`
independente, com leitura directa via `ssh://server` dos ficheiros PHP reais da instalação em
`emanuelalmeida.pt`, sem overlap de ficheiros entre agentes (coordenado via `hub` IRC quando
necessário — ver `history://Doc07SystemOps` para um exemplo de coordenação real). Nenhum conteúdo
foi inferido a partir de nomes de classe ou convenções assumidas sem confirmação directa no
código-fonte; onde a leitura foi parcial (ex. catálogos Pro de 1000+ linhas), o documento
correspondente declara explicitamente o que foi e não foi lido (ver `02-ATOMIC-V4-GUTENBERG.md`
§4.5 para o exemplo mais claro desta prática). Revisão cruzada final (secção 2 do processo desta
sessão) confirmou consistência de nomes de classe, tipos de rollback, e condições de gating entre
todos os 11 documentos — nenhuma contradição encontrada.