AdsAgent Tri-Channel Plugin

Öffentliches Claude-Plugin + Skill-Paket für den gehosteten AdsAgent-Tri-Channel MCP: Meta, Google Ads und TikTok.

Aufteilung der Verteilung (wichtig):

Offizielles GitHub-Repo: github.com/adsagents/adsagent-ai-skills

Website: adsagent.md Offizieller Links-Hub: adsagent.md/connect Skill-Pack-Landingpage: adsagent.md/skills Support: support@adsagent.md

Aktuelle Vertragsversion: 0.7.64. Der Plugin-Slug ist adsagent (Marktplatzschlüssel adsagent). Neue Meta-Verbindungen verwenden standardmäßig das v2-Produktprofil; alle drei gehosteten Endpunkte handeln moderne MCP-2026-07-28-zustandslose Erkennung aus, während sie unterstützte Legacy-Initialize-Clients beibehalten.

Die Versionshistorie befindet sich in CHANGELOG.md.

Das lokale Hilfsskript scripts/update_reminder.py vergleicht strikte semantische Versionen und speichert nur begrenzten Versions-/Zeitstempelzustand in $XDG_CACHE_HOME/adsagent-ai-skills/update-reminder-v1.json (oder ~/.cache/...). Ein Cache-Fehler blockiert niemals die MCP-Arbeit.

Was dies ist

• Ein öffentliches Claude-Plugin-Marktplatzpaket: Verhaltens-Skills plus gehostete MCP-URLs über .mcp.json.

• Ein Verhaltensleitfaden für Claude Code, Cursor, Codex und andere MCP-fähige Clients.

• Eine Zuverlässigkeits- und Sicherheitsschicht, die Agenten sagt, wann sie wiederholen, wann sie warten und wann sie anhalten sollen.

• Eine versionierte GitHub-Verteilung für das Onboarding von AdsAgent-Benutzern und die Verhaltenssteuerung von Agenten.

• Ein Datenminimierungsvertrag für KI-Agenten, die AdsAgent nicht wie eine Rohdatenbank scannen sollten.

Related MCP server: Meta Marketing API MCP Server

Was dies nicht ist

• Nicht die Anthropic Connectors Directory MCP-Liste (diese wird separat auf den gehosteten Servern registriert).

• Keine vollständige MCP-Tool-Referenz.

• Kein SDK.

• Kein lokaler Transport-Relay.

• Keine Offenlegung von AdsAgent-Backend-Routen, Schemata, Datenbanktabellen oder internen Diagnosen.

Für Claude-Code-Plugin-Installationen stammt die OAuth-MCP-Einrichtung aus der .mcp.json dieses Repos. Für Clients ohne Plugin-Unterstützung bleibt der AdsAgent-Dashboard-Installationsaufforderung manueller Fallback:

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

Verwenden Sie diesen kopierten Prompt nur, wenn Sie das Claude-Plugin-Bundle nicht installieren. Dieses Repository lehrt das Agentenverhalten, nachdem die MCP-Verbindung besteht.

Enthaltene Skills

Progressive Offenlegung

Agent-Clients laden jede Skill-Beschreibung zur Erkennung, sollten aber nur den ausgewählten SKILL.md-Body laden. Jeder Einstiegspunkt ist absichtlich klein und verlinkt auf lokale Referenzdateien, die nur gelesen werden, wenn der ausgewählte Workflow diese Details benötigt.

Die Dateien unter docs/ sind menschenlesbare Produkt- und Bedienerdokumentation. Sie sind kein automatischer Agentenkontext und kein Teil der Skill-Referenzdurchlauf. Agentenverhaltensverträge befinden sich unter skills/ und werden vom ausgewählten SKILL.md aus erreicht.

Agentenausgabe-Vertrag

Agenten, die AdsAgent verwenden, sollten standardmäßig in Markdown antworten:

## Answer
One-sentence answer.

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

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

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

Geben Sie keine JSON, CSV, versteckte Diagnosen, Rohzeilen oder jedes zurückgegebene Feld in den Chat aus. Bereinigen Sie die Antwort zu bedienerorientierten Tabellen und kurzen Aufzählungspunkten. Wenn eine forensische Rohinspektion erforderlich ist, erstellen Sie eine Bedienerübergabe, anstatt Rohzeilen zur Agentenantwort zu machen.

Semi-Black-Box-Richtlinie

Dieses Repository dokumentiert absichtlich Ergebnisse und Agentenverhalten, nicht die vollständige interne Schnittstelle. Agenten sollten:

• Den Live-AdsAgent-MCP-Leitfaden nach dem Verbinden lesen.

• Verfügbare Tools über die authentifizierte MCP-Sitzung verwenden.

• Vermeiden, versteckte Payload-Felder zu erraten.

• Vermeiden, abgelehnte Anfragen zu untersuchen.

• Bei Bediener-Review-Antworten anhalten und den AdsAgent-Bediener bitten, interne Diagnosen zu überprüfen.

