From fcc902e354dacf81e76e3c2edc432f637baa2810 Mon Sep 17 00:00:00 2001 From: Joel Horwitz Date: Sat, 31 Oct 2026 14:06:10 -0700 Subject: [PATCH] fix: drop ga4_* tool refs, use hosted /mcp connector, add tool-ref guard The hosted Claude connector does not expose ga4_* or generate_* tools. Remove ga4_* references from skills, agents, SDK runner and the tool directory (34 -> 31), point the Claude .mcp.json at the OAuth-only https://mcp.synterai.com/mcp endpoint, and extend check-directory-tools.js to fail on unavailable tool families, 'free' wording, or a non-canonical .mcp.json in the repo and directory bundle. Amp-Thread-ID: https://ampcode.com/threads/T-01a193c4-5c68-7631-86ce-dd8396a0f977 Co-authored-by: Amp --- .mcp.json | 2 +- CHANGELOG.md | 5 ++ README.md | 6 +- agents/media-buyer.md | 2 +- agents/performance-analyst.md | 2 +- packages/claude-directory/.mcp.json | 2 +- .../claude-directory/agents/media-buyer.md | 2 +- .../agents/performance-analyst.md | 2 +- .../skills/attribution/SKILL.md | 2 +- .../skills/campaign-preflight/SKILL.md | 2 +- .../claude-directory/skills/connect/SKILL.md | 2 +- .../skills/conversion-tracking/SKILL.md | 2 +- .../skills/executive-reporting/SKILL.md | 2 +- .../skills/first-party-data-strategy/SKILL.md | 4 +- .../skills/geo-integrity-audit/SKILL.md | 2 +- .../skills/incrementality-testing/SKILL.md | 2 +- .../skills/keyword-research/SKILL.md | 2 +- .../claude-directory/skills/launch/SKILL.md | 2 +- .../skills/performance-max-optimizer/SKILL.md | 2 +- .../skills/pixel-capi-auditor/SKILL.md | 4 +- .../skills/platform-google/SKILL.md | 2 +- .../skills/platform-linkedin/SKILL.md | 2 +- .../skills/platform-meta/SKILL.md | 2 +- .../skills/platform-microsoft/SKILL.md | 2 +- .../skills/platform-openai/SKILL.md | 2 +- .../skills/pre-pause-analysis/SKILL.md | 2 +- .../skills/quickstart/SKILL.md | 4 +- .../skills/replicate/SKILL.md | 2 +- .../claude-directory/skills/report/SKILL.md | 4 +- .../skills/seasonal-budget-planner/SKILL.md | 2 +- .../skills/utm-builder/SKILL.md | 2 +- .../tools/directory-tools.json | 3 - scripts/build-packages.py | 2 +- scripts/check-directory-tools.js | 78 +++++++++++++++++-- scripts/check-directory-tools.test.js | 70 ++++++++++++++++- scripts/test_build_packages.py | 13 ++-- scripts/validate-manifests.js | 2 +- sdk/README.md | 2 +- sdk/synter-agent.mjs | 3 - skills/attribution/SKILL.md | 2 +- skills/campaign-preflight/SKILL.md | 2 +- skills/connect/SKILL.md | 2 +- skills/conversion-tracking/SKILL.md | 2 +- skills/executive-reporting/SKILL.md | 2 +- skills/first-party-data-strategy/SKILL.md | 4 +- skills/geo-integrity-audit/SKILL.md | 2 +- skills/incrementality-testing/SKILL.md | 2 +- skills/keyword-research/SKILL.md | 2 +- skills/launch/SKILL.md | 2 +- skills/performance-max-optimizer/SKILL.md | 2 +- skills/pixel-capi-auditor/SKILL.md | 4 +- skills/platform-google/SKILL.md | 2 +- skills/platform-linkedin/SKILL.md | 2 +- skills/platform-meta/SKILL.md | 2 +- skills/platform-microsoft/SKILL.md | 2 +- skills/platform-openai/SKILL.md | 2 +- skills/pre-pause-analysis/SKILL.md | 2 +- skills/quickstart/SKILL.md | 4 +- skills/replicate/SKILL.md | 2 +- skills/report/SKILL.md | 4 +- skills/seasonal-budget-planner/SKILL.md | 2 +- skills/utm-builder/SKILL.md | 2 +- tools/directory-tools.json | 3 - 63 files changed, 217 insertions(+), 90 deletions(-) diff --git a/.mcp.json b/.mcp.json index c3ae094..c5f758a 100644 --- a/.mcp.json +++ b/.mcp.json @@ -2,7 +2,7 @@ "mcpServers": { "synter": { "type": "http", - "url": "https://mcp.synterai.com", + "url": "https://mcp.synterai.com/mcp", "description": "Synter Advertising Platform MCP \u2014 cross-channel ad management for AI agents. Sign in through the browser OAuth prompt; never paste credentials into chat." } } diff --git a/CHANGELOG.md b/CHANGELOG.md index 7c7e76b..993c76b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,11 @@ ## [1.2.1] - Unreleased +- Remove `ga4_*` tool references from skills, agents, the SDK runner, and the + tool directory (now 31 tools); the hosted Claude connector does not expose them. +- Point the Claude `.mcp.json` at the hosted OAuth connector `https://mcp.synterai.com/mcp`. +- `check-directory-tools.js` now fails on `ga4_*`/`generate_*` tool references, + "free" wording, or a non-canonical `.mcp.json`, for the repo and the directory bundle. - Add a portable OpenAI package targeting the existing Synter Ads MCP draft, with directory metadata, OAuth discovery, and reviewer test cases. - Preserve the four existing creative, page, visibility, and creator-brief skill diff --git a/README.md b/README.md index 8242c90..9d89ed8 100644 --- a/README.md +++ b/README.md @@ -59,13 +59,13 @@ Both plugin configurations use remote HTTP MCP with browser OAuth. They contain | Client | Configuration | Hosted MCP URL | | --- | --- | --- | | Cursor | `.cursor-mcp.json`, referenced by `.cursor-plugin/plugin.json` | `https://mcp.synterai.com` | -| Claude | `.mcp.json`, discovered by the Claude plugin | `https://mcp.synterai.com` | +| Claude | `.mcp.json`, discovered by the Claude plugin | `https://mcp.synterai.com/mcp` | The portable base `mcp.json` uses the Agent Plugins schema and `streamable-http` transport. The OpenAI build adds its documented server authentication extension; the published portable 1.0.0 schema currently rejects that extension, so validate the base against that schema and the generated vendor settings against the documented contract separately. Claude and Cursor use their own HTTP configuration files. All generated packages connect to the canonical endpoint. Existing OpenAI connections on another origin require a new plugin or support-assisted recovery, not a blind endpoint replacement. For another remote MCP client, use its browser OAuth flow with the appropriate hosted URL. If sign-in fails, reconnect through the client’s settings or contact [support](https://synterai.com/contact). ## What this plugin runs -The plugin connects to the hosted Synter MCP server over OAuth. The advertising tools run on that server. Local Markdown skills, agents, and rules guide how the client uses them; the checked-in [tool directory](tools/directory-tools.json) contains the 34 supported tool names. +The plugin connects to the hosted Synter MCP server over OAuth. The advertising tools run on that server. Local Markdown skills, agents, and rules guide how the client uses them; the checked-in [tool directory](tools/directory-tools.json) contains the 31 supported tool names. Claude also runs one `SessionStart` hook from [.claude-plugin/plugin.json](.claude-plugin/plugin.json). It invokes [scripts/session-context.sh](scripts/session-context.sh), a Bash script that uses `cat` to print static account-scope and approval guidance. It does not read credentials or make network requests. Cursor declares no hooks and uses [rules/synter-operator.mdc](rules/synter-operator.mdc). @@ -112,7 +112,7 @@ npx -y @anthropic-ai/claude-code@2.1.263 plugin validate . --strict bash scripts/build-zip.sh ``` -The directory check scans every file under `skills/`, `commands/` (when present), `rules/`, and `agents/`, including prose, tables, and code fences. Spell out exact tool names; dynamic tool-name templates fail validation. Snake-case data fields are recognized separately, but calling them as functions still counts as a tool reference. For a tool name without underscores, use explicit `tool:name` or its MCP-qualified name. +The directory check scans every file under `skills/`, `commands/` (when present), `rules/`, `agents/`, `context/`, `output-styles/`, and the SessionStart hook, including prose, tables, and code fences. It also fails on `ga4_*` and `generate_*` tool names, which the hosted Claude connector does not expose, on pricing wording in instructions, the README, and Claude manifests, and on any `.mcp.json` that is not the OAuth-only `https://mcp.synterai.com/mcp` server. The checked-in `packages/claude-directory` bundle is held to the same rules. Spell out exact tool names; dynamic tool-name templates fail validation. Snake-case data fields are recognized separately, but calling them as functions still counts as a tool reference. For a tool name without underscores, use explicit `tool:name` or its MCP-qualified name. The check runs offline in CI. To also compare the directory against live MCP `tools/list`, supply an OAuth access token through `SYNTER_MCP_TOKEN` in your environment and run the same script. It initializes an MCP session and follows paginated results. `--live` requires the token instead of silently running offline. `SYNTER_MCP_URL` optionally selects either hosted URL in the table; it defaults to the Cursor endpoint. The token is for this development check only and is never written to plugin configuration. Extra live tools do not expand the checked-in directory. diff --git a/agents/media-buyer.md b/agents/media-buyer.md index f6e132a..147bb91 100644 --- a/agents/media-buyer.md +++ b/agents/media-buyer.md @@ -9,7 +9,7 @@ You are Synter's media buyer. You take an approved plan and make it live, correc Discipline: - Confirm the target before touching anything: `list_connected_accounts`. Use the exact account IDs the tools return — never invent or guess an ID. Never run one org's campaign through another org's key. -- Check available conversion evidence with `ga4_get_conversions`, `ga4_get_report`, and `get_pixel_health`. Stop if required tracking verification is missing. +- Check available conversion evidence with `get_pixel_health` and `get_attribution`. Stop if required tracking verification is missing. - Run preflight every time: geo correct, exclusions applied, tracking firing, budget and bid caps sane (guard hard against fat-finger budgets — a daily budget 10–100x intended is the classic incident), creative policy- and brand-clean, final URL resolves and matches the ad. - Before launch, verify RSA assets meet the platform’s required counts and character limits. Prefer fewer concise, relevant headlines that qualify the intended audience and communicate the offer. Never pad headlines to reach 15. Ad Strength is not a launch gate. - Build with `create_campaign_plan` and `upsert_plan_entity`. Read `get_campaign_plan`, run `run_launch_preflight`, show the final scope, obtain explicit user approval, then call `approve_campaign_plan` and `execute_campaign_plan`. Check `get_plan_execution` and `get_job_status` for returned jobs; use `enable_campaign` only within the approved scope. diff --git a/agents/performance-analyst.md b/agents/performance-analyst.md index c6ed649..565f257 100644 --- a/agents/performance-analyst.md +++ b/agents/performance-analyst.md @@ -8,6 +8,6 @@ disallowedTools: Write, Edit Confirm the workspace and account IDs with `list_connected_accounts`. Pull comparable periods with `pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, and `pull_reddit_ads_performance` where connected. -Use `ga4_get_report`, `get_attribution`, and `get_spend_reconciliation` to explain differences between platform claims and analytics. Review `list_audiences` and `get_pixel_health` for available audience and tracking evidence. Request platform exports for missing breakdowns or change history. Never present a correlation as a proven cause. +Use `get_attribution` and `get_spend_reconciliation` to explain differences between platform claims and analytics; request a GA4 export when site analytics are needed. Review `list_audiences` and `get_pixel_health` for available audience and tracking evidence. Request platform exports for missing breakdowns or change history. Never present a correlation as a proven cause. Lead with spend, conversions, CPA/ROAS, and the comparison period. Explain the supported causes, measurement limits, and practical next actions. Name the platform, account, and account ID for every recommendation. Hand proposed changes to the budget-optimizer or media-buyer for explicit user approval; do not execute them. diff --git a/packages/claude-directory/.mcp.json b/packages/claude-directory/.mcp.json index c3ae094..c5f758a 100644 --- a/packages/claude-directory/.mcp.json +++ b/packages/claude-directory/.mcp.json @@ -2,7 +2,7 @@ "mcpServers": { "synter": { "type": "http", - "url": "https://mcp.synterai.com", + "url": "https://mcp.synterai.com/mcp", "description": "Synter Advertising Platform MCP \u2014 cross-channel ad management for AI agents. Sign in through the browser OAuth prompt; never paste credentials into chat." } } diff --git a/packages/claude-directory/agents/media-buyer.md b/packages/claude-directory/agents/media-buyer.md index f6e132a..147bb91 100644 --- a/packages/claude-directory/agents/media-buyer.md +++ b/packages/claude-directory/agents/media-buyer.md @@ -9,7 +9,7 @@ You are Synter's media buyer. You take an approved plan and make it live, correc Discipline: - Confirm the target before touching anything: `list_connected_accounts`. Use the exact account IDs the tools return — never invent or guess an ID. Never run one org's campaign through another org's key. -- Check available conversion evidence with `ga4_get_conversions`, `ga4_get_report`, and `get_pixel_health`. Stop if required tracking verification is missing. +- Check available conversion evidence with `get_pixel_health` and `get_attribution`. Stop if required tracking verification is missing. - Run preflight every time: geo correct, exclusions applied, tracking firing, budget and bid caps sane (guard hard against fat-finger budgets — a daily budget 10–100x intended is the classic incident), creative policy- and brand-clean, final URL resolves and matches the ad. - Before launch, verify RSA assets meet the platform’s required counts and character limits. Prefer fewer concise, relevant headlines that qualify the intended audience and communicate the offer. Never pad headlines to reach 15. Ad Strength is not a launch gate. - Build with `create_campaign_plan` and `upsert_plan_entity`. Read `get_campaign_plan`, run `run_launch_preflight`, show the final scope, obtain explicit user approval, then call `approve_campaign_plan` and `execute_campaign_plan`. Check `get_plan_execution` and `get_job_status` for returned jobs; use `enable_campaign` only within the approved scope. diff --git a/packages/claude-directory/agents/performance-analyst.md b/packages/claude-directory/agents/performance-analyst.md index c6ed649..565f257 100644 --- a/packages/claude-directory/agents/performance-analyst.md +++ b/packages/claude-directory/agents/performance-analyst.md @@ -8,6 +8,6 @@ disallowedTools: Write, Edit Confirm the workspace and account IDs with `list_connected_accounts`. Pull comparable periods with `pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, and `pull_reddit_ads_performance` where connected. -Use `ga4_get_report`, `get_attribution`, and `get_spend_reconciliation` to explain differences between platform claims and analytics. Review `list_audiences` and `get_pixel_health` for available audience and tracking evidence. Request platform exports for missing breakdowns or change history. Never present a correlation as a proven cause. +Use `get_attribution` and `get_spend_reconciliation` to explain differences between platform claims and analytics; request a GA4 export when site analytics are needed. Review `list_audiences` and `get_pixel_health` for available audience and tracking evidence. Request platform exports for missing breakdowns or change history. Never present a correlation as a proven cause. Lead with spend, conversions, CPA/ROAS, and the comparison period. Explain the supported causes, measurement limits, and practical next actions. Name the platform, account, and account ID for every recommendation. Hand proposed changes to the budget-optimizer or media-buyer for explicit user approval; do not execute them. diff --git a/packages/claude-directory/skills/attribution/SKILL.md b/packages/claude-directory/skills/attribution/SKILL.md index 6ddee1f..94917d8 100644 --- a/packages/claude-directory/skills/attribution/SKILL.md +++ b/packages/claude-directory/skills/attribution/SKILL.md @@ -11,7 +11,7 @@ Confirm the account: `list_connected_accounts`. ## 1. Get the cross-platform view -Use `get_attribution` for the cross-platform attribution view and `get_spend_reconciliation` for spend differences. Compare conversion counts from `ga4_get_report` with `pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, and `pull_reddit_ads_performance` for connected accounts. State what each source measures before interpreting differences. +Use `get_attribution` for the cross-platform attribution view and `get_spend_reconciliation` for spend differences. Compare conversion counts from `get_attribution` with `pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, and `pull_reddit_ads_performance` for connected accounts. State what each source measures before interpreting differences. ## 2. Read the discrepancy honestly diff --git a/packages/claude-directory/skills/campaign-preflight/SKILL.md b/packages/claude-directory/skills/campaign-preflight/SKILL.md index ade139f..50631bd 100644 --- a/packages/claude-directory/skills/campaign-preflight/SKILL.md +++ b/packages/claude-directory/skills/campaign-preflight/SKILL.md @@ -22,7 +22,7 @@ If a required level is missing, do not enable. Fix it first. Without tracking, the spend is blind and smart bidding cannot work. -- Use `ga4_get_conversions`, `ga4_get_report`, and `get_pixel_health` for available conversion evidence. A configured action does not prove that a tag is firing; mark missing verification explicitly. +- Use `get_pixel_health` and `run_launch_preflight` for available conversion evidence. A configured action does not prove that a tag is firing; mark missing verification explicitly. - Missing verified tracking on a conversion campaign is a stop. Once conversion goals are established, use MAXIMIZE_CONVERSIONS for Google Search conversion campaigns; do not substitute unconstrained Max Clicks. Consider Target CPA when conversion volume supports it. ## 3. UTMs on every ad (blocking) diff --git a/packages/claude-directory/skills/connect/SKILL.md b/packages/claude-directory/skills/connect/SKILL.md index ad3a015..48e7bba 100644 --- a/packages/claude-directory/skills/connect/SKILL.md +++ b/packages/claude-directory/skills/connect/SKILL.md @@ -7,7 +7,7 @@ description: Connect ad accounts and GA4 through the Synter browser flow and ver Use `get_connection_status` and `list_connected_accounts` to identify the workspace and existing accounts. Report the platform, account name, and account ID. -Direct the user to https://synterai.com/settings/credentials to connect the required platform or GA4 account in the browser. Afterward, re-run `list_connected_accounts` and `verify_platform_accounts`. For GA4, confirm access with `ga4_get_properties`. Use `get_pixel_health` for the available tracking diagnostics; do not treat account access as proof of a working conversion event. +Direct the user to https://synterai.com/settings/credentials to connect the required platform or GA4 account in the browser. Afterward, re-run `list_connected_accounts` and `verify_platform_accounts`. For GA4, confirm the account appears in `list_connected_accounts`. Use `get_pixel_health` for the available tracking diagnostics; do not treat account access as proof of a working conversion event. If access fails, confirm the selected workspace and the connected user's platform permissions. Reconnect through browser OAuth when needed. Never collect keys, tokens, or authorization codes in chat. For accounts that need provisioning help, link https://synterai.com/contact. diff --git a/packages/claude-directory/skills/conversion-tracking/SKILL.md b/packages/claude-directory/skills/conversion-tracking/SKILL.md index 7c13e57..c29f321 100644 --- a/packages/claude-directory/skills/conversion-tracking/SKILL.md +++ b/packages/claude-directory/skills/conversion-tracking/SKILL.md @@ -5,7 +5,7 @@ description: Verify available conversion and pixel diagnostics before launch; ha # Conversion tracking -Confirm the account with `list_connected_accounts` and `verify_platform_accounts`. Use `ga4_get_properties` to select the right property, `ga4_get_conversions` to inspect configured conversions, and `ga4_get_report` to check recorded events over a stated period. Read `get_pixel_health` for available pixel diagnostics. +Confirm the account with `list_connected_accounts` and `verify_platform_accounts`. Read `get_pixel_health` for available pixel and conversion diagnostics, and `get_attribution` to check recorded conversions over a stated period. For GA4 property or event detail, request an export from the GA4 UI. A configured conversion is not proof that the right event fires or that the campaign optimizes toward it. Compare the intended business action with the evidence returned. Use `run_launch_preflight` for a campaign plan. Mark fields and checks unavailable from the tools as unverified. diff --git a/packages/claude-directory/skills/executive-reporting/SKILL.md b/packages/claude-directory/skills/executive-reporting/SKILL.md index 6a96c34..9b1ba51 100644 --- a/packages/claude-directory/skills/executive-reporting/SKILL.md +++ b/packages/claude-directory/skills/executive-reporting/SKILL.md @@ -7,7 +7,7 @@ description: Build C-suite and board ad reports — blended ROAS, month-over-mon Write for a reader who does not live in the ad accounts. Lead with the result and the decision, not the dashboard. Reads only; this produces a report, it does not change spend. -Confirm the account: `list_connected_accounts`, then pull real numbers across platforms: the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`), `get_attribution` for the cross-platform view, `ga4_get_report` for outcomes. Reconcile platform self-reports before quoting a total (see **attribution**). +Confirm the account: `list_connected_accounts`, then pull real numbers across platforms: the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`), `get_attribution` for the cross-platform view and outcomes. Reconcile platform self-reports before quoting a total (see **attribution**). ## What an exec report says diff --git a/packages/claude-directory/skills/first-party-data-strategy/SKILL.md b/packages/claude-directory/skills/first-party-data-strategy/SKILL.md index 1aeb40d..588a6b4 100644 --- a/packages/claude-directory/skills/first-party-data-strategy/SKILL.md +++ b/packages/claude-directory/skills/first-party-data-strategy/SKILL.md @@ -11,7 +11,7 @@ Confirm the workspace with `list_connected_accounts` and `get_connection_status` ## 1. Audit what you collect today -Inventory every point where you capture an identifier: forms, signups, purchases, email lists, CRM records, in-app events. For each, note the identifier (email, phone, address), consent status, and freshness. Check what conversion data actually reaches the platforms: `ga4_get_conversions` and `ga4_get_report` for the site side, the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`) for what each platform claims. Big gaps between GA4 and platform numbers usually mean tracking loss, not attribution magic — see **conversion-tracking**. +Inventory every point where you capture an identifier: forms, signups, purchases, email lists, CRM records, in-app events. For each, note the identifier (email, phone, address), consent status, and freshness. Check what conversion data actually reaches the platforms: `get_pixel_health` and `get_attribution` for the site side, the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`) for what each platform claims. Big gaps between GA4 and platform numbers usually mean tracking loss, not attribution magic — see **conversion-tracking**. ## 2. Set up Enhanced Conversions and CAPI @@ -51,7 +51,7 @@ Collected data earns its keep in audiences: ## 7. Verify the pipeline end to end -After changes, compare site events with `ga4_get_report` and available platform performance results, then inspect attribution differences with `get_attribution`. Use `get_spend_reconciliation` for spend records separately. Mark unsupported event-level checks as unverified. +After changes, compare site events from `get_pixel_health` (or a GA4 export the user provides) with available platform performance results, then inspect attribution differences with `get_attribution`. Use `get_spend_reconciliation` for spend records separately. Mark unsupported event-level checks as unverified. ## Rules diff --git a/packages/claude-directory/skills/geo-integrity-audit/SKILL.md b/packages/claude-directory/skills/geo-integrity-audit/SKILL.md index abdecd6..b3ba006 100644 --- a/packages/claude-directory/skills/geo-integrity-audit/SKILL.md +++ b/packages/claude-directory/skills/geo-integrity-audit/SKILL.md @@ -9,7 +9,7 @@ Confirm the workspace with `list_connected_accounts`, then read `list_campaigns` Compare the intended geography with the location criteria, exclusions, and presence settings actually returned. A campaign name is not targeting evidence. Check every ad set or ad group when the data is available. Missing fields mean UNVERIFIED, not worldwide delivery or a passed check. -Use `pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, or `pull_reddit_ads_performance` for delivery evidence. Request geography only when the tool schema supports that breakdown. Cross-check site engagement by country with `ga4_get_report`. If targeting or delivery detail is unavailable, request an export from the platform UI. +Use `pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, or `pull_reddit_ads_performance` for delivery evidence. Request geography only when the tool schema supports that breakdown. Cross-check site engagement by country with a GA4 export the user provides. If targeting or delivery detail is unavailable, request an export from the platform UI. Investigate spend outside the intended market, unusually cheap clicks with weak engagement, and traffic spikes. These are signals to investigate, not proof of fraud. diff --git a/packages/claude-directory/skills/incrementality-testing/SKILL.md b/packages/claude-directory/skills/incrementality-testing/SKILL.md index f0ed5f5..2cfed03 100644 --- a/packages/claude-directory/skills/incrementality-testing/SKILL.md +++ b/packages/claude-directory/skills/incrementality-testing/SKILL.md @@ -11,7 +11,7 @@ Start with `measure_incrementality` where the platform and data support it; desi ## 1. Define the question -Pick one testable claim: channel incrementality ("does Display drive anything?"), budget incrementality ("does doubling spend double conversions?"), or tactic incrementality ("is retargeting real?"). One variable per test. Pull the baseline first: the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`) for spend and attributed conversions, `ga4_get_report` for a platform-neutral conversion count. +Pick one testable claim: channel incrementality ("does Display drive anything?"), budget incrementality ("does doubling spend double conversions?"), or tactic incrementality ("is retargeting real?"). One variable per test. Pull the baseline first: the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`) for spend and attributed conversions, `get_attribution` for a cross-platform conversion view. ## 2. Choose the method diff --git a/packages/claude-directory/skills/keyword-research/SKILL.md b/packages/claude-directory/skills/keyword-research/SKILL.md index d90e434..93811e2 100644 --- a/packages/claude-directory/skills/keyword-research/SKILL.md +++ b/packages/claude-directory/skills/keyword-research/SKILL.md @@ -28,7 +28,7 @@ Use `research_campaign_opportunity` and available `pull_google_ads_performance` ## 4. Add on approval -Draft supported keyword entities with `upsert_plan_entity` and follow **launch** for review, preflight, approval, execution, and verification. Use the platform UI if keyword edits are unsupported. Pair expansions with exclusions and verify tracking with `ga4_get_conversions` and **conversion-tracking**. +Draft supported keyword entities with `upsert_plan_entity` and follow **launch** for review, preflight, approval, execution, and verification. Use the platform UI if keyword edits are unsupported. Pair expansions with exclusions and verify tracking with `get_pixel_health` and **conversion-tracking**. ## Rules diff --git a/packages/claude-directory/skills/launch/SKILL.md b/packages/claude-directory/skills/launch/SKILL.md index 83e25ce..91fde4b 100644 --- a/packages/claude-directory/skills/launch/SKILL.md +++ b/packages/claude-directory/skills/launch/SKILL.md @@ -17,7 +17,7 @@ Get the brief in plain English, then pin down what you need: - **Budget** — daily/total, and the **target CPA/ROAS**. - **Landing page / final URL** and the offer. -Confirm the account with `list_connected_accounts`. Check conversion evidence with `ga4_get_conversions`, `ga4_get_report`, and `get_pixel_health`. Resolve missing verification before launching. +Confirm the account with `list_connected_accounts`. Check conversion evidence with `get_pixel_health` and `run_launch_preflight`. Resolve missing verification before launching. ## 2. Plan it diff --git a/packages/claude-directory/skills/performance-max-optimizer/SKILL.md b/packages/claude-directory/skills/performance-max-optimizer/SKILL.md index 0c32a70..726bf91 100644 --- a/packages/claude-directory/skills/performance-max-optimizer/SKILL.md +++ b/packages/claude-directory/skills/performance-max-optimizer/SKILL.md @@ -36,7 +36,7 @@ Signals guide initial learning; PMax expands beyond them. Stack them by strength - Review customer and high-value purchaser lists with `list_audiences`. Have the account owner create or refresh lists in the platform UI before using them in supported campaign-plan fields. - Custom segments from high-intent search terms and competitor URLs (50-100 entries each). -- Site visitors and cart abandoners from GA4 (`ga4_get_report` to size them). +- Site visitors and cart abandoners from GA4 (check available lists with `list_audiences`). - Interests and demographics last, as seasoning only. After 30 days, check which segments convert and whether expansion aligns with them. Deeper audience work lives in **audience**. diff --git a/packages/claude-directory/skills/pixel-capi-auditor/SKILL.md b/packages/claude-directory/skills/pixel-capi-auditor/SKILL.md index 369f739..5b80ebc 100644 --- a/packages/claude-directory/skills/pixel-capi-auditor/SKILL.md +++ b/packages/claude-directory/skills/pixel-capi-auditor/SKILL.md @@ -36,7 +36,7 @@ Failure signatures: - Conversions roughly double the true count: event ID missing on one side. - Counts too low: IDs present but formatted differently on each side, or event names mismatched. -- Platform reports far more conversions than GA4 shows (`ga4_get_report` on the conversion event): dedup broken — this is the most common finding. +- Platform reports far more conversions than GA4 shows (compare with `get_attribution` or a GA4 export of the conversion event): dedup broken — this is the most common finding. ## 4. Raise match quality @@ -44,7 +44,7 @@ Match quality (Meta EMQ 0-10; TikTok match rate) decides how many conversions at ## 5. Reconcile across platforms -Platforms can claim overlapping conversions. Compare platform results with `ga4_get_report` and inspect attribution with `get_attribution`, using consistent periods and stated attribution windows. Use `get_spend_reconciliation` for spend discrepancies; it does not establish conversion deduplication. +Platforms can claim overlapping conversions. Compare platform results and inspect attribution with `get_attribution`, using consistent periods and stated attribution windows. Use `get_spend_reconciliation` for spend discrepancies; it does not establish conversion deduplication. ## 6. Report and fix in priority order diff --git a/packages/claude-directory/skills/platform-google/SKILL.md b/packages/claude-directory/skills/platform-google/SKILL.md index 3d534f5..2a8f099 100644 --- a/packages/claude-directory/skills/platform-google/SKILL.md +++ b/packages/claude-directory/skills/platform-google/SKILL.md @@ -28,7 +28,7 @@ Use `create_campaign_plan` and `upsert_plan_entity` for the supported campaign s - Keep match types deliberate. Broad without good negatives and conversion tracking wastes budget fast. - Geo is the classic miss: a "US" campaign with no location criteria serves everywhere. Verify location criteria exist and match intent. -- Conversion tracking must exist and be attached before scaling: `ga4_get_conversions`, `get_pixel_health`. Blind spend is worse than no spend. +- Conversion tracking must exist and be attached before scaling: `get_pixel_health`, `run_launch_preflight`. Blind spend is worse than no spend. - Guard budgets against a fat-finger daily amount 10 to 100x intended. - Adjust budgets with `update_campaign_budget`; pause with `pause_campaign`. Start conservative; scale winners with the **optimize** skill. - "Created" is not "live and spending." Confirm with `list_campaigns` and report the real IDs. diff --git a/packages/claude-directory/skills/platform-linkedin/SKILL.md b/packages/claude-directory/skills/platform-linkedin/SKILL.md index 58be634..17937a7 100644 --- a/packages/claude-directory/skills/platform-linkedin/SKILL.md +++ b/packages/claude-directory/skills/platform-linkedin/SKILL.md @@ -29,7 +29,7 @@ Use `create_campaign_plan` and `upsert_plan_entity` for the supported campaign s - Expect higher CPL than other platforms. Judge LinkedIn on pipeline quality and downstream conversion, not raw CPC. - Keep targeting to decision makers where the offer warrants it; do not spray a broad seniority range on an expensive platform. - Give campaigns room before judging; B2B conversion windows are long. Follow **pre-pause-analysis** before cutting. -- Conversion tracking (Insight Tag and offline/CRM conversions) must be attached before scaling: `get_pixel_health`, `ga4_get_conversions`. Measure with `get_attribution`. +- Conversion tracking (Insight Tag and offline/CRM conversions) must be attached before scaling: `get_pixel_health`. Measure with `get_attribution`. - Guard against a fat-finger daily budget 10 to 100x intended. Adjust with `update_campaign_budget`, pause with `pause_campaign`. - "Created" is not "live and spending." Confirm with `list_campaigns` and report the real IDs. Build an audience first with the **audience** skill when one does not exist yet. diff --git a/packages/claude-directory/skills/platform-meta/SKILL.md b/packages/claude-directory/skills/platform-meta/SKILL.md index 875fe1f..78a32c1 100644 --- a/packages/claude-directory/skills/platform-meta/SKILL.md +++ b/packages/claude-directory/skills/platform-meta/SKILL.md @@ -30,7 +30,7 @@ Use `create_campaign_plan` and `upsert_plan_entity` for the supported campaign s - **Learning Phase:** a new ad set needs enough conversions to exit learning. Do not judge or kill it early, and do not edit it constantly; each significant edit resets learning. See the **pre-pause-analysis** discipline before cutting anything. - **Creative fatigue:** rising frequency with falling CTR means the creative is spent. Watch it with the **creative-fatigue-detector** skill and rotate before performance collapses. - Keep audience overlap in check; ad sets competing against each other inflate CPM. -- Conversion tracking (pixel and CAPI) must be firing and attached: `get_pixel_health`, `ga4_get_conversions`. Blind spend is worse than no spend. +- Conversion tracking (pixel and CAPI) must be firing and attached: `get_pixel_health`. Blind spend is worse than no spend. - Guard against a fat-finger daily budget 10 to 100x intended. Adjust with `update_campaign_budget`, pause with `pause_campaign`. Start conservative; scale winners with the **optimize** skill. - "Created" is not "live and spending." Confirm with `list_campaigns` and report the real IDs. diff --git a/packages/claude-directory/skills/platform-microsoft/SKILL.md b/packages/claude-directory/skills/platform-microsoft/SKILL.md index 6de4bb1..bc13bea 100644 --- a/packages/claude-directory/skills/platform-microsoft/SKILL.md +++ b/packages/claude-directory/skills/platform-microsoft/SKILL.md @@ -36,7 +36,7 @@ Use `create_campaign_plan` and `upsert_plan_entity` for the supported campaign s - Enabling a campaign does not serve its ad groups if those stay paused. After enabling, re-pull and confirm the children actually serve; never trust the campaign status alone. - Carry negatives across, not just keywords. Keywords without negatives burn budget. - Verify geo/location criteria exist and match intent. -- Conversion tracking must exist and be attached before scaling: `ga4_get_conversions`, `get_pixel_health`. +- Conversion tracking must exist and be attached before scaling: `get_pixel_health`, `run_launch_preflight`. - Guard against a fat-finger daily budget 10 to 100x intended. Adjust with `update_campaign_budget`, pause with `pause_campaign`. - "Created" is not "live and spending." Confirm with `list_campaigns` and report the real IDs. diff --git a/packages/claude-directory/skills/platform-openai/SKILL.md b/packages/claude-directory/skills/platform-openai/SKILL.md index e760ff7..59f4443 100644 --- a/packages/claude-directory/skills/platform-openai/SKILL.md +++ b/packages/claude-directory/skills/platform-openai/SKILL.md @@ -23,7 +23,7 @@ A newer surface: ads that appear alongside AI answers. Structure is campaign → ## Plan and ship -- Build with `create_campaign_plan` + `upsert_plan_entity`; `forecast_campaign` where projections are available. Run **campaign-preflight**: tracking attached (`get_pixel_health` / `ga4_get_conversions`), sane budgets. +- Build with `create_campaign_plan` + `upsert_plan_entity`; `forecast_campaign` where projections are available. Run **campaign-preflight**: tracking attached (`get_pixel_health`), sane budgets. - Ship only on explicit approval: `execute_campaign_plan`, then `enable_campaign`. Nothing that spends money goes live without a clear go. - Confirm live with `list_campaigns(platform="openai_ads")` and report the real ID. Start conservative; read results before scaling with the **optimize** skill. diff --git a/packages/claude-directory/skills/pre-pause-analysis/SKILL.md b/packages/claude-directory/skills/pre-pause-analysis/SKILL.md index 7c3878c..713e44a 100644 --- a/packages/claude-directory/skills/pre-pause-analysis/SKILL.md +++ b/packages/claude-directory/skills/pre-pause-analysis/SKILL.md @@ -11,7 +11,7 @@ Confirm the account: `list_connected_accounts`. ## 1. Is the data even real -- Confirm conversion tracking is firing and attached to the right action (`ga4_get_conversions`, `get_pixel_health`). A campaign with broken tracking looks dead when it may be converting. See the **conversion-tracking** skill. +- Confirm conversion tracking is firing and attached to the right action (`get_pixel_health`). A campaign with broken tracking looks dead when it may be converting. See the **conversion-tracking** skill. - Check the destination: does the final URL resolve and match the ad's promise. A broken or mismatched landing page kills conversion rate independent of the campaign. ## 2. Has it had enough time and volume diff --git a/packages/claude-directory/skills/quickstart/SKILL.md b/packages/claude-directory/skills/quickstart/SKILL.md index 8659bfd..edccde4 100644 --- a/packages/claude-directory/skills/quickstart/SKILL.md +++ b/packages/claude-directory/skills/quickstart/SKILL.md @@ -7,9 +7,9 @@ description: Sign in through OAuth, confirm the workspace, and run a first repor 1. Call `get_connection_status`. Complete the client’s browser OAuth prompt if requested, then retry. If sign-in fails, reconnect from the client’s plugin settings. Never ask for credentials in chat. 2. Call `list_connected_accounts` and show the workspace, platform, account name, and account ID. If an account is missing, use the **connect** skill. -3. For connected GA4 accounts, use `ga4_get_properties`, then `ga4_get_report` with the selected property and requested period. Use the tool’s returned schema for parameters. +3. For connected ad accounts, use `list_campaigns`, then the matching performance tool (for example `pull_google_ads_performance`) for the requested period. Use the tool’s returned schema for parameters. 4. Offer a first task: a **report**, a **launch** plan, an **audience** review, or **ad-copy-generation**. Do not claim access to accounts or data that the tools did not return. -The plugin connects to the hosted Synter MCP server over OAuth. Cursor uses https://mcp.synterai.com; Claude uses https://mcp.synterai.com. Both require a client that supports remote MCP and browser OAuth. +The plugin connects to the hosted Synter MCP server over OAuth. Cursor uses https://mcp.synterai.com; Claude uses https://mcp.synterai.com/mcp. Both require a client that supports remote MCP and browser OAuth. Reads do not require approval. Show the exact scope and obtain explicit approval before account mutations or spend changes. More help: **help** or https://synterai.com/contact. diff --git a/packages/claude-directory/skills/replicate/SKILL.md b/packages/claude-directory/skills/replicate/SKILL.md index c132e07..166c2a5 100644 --- a/packages/claude-directory/skills/replicate/SKILL.md +++ b/packages/claude-directory/skills/replicate/SKILL.md @@ -47,7 +47,7 @@ Run the **campaign-preflight** checklist and report pass/fail: - Geo/location criteria copied and correct (a "US" name with no location criteria is the classic miss). - Negatives carried over — porting keywords without negatives burns budget fast. -- Check target-side evidence with `ga4_get_conversions` and `get_pixel_health`. Resolve missing tracking verification before launch. +- Check target-side evidence with `get_pixel_health`. Resolve missing tracking verification before launch. - Budget and bid caps sane — guard against a fat-finger daily budget 10–100x intended. - Match types preserved; final URLs resolve and match the ad's promise. diff --git a/packages/claude-directory/skills/report/SKILL.md b/packages/claude-directory/skills/report/SKILL.md index 12ef44b..37ff1e2 100644 --- a/packages/claude-directory/skills/report/SKILL.md +++ b/packages/claude-directory/skills/report/SKILL.md @@ -9,11 +9,11 @@ Pull every connected platform the tools support, reconcile, and tell the story s ## 1. Gather -Pull the period the user wants across all connected platforms using the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`). Add analytics ground truth: `ga4_get_report` for sessions/conversions, `get_attribution` for conversion paths. +Pull the period the user wants across all connected platforms using the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`). Add analytics context: `get_attribution` for conversion paths. ## 2. Reconcile -Use `get_spend_reconciliation` to compare spend records. Compare conversion counts separately with `ga4_get_report` and `get_attribution`, stating the attribution model and window. Flag deduplication uncertainty and access failures rather than treating them as verified tracking defects. +Use `get_spend_reconciliation` to compare spend records. Compare conversion counts separately with `get_attribution`, stating the attribution model and window. Flag deduplication uncertainty and access failures rather than treating them as verified tracking defects. ## 3. Tell the story diff --git a/packages/claude-directory/skills/seasonal-budget-planner/SKILL.md b/packages/claude-directory/skills/seasonal-budget-planner/SKILL.md index b243ad0..324c214 100644 --- a/packages/claude-directory/skills/seasonal-budget-planner/SKILL.md +++ b/packages/claude-directory/skills/seasonal-budget-planner/SKILL.md @@ -7,7 +7,7 @@ description: Plan ad budgets around seasonal peaks — holiday scaling, CPM infl Peak season punishes flat budgets twice: CPMs inflate 50-150% while unprepared accounts pay them with untested creative and cold audiences. Plan in phases, not in a panic the week before. -Ground the plan in your own history first: the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`) over last year's season and `ga4_get_report` with a date dimension to see your real demand curve. +Ground the plan in your own history first: the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`) over last year's season to see your real demand curve. ## 1. Plan in four phases diff --git a/packages/claude-directory/skills/utm-builder/SKILL.md b/packages/claude-directory/skills/utm-builder/SKILL.md index d01d37b..725e968 100644 --- a/packages/claude-directory/skills/utm-builder/SKILL.md +++ b/packages/claude-directory/skills/utm-builder/SKILL.md @@ -24,7 +24,7 @@ Clean UTMs are why analytics can tell platforms apart. Inconsistent tags turn re ## Wire it up -Apply the convention across the campaign's final URLs, and confirm the parameters survive to the landing page (redirects sometimes strip them). Check they resolve in analytics with `ga4_get_report` (source/medium) after traffic starts. Consistent UTMs make the **attribution** and **report** skills far more accurate. +Apply the convention across the campaign's final URLs, and confirm the parameters survive to the landing page (redirects sometimes strip them). After traffic starts, check that they resolve in analytics (source/medium) through `get_attribution` or a GA4 export the user provides. Consistent UTMs make the **attribution** and **report** skills far more accurate. ## Rules diff --git a/packages/claude-directory/tools/directory-tools.json b/packages/claude-directory/tools/directory-tools.json index d84d815..7ef94d9 100644 --- a/packages/claude-directory/tools/directory-tools.json +++ b/packages/claude-directory/tools/directory-tools.json @@ -8,9 +8,6 @@ "pull_linkedin_ads_performance", "pull_microsoft_ads_performance", "pull_reddit_ads_performance", - "ga4_get_properties", - "ga4_get_report", - "ga4_get_conversions", "get_attribution", "get_spend_reconciliation", "get_pixel_health", diff --git a/scripts/build-packages.py b/scripts/build-packages.py index e835688..014fb55 100644 --- a/scripts/build-packages.py +++ b/scripts/build-packages.py @@ -108,7 +108,7 @@ def validate_claude_directory(files): servers = json.loads(files['.mcp.json']).get('mcpServers', {}) if (set(servers) != {'synter'} or set(servers['synter']) != {'type', 'url', 'description'} or servers['synter']['type'] != 'http' - or servers['synter']['url'] != 'https://mcp.synterai.com' + or servers['synter']['url'] != 'https://mcp.synterai.com/mcp' or not isinstance(servers['synter']['description'], str)): raise ValueError('Directory supports only the declared remote HTTPS MCP server') if len(files['README.md'].decode().split()) < 40: diff --git a/scripts/check-directory-tools.js b/scripts/check-directory-tools.js index b7aee51..0099a0b 100644 --- a/scripts/check-directory-tools.js +++ b/scripts/check-directory-tools.js @@ -14,8 +14,19 @@ const DATA_IDENTIFIERS = new Set([ 'utm_content', 'utm_medium', 'utm_source', 'utm_term', ]); const ROOT = path.resolve(__dirname, '..'); -const SURFACES = ['skills', 'commands', 'rules', 'agents']; -const ENDPOINTS = new Set(['https://mcp.synterai.com', 'https://mcp.syntermedia.ai']); +const SURFACES = ['skills', 'commands', 'rules', 'agents', 'context', 'output-styles', 'scripts/session-context.sh']; +// Docs mix tool names with shell commands, so they are checked only for +// unavailable tool families and banned phrases, not against the allowlist. +const DOCS = ['README.md']; +// Hosted Claude connector: OAuth only, so the config carries no headers or keys. +const MCP_URL = 'https://mcp.synterai.com/mcp'; +const ENDPOINTS = new Set([MCP_URL, 'https://mcp.synterai.com', 'https://mcp.syntermedia.ai']); +// Tool families the hosted Claude connector does not expose. +const UNAVAILABLE_TOOL = /^(?:ga4|generate)_/; +// Pricing language is not allowed in listing or instruction copy. Hyphenated +// compounds such as "credential-free" and words such as "freed" are fine. +const BANNED_PHRASES = [/(? { const filename = path.join(dir, entry.name); if (entry.isSymbolicLink()) throw new Error(`Instruction symlinks are not supported: ${filename}`); @@ -51,10 +63,12 @@ function listFiles(dir) { function readAllowlist(root) { const names = JSON.parse(fs.readFileSync(path.join(root, 'tools/directory-tools.json'), 'utf8')); - if (!Array.isArray(names) || names.length !== 34 || new Set(names).size !== 34 || + if (!Array.isArray(names) || names.length !== 31 || new Set(names).size !== 31 || names.some(name => typeof name !== 'string' || !/^[a-z][a-z0-9_]+$/.test(name))) { - throw new Error('tools/directory-tools.json must contain 34 unique tool names.'); + throw new Error('tools/directory-tools.json must contain 31 unique tool names.'); } + const unavailable = names.filter(name => UNAVAILABLE_TOOL.test(name)); + if (unavailable.length) throw new Error(`tools/directory-tools.json lists tools the hosted connector does not expose: ${unavailable.join(', ')}`); return new Set(names); } @@ -65,15 +79,62 @@ function scan(root = ROOT) { const files = SURFACES.flatMap(surface => listFiles(path.join(root, surface))); if (!files.length) throw new Error('No instruction files found.'); for (const filename of files) { - for (const ref of extractReferences(fs.readFileSync(filename, 'utf8'))) { + const source = fs.readFileSync(filename, 'utf8'); + const relative = path.relative(root, filename); + for (const ref of extractReferences(source)) { references.add(ref.name); - if (!allowed.has(ref.name)) errors.push(`${path.relative(root, filename)}:${ref.line}: unlisted tool ${ref.name}`); + if (UNAVAILABLE_TOOL.test(ref.name)) errors.push(`${relative}:${ref.line}: tool ${ref.name} is not available on the hosted Claude connector`); + else if (!allowed.has(ref.name)) errors.push(`${relative}:${ref.line}: unlisted tool ${ref.name}`); } + errors.push(...findBannedPhrases(source, relative)); } + for (const doc of DOCS) { + const filename = path.join(root, doc); + if (!fs.existsSync(filename)) continue; + const source = fs.readFileSync(filename, 'utf8'); + source.split(/\r?\n/).forEach((line, index) => { + for (const match of line.matchAll(/\b(?:ga4|generate)_[a-z0-9_]+/g)) { + errors.push(`${doc}:${index + 1}: tool ${match[0]} is not available on the hosted Claude connector`); + } + }); + errors.push(...findBannedPhrases(source, doc)); + } + for (const manifest of MANIFESTS) { + const filename = path.join(root, manifest); + if (fs.existsSync(filename)) errors.push(...findBannedPhrases(fs.readFileSync(filename, 'utf8'), manifest)); + } + errors.push(...checkMcpConfig(root)); return { allowed, references, errors, fileCount: files.length }; } -async function readLiveTools({ token, url = 'https://mcp.synterai.com', fetchImpl = fetch }) { +function findBannedPhrases(source, relative) { + const errors = []; + source.split(/\r?\n/).forEach((line, index) => { + for (const pattern of BANNED_PHRASES) { + const match = line.match(pattern); + if (match) errors.push(`${relative}:${index + 1}: banned phrase "${match[0]}"`); + } + }); + return errors; +} + +function checkMcpConfig(root) { + let server; + let servers; + try { + servers = JSON.parse(fs.readFileSync(path.join(root, '.mcp.json'), 'utf8')).mcpServers; + server = servers && servers.synter; + } catch { + return ['.mcp.json: missing or invalid JSON']; + } + if (!server || Object.keys(servers).length !== 1 || server.type !== 'http' || server.url !== MCP_URL || + Object.keys(server).some(key => !['type', 'url', 'description'].includes(key))) { + return [`.mcp.json: expected one OAuth-only Synter HTTP server at ${MCP_URL} with no headers or credentials`]; + } + return []; +} + +async function readLiveTools({ token, url = MCP_URL, fetchImpl = fetch }) { if (!token) throw new Error('Live check requires SYNTER_MCP_TOKEN (an OAuth access token).'); if (!ENDPOINTS.has(url)) throw new Error('Live check URL must be one of the two production Synter MCP endpoints.'); let session; @@ -150,6 +211,9 @@ async function main() { const args = process.argv.slice(2); if (args.some(arg => arg !== '--live')) throw new Error('Usage: node scripts/check-directory-tools.js [--live]'); const result = scan(); + // The checked-in Claude directory bundle ships separately; hold it to the same rules. + const bundle = path.join(ROOT, 'packages/claude-directory'); + if (fs.existsSync(bundle)) result.errors.push(...scan(bundle).errors.map(error => `packages/claude-directory/${error}`)); if (result.errors.length) throw new Error(result.errors.join('\n')); if (args.includes('--live') || process.env.SYNTER_MCP_TOKEN) { const live = await readLiveTools({ token: process.env.SYNTER_MCP_TOKEN, url: process.env.SYNTER_MCP_URL }); diff --git a/scripts/check-directory-tools.test.js b/scripts/check-directory-tools.test.js index 7ea0295..6c04dd1 100644 --- a/scripts/check-directory-tools.test.js +++ b/scripts/check-directory-tools.test.js @@ -39,6 +39,7 @@ test('checks nested files in every instruction surface, including optional comma t.after(() => fs.rmSync(root, { recursive: true, force: true })); fs.mkdirSync(path.join(root, 'tools')); fs.copyFileSync(path.join(__dirname, '../tools/directory-tools.json'), path.join(root, 'tools/directory-tools.json')); + fs.copyFileSync(path.join(__dirname, '../.mcp.json'), path.join(root, '.mcp.json')); for (const surface of ['skills', 'commands', 'rules', 'agents']) { fs.mkdirSync(path.join(root, surface, 'nested'), { recursive: true }); fs.writeFileSync(path.join(root, surface, 'nested/instructions.md'), `Use list_campaigns and unknown_${surface}.`); @@ -56,7 +57,72 @@ test('checks nested files in every instruction surface, including optional comma assert.equal(cli.status, 1); assert.match(cli.stderr, /unlisted tool unknown_commands/); fs.writeFileSync(path.join(root, 'tools/directory-tools.json'), '["list_campaigns", "list_campaigns"]'); - assert.throws(() => scan(root), /34 unique tool names/); + assert.throws(() => scan(root), /31 unique tool names/); +}); + +function fixtureRoot(t) { + const root = fs.mkdtempSync(path.join(os.tmpdir(), 'synter-directory-test-')); + t.after(() => fs.rmSync(root, { recursive: true, force: true })); + fs.mkdirSync(path.join(root, 'tools')); + fs.mkdirSync(path.join(root, 'skills/example'), { recursive: true }); + fs.copyFileSync(path.join(__dirname, '../tools/directory-tools.json'), path.join(root, 'tools/directory-tools.json')); + fs.copyFileSync(path.join(__dirname, '../.mcp.json'), path.join(root, '.mcp.json')); + fs.writeFileSync(path.join(root, 'skills/example/SKILL.md'), 'Use list_campaigns.'); + return root; +} + +test('a clean fixture passes, so the failures below come from the injected defect', t => { + assert.deepEqual(scan(fixtureRoot(t)).errors, []); +}); + +test('ga4_* and generate_* tools fail in instructions, hooks, README, and the allowlist', t => { + const root = fixtureRoot(t); + fs.writeFileSync(path.join(root, 'skills/example/SKILL.md'), 'Use list_campaigns, then `ga4_get_report`.\nCall generate_image.'); + fs.mkdirSync(path.join(root, 'scripts')); + fs.writeFileSync(path.join(root, 'scripts/session-context.sh'), 'echo "Run ga4_get_properties first"'); + fs.writeFileSync(path.join(root, 'README.md'), '```bash\nnode test_*.py\n```\nCall `generate_video_ad`.'); + const errors = scan(root).errors; + assert.deepEqual(errors, [ + 'skills/example/SKILL.md:1: tool ga4_get_report is not available on the hosted Claude connector', + 'skills/example/SKILL.md:2: tool generate_image is not available on the hosted Claude connector', + 'scripts/session-context.sh:1: tool ga4_get_properties is not available on the hosted Claude connector', + 'README.md:4: tool generate_video_ad is not available on the hosted Claude connector', + ]); + const names = JSON.parse(fs.readFileSync(path.join(root, 'tools/directory-tools.json'), 'utf8')); + names[0] = 'ga4_get_report'; + fs.writeFileSync(path.join(root, 'tools/directory-tools.json'), JSON.stringify(names)); + assert.throws(() => scan(root), /does not expose: ga4_get_report/); +}); + +test('"free" wording fails in instructions, README, and manifests; compounds pass', t => { + const root = fixtureRoot(t); + fs.writeFileSync(path.join(root, 'skills/example/SKILL.md'), 'Use list_campaigns.\nStart your Free trial.\nKeep it credential-free; reuse freed budget.'); + fs.writeFileSync(path.join(root, 'README.md'), 'Install the plugin for free.'); + fs.mkdirSync(path.join(root, '.claude-plugin')); + fs.writeFileSync(path.join(root, '.claude-plugin/plugin.json'), '{"description": "FREE ad operator"}'); + assert.deepEqual(scan(root).errors, [ + 'skills/example/SKILL.md:2: banned phrase "Free"', + 'README.md:1: banned phrase "free"', + '.claude-plugin/plugin.json:1: banned phrase "FREE"', + ]); +}); + +test('.mcp.json must be the OAuth-only hosted connector URL', t => { + const root = fixtureRoot(t); + const write = server => fs.writeFileSync(path.join(root, '.mcp.json'), JSON.stringify({ mcpServers: { synter: server } })); + for (const server of [ + { type: 'http', url: 'https://mcp.synterai.com' }, + { type: 'http', url: 'https://mcp.syntermedia.ai/mcp' }, + { type: 'http', url: 'https://mcp.synterai.com/mcp', headers: { 'X-Synter-Key': '${SYNTER_API_KEY}' } }, + { type: 'sse', url: 'https://mcp.synterai.com/mcp' }, + ]) { + write(server); + assert.match(scan(root).errors.join('\n'), /\.mcp\.json: expected one OAuth-only Synter HTTP server at https:\/\/mcp\.synterai\.com\/mcp/, JSON.stringify(server)); + } + write({ type: 'http', url: 'https://mcp.synterai.com/mcp', description: 'Synter' }); + assert.deepEqual(scan(root).errors, []); + fs.rmSync(path.join(root, '.mcp.json')); + assert.deepEqual(scan(root).errors, ['.mcp.json: missing or invalid JSON']); }); function response(id, result, { sse = false, session = false } = {}) { @@ -74,7 +140,7 @@ test('live check initializes, passes session headers, parses JSON/SSE, and pagin const names = await readLiveTools({ token: 'test-oauth-token', fetchImpl: async (url, options) => { const body = JSON.parse(options.body); calls.push(body); - assert.equal(url, 'https://mcp.synterai.com'); + assert.equal(url, 'https://mcp.synterai.com/mcp'); assert.equal(options.headers.Authorization, 'Bearer test-oauth-token'); assert.equal(options.redirect, 'error'); if (body.method === 'initialize') return response(body.id, { protocolVersion: '2025-03-26' }, { session: true }); diff --git a/scripts/test_build_packages.py b/scripts/test_build_packages.py index 08daf25..30be325 100644 --- a/scripts/test_build_packages.py +++ b/scripts/test_build_packages.py @@ -58,7 +58,8 @@ def test_directory_rejects_local_execution_and_unknown_files(self): with self.assertRaises(ValueError): mod.validate_claude_directory(changed) for server in [{'command': 'node'}, {'type': 'http', 'url': 'https://other.example', 'description': 'test'}, - {'type': 'http', 'url': 'https://mcp.synterai.com', 'description': 'test', 'headers': {'x-key': 'fake'}}]: + {'type': 'http', 'url': 'https://mcp.synterai.com', 'description': 'test'}, + {'type': 'http', 'url': 'https://mcp.synterai.com/mcp', 'description': 'test', 'headers': {'x-key': 'fake'}}]: with self.subTest(server=server), self.assertRaises(ValueError): mod.validate_claude_directory({**files, '.mcp.json': mod.encoded({'mcpServers': {'synter': server}})}) @@ -99,12 +100,12 @@ def test_directory_generated_source_detects_drift_and_symlinks(self): def test_archives_match_reviewed_rsa_correction_bytes(self): expected = { - 'claude': '72fecb572222d3725acd884f4d7f49a3f5493a2c084d4a4ee201a53a960aee73', - 'claude-directory': 'e313a4ed69ef3e2e80d13c622d102e69d8e6c51cfeb8f0ba13f29b2e0340efc1', - 'openai': '5ab905019791b7f0f71033e19e18042e26ba272b7b2d958aac4ff177a7c0f665', - 'openai-new-draft': '48bbdbedbc5eb96ffacfcd18b339048139ac6f67dbca160e5fd2d13b7682cd87', + 'claude': 'db3ff6f763b55df338d20464d615ca2512ee6c089f3e7afb61b9fed376beadf7', + 'claude-directory': '503b3fa379822b6eaa3476fd456bc110c473d8615c26735f817fe9fbd76e8109', + 'openai': '273cd2584b0f7e49799fabbb61c37c56d899be4c7f4ab12dd893ca69da99cc3e', + 'openai-new-draft': '5110ecac864a3c2f143a17c38f98d8a468bce5ad1166335238a44587690062cf', } - # Snapshot after the approved RSA/bidding correction across all hosts. + # Snapshot after removing ga4_* references and moving Claude to the /mcp endpoint. # Update deliberately when reviewed package contents change. for target, digest in expected.items(): _, files = mod.collect(mod.ROOT, target) diff --git a/scripts/validate-manifests.js b/scripts/validate-manifests.js index a2a246d..6b7b505 100644 --- a/scripts/validate-manifests.js +++ b/scripts/validate-manifests.js @@ -115,7 +115,7 @@ if (fs.existsSync(SKILLS_DIR)) { // (d) Client-specific HTTP syntax remains separate from the portable MCP schema. for (const [configPath, expectedUrl] of [ - ['.mcp.json', 'https://mcp.synterai.com'], + ['.mcp.json', 'https://mcp.synterai.com/mcp'], ['.cursor-mcp.json', 'https://mcp.synterai.com'], ]) { const config = manifests[configPath]; diff --git a/sdk/README.md b/sdk/README.md index 02a690c..a1d29fe 100644 --- a/sdk/README.md +++ b/sdk/README.md @@ -8,7 +8,7 @@ npm install node synter-agent.mjs "/synter:report last 7 days" ``` -Use the host SDK’s supported Claude authentication. Synter uses the plugin’s browser OAuth connection at `https://mcp.synterai.com`. Establish that connection interactively in the host environment first. An unattended process cannot complete a browser prompt; if the host does not reuse the authorized session, run the task interactively. OAuth session reuse depends on the host and must be verified before scheduling this runner. +Use the host SDK’s supported Claude authentication. Synter uses the plugin’s browser OAuth connection at `https://mcp.synterai.com/mcp`. Establish that connection interactively in the host environment first. An unattended process cannot complete a browser prompt; if the host does not reuse the authorized session, run the task interactively. OAuth session reuse depends on the host and must be verified before scheduling this runner. The runner permits the explicitly listed read tools and blocks other Synter tools by default. It also blocks local write and shell tools. Review `synter-agent.mjs` before use. The existing `--allow-writes` option removes the runner’s mutation guard; campaign instructions still require the user’s explicit approval of the action scope. Prefer interactive use when campaign changes need review. diff --git a/sdk/synter-agent.mjs b/sdk/synter-agent.mjs index 8dfd5dd..a375d27 100644 --- a/sdk/synter-agent.mjs +++ b/sdk/synter-agent.mjs @@ -37,9 +37,6 @@ const READ_ONLY = new Set([ "pull_linkedin_ads_performance", "pull_microsoft_ads_performance", "pull_reddit_ads_performance", - "ga4_get_properties", - "ga4_get_report", - "ga4_get_conversions", "get_attribution", "get_spend_reconciliation", "get_pixel_health", diff --git a/skills/attribution/SKILL.md b/skills/attribution/SKILL.md index 6ddee1f..94917d8 100644 --- a/skills/attribution/SKILL.md +++ b/skills/attribution/SKILL.md @@ -11,7 +11,7 @@ Confirm the account: `list_connected_accounts`. ## 1. Get the cross-platform view -Use `get_attribution` for the cross-platform attribution view and `get_spend_reconciliation` for spend differences. Compare conversion counts from `ga4_get_report` with `pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, and `pull_reddit_ads_performance` for connected accounts. State what each source measures before interpreting differences. +Use `get_attribution` for the cross-platform attribution view and `get_spend_reconciliation` for spend differences. Compare conversion counts from `get_attribution` with `pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, and `pull_reddit_ads_performance` for connected accounts. State what each source measures before interpreting differences. ## 2. Read the discrepancy honestly diff --git a/skills/campaign-preflight/SKILL.md b/skills/campaign-preflight/SKILL.md index ade139f..50631bd 100644 --- a/skills/campaign-preflight/SKILL.md +++ b/skills/campaign-preflight/SKILL.md @@ -22,7 +22,7 @@ If a required level is missing, do not enable. Fix it first. Without tracking, the spend is blind and smart bidding cannot work. -- Use `ga4_get_conversions`, `ga4_get_report`, and `get_pixel_health` for available conversion evidence. A configured action does not prove that a tag is firing; mark missing verification explicitly. +- Use `get_pixel_health` and `run_launch_preflight` for available conversion evidence. A configured action does not prove that a tag is firing; mark missing verification explicitly. - Missing verified tracking on a conversion campaign is a stop. Once conversion goals are established, use MAXIMIZE_CONVERSIONS for Google Search conversion campaigns; do not substitute unconstrained Max Clicks. Consider Target CPA when conversion volume supports it. ## 3. UTMs on every ad (blocking) diff --git a/skills/connect/SKILL.md b/skills/connect/SKILL.md index ad3a015..48e7bba 100644 --- a/skills/connect/SKILL.md +++ b/skills/connect/SKILL.md @@ -7,7 +7,7 @@ description: Connect ad accounts and GA4 through the Synter browser flow and ver Use `get_connection_status` and `list_connected_accounts` to identify the workspace and existing accounts. Report the platform, account name, and account ID. -Direct the user to https://synterai.com/settings/credentials to connect the required platform or GA4 account in the browser. Afterward, re-run `list_connected_accounts` and `verify_platform_accounts`. For GA4, confirm access with `ga4_get_properties`. Use `get_pixel_health` for the available tracking diagnostics; do not treat account access as proof of a working conversion event. +Direct the user to https://synterai.com/settings/credentials to connect the required platform or GA4 account in the browser. Afterward, re-run `list_connected_accounts` and `verify_platform_accounts`. For GA4, confirm the account appears in `list_connected_accounts`. Use `get_pixel_health` for the available tracking diagnostics; do not treat account access as proof of a working conversion event. If access fails, confirm the selected workspace and the connected user's platform permissions. Reconnect through browser OAuth when needed. Never collect keys, tokens, or authorization codes in chat. For accounts that need provisioning help, link https://synterai.com/contact. diff --git a/skills/conversion-tracking/SKILL.md b/skills/conversion-tracking/SKILL.md index 7c13e57..c29f321 100644 --- a/skills/conversion-tracking/SKILL.md +++ b/skills/conversion-tracking/SKILL.md @@ -5,7 +5,7 @@ description: Verify available conversion and pixel diagnostics before launch; ha # Conversion tracking -Confirm the account with `list_connected_accounts` and `verify_platform_accounts`. Use `ga4_get_properties` to select the right property, `ga4_get_conversions` to inspect configured conversions, and `ga4_get_report` to check recorded events over a stated period. Read `get_pixel_health` for available pixel diagnostics. +Confirm the account with `list_connected_accounts` and `verify_platform_accounts`. Read `get_pixel_health` for available pixel and conversion diagnostics, and `get_attribution` to check recorded conversions over a stated period. For GA4 property or event detail, request an export from the GA4 UI. A configured conversion is not proof that the right event fires or that the campaign optimizes toward it. Compare the intended business action with the evidence returned. Use `run_launch_preflight` for a campaign plan. Mark fields and checks unavailable from the tools as unverified. diff --git a/skills/executive-reporting/SKILL.md b/skills/executive-reporting/SKILL.md index 6a96c34..9b1ba51 100644 --- a/skills/executive-reporting/SKILL.md +++ b/skills/executive-reporting/SKILL.md @@ -7,7 +7,7 @@ description: Build C-suite and board ad reports — blended ROAS, month-over-mon Write for a reader who does not live in the ad accounts. Lead with the result and the decision, not the dashboard. Reads only; this produces a report, it does not change spend. -Confirm the account: `list_connected_accounts`, then pull real numbers across platforms: the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`), `get_attribution` for the cross-platform view, `ga4_get_report` for outcomes. Reconcile platform self-reports before quoting a total (see **attribution**). +Confirm the account: `list_connected_accounts`, then pull real numbers across platforms: the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`), `get_attribution` for the cross-platform view and outcomes. Reconcile platform self-reports before quoting a total (see **attribution**). ## What an exec report says diff --git a/skills/first-party-data-strategy/SKILL.md b/skills/first-party-data-strategy/SKILL.md index 1aeb40d..588a6b4 100644 --- a/skills/first-party-data-strategy/SKILL.md +++ b/skills/first-party-data-strategy/SKILL.md @@ -11,7 +11,7 @@ Confirm the workspace with `list_connected_accounts` and `get_connection_status` ## 1. Audit what you collect today -Inventory every point where you capture an identifier: forms, signups, purchases, email lists, CRM records, in-app events. For each, note the identifier (email, phone, address), consent status, and freshness. Check what conversion data actually reaches the platforms: `ga4_get_conversions` and `ga4_get_report` for the site side, the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`) for what each platform claims. Big gaps between GA4 and platform numbers usually mean tracking loss, not attribution magic — see **conversion-tracking**. +Inventory every point where you capture an identifier: forms, signups, purchases, email lists, CRM records, in-app events. For each, note the identifier (email, phone, address), consent status, and freshness. Check what conversion data actually reaches the platforms: `get_pixel_health` and `get_attribution` for the site side, the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`) for what each platform claims. Big gaps between GA4 and platform numbers usually mean tracking loss, not attribution magic — see **conversion-tracking**. ## 2. Set up Enhanced Conversions and CAPI @@ -51,7 +51,7 @@ Collected data earns its keep in audiences: ## 7. Verify the pipeline end to end -After changes, compare site events with `ga4_get_report` and available platform performance results, then inspect attribution differences with `get_attribution`. Use `get_spend_reconciliation` for spend records separately. Mark unsupported event-level checks as unverified. +After changes, compare site events from `get_pixel_health` (or a GA4 export the user provides) with available platform performance results, then inspect attribution differences with `get_attribution`. Use `get_spend_reconciliation` for spend records separately. Mark unsupported event-level checks as unverified. ## Rules diff --git a/skills/geo-integrity-audit/SKILL.md b/skills/geo-integrity-audit/SKILL.md index abdecd6..b3ba006 100644 --- a/skills/geo-integrity-audit/SKILL.md +++ b/skills/geo-integrity-audit/SKILL.md @@ -9,7 +9,7 @@ Confirm the workspace with `list_connected_accounts`, then read `list_campaigns` Compare the intended geography with the location criteria, exclusions, and presence settings actually returned. A campaign name is not targeting evidence. Check every ad set or ad group when the data is available. Missing fields mean UNVERIFIED, not worldwide delivery or a passed check. -Use `pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, or `pull_reddit_ads_performance` for delivery evidence. Request geography only when the tool schema supports that breakdown. Cross-check site engagement by country with `ga4_get_report`. If targeting or delivery detail is unavailable, request an export from the platform UI. +Use `pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, or `pull_reddit_ads_performance` for delivery evidence. Request geography only when the tool schema supports that breakdown. Cross-check site engagement by country with a GA4 export the user provides. If targeting or delivery detail is unavailable, request an export from the platform UI. Investigate spend outside the intended market, unusually cheap clicks with weak engagement, and traffic spikes. These are signals to investigate, not proof of fraud. diff --git a/skills/incrementality-testing/SKILL.md b/skills/incrementality-testing/SKILL.md index f0ed5f5..2cfed03 100644 --- a/skills/incrementality-testing/SKILL.md +++ b/skills/incrementality-testing/SKILL.md @@ -11,7 +11,7 @@ Start with `measure_incrementality` where the platform and data support it; desi ## 1. Define the question -Pick one testable claim: channel incrementality ("does Display drive anything?"), budget incrementality ("does doubling spend double conversions?"), or tactic incrementality ("is retargeting real?"). One variable per test. Pull the baseline first: the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`) for spend and attributed conversions, `ga4_get_report` for a platform-neutral conversion count. +Pick one testable claim: channel incrementality ("does Display drive anything?"), budget incrementality ("does doubling spend double conversions?"), or tactic incrementality ("is retargeting real?"). One variable per test. Pull the baseline first: the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`) for spend and attributed conversions, `get_attribution` for a cross-platform conversion view. ## 2. Choose the method diff --git a/skills/keyword-research/SKILL.md b/skills/keyword-research/SKILL.md index d90e434..93811e2 100644 --- a/skills/keyword-research/SKILL.md +++ b/skills/keyword-research/SKILL.md @@ -28,7 +28,7 @@ Use `research_campaign_opportunity` and available `pull_google_ads_performance` ## 4. Add on approval -Draft supported keyword entities with `upsert_plan_entity` and follow **launch** for review, preflight, approval, execution, and verification. Use the platform UI if keyword edits are unsupported. Pair expansions with exclusions and verify tracking with `ga4_get_conversions` and **conversion-tracking**. +Draft supported keyword entities with `upsert_plan_entity` and follow **launch** for review, preflight, approval, execution, and verification. Use the platform UI if keyword edits are unsupported. Pair expansions with exclusions and verify tracking with `get_pixel_health` and **conversion-tracking**. ## Rules diff --git a/skills/launch/SKILL.md b/skills/launch/SKILL.md index 83e25ce..91fde4b 100644 --- a/skills/launch/SKILL.md +++ b/skills/launch/SKILL.md @@ -17,7 +17,7 @@ Get the brief in plain English, then pin down what you need: - **Budget** — daily/total, and the **target CPA/ROAS**. - **Landing page / final URL** and the offer. -Confirm the account with `list_connected_accounts`. Check conversion evidence with `ga4_get_conversions`, `ga4_get_report`, and `get_pixel_health`. Resolve missing verification before launching. +Confirm the account with `list_connected_accounts`. Check conversion evidence with `get_pixel_health` and `run_launch_preflight`. Resolve missing verification before launching. ## 2. Plan it diff --git a/skills/performance-max-optimizer/SKILL.md b/skills/performance-max-optimizer/SKILL.md index 0c32a70..726bf91 100644 --- a/skills/performance-max-optimizer/SKILL.md +++ b/skills/performance-max-optimizer/SKILL.md @@ -36,7 +36,7 @@ Signals guide initial learning; PMax expands beyond them. Stack them by strength - Review customer and high-value purchaser lists with `list_audiences`. Have the account owner create or refresh lists in the platform UI before using them in supported campaign-plan fields. - Custom segments from high-intent search terms and competitor URLs (50-100 entries each). -- Site visitors and cart abandoners from GA4 (`ga4_get_report` to size them). +- Site visitors and cart abandoners from GA4 (check available lists with `list_audiences`). - Interests and demographics last, as seasoning only. After 30 days, check which segments convert and whether expansion aligns with them. Deeper audience work lives in **audience**. diff --git a/skills/pixel-capi-auditor/SKILL.md b/skills/pixel-capi-auditor/SKILL.md index 369f739..5b80ebc 100644 --- a/skills/pixel-capi-auditor/SKILL.md +++ b/skills/pixel-capi-auditor/SKILL.md @@ -36,7 +36,7 @@ Failure signatures: - Conversions roughly double the true count: event ID missing on one side. - Counts too low: IDs present but formatted differently on each side, or event names mismatched. -- Platform reports far more conversions than GA4 shows (`ga4_get_report` on the conversion event): dedup broken — this is the most common finding. +- Platform reports far more conversions than GA4 shows (compare with `get_attribution` or a GA4 export of the conversion event): dedup broken — this is the most common finding. ## 4. Raise match quality @@ -44,7 +44,7 @@ Match quality (Meta EMQ 0-10; TikTok match rate) decides how many conversions at ## 5. Reconcile across platforms -Platforms can claim overlapping conversions. Compare platform results with `ga4_get_report` and inspect attribution with `get_attribution`, using consistent periods and stated attribution windows. Use `get_spend_reconciliation` for spend discrepancies; it does not establish conversion deduplication. +Platforms can claim overlapping conversions. Compare platform results and inspect attribution with `get_attribution`, using consistent periods and stated attribution windows. Use `get_spend_reconciliation` for spend discrepancies; it does not establish conversion deduplication. ## 6. Report and fix in priority order diff --git a/skills/platform-google/SKILL.md b/skills/platform-google/SKILL.md index 3d534f5..2a8f099 100644 --- a/skills/platform-google/SKILL.md +++ b/skills/platform-google/SKILL.md @@ -28,7 +28,7 @@ Use `create_campaign_plan` and `upsert_plan_entity` for the supported campaign s - Keep match types deliberate. Broad without good negatives and conversion tracking wastes budget fast. - Geo is the classic miss: a "US" campaign with no location criteria serves everywhere. Verify location criteria exist and match intent. -- Conversion tracking must exist and be attached before scaling: `ga4_get_conversions`, `get_pixel_health`. Blind spend is worse than no spend. +- Conversion tracking must exist and be attached before scaling: `get_pixel_health`, `run_launch_preflight`. Blind spend is worse than no spend. - Guard budgets against a fat-finger daily amount 10 to 100x intended. - Adjust budgets with `update_campaign_budget`; pause with `pause_campaign`. Start conservative; scale winners with the **optimize** skill. - "Created" is not "live and spending." Confirm with `list_campaigns` and report the real IDs. diff --git a/skills/platform-linkedin/SKILL.md b/skills/platform-linkedin/SKILL.md index 58be634..17937a7 100644 --- a/skills/platform-linkedin/SKILL.md +++ b/skills/platform-linkedin/SKILL.md @@ -29,7 +29,7 @@ Use `create_campaign_plan` and `upsert_plan_entity` for the supported campaign s - Expect higher CPL than other platforms. Judge LinkedIn on pipeline quality and downstream conversion, not raw CPC. - Keep targeting to decision makers where the offer warrants it; do not spray a broad seniority range on an expensive platform. - Give campaigns room before judging; B2B conversion windows are long. Follow **pre-pause-analysis** before cutting. -- Conversion tracking (Insight Tag and offline/CRM conversions) must be attached before scaling: `get_pixel_health`, `ga4_get_conversions`. Measure with `get_attribution`. +- Conversion tracking (Insight Tag and offline/CRM conversions) must be attached before scaling: `get_pixel_health`. Measure with `get_attribution`. - Guard against a fat-finger daily budget 10 to 100x intended. Adjust with `update_campaign_budget`, pause with `pause_campaign`. - "Created" is not "live and spending." Confirm with `list_campaigns` and report the real IDs. Build an audience first with the **audience** skill when one does not exist yet. diff --git a/skills/platform-meta/SKILL.md b/skills/platform-meta/SKILL.md index 875fe1f..78a32c1 100644 --- a/skills/platform-meta/SKILL.md +++ b/skills/platform-meta/SKILL.md @@ -30,7 +30,7 @@ Use `create_campaign_plan` and `upsert_plan_entity` for the supported campaign s - **Learning Phase:** a new ad set needs enough conversions to exit learning. Do not judge or kill it early, and do not edit it constantly; each significant edit resets learning. See the **pre-pause-analysis** discipline before cutting anything. - **Creative fatigue:** rising frequency with falling CTR means the creative is spent. Watch it with the **creative-fatigue-detector** skill and rotate before performance collapses. - Keep audience overlap in check; ad sets competing against each other inflate CPM. -- Conversion tracking (pixel and CAPI) must be firing and attached: `get_pixel_health`, `ga4_get_conversions`. Blind spend is worse than no spend. +- Conversion tracking (pixel and CAPI) must be firing and attached: `get_pixel_health`. Blind spend is worse than no spend. - Guard against a fat-finger daily budget 10 to 100x intended. Adjust with `update_campaign_budget`, pause with `pause_campaign`. Start conservative; scale winners with the **optimize** skill. - "Created" is not "live and spending." Confirm with `list_campaigns` and report the real IDs. diff --git a/skills/platform-microsoft/SKILL.md b/skills/platform-microsoft/SKILL.md index 6de4bb1..bc13bea 100644 --- a/skills/platform-microsoft/SKILL.md +++ b/skills/platform-microsoft/SKILL.md @@ -36,7 +36,7 @@ Use `create_campaign_plan` and `upsert_plan_entity` for the supported campaign s - Enabling a campaign does not serve its ad groups if those stay paused. After enabling, re-pull and confirm the children actually serve; never trust the campaign status alone. - Carry negatives across, not just keywords. Keywords without negatives burn budget. - Verify geo/location criteria exist and match intent. -- Conversion tracking must exist and be attached before scaling: `ga4_get_conversions`, `get_pixel_health`. +- Conversion tracking must exist and be attached before scaling: `get_pixel_health`, `run_launch_preflight`. - Guard against a fat-finger daily budget 10 to 100x intended. Adjust with `update_campaign_budget`, pause with `pause_campaign`. - "Created" is not "live and spending." Confirm with `list_campaigns` and report the real IDs. diff --git a/skills/platform-openai/SKILL.md b/skills/platform-openai/SKILL.md index e760ff7..59f4443 100644 --- a/skills/platform-openai/SKILL.md +++ b/skills/platform-openai/SKILL.md @@ -23,7 +23,7 @@ A newer surface: ads that appear alongside AI answers. Structure is campaign → ## Plan and ship -- Build with `create_campaign_plan` + `upsert_plan_entity`; `forecast_campaign` where projections are available. Run **campaign-preflight**: tracking attached (`get_pixel_health` / `ga4_get_conversions`), sane budgets. +- Build with `create_campaign_plan` + `upsert_plan_entity`; `forecast_campaign` where projections are available. Run **campaign-preflight**: tracking attached (`get_pixel_health`), sane budgets. - Ship only on explicit approval: `execute_campaign_plan`, then `enable_campaign`. Nothing that spends money goes live without a clear go. - Confirm live with `list_campaigns(platform="openai_ads")` and report the real ID. Start conservative; read results before scaling with the **optimize** skill. diff --git a/skills/pre-pause-analysis/SKILL.md b/skills/pre-pause-analysis/SKILL.md index 7c3878c..713e44a 100644 --- a/skills/pre-pause-analysis/SKILL.md +++ b/skills/pre-pause-analysis/SKILL.md @@ -11,7 +11,7 @@ Confirm the account: `list_connected_accounts`. ## 1. Is the data even real -- Confirm conversion tracking is firing and attached to the right action (`ga4_get_conversions`, `get_pixel_health`). A campaign with broken tracking looks dead when it may be converting. See the **conversion-tracking** skill. +- Confirm conversion tracking is firing and attached to the right action (`get_pixel_health`). A campaign with broken tracking looks dead when it may be converting. See the **conversion-tracking** skill. - Check the destination: does the final URL resolve and match the ad's promise. A broken or mismatched landing page kills conversion rate independent of the campaign. ## 2. Has it had enough time and volume diff --git a/skills/quickstart/SKILL.md b/skills/quickstart/SKILL.md index 8659bfd..edccde4 100644 --- a/skills/quickstart/SKILL.md +++ b/skills/quickstart/SKILL.md @@ -7,9 +7,9 @@ description: Sign in through OAuth, confirm the workspace, and run a first repor 1. Call `get_connection_status`. Complete the client’s browser OAuth prompt if requested, then retry. If sign-in fails, reconnect from the client’s plugin settings. Never ask for credentials in chat. 2. Call `list_connected_accounts` and show the workspace, platform, account name, and account ID. If an account is missing, use the **connect** skill. -3. For connected GA4 accounts, use `ga4_get_properties`, then `ga4_get_report` with the selected property and requested period. Use the tool’s returned schema for parameters. +3. For connected ad accounts, use `list_campaigns`, then the matching performance tool (for example `pull_google_ads_performance`) for the requested period. Use the tool’s returned schema for parameters. 4. Offer a first task: a **report**, a **launch** plan, an **audience** review, or **ad-copy-generation**. Do not claim access to accounts or data that the tools did not return. -The plugin connects to the hosted Synter MCP server over OAuth. Cursor uses https://mcp.synterai.com; Claude uses https://mcp.synterai.com. Both require a client that supports remote MCP and browser OAuth. +The plugin connects to the hosted Synter MCP server over OAuth. Cursor uses https://mcp.synterai.com; Claude uses https://mcp.synterai.com/mcp. Both require a client that supports remote MCP and browser OAuth. Reads do not require approval. Show the exact scope and obtain explicit approval before account mutations or spend changes. More help: **help** or https://synterai.com/contact. diff --git a/skills/replicate/SKILL.md b/skills/replicate/SKILL.md index c132e07..166c2a5 100644 --- a/skills/replicate/SKILL.md +++ b/skills/replicate/SKILL.md @@ -47,7 +47,7 @@ Run the **campaign-preflight** checklist and report pass/fail: - Geo/location criteria copied and correct (a "US" name with no location criteria is the classic miss). - Negatives carried over — porting keywords without negatives burns budget fast. -- Check target-side evidence with `ga4_get_conversions` and `get_pixel_health`. Resolve missing tracking verification before launch. +- Check target-side evidence with `get_pixel_health`. Resolve missing tracking verification before launch. - Budget and bid caps sane — guard against a fat-finger daily budget 10–100x intended. - Match types preserved; final URLs resolve and match the ad's promise. diff --git a/skills/report/SKILL.md b/skills/report/SKILL.md index 12ef44b..37ff1e2 100644 --- a/skills/report/SKILL.md +++ b/skills/report/SKILL.md @@ -9,11 +9,11 @@ Pull every connected platform the tools support, reconcile, and tell the story s ## 1. Gather -Pull the period the user wants across all connected platforms using the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`). Add analytics ground truth: `ga4_get_report` for sessions/conversions, `get_attribution` for conversion paths. +Pull the period the user wants across all connected platforms using the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`). Add analytics context: `get_attribution` for conversion paths. ## 2. Reconcile -Use `get_spend_reconciliation` to compare spend records. Compare conversion counts separately with `ga4_get_report` and `get_attribution`, stating the attribution model and window. Flag deduplication uncertainty and access failures rather than treating them as verified tracking defects. +Use `get_spend_reconciliation` to compare spend records. Compare conversion counts separately with `get_attribution`, stating the attribution model and window. Flag deduplication uncertainty and access failures rather than treating them as verified tracking defects. ## 3. Tell the story diff --git a/skills/seasonal-budget-planner/SKILL.md b/skills/seasonal-budget-planner/SKILL.md index b243ad0..324c214 100644 --- a/skills/seasonal-budget-planner/SKILL.md +++ b/skills/seasonal-budget-planner/SKILL.md @@ -7,7 +7,7 @@ description: Plan ad budgets around seasonal peaks — holiday scaling, CPM infl Peak season punishes flat budgets twice: CPMs inflate 50-150% while unprepared accounts pay them with untested creative and cold audiences. Plan in phases, not in a panic the week before. -Ground the plan in your own history first: the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`) over last year's season and `ga4_get_report` with a date dimension to see your real demand curve. +Ground the plan in your own history first: the supported performance tools (`pull_google_ads_performance`, `pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_microsoft_ads_performance`, `pull_reddit_ads_performance`) over last year's season to see your real demand curve. ## 1. Plan in four phases diff --git a/skills/utm-builder/SKILL.md b/skills/utm-builder/SKILL.md index d01d37b..725e968 100644 --- a/skills/utm-builder/SKILL.md +++ b/skills/utm-builder/SKILL.md @@ -24,7 +24,7 @@ Clean UTMs are why analytics can tell platforms apart. Inconsistent tags turn re ## Wire it up -Apply the convention across the campaign's final URLs, and confirm the parameters survive to the landing page (redirects sometimes strip them). Check they resolve in analytics with `ga4_get_report` (source/medium) after traffic starts. Consistent UTMs make the **attribution** and **report** skills far more accurate. +Apply the convention across the campaign's final URLs, and confirm the parameters survive to the landing page (redirects sometimes strip them). After traffic starts, check that they resolve in analytics (source/medium) through `get_attribution` or a GA4 export the user provides. Consistent UTMs make the **attribution** and **report** skills far more accurate. ## Rules diff --git a/tools/directory-tools.json b/tools/directory-tools.json index d84d815..7ef94d9 100644 --- a/tools/directory-tools.json +++ b/tools/directory-tools.json @@ -8,9 +8,6 @@ "pull_linkedin_ads_performance", "pull_microsoft_ads_performance", "pull_reddit_ads_performance", - "ga4_get_properties", - "ga4_get_report", - "ga4_get_conversions", "get_attribution", "get_spend_reconciliation", "get_pixel_health",