Migrar uma API WordPress existente para MCP: um plano de 4 semanas
Construir um servidor MCP de raiz é simples. Migrar a partir de uma REST API do WordPress existente e a funcionar, enquanto continua a servir tráfego de produção, é uma forma mais difícil. Este plano é o que uso para passar de “temos /wp-json/ e um consumidor parceiro” para “temos /wp-json/, esse parceiro e um servidor MCP amigo dos LLM à frente”, sem partir nada.
O artigo faz parte do pilar desenvolvimento de servidores MCP.
TL;DR
- Quatro semanas: auditoria, estrutura, execução em paralelo, transição.
- A REST continua ativa para os consumidores existentes; o MCP é um acréscimo, não um substituto.
- Os esquemas Zod vêm da auditoria à REST, não de uma lista de desejos.
- Execução em paralelo com um agente interno antes de o tráfego externo chegar ao MCP.
- O Logpush capta cada chamada de ferramenta; as discrepâncias entre respostas MCP e REST aparecem como erros de esquema.
Como auditar os endpoints da REST API do WordPress
A auditoria é uma folha de cálculo. Uma linha por endpoint, com estas colunas:
| Coluna | O que registamos |
|---|---|
| Endpoint | /wp-json/wp/v2/posts, /wp-json/wc/v3/products, etc. |
| Verbos HTTP | GET, POST, PUT, DELETE suportados |
| Consumidores atuais | Loja, ERP do parceiro, recetores de webhooks |
| Volume de tráfego | Pedidos por dia a partir dos registos de acesso |
| Sensibilidade dos dados | Públicos, de clientes, só administração |
| Altera o estado? | Sim/não |
| Corresponde a uma ferramenta MCP? | Nome proposto da ferramenta e intenção |
| Notas | Plugins envolvidos, formas de campos personalizados, armadilhas |
Para uma loja WooCommerce típica, a folha tem 20 a 60 linhas. A maioria traduz-se de forma limpa em ferramentas MCP; um punhado (internos da administração, endpoints específicos de plugins, recetores de webhooks) fica só em REST.
O resultado da semana 1 são dois artefactos:
- Um inventário de ferramentas proposto:
catalogue.list,product.detail,order.intent,order.status,inventory.check, mais o que for específico da sua construção. - Um primeiro rascunho dos esquemas Zod para as entradas e saídas de cada ferramenta, derivado das respostas REST reais captadas durante a auditoria.
Capto as respostas REST com curl e jq para inspecionar a forma, ou com uma coleção do Postman partilhada pela equipa. O objetivo é a verdade empírica, não o que o README diz. Os plugins do WordPress são conhecidos por acrescentar campos que a documentação nunca regista; a auditoria apanha-os.
Como montar um servidor MCP no Cloudflare Workers
O resultado da semana 2 é um servidor MCP funcional, com deploy num ambiente Cloudflare Workers fora de produção, e o inventário de ferramentas da semana 1 implementado como adaptadores finos sobre os endpoints REST existentes.
O esqueleto do servidor:
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { catalogueListInput, catalogueListOutput, handleCatalogueList } from "./tools/catalogue-list.js";
import { productDetailInput, productDetailOutput, handleProductDetail } from "./tools/product-detail.js";
// ... jeden import na narzędzie
export function createMcpServer(env: Env): Server {
const server = new Server({
name: "wppoland-mcp",
version: "0.1.0",
});
server.tool(
"catalogue.list",
catalogueListInput,
catalogueListOutput,
(input) => handleCatalogueList(input, env),
);
server.tool(
"product.detail",
productDetailInput,
productDetailOutput,
(input) => handleProductDetail(input, env),
);
// ... jedno wywołanie .tool() na narzędzie
return server;
}Cada handler é um adaptador fino. Recebe a entrada validada, constrói a query string, faz fetch a /wp-json/, mapeia a resposta para uma forma de saída alinhada com schema.org, chama parse sobre a saída e devolve. A lógica de negócio fica no WordPress; o handler é uma tradução mecânica.
A semana 2 inclui também a estrutura de autenticação do guia de padrões de autenticação MCP. Para a execução em paralelo da semana 3 uso um único token de teste com todos os scopes; os scopes de produção aperto-os na semana 4.
O wrangler.toml do ambiente de preview aponta para uma instalação de staging do WordPress ou uma cópia da produção. O servidor MCP está acessível num URL *.mcp-staging.wppoland.workers.dev disponível apenas para a equipa.
Como testar o servidor MCP em paralelo com a REST API
É na semana 3 que os bugs aparecem. O padrão:
Construa um harness de comparação. Um pequeno script TypeScript que recebe o nome de uma ferramenta e uma entrada, chama o servidor MCP, depois chama diretamente o endpoint REST equivalente e compara as duas respostas. A diferença fica registada com o nome da ferramenta, a entrada e um caminho ao estilo JSON pointer para cada discrepância.
async function compareToolToRest(toolName: string, input: unknown) {
const mcpResponse = await callMcp(toolName, input);
const restResponse = await callEquivalentRest(toolName, input);
const diff = jsonDiff(restResponse, mcpResponse);
if (diff.length > 0) {
await logMismatch({ toolName, input, diff });
}
}Cada ferramenta contra um conjunto representativo de entradas. Para catalogue.list: query vazia, query que devolve centenas de produtos, query com filtro de categoria, query com intervalo de preços, query sem resultados. Para product.detail: SKU conhecido, SKU desconhecido, SKU com variações, SKU com campos personalizados. Cubra os casos-limite da auditoria.
Aponte um agente interno para o servidor MCP. O Claude Desktop com o servidor MCP configurado como fonte remota de ferramentas é a configuração que uso. Alguém da equipa passa 30 minutos por dia, durante uma semana, a interagir com a própria loja através do agente e a registar as surpresas num documento partilhado.
Aperte os esquemas com base no que volta. Cada falha de validação Zod no registo é um bug de esquema ou um bug de mapeamento. Corrija, volte a fazer deploy do Worker de preview, repita o harness.
O resultado da semana 3 é um harness que passa com zero diferenças e um inventário de ferramentas que sobreviveu a cinco dias de 30 minutos diários de interação real com o agente. Se faltar algum dos dois, a semana 4 não arranca.
Como pôr o servidor MCP em produção e monitorizá-lo
A transição não tem drama se as semanas 1 a 3 correram bem.
Faça deploy dos Workers de produção. wrangler deploy --env production. O servidor MCP de produção aponta para a origem WordPress de produção, com scopes de produção nos tokens emitidos pela administração do WordPress.
Emita tokens para o primeiro runtime real de agente. Normalmente um destes: um agente interno para colaboradores, uma integração de parceiro que pede uma superfície MCP, um assistente público na loja. Comece pelo consumidor mais pequeno e de menor risco.
Ligue o Cloudflare Logpush a um armazenamento de longo prazo. Os campos de registo descritos no artigo sobre construir um servidor MCP para WooCommerce são as predefinições certas: nome da ferramenta, hash da entrada, latência, resultado da validação, scope do token. O armazenamento é o que a sua equipa já usa (BigQuery, ClickHouse, S3 + Athena).
Construa um painel de observação. Três consultas desde o primeiro dia:
- Chamadas de ferramentas por minuto, divididas por nome da ferramenta. Deteta picos de carga.
- Taxa de falhas de validação por ferramenta, dividida por código (
input_invalid,output_invalid). Deteta regressões. - Latência p50/p95/p99 por ferramenta. Deteta um WordPress lento mais acima na cadeia.
Mantenha a REST viva e intocada. A loja existente, as integrações de parceiros existentes e os recetores de webhooks existentes continuam a usar /wp-json/ exatamente como antes. O MCP é um acréscimo, não um substituto. É a regra mais importante da migração.
Os erros mais comuns ao migrar a REST API para MCP
Seis coisas que vi falhar em migrações reais:
Um campo da resposta REST que a auditoria não apanhou. Um plugin acrescenta meta_data: [...] às respostas de produtos. O esquema de saída MCP não o conhece. O parse do Zod falha com dados reais. Correção: repita a auditoria sobre tráfego de produção, alargue o esquema ou descarte o campo explicitamente com .transform().
Permalinks diferentes entre staging e produção. A ferramenta MCP product.detail devolve o campo permalink do WooCommerce. Os permalinks de staging são https://staging.example.com/...; os de produção https://example.com/.... Os dados de teste passam; a produção falha no validador de URL. Correção: configure o Worker de staging com um passo de reescrita de permalinks que espelhe o comportamento de produção.
Tratamento de variações do WooCommerce. A auditoria captou a forma da resposta de um produto simples. As respostas das variações são diferentes (os SKU das variações vivem em /wp-json/wc/v3/products/<id>/variations). Correção: trate as variações como um fetch separado em product.detail e mapeie-as para hasVariant do schema.org.
O token de autenticação vaza para os registos. Um handler regista o cabeçalho Authorization completo para depuração. O token acaba no armazenamento de registos. Correção: oculte o cabeçalho na camada de registo; rode todos os tokens emitidos antes de a ocultação estar em vigor. Relevante para o cumprimento do artigo 32.º do RGPD.
A atualização de um plugin parte a resposta REST. O WooCommerce 9.x muda o nome de um campo, o handler MCP continua à espera do nome antigo, o parse do Zod falha. Correção: fixe a versão do WooCommerce em staging, corra o harness de comparação em cada atualização do WordPress e trate o harness como parte da barreira de atualização.
O agente entra em ciclo numa chamada de ferramenta malformada. Um agente defeituoso repete order.intent 100 vezes por minuto quando a entrada falha a validação. Sem rate limit, a origem WordPress recebe 100 chamadas em cascata. Correção: rate limit por principal, como no guia de padrões de autenticação MCP, e devolva retry_after_seconds no envelope de erro.
Quanto tempo demora migrar a API do WordPress para MCP
Quatro semanas é a predefinição. Dois ajustes:
Superfície menor, duas semanas. Três ferramentas, um consumidor, sem complexidade de autenticação. Comprima a auditoria e a estrutura na semana 1, a execução em paralelo e a transição na semana 2. O mesmo padrão, um calendário mais curto.
Superfície maior, seis semanas. Uma dúzia de ferramentas, vários modos de autenticação, ações sensíveis que alteram dados. Acrescente uma semana entre a estrutura e a execução em paralelo para revisão de segurança. Acrescente uma semana entre a execução em paralelo e a transição para um lançamento suave com um único utilizador autorizado por OAuth, antes de um rollout mais amplo.
As quatro fases mantêm a mesma ordem, seja qual for o orçamento de tempo.
O WordPress muda depois de adotar MCP?
Em termos simples, depois da migração:
- A interface de administração do WordPress fica igual.
- O Block Editor fica igual.
- O sistema de autenticação de utilizadores fica igual.
- Os endpoints REST existentes ficam iguais e continuam a servir os seus consumidores.
- A lógica de disparo de webhooks fica igual.
- A camada de dados (
wp_posts,wp_postmeta, tabelas do WooCommerce) fica igual.
O que se acrescenta: o servidor MCP no Cloudflare Workers, uma interface de emissão de tokens na administração do WordPress (um pequeno plugin ou uma função do tema) e a configuração do Cloudflare Logpush. Tudo o resto fica igual.
É precisamente isto que torna a migração de baixo risco. Se o servidor MCP tiver um mau dia, desliga o Worker. A superfície para agentes desaparece. A loja continua a funcionar, as integrações de parceiros continuam a funcionar e as encomendas continuam a entrar.
Temas relacionados
Este artigo trata da forma da migração. A implementação está descrita no artigo sobre construir um servidor MCP para WooCommerce. A estratégia de autenticação é tratada no guia de padrões de autenticação MCP. O desenho de ferramentas tipadas é tratado no artigo sobre ferramentas de catálogo tipadas com Zod para MCP. A decisão ao nível do protocolo é tratada na comparação entre MCP e REST. A página do serviço é desenvolvimento de servidores MCP.
O orçamento é individual, porque o âmbito da migração depende do número de endpoints na auditoria, da complexidade da autenticação e do número de consumidores.
Do lado da implementação, este tema enquadra-se na migração para Next.js ou Astro.
