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	Bootstrap, ability registrar, dispatcher compact mode, register_mcp_server, guarda Free⇄Pro	277	n/a (estrutural)	— (fundação de tudo)
01-ELEMENTOR-CLASSICO	Páginas, layout, widgets (catálogo), templates, global settings/classes, custom code, SVG, composite	632	~35	Elementor activo
02-ATOMIC-V4-GUTENBERG	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	Posts/media/settings/plugins/temas/users/menus + integrações de tema (Astra/Spectra/Kadence)	494	~30	Nenhuma (core puro)
04-THEMER	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	Redirects 301/302, broken-links, change ledger unificado (rollback), content-mirror	727	~14	Módulo redirects (redirects) · nenhuma (ledger)
06-SANDBOX-CUSTOM-CODE	PHP snippets com aprovação humana, export/import de artefactos, Widget Builder (Pro, ausente)	336	~20	Nenhuma (snippets free)
07-SYSTEM-OPS	Filesystem, base de dados directa, WP-CLI, Security Scanner, Performance Analyzer	629	~15	Nenhuma — maior risco do plugin
08-INTEGRACOES-TERCEIROS	ACF, Meta Box, formulários (CF7 free), SEO (SlimSEO free)	457	~30 (free)	Plugin de terceiros instalado
09-STOCK-IMAGES-CLOUD-OAUTH	Unsplash/Pexels/Pixabay, EMCP Cloud (ligação/sync), servidor OAuth para MCP remoto	654	~17	Nenhuma
10-MODULOS-E-INVENTARIO-PRO	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	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	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.