• Den kleinsten sicheren Datenplan vor dem Aufrufen verwenden.

• Gruppierte Zusammenfassungen und bereinigte Aufschlüsselungen gegenüber Rohzeilen bevorzugen.

Der externe Agentenvertrag lautet: klare Fragen stellen, Limits respektieren, vor Schreibvorgängen bestätigen und die dashboardgestützte Einführung verwenden.

Offizielle Quelle und Rechte

Dieses Repository enthält nur das clientlesbare Verhaltenspaket. AdsAgent-Serverquellcode, Anmeldeinformationen, Schemata, Routing-Logik und Betriebsdiagnosen werden hier nicht verteilt.

Das Paket ist proprietär und alle Rechte sind vorbehalten von adsagents LLC. Öffentliches GitHub-Hosting ermöglicht es Personen, das Repository unter den GitHub-Nutzungsbedingungen anzusehen und zu forken, aber ein Fork oder eine lokale Kopie gewährt keine zusätzliche Lizenz für geistiges Eigentum, außer den eingeschränkten Anthropic-Claude-Plugin-Verzeichnis-Spiegelungsrechten in LICENSE.md. Es wird keine andere Erlaubnis erteilt, das Paket weiterzuverbreiten, zu spiegeln, zu verkaufen, unterzulizenzieren, modifizierte Versionen zu veröffentlichen, abgeleitete Werke zu erstellen, ein Konkurrenzprodukt aus dem Paket zu trainieren oder einen Fork als offiziell darzustellen. Siehe LICENSE.md und NOTICE.md.

Beispiel-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.

Weitere Beispiele finden Sie in docs/examples.md.

Validierung

Führen Sie den lokalen Release-Vertrag und die Tests aus:

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

Die Release-Validierung ist fail-closed gegenüber den drei festgeschriebenen Snapshots in contracts/manifests/. Jeder Snapshot wird Byte-für-Byte von einem festgeschriebenen Dienst-Artefakt kopiert und an seinen Kanal, Quellrevision, öffentlichen Artefaktpfad, Metadaten und SHA-256 in contracts/manifests/provenance.json gebunden. CI führt keine Live-Netzwerkanfragen durch.

python scripts/validate_public_tool_manifests.py

Ein Bediener kann alle drei Snapshots deterministisch aktualisieren, nachdem sich das Dienst-Manifest geändert hat. Der Befehl lehnt nicht festgeschriebene, schmutzige, fehlende oder vertragsinkompatible Quellen ab und ruft niemals aus dem Netzwerk ab:

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

Alle drei Quellen sind obligatorisch. Ein fehlendes referenziertes Tool, eine nicht nachgewiesene erforderliche Fähigkeit oder ein Gate, ein veralteter Provenienz-Digest oder ein fehlender Kanal führt zum Scheitern der Release-Validierung. --allow-missing existiert nur für explizite lokale Diagnosen und wird nicht von Release-CI verwendet.

Installation

Dieses Repository wird als adsagent-Claude-Plugin (Skills + .mcp.json-MCP-URLs) ausgeliefert. Der GitHub-Repository-Name bleibt adsagent-ai-skills.

Claude Code (empfohlen)

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

Aktualisieren einer vorhandenen benutzerweiten Installation:

claude plugin update --scope user adsagent@adsagent

Wenn claude plugin list doppelte lokale und benutzerweite Installationen anzeigt, behalten Sie den benutzerweiten Bereich:

claude plugin uninstall --scope local adsagent@adsagent

Starten Sie eine neue Claude Code-Sitzung nach der Installation oder Aktualisierung.

Cloud / Cowork Vorinstallation (Einstellungs-Snippet)

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

Nach der Installation authentifizieren Sie jeden MCP-Server, der in /mcp angezeigt wird (Meta, Google, TikTok). Fügen Sie headers.Authorization nicht zu .mcp.json hinzu; OAuth muss der Authentifizierungspfad bleiben.

Migration von Legacy-Plugin-Slugs

Ältere Installationen verwendeten adsagent-ai-skills@adsagent-ai-skills oder adsagent-meta-ai-skills@adsagent-meta-ai-skills. Der Marktplatz deklariert eine Umbenennung zu adsagent@adsagent. Nach der Migration entfernen Sie Legacy-Duplikate:

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

Aktualisieren:

codex plugin marketplace upgrade adsagent

Starten Sie eine neue Codex-Sitzung nach der Installation oder Aktualisierung.

Git-Fallback und andere Agent-Skills-kompatible Clients

Die Skills in skills/ verwenden das Standard-Agent-Skills-Layout (skills/<name>/SKILL.md mit YAML-Frontmatter). Clients, die nur Skills konsumieren (ohne das Plugin-MCP-Bundle), können manuell klonen:

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

