AdsAgent Tri-Channel Plugin

Public Claude plugin + skill pack for AdsAgent tri-channel hosted MCP: Meta, Google Ads, and TikTok.

Distribution split (important):

Official GitHub repo: github.com/adsagents/adsagent-ai-skills

Website: adsagent.md
Official links hub: adsagent.md/connect
Skill pack landing page: adsagent.md/skills
Support: support@adsagent.md

Current contract version: 0.7.64. The plugin slug is adsagent (marketplace key adsagent). New Meta connections default to the v2 product profile; all three hosted endpoints negotiate modern MCP 2026-07-28 stateless discovery while retaining supported legacy initialize clients.

Version history lives in CHANGELOG.md.

The local helper scripts/update_reminder.py compares strict semantic versions and stores only bounded version/timestamp state in $XDG_CACHE_HOME/adsagent-ai-skills/update-reminder-v1.json (or ~/.cache/...). Cache failure never blocks MCP work.

What This Is

• A public Claude plugin marketplace package: behavior skills plus hosted MCP URLs via .mcp.json.

• A behavior guide for Claude Code, Cursor, Codex, and other MCP-aware clients.

• A reliability and safety layer that tells agents when to retry, when to wait, and when to stop.

• A versioned GitHub distribution for AdsAgent user onboarding and agent behavior guidance.

• A data-minimization contract for AI agents that should not scan AdsAgent like a raw database.

Related MCP server: Meta Marketing API MCP Server

What This Is Not

• Not the Anthropic Connectors Directory MCP listing (that is registered separately on the hosted servers).

• Not a complete MCP tool reference.

• Not an SDK.

• Not a local transport relay.

• Not a disclosure of AdsAgent backend routes, schemas, database tables, or internal diagnostics.

For Claude Code plugin installs, OAuth MCP setup comes from this repo's .mcp.json. For clients without plugin support, the AdsAgent dashboard install prompt remains the manual fallback:

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

Use that copied prompt only when you are not installing the Claude plugin bundle. This repository teaches agent behavior after the MCP connection exists.

Included Skills

Progressive Disclosure

Agent clients load every Skill description for discovery, but should load only the selected SKILL.md body. Each entrypoint is intentionally small and links to local reference files that are read only when the selected workflow needs those details.

The files under docs/ are human-facing product and operator documentation. They are not automatic agent context and are not part of Skill reference traversal. Agent behavior contracts live under skills/ and are reached from the selected SKILL.md.

Agent Output Contract

Agents using AdsAgent should answer in Markdown by default:

## Answer
One-sentence answer.

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

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

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

Do not dump JSON, CSV, hidden diagnostics, raw rows, or every returned field into chat. Clean the response into operator-facing tables and short bullets. If forensic raw inspection is needed, create an operator handoff instead of making raw rows the agent answer.

Semi-Black-Box Policy

This repository intentionally documents outcomes and agent behavior, not the complete internal interface. Agents should:

• Read the live AdsAgent MCP guide after connecting.

• Use available tools through the authenticated MCP session.

• Avoid guessing hidden payload fields.

• Avoid probing rejected requests.

• Stop on operator-review responses and ask the AdsAgent operator to inspect internal diagnostics.

• Use the smallest safe data plan before making calls.

• Prefer grouped summaries and cleaned breakdowns over raw rows.

The external agent contract is: ask clear questions, respect limits, confirm before writes, and use dashboard-provided onboarding.

Official Source And Rights

This repository contains only the client-readable behavior pack. AdsAgent server source, credentials, schemas, routing logic, and operational diagnostics are not distributed here.

The package is proprietary and all rights are reserved by adsagents LLC. Public GitHub hosting allows people to view and fork the repository under GitHub's Terms of Service, but a fork or local copy does not grant any additional intellectual-property license except the limited Anthropic Claude plugin directory mirroring rights in LICENSE.md. No other permission is granted to redistribute, mirror, sell, sublicense, publish modified versions, create derivative works, train a competing product from the pack, or represent a fork as official. See LICENSE.md and NOTICE.md.

Example Prompts

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.

More examples are in docs/examples.md.

Validation

Run the local release contract and tests:

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

Release validation is fail-closed against the three committed snapshots in contracts/manifests/. Each snapshot is copied byte-for-byte from a committed service artifact and locked to its channel, source revision, public artifact path, metadata, and SHA-256 in contracts/manifests/provenance.json. CI does not make live network requests.

python scripts/validate_public_tool_manifests.py

An operator can deterministically update all three snapshots after the service manifest changes. The command rejects uncommitted, dirty, missing, or contract-incompatible sources and never fetches from the network:

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

All three sources are mandatory. A missing referenced tool, an unproven required capability or gate, a stale provenance digest, or an absent channel fails release validation. --allow-missing exists only for explicit local diagnostics and is not used by release CI.

Installation

This repo ships as the adsagent Claude plugin (skills + .mcp.json MCP URLs). The GitHub repository name stays adsagent-ai-skills.

Claude Code (recommended)

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

Update an existing user-scope install:

claude plugin update --scope user adsagent@adsagent

If claude plugin list shows duplicate local and user installs, keep user scope:

claude plugin uninstall --scope local adsagent@adsagent

Start a fresh Claude Code session after installing or updating.

Cloud / Cowork preinstall (settings snippet)

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

After install, authenticate each MCP server shown in /mcp (Meta, Google, TikTok). Do not add headers.Authorization to .mcp.json; OAuth must remain the auth path.

Migrating from legacy plugin slugs

Older installs used adsagent-ai-skills@adsagent-ai-skills or adsagent-meta-ai-skills@adsagent-meta-ai-skills. The marketplace declares a rename to adsagent@adsagent. After migrating, remove legacy duplicates:

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

Refresh:

codex plugin marketplace upgrade adsagent

Start a fresh Codex session after installing or upgrading.

Git fallback and other Agent-Skills-compatible clients

The skills in skills/ use the standard Agent Skills layout (skills/<name>/SKILL.md with YAML frontmatter). Clients that only consume skills (without the plugin MCP bundle) can clone manually:

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

Those clients still need a separate MCP connection (dashboard install prompt or Connectors Directory). The plugin path is the one-step skills + MCP bundle.

Then open AdsAgent only if you need dashboard OAuth/token setup for non-plugin clients:

Settings -> MCP Access -> Copy install prompt

Paste the copied prompt into a fresh chat when the plugin bundle is not used. The prompt provides hosted HTTP MCP URLs for:

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

Important Runtime Rules

• Только размещенный HTTP MCP.

• Используйте https://adsagent.md/mcp/v2 для новых Meta-подключений; /mcp — устаревший запасной вариант.

• Не запускайте код AdsAgent MCP локально.

• Не используйте локальный ретранслятор, если панель AdsAgent явно не указывает на это.

• Кэшируйте настройку подключения там, где клиент это поддерживает.

• Ограничивайте параллелизм MCP для каждого токена.

• Уважайте заголовок Retry-After.

• Извлекайте Retry-After из HTTP-заголовка, верхнего уровня data или JSON-RPC error.data.

• Соблюдайте mcp_concurrency_limited с ожиданием и джиттером.

• При mcp_fanout_detected переключайтесь на инструмент сводки по платформе вместо повторной попытки заблокированного одноблочного запроса.

• Когда agent_method_profile.profile_id=adsagent_agent_methods_v1 и его консистентное чтение присутствует в локальном каталоге клиента, используйте один запрос insights_query_consistent с scope или упорядоченными scopes для всех трех платформ.

• Без этого профиля или если его объявленное чтение отсутствует только в локальном каталоге клиента, используйте именованный нативный запасной вариант профиля или задокументированные серверные инструменты: Meta/TikTok insights_query_batch_overview, Google google_ads_insights_overview_batch. Не сообщайте об ошибке регистрации сервера из-за пропуска локального селектора.

• Сначала запрашивайте агрегированные данные и никогда не делайте выводов о равных возможностях разных платформ на основе общего имени инструмента.

• Сообщайте итоги, вычисленные сервером, из ответа; не суммируйте видимые строки.

• Доверяйте итогам только при meta.complete=true; отсутствующие области неизвестны, но не равны нулю.

• Опрашивайте задачи в очереди до terminal=true и возвращайте ссылку на артефакт вместо сырых CSV.

• Опрашивайте поставленную в очередь работу напрямую с помощью tasks_get_status(task_ref=...), когда сервер рекламирует прямые ссылки на задачи.

• Маркеры подтверждения QuickCreate одноразовые и истекают через 15 минут. Проверяйте expires_at; после confirm_token_invalid подготавливайте заново, показывайте новую сводку и получайте явное одобрение.

• Опрашивайте задачи создания Meta с помощью tasks_get_status(task_ref=..., response_mode=compact). При no_create_permission направляйте пользователя на /dashboard/assets/fb-users; никогда не изменяйте разрешения клиента и не повторяйте неудачное создание автоматически.

• Избегайте чтения сырых строк в обычных диалогах с пользователем.

• Для чисел используйте таблицы Markdown.

• Подтверждайте перед созданием или изменением объявления.

• Используйте grouped_plan для нескольких различных исходных объявлений; никогда не эмулируйте его через клиентскую серию копирующих мутаций.

• Останавливайтесь при ошибках, требующих проверки оператором.

• Если ошибка содержит support_ref, сохраняйте и показывайте его дословно для поддержки. Это не авторизация; никогда не изобретайте, не изменяйте, не перечисляйте и не заменяйте его токенами, телами запросов или логами.

Ссылки

• Официальный сайт: https://adsagent.md

• Официальный репозиторий: https://github.com/adsagents/adsagent-ai-skills

• Поддержка: support@adsagent.md

• Публичный путь адаптации: https://adsagent.md/docs/mcp-onboarding

Лицензия

Все права защищены. См. LICENSE.md.