Skip to content

Hainrixz/claude-ads / ads

Free-first paid advertising audit and optimization skill, focused on the 3 platforms where 95% of advertiser spend lives: Meta, Google, TikTok. Guided onboarding (/ads start) saves context once and step-by-step OAuth walkthroughs; continuous coach (/ads next) ranks Quick Wins after each audit. ~158 weighted checks with scoring, parallel agents, industry templates, and AI creative generation.

FileKindSize
SKILL.mdskill md18.6 KB
references/additional-platforms.mdmarkdown3.6 KB
references/audit-history-schema.jsonconfig2.5 KB
references/audit-methodology.mdmarkdown4.3 KB
references/audit-output-schema.jsonconfig4.9 KB
references/benchmarks-cross.mdmarkdown1003 B
references/benchmarks-google.mdmarkdown1.6 KB
references/benchmarks-social.mdmarkdown2.6 KB
references/benchmarks.mdmarkdown929 B
references/bidding-google.mdmarkdown5.2 KB
references/bidding-meta.mdmarkdown1.8 KB
references/bidding-strategies.mdmarkdown989 B
references/bidding-tiktok.mdmarkdown2.0 KB
references/brand-dna-template.mdmarkdown6.9 KB
references/budget-allocation.mdmarkdown5.8 KB
references/compliance-changes-2025-2026.mdmarkdown2.5 KB
references/compliance-platforms.mdmarkdown3.6 KB
references/compliance-privacy.mdmarkdown3.1 KB
references/compliance.mdmarkdown1.6 KB
references/conciencia-schema.jsonconfig5.3 KB
references/conciencia.mdmarkdown5.2 KB
references/conversion-tracking.mdmarkdown1.2 KB
references/copy-frameworks.mdmarkdown8.9 KB
references/gaql-notes.mdmarkdown2.8 KB
references/google-audit-notes.mdmarkdown3.9 KB
references/google-audit.mdmarkdown12.5 KB
references/google-changelog-30d.mdmarkdown3.6 KB
references/google-creative-specs.mdmarkdown3.7 KB
references/image-providers.mdmarkdown4.9 KB
references/mcp-integration.mdmarkdown5.7 KB
references/mcp-meta-integration.mdmarkdown5.8 KB
references/meta-audit.mdmarkdown12.4 KB
references/meta-changelog-30d.mdmarkdown4.0 KB
references/meta-creative-specs.mdmarkdown4.5 KB
references/platform-specs-cross.mdmarkdown1.3 KB
references/platform-specs.mdmarkdown799 B
references/profile-schema.jsonconfig4.5 KB
references/scoring-system.mdmarkdown6.1 KB
references/setup-google.mdmarkdown7.1 KB
references/setup-meta-developers.mdmarkdown4.7 KB
references/setup-meta.mdmarkdown7.0 KB
references/setup-tiktok.mdmarkdown5.2 KB
references/setup-zernio.mdmarkdown4.5 KB
references/tiktok-audit.mdmarkdown10.1 KB
references/tiktok-changelog-30d.mdmarkdown3.5 KB
references/tiktok-creative-specs.mdmarkdown4.8 KB
references/tracking-cross.mdmarkdown1.5 KB
references/tracking-google.mdmarkdown2.8 KB
references/tracking-meta.mdmarkdown2.4 KB
references/tracking-tiktok.mdmarkdown1.5 KB
references/update-cost-warning.mdmarkdown2.0 KB
references/voice-to-style.mdmarkdown3.9 KB
research-sources/README.mdmarkdown883 B
research-sources/claude-research.mdmarkdown3.9 KB
research-sources/gemini-research.mdmarkdown10.2 KB
research-sources/google-audit-checklists.mdmarkdown25.9 KB
research-sources/google-optimization-logic.mdmarkdown11.9 KB
research-sources/google-platform-specs.mdmarkdown16.6 KB

references/mcp-meta-integration.md

View on GitHub
# Meta MCP Integration — Check ↔ Tool Mapping

> **Source of truth** for `agents/audit-meta.md`. When an `ad_account_id` is supplied,
> the agent calls the MCP tools listed below instead of asking for exports.
> This file is also the **canonical template** for any future MCP integration
> (Pinterest, Reddit, X, …): duplicate its structure, swap the tool names.

## Activation

The Meta MCP path activates when **all** of these are true:

1. `mcp__claude_ai_Facebook__*` tools are listed in the agent's `tools:` frontmatter.
2. The user (or upstream `/ads audit`) supplies a Meta `ad_account_id` (format `act_<numeric>`).
3. A date range is specified or defaults to the last 28 days.

If any condition fails, fall back to manual exports and set `"data_source": "export"` in the JSON output.

## Check → MCP Tool Mapping

### Pixel / CAPI Health (30% weight)

