roasr-hermes

RoASr in Hermes — ad audit, competitor spy & Vision creative analysis

RoASr connects to a user's Meta, Google Ads and Yandex Direct data and returns an A–F account audit with findings ranked by money at stake, plus competitor intelligence from the Meta Ad Library and Vision analysis of creatives. This skill drives RoASr from Hermes through RoASr's remote MCP endpoint. Access is scoped to the user's own workspace; isolation and scopes are enforced API-side. Everything is read-only except one campaign pause/resume tool, which only works inside permissions the owner granted explicitly.

Setup (do this first — and tell the user if they haven't)

RoASr is a hosted service. Hermes cannot use it without the user's own account and API key.

1. Sign up or log in at https://roasr.com — it's free.
2. Go to Settings → API keys and create a key pg_live_… (owner/admin) with the scopes you need. The token is shown once — copy it.
3. Add RoASr as a remote MCP connector in Hermes. In Hermes' MCP / connectors / integrations settings, add a new MCP server of type HTTP (remote / streamable):

   Name:  roasr
   URL:   https://roasr.com/api/mcp
   Auth:  Bearer pg_live_…        (Authorization header)
   

   No install is needed — Hermes talks to the hosted endpoint directly.
4. Reload connectors and confirm the roasr_* tools appear.

If no API key is set, or a tool returns an auth error (auth.invalid_api_key / 401): tell the user to sign up free at https://roasr.com, open Settings → API keys, create a key, and paste it as the connector's Bearer token. Do not retry tools until a valid key is configured.

Tools (and required scope)

• roasr_list_findings — AI audit findings ranked by priority (severity high/med/low); optional clientId. scope findings:read
• roasr_metrics_summary — KPI summary (spend, impressions, clicks, conversions, revenue, CTR/CPC/CPM/ROAS/CPA, reach, frequency). Optional entityRef (campaign:<id> | adset:<id>) scopes to one entity. scope metrics:read
• roasr_metrics_daily — daily time series of the same metrics, for trends/charts. Optional entityRef. scope metrics:read
• roasr_metrics_breakdown — metrics segmented by dimension (audience/placement/platform/country/region/device/dma/hourly), required dimension, optional limit. scope metrics:read
• roasr_metrics_campaigns — per-campaign/adset metrics and KPIs sorted by spend; optional level (campaign/adset), limit. scope metrics:read
• roasr_metrics_actions — conversion breakdown by action type: actions (raw action-type → sum) + buckets (canonical: purchase, lead, add_to_cart, complete_registration, landing_page_view, engagement…; buckets aren't additive). scope metrics:read
• roasr_list_clients — workspace clients with context (name, niche, margin, status). scope clients:read
• roasr_spy_tag_leaderboard — competitor creative tag leaderboard; optional limit (1–100, default 20). days_live ≈ winning-ad proxy. scope spy:read
• roasr_spy_search — search stored competitor creatives by query (keyword/hook/title/tag) and/or brand (page name); optional limit. Returns hook, title, format, tags, country and adArchiveId. scope spy:read
• roasr_vision_analyze — Vision breakdown of one creative by adArchiveId (hook, angle, format, strengths, risks + video transcription). scope spy:read
• roasr_signals — rich platform signals by required kind (16: Google/Meta search terms, keyword quality score, impression share, auction insights, conversion actions, asset performance, landing pages, shopping, video funnel, bidding, asset groups, Meta ad quality, plus the four Direct kinds). Optional limit. scope metrics:read
• roasr_yandex_goals — which Yandex.Metrika goals the account's conversions are counted against. No date window — current config. Empty goals means the conversion numbers cannot be attributed and must not be presented as a clean CPA. scope metrics:read
• roasr_yandex_search_queries — Direct search queries for a window (text, campaign/ad group, match type, impressions, clicks, spend, conversions). The most valuable Direct signal: use it to size the share of spend on queries with zero conversions. scope metrics:read
• roasr_yandex_ads — Direct ads with moderation state and metrics: state/status/statusClarification, second headline, sitelinks, UTM markup, image, turbo page. Finds rejected and half-built ads. scope metrics:read
• roasr_yandex_breakdown — one Direct call by dimension: search_queries | keywords | ads | bidding. scope metrics:read
• roasr_limits — remaining daily Yandex API unit quota and plan limits. Direct meters per login and its Reports endpoint hides its own consumption, so check this before a heavy pull. scope metrics:read
• roasr_campaign_set_state — the one write tool: pauses/resumes a live Direct campaign, only within permissions the owner granted for that key. Confirm with the human first; on a timeout retry with the same idempotencyKey, never a fresh one. scope campaigns:write
• roasr_command_get — resolve a write command left in verifying/unknown by its id. scope campaigns:read