Plugin de tres canales de AdsAgent

Plugin público de Claude + paquete de habilidades para MCP alojado en tres canales de AdsAgent: Meta, Google Ads y TikTok.

División de distribución (importante):

Repositorio oficial de GitHub: github.com/adsagents/adsagent-ai-skills

Sitio web: adsagent.md

Centro de enlaces oficiales: adsagent.md/connect

Página de inicio del paquete de habilidades: adsagent.md/skills

Soporte: support@adsagent.md

Versión actual del contrato: 0.7.64. El slug del plugin es adsagent (clave de marketplace adsagent). Las nuevas conexiones de Meta utilizan por defecto el perfil de producto v2; los tres puntos finales alojados negocian detección sin estado MCP moderna 2026-07-28 manteniendo clientes de inicialización heredados compatibles.

El historial de versiones se encuentra en CHANGELOG.md.

El script auxiliar local scripts/update_reminder.py compara versiones semánticas estrictas y almacena solo estado de versión/marca de tiempo limitado en $XDG_CACHE_HOME/adsagent-ai-skills/update-reminder-v1.json (o ~/.cache/...). Un fallo de caché nunca bloquea el trabajo de MCP.

Qué es esto

• Un paquete de marketplace público de plugin de Claude: habilidades de comportamiento más URLs MCP alojadas a través de .mcp.json.

• Una guía de comportamiento para Claude Code, Cursor, Codex y otros clientes compatibles con MCP.

• Una capa de fiabilidad y seguridad que indica a los agentes cuándo reintentar, cuándo esperar y cuándo detenerse.

• Una distribución versionada en GitHub para la incorporación de usuarios de AdsAgent y la guía de comportamiento de agentes.

• Un contrato de minimización de datos para agentes de IA que no deben escanear AdsAgent como una base de datos en bruto.

Related MCP server: Meta Marketing API MCP Server

Qué no es esto

• No es la lista de MCP del Directorio de Conectores de Anthropic (eso está registrado por separado en los servidores alojados).

• No es una referencia completa de herramientas MCP.

• No es un SDK.

• No es un relé de transporte local.

• No es una divulgación de rutas, esquemas, tablas de bases de datos o diagnósticos internos del backend de AdsAgent.

Para instalaciones de plugins de Claude Code, la configuración de MCP OAuth proviene del .mcp.json de este repositorio. Para clientes sin soporte de plugin, el mensaje de instalación del panel de AdsAgent sigue siendo la alternativa manual:

AdsAgent dashboard -> Settings -> MCP Access -> Copy install prompt

Usa ese prompt copiado solo cuando no estés instalando el paquete de plugin de Claude. Este repositorio enseña el comportamiento del agente después de que exista la conexión MCP.

Habilidades incluidas

Divulgación progresiva

Los clientes agente cargan cada descripción de Habilidad para su descubrimiento, pero deben cargar solo el cuerpo del SKILL.md seleccionado. Cada punto de entrada es intencionalmente pequeño y enlaza a archivos de referencia locales que se leen solo cuando el flujo de trabajo seleccionado necesita esos detalles.

Los archivos bajo docs/ son documentación de producto y operativa dirigida a humanos. No son contexto automático del agente y no forman parte del recorrido de referencia de Habilidades. Los contratos de comportamiento del agente se encuentran bajo skills/ y se accede a ellos desde el SKILL.md seleccionado.

Contrato de salida del agente

Los agentes que usan AdsAgent deben responder en Markdown por defecto:

## Answer
One-sentence answer.

## Scope
- Date:
- Entity:
- Grouping:
- Attribution / channel:

## Results
| Metric | Value |
| --- | ---: |

## Notes
- Data freshness:
- Limits or missing fields:
- Next safe action:

No vuelques JSON, CSV, diagnósticos ocultos, filas en bruto o cada campo devuelto en el chat. Limpia la respuesta en tablas orientadas al operador y viñetas cortas. Si se necesita una inspección forense en bruto, crea una transferencia al operador en lugar de hacer que las filas en bruto sean la respuesta del agente.

Política de caja seminegra

Este repositorio documenta intencionalmente resultados y comportamiento del agente, no la interfaz interna completa. Los agentes deben:

• Leer la guía MCP en vivo de AdsAgent después de conectarse.

• Usar las herramientas disponibles a través de la sesión MCP autenticada.

• Evitar adivinar campos de carga útil ocultos.

• Evitar sondear solicitudes rechazadas.

• Detenerse en respuestas de revisión del operador y pedir al operador de AdsAgent que inspeccione los diagnósticos internos.

• Usar el plan de datos seguro más pequeño antes de hacer llamadas.

• Preferir resúmenes agrupados y desgloses limpios sobre filas en bruto.

