feat: first-class Amazon Ads support (official Amazon Ads MCP integration)

[hyoshi]

Summary

Amazon Ads now ships an official, first-party MCP server (Amazon Ads MCP, open beta announced 2026-02-02, available worldwide, write-capable). Today mureo's workflow/value layer (skills, STRATEGY/STATE grounding, audit log, rollback, anomaly detection, scoring, BYOD) only covers Google Ads, Meta Ads, Search Console, GA4. Simply installing Amazon's MCP makes its tools available to the LLM but mureo does not orchestrate Amazon. This issue tracks adding first-class Amazon Ads support to mureo.

Current state / gap analysis (verified in code)

mureo has zero Amazon-specific code:

• mureo/adapters/ = google_ads, meta_ads only.
• Operational skills (daily-check, rescue, budget-rebalance, creative-refresh, search-term-cleanup, goal-review, weekly-report, sync-state, competitive-scan, onboard) iterate google_ads / meta_ads / search_console / ga4; Amazon is not a configured mureo platform → skills never include it.
• coexists_with_mureo_platform / MUREO_DISABLE_* wired for google_ads / meta_ads (+ SC / GA) only.
• mureo/byod/adapters/ = google_ads, meta_ads only.
• No amazon-ads-official entry in mureo/providers/catalog.py (catalog = google-ads-official, meta-ads-official, ga4-official).
• Skill provider-aware fallback text names only google-ads-official / meta-ads-official.

So this is a substantial feature, not a config/catalog add.

Official documentation findings (cite + confidence)

