MCP Meta Ads

Servidor MCP para preparar, validar y crear campañas de Meta Ads desde un brief en castellano. El contrato está congelado en CAMPAIGN_SPEC.md: ese documento manda, este README solo cuenta cómo está implementado.

Estado: núcleo completo con la suite de tests de la sección 5 en verde. Nunca se corrió contra la Marketing API real — la sección 6 del spec (log de errores de Meta) sigue vacía justamente por eso.

Las 6 reglas invariantes, y dónde viven en el código

Related MCP server: meta-ads-manager-mcp

Estructura

meta_ads/
  errors.py        errores con `code` estable + mensaje accionable
  enums.py         objetivos, compatibilidades, CTAs, mínimos por moneda
  profiles.py      perfil de cuentas, resolución de cuenta, token, sandbox
  brief.py         brief en castellano -> hechos (nada que el brief no diga)
  spec.py          armado del Campaign Spec + provenance + warnings
  validate.py      validación local (2 severidades) + validate_only contra Meta
  payloads.py      spec -> payloads de la Marketing API (un solo lugar)
  meta_client.py   cliente HTTP (solo stdlib, urllib)
  create.py        creación de los 4 objetos + rollback
  server.py        adaptador MCP (mcp 1.x y 2.x)
tests/             80 tests, sin red, stdlib

El núcleo no tiene dependencias: pip install -r requirements.txt solo hace falta para exponerlo como servidor MCP.

Uso

cp profiles.example.json profiles.json     # completar ids reales (sandbox)
cp .env.example .env                       # y exportar SECRET_META_TOKEN_OWN
export META_ADS_PROFILES=$PWD/profiles.json
python3 -m meta_ads.server                 # stdio
./correr_tests.sh                          # la suite entera, sin red

Los tools se registran con nombre ASCII (preparar_campana, validar_campana, crear_campana) porque MCP no admite ñ en los identificadores; son los preparar_campaña / validar_campaña / crear_campaña del documento. Hay un cuarto tool, listar_cuentas, que no toca Meta: sirve para que el agente pueda preguntar "¿cuál de estas?" cuando la regla 2 lo obliga a preguntar.

El copy no lo inventa el servidor

preparar_campana(brief, account_alias?, creatives?) acepta creatives como lista de dicts escritos por el agente. Si no vienen, el spec sale con primary_text / headline en null, provenance pending y un warning; validar y crear los exigen completos. Es la división honesta: el spec resuelve estructura, el agente escribe texto. Lo mismo con los assets: image_hash / video_id entran ya resueltos, el spec no sube nada.

Desviaciones del spec congelado

Dos campos aditivos y opcionales (un spec sin ellos sigue siendo válido):

• preset (raíz): nombre del preset aplicado. Sin esto, las reglas 11-13 de la sección 5 no son verificables. Si falta, validate.py deduce el preset comparando objective + optimization_goal + destination_type contra los presets del perfil.

• ad_set.destination_type: los presets ya lo definen y la API lo pide.

Y dos valores de provenance que el documento no enumera: pending (copy que falta escribir) y brief aplicado a account.resolved_by cuando el propio brief nombra la cuenta.

Lo que todavía no está probado contra Meta

Esto es lo que hay que mirar primero cuando haya token de sandbox:

1. validate_only del ad set. Meta exige campaign_id para validar un ad set, y en preparar la campaña todavía no existe. Hoy se valida la campaña contra la API y el resto solo localmente; si el spec trae existing.campaign_id, también se valida el ad set. Ver validar_campana.

2. Click-to-WhatsApp. payloads.creative_payload arma call_to_action.value.app_destination = "WHATSAPP" con link = https://api.whatsapp.com/send. Es la forma más documentada, no está confirmada contra la cuenta.

3. Mínimos por moneda (enums.MIN_DIARIO_POR_MONEDA_MINOR): solo el USD sale de documentación. El resto son valores conservadores. El mínimo efectivo es max(mínimo de moneda, limits.daily_budget_min_minor), así que el techo real lo pone el perfil.

4. Nombres de enum en general: la tabla COMPATIBILIDAD es una foto y validate_only es el árbitro. Cada Invalid parameter que aparezca se corrige en enums.py y se anota en la sección 6 del CAMPAIGN_SPEC.md.

Mapa de los casos de test de la sección 5

test_invariantes.py cubre las 6 reglas de la sección 1 y el cliente HTTP; test_server.py, el contrato de los handlers MCP.

Los casos que "deben fallar" se verifican en las dos puertas: preparar los rechaza al armar el spec y validar/crear los rechazan también si alguien edita el spec a mano — con la comprobación extra de que la API no se llamó.