El contrato del agente externo es: hacer preguntas claras, respetar los límites, confirmar antes de escribir y usar la incorporación proporcionada por el panel.

Fuente oficial y derechos

Este repositorio contiene solo el paquete de comportamiento legible por el cliente. El código fuente del servidor de AdsAgent, credenciales, esquemas, lógica de enrutamiento y diagnósticos operativos no se distribuyen aquí.

El paquete es propietario y todos los derechos están reservados por adsagents LLC. El alojamiento público en GitHub permite a las personas ver y bifurcar el repositorio bajo los Términos de Servicio de GitHub, pero una bifurcación o copia local no otorga ninguna licencia de propiedad intelectual adicional, excepto los derechos limitados de duplicación en el directorio de plugins de Anthropic Claude en LICENSE.md. No se concede ningún otro permiso para redistribuir, duplicar, vender, sublicenciar, publicar versiones modificadas, crear trabajos derivados, entrenar un producto competidor a partir del paquete o representar una bifurcación como oficial. Consulta LICENSE.md y NOTICE.md.

Prompts de ejemplo

Use AdsAgent to list my connected Meta products, Google Ads customers, or TikTok advertisers, then ask which scope's today data I want to inspect.

For Google Ads, inspect agent_method_profile, pick an enabled non-manager customer, and use one cached insights_query_consistent request when the profile is advertised.

For TikTok, inspect agent_method_profile and use one insights_query_consistent scopes request when advertised; otherwise use the native batch overview fallback.

Prepare a copy of this winning Meta ad into the target account, but ask me for confirmation before creating anything.

Group these distinct Meta Ads by language into the requested Campaign and AdSet layout. Prepare one grouped_plan, show every settings_source_ad_id and geography override, and wait for my approval before confirming once.

Hay más ejemplos en docs/examples.md.

Validación

Ejecuta el contrato de lanzamiento local y las pruebas:

python scripts/validate_tri_channel_pack.py
python -m pytest -q

La validación de lanzamiento falla de forma cerrada contra las tres instantáneas confirmadas en contracts/manifests/. Cada instantánea se copia byte por byte de un artefacto de servicio confirmado y se bloquea a su canal, revisión fuente, ruta de artefacto público, metadatos y SHA-256 en contracts/manifests/provenance.json. CI no realiza solicitudes de red en vivo.

python scripts/validate_public_tool_manifests.py

Un operador puede actualizar de forma determinista las tres instantáneas después de que el manifiesto del servicio cambie. El comando rechaza fuentes no confirmadas, sucias, faltantes o incompatibles con el contrato y nunca obtiene de la red:

python scripts/sync_public_tool_manifests.py \
  --source meta=/path/to/meta-tools.json \
  --source google=/path/to/google-tools.json \
  --source tiktok=/path/to/tiktok-tools.json

Las tres fuentes son obligatorias. Una herramienta referenciada faltante, una capacidad o puerta requerida no probada, un resumen de procedencia obsoleto o un canal ausente hace fallar la validación de lanzamiento. --allow-missing existe solo para diagnósticos locales explícitos y no es utilizado por CI de lanzamiento.

Instalación

Este repositorio se distribuye como el plugin de Claude adsagent (habilidades + URLs MCP de .mcp.json). El nombre del repositorio de GitHub permanece adsagent-ai-skills.

Claude Code (recomendado)

claude plugin marketplace add adsagents/adsagent-ai-skills
claude plugin install adsagent@adsagent

Actualizar una instalación existente en el ámbito de usuario:

claude plugin update --scope user adsagent@adsagent

Si claude plugin list muestra instalaciones locales y de usuario duplicadas, mantén el ámbito de usuario:

claude plugin uninstall --scope local adsagent@adsagent

Inicia una sesión nueva de Claude Code después de instalar o actualizar.

Preinstalación en la nube / Cowork (fragmento de configuración)

{
  "extraKnownMarketplaces": {
    "adsagent": {
      "source": {
        "source": "github",
        "repo": "adsagents/adsagent-ai-skills"
      }
    }
  },
  "enabledPlugins": ["adsagent@adsagent"]
}

Después de la instalación, autentica cada servidor MCP que se muestra en /mcp (Meta, Google, TikTok). No agregues headers.Authorization a .mcp.json; OAuth debe seguir siendo la ruta de autenticación.

Migración desde slugs de plugin heredados

Las instalaciones antiguas usaban adsagent-ai-skills@adsagent-ai-skills o adsagent-meta-ai-skills@adsagent-meta-ai-skills. El marketplace declara un cambio de nombre a adsagent@adsagent. Después de migrar, elimina los duplicados heredados:

claude plugin uninstall --scope user adsagent-ai-skills@adsagent-ai-skills
claude plugin uninstall --scope user adsagent-meta-ai-skills@adsagent-meta-ai-skills

Codex CLI

