Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .mcp.json
Original file line number Diff line number Diff line change
Expand Up @@ -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."
}
}
Expand Down
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion agents/media-buyer.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion agents/performance-analyst.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 1 addition & 1 deletion packages/claude-directory/.mcp.json
Original file line number Diff line number Diff line change
Expand Up @@ -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."
}
}
Expand Down
2 changes: 1 addition & 1 deletion packages/claude-directory/agents/media-buyer.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion packages/claude-directory/agents/performance-analyst.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 1 addition & 1 deletion packages/claude-directory/skills/attribution/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion packages/claude-directory/skills/connect/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Loading
Loading