Diese Clients benötigen immer noch eine separate MCP-Verbindung (Dashboard-Installationsaufforderung oder Connectors Directory). Der Plugin-Pfad ist das One-Step-Skills- + MCP-Bundle.

Öffnen Sie dann AdsAgent nur, wenn Sie Dashboard-OAuth/Token-Setup für Nicht-Plugin-Clients benötigen:

Settings -> MCP Access -> Copy install prompt

Fügen Sie den kopierten Prompt in einen neuen Chat ein, wenn das Plugin-Bundle nicht verwendet wird. Der Prompt stellt gehostete HTTP-MCP-URLs bereit für:

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

Wichtige Laufzeitregeln

• Nur gehostetes HTTP MCP.

• Verwenden Sie https://adsagent.md/mcp/v2 für neue Meta-Verbindungen; /mcp ist der Legacy-Fallback.

• Führen Sie AdsAgent MCP-Code nicht lokal aus.

• Verwenden Sie kein lokales Relay, es sei denn, das AdsAgent-Dashboard gibt dies explizit an.

• Richten Sie die Verbindung zwischenzuspeichern, wo der Client dies unterstützt.

• Halten Sie die MCP-Gleichzeitigkeit pro Token begrenzt.

• Beachten Sie Retry-After.

• Parsen Sie Retry-After aus dem HTTP-Header, dem data der obersten Ebene oder error.data von JSON-RPC.

• Beachten Sie mcp_concurrency_limited mit Wartezeit plus Jitter.

• Beachten Sie mcp_fanout_detected, indem Sie zum plattformübergreifenden Batch-Übersichts-Tool wechseln, anstatt die blockierte Einzelbereichsanfrage zu wiederholen.

• Wenn agent_method_profile.profile_id=adsagent_agent_methods_v1 und dessen konsistenter Lesevorgang im client-lokalen Katalog vorhanden ist, verwenden Sie eine insights_query_consistent-Anfrage mit scope oder geordneten scopes für alle drei Plattformen.

• Verwenden Sie ohne dieses Profil oder wenn dessen beworbener Lesevorgang nur im client-lokalen Katalog fehlt, den benannten nativen Fallback des Profils oder die dokumentierten serverseitigen Tools: Meta/TikTok insights_query_batch_overview, Google google_ads_insights_overview_batch. Melden Sie keinen Server-Registrierungsfehler aufgrund eines lokalen Selektor-Fehlschlags.

• Fragen Sie zuerst aggregierte Daten ab und leiten Sie niemals plattformübergreifende Fähigkeitsparität aus einem gemeinsamen Toolnamen ab.

• Melden Sie serverberechnete Summen aus der Antwort; summieren Sie nicht die aktuell sichtbaren Zeilen.

• Vertrauen Sie Summen nur, wenn meta.complete=true; fehlende Bereiche sind unbekannt, niemals null.

• Pollen Sie in die Warteschlange gestellte Aufgaben bis terminal=true und geben Sie den Artefakt-Link anstelle von rohem CSV zurück.

• Pollen Sie in die Warteschlange gestellte Arbeiten direkt mit tasks_get_status(task_ref=...), wenn der Server direkte Aufgabenreferenzen bewirbt.

• QuickCreate-Bestätigungstoken sind Einmal-Token und verfallen nach 15 Minuten. Überprüfen Sie expires_at; nach confirm_token_invalid bereiten Sie erneut vor, zeigen Sie die neue Zusammenfassung an und holen Sie eine frische explizite Zustimmung ein.

• Pollen Sie Meta-Erstellungsaufgaben mit tasks_get_status(task_ref=..., response_mode=compact). Bei no_create_permission leiten Sie den Benutzer zu /dashboard/assets/fb-users; ändern Sie niemals Kundenberechtigungen oder wiederholen Sie die fehlgeschlagene Erstellung automatisch.

• Vermeiden Sie Rohzeilen-Lesevorgänge in normalen Benutzerkonversationen.

• Verwenden Sie Markdown-Tabellen für Zahlen.

• Bestätigen Sie vor der Anzeigenerstellung oder -änderung.

• Verwenden Sie grouped_plan für mehrere unterschiedliche Quell-Anzeigen; emulieren Sie dies niemals durch eine clientseitige Serie von Kopiermutationen.

• Stoppen Sie bei Operator-Review-Fehlern.

• Wenn ein Fehler support_ref enthält, bewahren und zeigen Sie ihn wörtlich für den Support an. Es handelt sich nicht um eine Autorisierung; erfinden, modifizieren, aufzählen oder ersetzen Sie ihn niemals durch Token, Anfragekörper oder Protokolle.

Links

• Offizielle Website: https://adsagent.md

• Offizielles Repository: https://github.com/adsagents/adsagent-ai-skills

• Support: support@adsagent.md

• Öffentlicher Onboarding-Pfad: https://adsagent.md/docs/mcp-onboarding

Lizenz

Alle Rechte vorbehalten. Siehe LICENSE.md.