codex plugin marketplace add adsagents/adsagent-ai-skills
codex plugin add adsagent@adsagent

Actualizar:

codex plugin marketplace upgrade adsagent

Inicia una sesión nueva de Codex después de instalar o actualizar.

Alternativa Git y otros clientes compatibles con Agent-Skills

Las habilidades en skills/ usan el diseño estándar de Agent Skills (skills/<name>/SKILL.md con frontmatter YAML). Los clientes que solo consumen habilidades (sin el paquete MCP del plugin) pueden clonar manualmente:

git clone https://github.com/adsagents/adsagent-ai-skills.git ~/.codex/skills/adsagent-ai-skills

Esos clientes aún necesitan una conexión MCP separada (mensaje de instalación del panel o Directorio de Conectores). La ruta del plugin es el paquete de habilidades + MCP en un solo paso.

Luego abre AdsAgent solo si necesitas configuración OAuth/token del panel para clientes que no son plugin:

Settings -> MCP Access -> Copy install prompt

Pega el prompt copiado en un chat nuevo cuando no se use el paquete de plugin. El prompt proporciona URLs MCP HTTP alojadas para:

Meta default: https://adsagent.md/mcp/v2
Meta legacy fallback: https://adsagent.md/mcp
Google Ads: https://google.adsagent.md/mcp
TikTok: https://tiktok.adsagent.md/mcp

Reglas importantes de tiempo de ejecución

• Solo MCP HTTP alojado.

• Usa https://adsagent.md/mcp/v2 para nuevas conexiones de Meta; /mcp es la alternativa heredada.

• No ejecutes código de MCP de AdsAgent localmente.

• No uses un relé local a menos que el panel de AdsAgent lo indique explícitamente.

• Almacena en caché la configuración de la conexión cuando el cliente lo permita.

• Mantén acotada la concurrencia de MCP por token.

• Respeta Retry-After.

• Analiza Retry-After del encabezado HTTP, data de nivel superior o error.data de JSON-RPC.

• Reconoce mcp_concurrency_limited con espera más jitter.

• Reconoce mcp_fanout_detected cambiando a la herramienta de resumen por lotes de la plataforma en lugar de reintentar la solicitud de ámbito único bloqueada.

• Cuando agent_method_profile.profile_id=adsagent_agent_methods_v1 y su lectura coherente esté presente en el catálogo local del cliente, usa una solicitud insights_query_consistent con scope o scopes ordenados para las tres plataformas.

• Sin ese perfil, o cuando su lectura publicitaria falte solo en el catálogo local del cliente, usa la alternativa nativa nombrada del perfil o las herramientas del lado del servidor documentadas: Meta/TikTok insights_query_batch_overview, Google google_ads_insights_overview_batch. No informes un fallo de registro del servidor por una falta de selector local.

• Consulta primero los datos agregados y nunca infieras la paridad de capacidades entre plataformas a partir de un nombre de herramienta compartido.

• Informa los totales calculados por el servidor a partir de la respuesta; no sumes las filas actualmente visibles.

• Confía en los totales solo cuando meta.complete=true; los ámbitos faltantes son desconocidos, nunca cero.

• Sondea tareas en cola hasta terminal=true y devuelve el enlace del artefacto en lugar del CSV sin procesar.

• Sondea el trabajo en cola directamente con tasks_get_status(task_ref=...) cuando el servidor anuncie referencias de tareas directas.

• Los tokens de confirmación de QuickCreate son de un solo uso y caducan después de 15 minutos. Verifica expires_at; después de confirm_token_invalid, prepara de nuevo, muestra el nuevo resumen y obtén una aprobación explícita nueva.

• Sondea las tareas de creación de Meta con tasks_get_status(task_ref=..., response_mode=compact). En no_create_permission, dirige al usuario a /dashboard/assets/fb-users; nunca cambies los permisos del cliente ni reproduzcas automáticamente la creación fallida.

• Evita lecturas de filas sin procesar en conversaciones normales de usuario.

• Usa tablas Markdown para números.

• Confirma antes de la creación o modificación de anuncios.

• Usa grouped_plan para múltiples anuncios fuente distintos; nunca lo emules mediante una serie de mutaciones de copia del lado del cliente.

• Detente en errores de revisión del operador.

• Cuando un error incluya support_ref, consérvalo y muéstralo textualmente para el soporte. No es autorización; nunca inventes, modifiques, enumeres ni lo reemplaces con tokens, cuerpos de solicitud o registros.

Enlaces

• Sitio web oficial: https://adsagent.md

• Repositorio oficial: https://github.com/adsagents/adsagent-ai-skills

• Soporte: support@adsagent.md

• Ruta de incorporación pública: https://adsagent.md/docs/mcp-onboarding

Licencia

Todos los derechos reservados. Consulta LICENSE.md.