From the official Amazon Ads newsroom (https://advertising.amazon.com/library/news/amazon-ads-mcp-server-open-beta), 2026-02-02:

• Status: open beta, available worldwide. Write-capable (campaign create/update/delete, reporting, account settings, billing/financial, multi-step incl. cross-region).
• Auth: requires valid Amazon Ads API partner credentials (Login with Amazon / Amazon Ads API). Implies a pre-registered API client model — DCR support unconfirmed (likely the same "hosted OAuth needs a pre-registered client" pattern as Meta's hosted MCP; see the Meta-on-Claude-Code / Claude.ai-connector decision).
• Connection: MCP "translation layer" integrating with AI platforms.
• NOT yet verified (blocking): exact endpoint URL(s) + regional variants (NA/EU/FE), transport (streamable HTTP vs SSE), DCR vs pre-registered client, scopes, install/registration method, exact tool surface/count, rate limits, pricing/eligibility. The primary docs page https://advertising.amazon.com/API/docs/en-us/mcp/get-started is a JS-rendered shell and could not be machine-fetched.

Phase 0 — verify official docs (blocking, do FIRST)

Per maintainer instruction, development must be grounded in official Amazon docs. Before any code depends on endpoint/auth specifics, confirm against the official Amazon Ads MCP docs (browser/manual — auto-fetch blocked):

• Exact MCP endpoint(s) + regional routing (NA/EU/FE).
• Transport + auth (Login with Amazon scopes; DCR vs pre-registered client — decides whether mureo registers it like a user-scope server or steers users to a Claude.ai connector / manual client, exactly like the Meta decision).
• Registration/connect method + minimal config.
• Tool surface (Sponsored Products/Brands/Display/DSP/AMC), read/write scope, rate limits, eligibility, pricing.
• Whether it's a hosted endpoint (no local install) — install_kind = hosted_http.

Proposed phased plan (mirrors how Meta hosted was onboarded)

Phase 1 — providers catalog + auth guidance (smallest shippable)

• Add amazon-ads-official to mureo/providers/catalog.py (likely hosted_http), with notes reflecting verified Phase 0 facts.
• Wizard/CLI guidance for Amazon auth (Claude.ai connector or pre-registered client — per DCR finding; reuse the Meta connector.code.* pattern).
• Docs (README/getting-started/byod compat note), EN + JA.
• Provider-aware skill fallback text extended to name amazon-ads-official for the relevant skills.

Phase 2 — mureo orchestration of Amazon

• Add amazon_ads as a mureo platform: skill diagnostic loops include it; STRATEGY.md/STATE.json schema + onboarding cover Amazon; coexists_with_mureo_platform / MUREO_DISABLE_AMAZON_ADS wiring; native↔official dashboard toggle; audit log / rollback semantics for write-capable Amazon ops (safety-gating — Amazon MCP can mutate).
• Decide: thin "official-only" platform (no mureo-native Amazon client) vs full native adapter. Likely official-only first (no Amazon API client maintenance), like the design intent for hosted providers.

Phase 3 — optional

• BYOD adapter for Amazon (if a CSV/export path exists) — only if there is real demand; Amazon BYOD is out of scope unless an export format is defined.

Risks / open questions

• Open beta → endpoint/tool surface volatile; pin/verify, expect churn.
• Write-capable: mureo's safety model (strategy gating, BYOD read-only, rollback/audit) must explicitly cover Amazon mutations before exposing them, or scope Phase 1/2 to read/report only initially.
• Hosted + likely no DCR → same UX friction as Meta on Claude Code (Claude.ai connector path); confirm in Phase 0.
• "Amazon Ads partner credentials" eligibility may gate who can use it.

Acceptance criteria (Phase 1)

• Phase 0 official-doc facts confirmed and recorded.
• amazon-ads-official installable via mureo providers add / configure UI with correct auth guidance.
• Skills' provider-aware fallback documents Amazon equivalents where applicable.
• Docs (EN/JA) state Amazon support scope honestly (what works vs not).
• Tests + CI green; no regression to existing providers.

Note: development will consult the official Amazon Ads MCP documentation at each step (maintainer instruction). Confidence on non-newsroom specifics is currently LOW until Phase 0.

[hyoshi]

Phase 0 — official Amazon Ads MCP facts (verified)

Browser-verified against the official docs on 2026-05-18 (advertising.amazon.com/API/docs/en-us/mcp/get-started and /mcp-overview):

• Endpoints are region-specific (NOT region-agnostic):
  • NA: https://advertising-ai.amazon.com/mcp
  • EU: https://advertising-ai-eu.amazon.com/mcp
  • FE: https://advertising-ai-fe.amazon.com/mcp
• Transport: streamable HTTP (Accept: application/json, text/event-stream). Hosted — no local install.
• Auth (key finding — differs from Meta and GA4): NOT DCR, NOT a browser OAuth handshake, NOT a Claude.ai connector. The user pre-registers a Login-with-Amazon (LwA) app + Amazon Developer account with Amazon Ads API access, obtains access + refresh tokens themselves, and the credentials are sent as HTTP request headers: Authorization: Bearer Atza|<token> + Amazon-Ads-ClientId: <client_id>. The access token expires; a static config has no auto-refresh.
• Account context: Dynamic (the LLM is asked for account IDs each call; account_management-query_advertiser_account tool) vs Fixed (Amazon-Ads-AI-Account-Selection-Mode: FIXED + Amazon-Advertising-API-Scope / Amazon-Ads-AccountID / Amazon-Ads-Manager-AccountID).
• Write-capable. Tool namespaces e.g. campaign_management-*, account_management-*. disabledTools supported. Claude (Anthropic) is an officially listed client. Amazon also ships its own MCP "Skills" (prompt definitions).

Architectural decision — supersedes the "Phase 1 = catalog hosted_http" plan in the issue body

The original phased plan leaned toward registering Amazon's official hosted endpoint directly in the host MCP config (secret in ~/.claude.json headers, Claude connects straight to Amazon, mureo not in the request path). On reflection with the maintainer this is the wrong model for mureo: it is inconsistent with how mureo already serves Google/Meta and discards mureo's value.

How mureo-native Google/Meta actually work (the standard experience): Claude talks to the mureo MCP server; mureo reads ~/.mureo/credentials.json and calls the platform API; Claude never sees the platform secret; and every call flows through mureo's audit / strategy-gating / rollback layer.

Decision: Amazon will follow the same model — a mureo-mediated bridge ("B"):

Claude  →  local mureo MCP  →  Amazon hosted MCP endpoint

• Secret (LwA client id / access token / refresh token) is stored in ~/.mureo/credentials.json (the existing credential store, same as Google/Meta) — never written into the host MCP config, never seen by Claude.
• The host config only points Claude at the local mureo server (as it already does).
• mureo proxies/forwards MCP traffic to the region-appropriate Amazon endpoint, attaching the auth headers, and handles LwA access-token refresh from the stored refresh token.
• Because mureo is in the path, Amazon calls automatically inherit mureo's audit, throttle, strategy gating, and rollback safety layer (same guarantees the plugin safety layer (feat: apply mureo's safety layer (audit / strategy / rollback / throttle) to plugin tools (BYOD excluded) #114/feat(plugin): mureo safety layer for plugin tools — audit / throttle / action_log (#114) #116) provides for entry-point providers).

This is larger than a catalog entry — it makes Amazon a first-class mureo-mediated platform — but it is the only design consistent with mureo's architecture and the credential model users already expect.

Revised phased plan

• Phase 1 — credential capture + bridge skeleton: configure UI collects Amazon LwA client id / tokens / region / account-context mode into ~/.mureo/credentials.json (same UX class as the Google developer token / Meta access token). mureo exposes Amazon tools by bridging to the region endpoint over streamable HTTP, with LwA token refresh. Read paths first.
• Phase 2 — mureo orchestration: amazon_ads becomes a first-class platform in the workflow skills / STRATEGY.md / STATE.json; write operations gated + audited + promoted to action_log like built-ins.
• Phase 3 (optional): BYOD only if a real export format exists.

Confidence on non-newsroom specifics is now HIGH for the Phase-0 items above (browser-verified). Tool surface / rate limits / pricing / eligibility still to be confirmed during Phase 1.

[hyoshi]

Phase 1 — implemented (branch feat/amazon-ads-mcp-bridge-113)

Per the architecture decision above (mureo-mediated bridge, not
direct host-config registration), Phase 1 is built and TDD-covered.

What shipped

• mureo/auth.py — AmazonAdsCredentials + load_amazon_ads_credentials
  (amazon_ads section in ~/.mureo/credentials.json; region /
  account_mode normalized; credentials.json only, env fallback = Phase 2).
• mureo/amazon_ads/ — endpoints.py (region→URL NA/EU/FE; Dynamic vs
  Fixed headers; Fixed-without-id degrades to Dynamic so we never emit a
  config Amazon would reject), manifest.py (authenticated one-time
  discovery → ~/.mureo/amazon_tools.json; atomic 0600 write; no
  partial file on failure; secret-free manifest), bridge.py
  (AmazonAdsBridge: pure, never-raising mcp_tools() reading the
  manifest; handle_mcp_tool() opens an authenticated MCP session and
  forwards).
• mureo/mcp/server.py — the bridge is fed through the existing feat: apply mureo's safety layer (audit / strategy / rollback / throttle) to plugin tools (BYOD excluded) #114
  collect/dispatch path (synthetic ProviderEntry), so Amazon calls
  inherit audit / throttle / Phase 2-4 action_log promotion with
  zero dispatch changes. Manifest absent ⇒ no Amazon tools ⇒
  byte-identical prior behaviour (regression-safe).
• mureo amazon refresh-manifest CLI.
• Secret hygiene hardening: the plugin-audit error field and the CLI
  error echo now scrub Bearer / LwA (Atza| / Atzr|) token shapes
  (the Amazon bridge is the first credentialed plugin path).
• Docs: docs/amazon-ads.md + docs/amazon-ads.ja.md.

Design notes (as agreed)

• Tool names are Amazon's own (campaign_management-*,
  account_management-*) — no taxonomy remap, consistent with how
  mureo treats other official MCPs.
• Credentials live in ~/.mureo/credentials.json (same exposure class
  as the existing Google/Meta secrets); Claude never sees them.

Verification

• 38 new TDD tests; clean-env full suite green (3289 passed pre-hardening
  re-run); ruff/black/mypy clean on all changed source; existing
  plugin/server-wiring suites unaffected. code-reviewer: no
  CRITICAL/HIGH; MEDIUM (secret-shape scrub) addressed.

Phase 2 (next, separate)

• LwA access-token auto-refresh (refresh_token + client_secret are
  already captured).
• amazon_ads as a first-class platform in workflow skills /
  STRATEGY.md / STATE.json (deep per-platform analytics — hand-written,
  independent of naming).
• Optional: env-var credential fallback; dynamic manifest refresh UX.