| Check | MCP Tool | What to extract |
|-------|----------|-----------------|
| M01 — Pixel installed and firing | `ads_get_dataset_details` | `is_created_by_business`, last event timestamp |
| M02 — CAPI active | `ads_get_dataset_quality` | `capi_status`, % of events with `server` source |
| M03 — Event dedup ≥90% | `ads_get_dataset_quality` | `deduplication_rate` per event |
| M04 — EMQ ≥8.0 for Purchase | `ads_get_dataset_quality` | `event_match_quality` per event |
| M05 — All standard events configured | `ads_get_dataset_stats` | event coverage list |
| M-AT1 — Offline Conversions API not in use | `ads_get_dataset_details` | flag if any offline-only dataset present |

### Creative — Diversity & Fatigue (30% weight)

| Check | MCP Tool | What to extract |
|-------|----------|-----------------|
| M25 — ≥3 creative formats active | `ads_get_ad_entities` | distinct `creative.object_type` count per ad set |
| M26 — ≥5 creatives per ad set | `ads_get_ad_entities` | ad count per ad set |
| M28 — Creative fatigue (CTR drop >20% / 14d) | `ads_insights_performance_trend` | 14-day CTR slope per ad |
| M-AN1 — Andromeda diversity (≥10 distinct concepts) | `ads_get_ad_entities` + manual concept tagging | total ads, then similarity inspection |

### Account Structure (20% weight)

| Check | MCP Tool | What to extract |
|-------|----------|-----------------|
| M11 — CBO vs ABO intentional | `ads_get_ad_entities` | `bid_strategy`, `budget_remaining` at campaign vs ad set |
| M13 — Learning phase health (<30% Limited) | `ads_get_ad_entities` | `learning_stage` per ad set |
| M14 — Budget per ad set ≥5x target CPA | `ads_get_ad_entities` + user-supplied CPA target | daily_budget / target_cpa |
| M15 — Advantage+ Sales active for e-commerce | `ads_catalog_get_catalogs` + `ads_get_ad_entities` | catalog connected + ASC enabled |
| M19 — Ad set overlap <30% | `ads_get_ad_entities` (audience definitions) | Jaccard-like overlap on audience specs |

### Audience & Targeting (20% weight)

| Check | MCP Tool | What to extract |
|-------|----------|-----------------|
| M21 — Prospecting frequency 7d <3.0 | `ads_insights_performance_trend` | `frequency` filtered to prospecting ad sets |
| M22 — Advantage+ Audience tested | `ads_get_ad_entities` | `targeting.targeting_automation` enabled |
| M-TH1 — Threads placement enabled | `ads_get_ad_entities` | `placements` contains `threads` |

### Advantage+ Shopping & Catalog

| Check | MCP Tool | What to extract |
|-------|----------|-----------------|
| M32 — Advantage+ Creative enhancements | `ads_get_ad_entities` | `degrees_of_freedom_spec` populated |
| M33 — Advantage+ Placements | `ads_get_ad_entities` | `targeting.publisher_platforms` = all |
| Catalog feed quality | `ads_catalog_get_diagnostics` | error counts per catalog |
| Product feed rules | `ads_catalog_get_feed_rules` | rule count and validity |

### Live Benchmarks Override

When `ads_insights_industry_benchmark` returns data for the relevant industry vertical,
prefer its numbers over the static `benchmarks.md` thresholds for that audit run.
Record the source in the JSON output: `evidence: { "benchmark_source": "mcp_live" | "static" }`.

## Output Wiring

The agent must populate the JSON schema (`audit-output-schema.json`) with:

```json
{
  "platform": "meta",
  "data_source": "mcp",
  "account_id": "act_123456789",
  "evidence": {
    "mcp_tools_called": [
      "ads_get_dataset_quality",
      "ads_get_ad_entities",
      "ads_catalog_get_diagnostics"
    ],
    "date_range": { "since": "2026-04-14", "until": "2026-05-11" }
  }
}
```

Per-check evidence should include the relevant MCP response slice (truncated to ≤200 chars per check).

## Failure & Fallback Rules

1. **Auth error** (account not accessible): emit `data_source: "manual"`, ask user for export, mark unevaluable checks `"result": "N/A"`.
2. **Partial data** (some tools return empty): emit `data_source: "mixed"`. Checks that depended on the missing tool become `"N/A"` with `"finding": "MCP returned no data; provide manual export to evaluate"`.
3. **Rate limit / quota**: retry once with exponential backoff (the MCP server already retries internally). On second failure, fall back to manual.
4. **Stale data warning**: if `ads_get_dataset_quality` indicates >24 h since last event, surface a `WARNING` regardless of metric values.

## Pattern Reuse for New Platforms

When adding a Pinterest / Reddit / X integration:

1. Copy this file → `mcp-<platform>-integration.md`.
2. Replace tool prefix `mcp__claude_ai_Facebook__` with the new server's prefix.
3. Rebuild the "Check → MCP Tool" tables against the new platform's check IDs (`Pxx`, `Rxx`, `Xxx`).
4. Update the corresponding `audit-<platform>.md` agent: add tools to frontmatter, add a step "0. If `<platform>_account_id` provided, fetch via MCP".
5. Update `mcp-integration.md` to list the new server under "Available MCP Servers".
6. No other changes should be necessary — the orchestrator (`ads/SKILL.md`) and JSON contract are platform-agnostic.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall