# 00 — Arquitectura do EMCP Tools e blueprint da réplica

Fonte: leitura directa do código-fonte `emcp-tools` v3.12.1 (build Free), instalado em
`emanuelalmeida.pt` (`/home/ealmeida/emanuelalmeida.pt/wp-content/plugins/emcp-tools/`),
19-08-2026. Autor terceiro: Mian Shahzad Raza (`msrbuilds.com`), repo público
`github.com/msrbuilds/elementor-mcp`, licença **GPL-2.0-or-later**.

## 0. Achado mais importante: a peça MCP não é do fornecedor — é do WordPress core team

O plugin **não implementa o protocolo MCP**. Depende de duas bibliotecas Composer, ambas
**projectos oficiais da equipa de IA do WordPress.org** (`WordPress AI Team`,
`make.wordpress.org/ai`), GPL-2.0-or-later, públicas:

| Pacote | Namespace PHP | Repo | O que faz |
|---|---|---|---|
| `wordpress/mcp-adapter` | `WP\MCP\` | `github.com/wordpress/mcp-adapter` | Expõe abilities da Abilities API como servidor MCP (`McpAdapter`, `McpServer`, `HttpTransport`, `SessionManager`, `RequestRouter`, `HttpSessionValidator`, `McpErrorFactory`) — cria o endpoint REST `/wp-json/mcp/{route}` |
| `wordpress/php-mcp-schema` | `WP\McpSchema\` | `github.com/WordPress/php-mcp-schema` | DTOs PHP para o schema oficial do protocolo MCP |

A **Abilities API em si é núcleo do WordPress 6.9+/7.0** (`wp_register_ability()`,
`wp_get_ability()`, `wp_get_abilities()`, hooks `wp_abilities_api_categories_init` /
`wp_abilities_api_init`) — não é código do plugin nem do adapter.

**Consequência directa para a réplica:** não há nada de protocolo para reimplementar.
`composer require wordpress/mcp-adapter` (ou vendorizar uma cópia, como o EMCP faz — ver §1)
dá-nos a mesma máquina JSON-RPC/sessão/transporte. O trabalho real do "clone" é: (a) registar
as nossas próprias abilities via `wp_register_ability()`, com o nosso próprio prefixo (ex.
`descomplicar-tools/*`), e (b) `$mcp_adapter->create_server(...)` com o nosso `server_id`. Tudo o
resto — catálogo de ~165 tools, módulos, sandbox, change-ledger, content-mirror — é trabalho de
aplicação, não de protocolo.

**Nota de licenciamento:** por ser GPL-2.0-or-later, nada impede legalmente copiar/adaptar o
código-fonte do EMCP Tools directamente para um plugin próprio (fork), mantendo a licença GPL a
jusante. "Réplica 100% nossa" pode ser lida como (a) fork com rebranding + remoção do Freemius +
namespace próprio (muito menos esforço, reutiliza ~78k linhas já testadas), ou (b) reimplementação
limpa a partir desta especificação (mais esforço, zero dependência de código de terceiros,
liberdade total de redesenho). Esta série de documentos serve ambos os caminhos — é a
especificação funcional; a decisão de fork-vs-reescrita é independente dela.

## 1. Estrutura de directórios do plugin

```
emcp-tools/
├── emcp-tools.php                    # bootstrap: header, guarda Free⇄Pro, Freemius, handoff
├── includes/
│   ├── class-bootstrap.php           # boot(): dependências, carrega classes, arranca Plugin
│   ├── class-plugin.php              # EMCP_Tools_Plugin (singleton orquestrador) — ver §3
│   ├── class-mcp-adapter-bootstrap.php  # preload do WP\MCP\ vendorizado — ver §2
│   ├── class-schema-compat.php       # emcp_tools_register_ability() + normalização de schema
│   ├── abilities/
│   │   ├── class-ability-registrar.php   # regista TODOS os grupos de abilities — índice mestre
│   │   ├── class-dispatcher-abilities.php # compact tool mode (list-tools/get-tool-schema/call-tool)
│   │   ├── class-{grupo}-abilities.php    # ~40 classes de abilities (uma por grupo funcional)
│   │   ├── forms/class-{plugin}-integration.php  # CF7 (free) + dispatcher genérico
│   │   └── seo/class-{plugin}-integration.php    # SlimSEO (free) + dispatcher genérico
│   ├── modules/          # os 9 módulos opcionais + registry — ver doc 10
│   ├── themer/            # Themer CPT/render/condições/blocos/widgets/PHP — ver doc 04
│   ├── sandbox/           # armazenamento de artefactos sandbox (bundle/paths/store) — ver doc 06
│   ├── security/          # 4 auditores + finding — ver doc 07
│   ├── performance/       # 3 auditores + finding — ver doc 07
│   ├── redirects/         # handler + store — ver doc 05
│   ├── cloud/              # ligação/sync EMCP Cloud — ver doc 09
│   ├── oauth/              # servidor OAuth para autenticação MCP remota — ver doc 09
│   ├── wpcli/              # runner/validator/jobs para run-wp-cli — ver doc 07
│   ├── widgets/            # catálogos de widgets Elementor (free/woo/pro) — ver doc 02
│   ├── blocks-catalog/     # catálogos Kadence Blocks / Spectra — ver doc 03
│   ├── schemas/            # gerador de JSON Schema a partir de controls Elementor
│   ├── validators/         # validador de settings/elementos
│   ├── admin/              # UI de admin: class-admin.php (6115 linhas!), views/*, mcpb-builder
│   └── vendors/fremius/    # SDK Freemius (licenciamento/billing) — ~50k linhas, IRRELEVANTE p/ réplica
├── vendor/wordpress/       # mcp-adapter + php-mcp-schema vendorizados (ver §0)
├── vendor/enshrined/svg-sanitize/  # sanitização SVG (módulo svg-support)
├── vendor/automattic/jetpack-autoloader/  # autoloader partilhado entre plugins que usam o adapter
└── prompts/, assets/, bin/, languages/
```

**Total:** ~128 465 linhas PHP fora de `vendor/`/`languages/` (medido 19-08-2026); ~50k dessas
são o SDK Freemius bundled (irrelevante para a réplica — ver §6). Ficheiro maior de longe:
`includes/admin/class-admin.php`, **6115 linhas** (catálogo de tools para a UI, aplicação do
deny-list incremental de 34 versões, todas as views de admin — ver doc dedicado se necessário).

## 2. Cadeia de arranque (ordem real de hooks)

```
emcp-tools.php carrega no arquivo (topo do request)
  ↓ guarda Free⇄Pro (§7), depois Freemius init
  ↓ require class-bootstrap.php
  add_action('plugins_loaded', [Bootstrap, 'boot'], 20)
    ↓
plugins_loaded:20 → EMCP_Tools_Bootstrap::boot()
  ↓ EMCP_Tools_Adapter_Bootstrap::ensure() — preload do WP\MCP\ vendorizado (ver §2.1)
  ↓ require de todas as classes includes/**/*.php
  ↓ EMCP_Tools_Plugin::instance() → init()
      add_action('wp_abilities_api_categories_init', register_category)
      add_action('wp_abilities_api_init', register_abilities)       # regista ~165 abilities
      add_action('mcp_adapter_init', register_mcp_server, 20)        # cria o servidor MCP
      add_filter('emcp_tools_ability_names', filter_disabled_tools)  # aplica o deny-list
      add_filter('rest_pre_dispatch', MCP_Host_Guard::guard, 5)      # valida Host header
      add_filter('rest_pre_dispatch'/'rest_post_dispatch', mcp_log_*) # log de pedidos MCP
    ↓
(Abilities API é lazy — só inicializa no primeiro wp_get_ability())
O PRÓPRIO adapter, ao arrancar (mcp_adapter_init prioridade 10), chama wp_get_ability()
internamente para descobrir tools → dispara wp_abilities_api_init → register_abilities() corre
ANTES do nosso register_mcp_server (prioridade 20) — por isso $this->ability_names já está
preenchido quando register_mcp_server lê $this->ability_names.
    ↓
mcp_adapter_init:20 → EMCP_Tools_Plugin::register_mcp_server($mcp_adapter)
  → $mcp_adapter->create_server('emcp-tools-server', 'mcp', 'emcp-tools-server', …, $tools, …)
  → endpoint fica disponível em /wp-json/mcp/emcp-tools-server
```

### 2.1 O preload "authoritative namespace" (`class-mcp-adapter-bootstrap.php`)

Problema real documentado no código (issue #99): quando **vários plugins activos** vendorizam
`wordpress/mcp-adapter` (ex. WooCommerce + EMCP Tools) em versões diferentes, e nem todos usam o
mesmo autoloader partilhado (Jetpack Autoloader), PHP carrega **classes individuais** de cópias
diferentes consoante qual plugin referencia cada classe primeiro — resultado: um `McpAdapter` da
v0.5.0 a par de um `HttpTransport` da v0.4.1 no mesmo request ("sheared namespace"), que falha
com `McpServerError: Session terminated` (JSON-RPC -32600).

**Mitigação do EMCP:** regista um autoloader `spl_autoload_register($cb, true, true)` (throw,
**prepend**) logo no arranque, servindo TODO o namespace `WP\MCP\` a partir da SUA cópia
vendorizada — antes que qualquer outro plugin possa referenciar uma classe do adapter. Reafirma-se
depois de carregar o Jetpack Autoloader do próprio adapter (que também se regista com prepend).

**Implicação para a réplica:** se formos "mais um plugin" a vendorizar `wordpress/mcp-adapter`
lado a lado com EMCP Tools/WooCommerce no mesmo WordPress, herdamos este mesmo risco de colisão.
Duas opções limpas: (a) usar o Jetpack Autoloader nós também (para participar na arbitragem de
versão-mais-alta em vez de competir com autoloaders simples), ou (b) não vendorizar — depender de
uma cópia `wordpress/mcp-adapter` partilhada ao nível do site (plugin dedicado só ao adapter,
todos os outros plugins declaram a dependência) — mais correcto a prazo mas exige coordenação com
todos os plugins que hoje bundlam a sua própria cópia.

## 3. `EMCP_Tools_Plugin` — orquestrador singleton

Ficheiro: `includes/class-plugin.php`. Contrato mínimo para a réplica:

- **`register_category()`** — `wp_register_ability_category('<prefixo>', ['label'=>…,
  'description'=>…])`, chamado em `wp_abilities_api_categories_init`.
- **`register_abilities()`** — `$this->ability_names = $registrar->register_all($elementor_active)`,
  chamado em `wp_abilities_api_init`. `$elementor_active` vem de
  `EMCP_Tools_Bootstrap::elementor_active()` (guarda de dependência — grupos Elementor-dependentes
  ficam todos atrás desta flag, ver doc 01/02 e a lista completa em `class-ability-registrar.php`
  reproduzida no doc 10).
- **`get_active_ability_names()`** — força a inicialização lazy da Abilities API
  (`wp_get_ability('emcp-tools/list-pages')` como gatilho) e devolve o array já filtrado pelo
  deny-list; usado pelo dispatcher (compact mode) e por qualquer superfície externa (ex. um chat
  de admin) que precise de saber "o que está mesmo disponível agora".
- **`filter_disabled_tools($names)`** — `array_values(array_diff($names,
  get_option('emcp_tools_disabled_tools', [])))`, hook em `emcp_tools_ability_names`. **Este é o
  único ponto de aplicação do deny-list** — mecanismo do deny-list incremental (34 migrações) já
  documentado em `skill://emcp-tools` §8; aqui confirma-se o hook exacto que o aplica.
- **`register_mcp_server($mcp_adapter)`** — chamado em `mcp_adapter_init` prioridade 20 (depois da
  Abilities API já ter corrido). Comportamento condicional:
  - **Server gate** (`emcp_tools_server_enabled`, on por omissão): se off, abilities continuam
    registadas no core mas **nenhum endpoint MCP é criado** — kill-switch total sem desregistar
    nada.
  - **Compact tool mode** (`emcp_tools_dispatcher_mode`, off por omissão): quando ligado, o
    `$tools` passado a `create_server()` é só os 3 nomes do dispatcher
    (`emcp-tools/{list-tools,get-tool-schema,call-tool}`) — o resto continua **registado e
    invocável via `call-tool`**, só não aparece em `tools/list`. Quando desligado, `$tools` é a
    lista cheia (+ as 3 abilities de contexto do core: `core/get-site-info`,
    `core/get-user-info`, `core/get-environment-info`, sempre incluídas quando existirem).
  - `create_server()` recebe: `server_id='emcp-tools-server'`, `route_namespace='mcp'`,
    `route='emcp-tools-server'` (→ endpoint final `/wp-json/mcp/emcp-tools-server`), nome/descrição
    (descrição compõe um resumo do ambiente do site via `EMCP_Tools_Site_Context`), versão,
    `transports=[HttpTransport::class]`, `tools=$tools`, `resources=[]`, `prompts=[]`, e um
    `transport_permission_callback` opcional: se o módulo OAuth (`EMCP_Tools_OAuth_Server`) está
    activo, usa Bearer OAuth; senão cai no default do adapter (Application Password / cookie
    admin).

