# EMCP Tools — Mapeamento completo e blueprint de réplica Índice e síntese de 12 documentos (~6 940 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 um doc adicional (11) fundamentado no WooCommerce 11.0.1 real instalado em `ecommerce.descomplicar.pt`. 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 | Total: **~6 940 linhas de documentação**, ~165 abilities EMCP confirmadas + ~35 abilities WooCommerce propostas (doc 11, não implementadas no EMCP — blueprint próprio) 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.