## 4. Compact tool mode — o dispatcher de 3 tools

`includes/abilities/class-dispatcher-abilities.php` (ver excerto completo lido nesta sessão).
Sempre **registado** (para `wp_get_ability()` resolver os 3 nomes), mas só **exposto no servidor**
quando `emcp_tools_dispatcher_mode=1` (§3). Este é exactamente o padrão que os 3 servidores
`emcp-tools`/`emcp-emanuelalmeida`/`emcp-descomplicar` deste ecossistema já usam pelo lado do
cliente (system prompt: "Compact tool mode... Discover tools with list-tools, fetch inputs with
get-tool-schema, run with call-tool").

| Tool | O que faz | Enforcement |
|---|---|---|
| `list-tools` | Devolve `{name, description, category, destructive}` para cada ability activa (pós-deny-list), filtrável por `search`/`category`. Inclui `context` (resumo do ambiente via `Site_Context`). | `permission_callback`: `current_user_can('edit_posts')` — é só metadata/routing |
| `get-tool-schema` | Devolve `{description, inputSchema}` por nome, em lote (`names: string[]`). Nomes fora do set activo entram em `unavailable`. | idem |
| `call-tool` | Resolve `wp_get_ability($name)`, corre `check_permissions($args)` **da ability alvo** (nunca do dispatcher), depois `validate_input()` se existir, depois `execute($args)`. | **A gate real é sempre a da tool alvo** — o dispatcher nunca contorna `permission_callback` individual |

**Blueprint para a réplica:** replicar este padrão exactamente — um dispatcher de 3 tools que só
resolve/chama `wp_get_ability()`, nunca duplica lógica de permissão. É ~250 linhas triviais de
reescrever do zero (schema simples, sem estado) — não vale a pena tentar simplificar mais.

## 5. `emcp_tools_register_ability()` — o único ponto de entrada de registo

`includes/class-schema-compat.php`. Toda classe de abilities chama esta função global (nunca
`wp_register_ability()` directamente). Faz 3 coisas antes de delegar:

1. **`sanitize()`** — normaliza o JSON Schema para clientes exigentes: remove valores vazios de
   `enum`, força `properties: {}` (objecto, nunca array vazio) — Gemini/Antigravity rejeitam a
   forma "errada". Recursivo em `items`/`allOf`/`oneOf`/`anyOf`.
2. **`strictify()`** *(opt-in, `emcp_tools_strict_schemas`, off por omissão)* — reescreve o schema
   para o modo "strict function calling" da OpenAI: toda a propriedade em `required`, as
   originalmente opcionais tornam-se nullable, `additionalProperties: false` em objectos com
   propriedades declaradas. Existe porque CrewAI e stacks OpenAI-compatíveis exigem esta forma; um
   schema "normal" (opcionais fora de `required`) é rejeitado por eles.
3. **`wrap_execute_callback()`** — envolve o callback da ability em dois cuidados:
   - **Veto de escrita** (`emcp_tools_before_write` filter, só para abilities não-read-only):
     um listener pode devolver `WP_Error` para bloquear a escrita antes de correr — mecanismo real
     de enforcement de guardrails (usado pela feature Pro "Memory Enforcer"). Seam útil para nós:
     dá um ponto único onde qualquer política de governança (ex. CARL) pode vetar uma escrita MCP
     sem tocar em cada ability individualmente.
   - **`normalize_result()`** — garante que o retorno cabe em `structuredContent` do MCP (que o
     schema tipa como objecto `{[key:string]:unknown}`, nunca lista). Arrays associativos e
     objectos passam直; listas/escalares/`null` são embrulhados em `{data: …}`; `array()` vazio
     TAMBÉM é embrulhado (PHP não distingue lista vazia de mapa vazio — desembrulhado serializa
     para `[]`, forma inválida). **Bug real que isto evita:** a integração WooCommerce devolve
     `WP_REST_Response::get_data()` verbatim, e várias rotas `wc/v3` respondem com array de topo
     (ex. `report-products-totals`) — sem este wrapper, clientes MCP estritos rejeitam a resposta.

**Blueprint para a réplica:** replicar exactamente este envelope (sanitize + normalize_result no
mínimo; strictify só se formos alvo de clientes OpenAI-strict). É a peça que evita uma classe
inteira de bugs "funciona no Claude, parte no CrewAI" — não pular esta camada achando-a
acessória.

## 6. Guardas de infraestrutura (fora do fluxo funcional, mas obrigatórias)

- **`EMCP_Tools_MCP_Host_Guard::guard`** (`rest_pre_dispatch`, prioridade 5) — recusa pedidos MCP
  cujo header `Host` já não bate com o `home` do site (conector apontado para um domínio
  antigo/temporário). `no_store_headers` (`rest_pre_serve_request`) força `Cache-Control:
  no-store` nas respostas MCP — proxies como LiteSpeed/QUIC descartam respostas suspeitas de cache
  sem isto (issue nomeada no código).
- **`EMCP_Tools_MCP_Request_Log`** — grava tool/status/duração/`x-request-id` de cada pedido MCP
  via `rest_pre_dispatch`(6)/`rest_post_dispatch`(10), só para rotas que começam por
  `/mcp/emcp-tools-server` — alimenta a tab "MCP Log" do admin.

## 7. Guarda Free⇄Pro (single-instance)

`emcp-tools.php`, topo do ficheiro (antes de qualquer `require`). Free e Pro são **o mesmo código**
em duas pastas de plugin (`emcp-tools/` vs `emcp-pro/`), distinguidas só por um marcador
`.emcp-pro` no directório. Como WordPress trata as duas pastas como plugins distintos,
`require_once` não deduplica entre elas — activar ambas redeclara todas as classes → fatal error.
A guarda corre **antes de qualquer require**, detecta se já correu neste request
(`defined('EMCP_TOOLS_VERSION')`) e decide: Premium sempre ganha — a cópia Free cede (mostra aviso,
`return` antes de declarar nada) se a Premium estiver activa; a cópia Premium desactiva a Free se
esta já tiver arrancado primeiro. **Não relevante para a réplica** (é housekeeping específico do
modelo de distribuição Free/Pro deste vendor) — mas explica porque é seguro assumir que só UMA
"visão" do código corre por request, mesmo no build Free.

## 8. Superfície total (dimensionamento)

Ver `class-ability-registrar.php::register_groups()` para a lista EXACTA de classes/condições —
reproduzida integralmente no doc 10 (módulos) como referência cruzada, porque a ordem de registo
ali É a fonte de verdade de que grupo depende de que módulo/plugin/licença. Resumo por doc:

| Doc | Assunto | Nº aprox. de abilities |
|---|---|---|
| 01 | Elementor clássico (páginas, layout, widgets, templates, globals, custom code, composite) | ~35 |
| 02 | Elementor Atomic v4 + Gutenberg | ~25 |
| 03 | WordPress core (conteúdo, media, settings, plugins, temas, users, menus) + temas/frameworks | ~30 |
| 04 | Themer (CPT header/footer/single/archive/search/404 + Themer PHP) | ~13 |
| 05 | Redirects + Search + Snapshot + Change-ledger + Content-mirror | ~14 |
| 06 | Sandbox (PHP snippets, custom widgets/blocks, cloud bundle) | ~20 |
| 07 | Filesystem + DB + WP-CLI + Security + Performance | ~15 |
| 08 | Integrações terceiros (ACF, Meta Box, forms, SEO) | ~30 |
| 09 | Stock images + Cloud sync + OAuth | ~17 |
| 10 | Módulos (lifecycle) + inventário Pro-only (metadata) | n/a (estrutural) |

Total bate aproximadamente com os 162-165 confirmados ao vivo em `skill://emcp-tools` §7 — a
diferença entre sites reflecte quais integrações de terceiros estão de facto instaladas.

## Fonte

Leitura directa (19-08-2026) de: `emcp-tools.php`, `includes/class-mcp-adapter-bootstrap.php`,
`includes/class-plugin.php`, `includes/class-schema-compat.php`,
`includes/abilities/class-ability-registrar.php`,
`includes/abilities/class-dispatcher-abilities.php`,
`vendor/wordpress/mcp-adapter/composer.json`, `vendor/wordpress/php-mcp-schema/composer.json`;
inventário completo de ficheiros (`find … -name '*.php' -exec wc -l`, 128 465 linhas). Cruzado com
`skill://emcp-tools` (auditoria de postura de segurança, 16-08-2026) para os números de abilities
activas/desligadas por site.