RevenueScope: revenue-first analytics for your EC site MCP Server

Consolidated breakdown tool. Pick `dimension`: 'channel' returns per-channel sessions/revenue/RPS plus engagement (visitors, avg dwell seconds, bounce rate) and bot_excluded_count (bot sessions removed from human metrics; a channel with sessions=0 but bot_excluded_count>0 is bot-only traffic, kept so it is not mistaken for 'no traffic') and — when ad spend is connected (Path B) — spend/ROAS/saturation; plus an 'Unattributed' row (is_unattributed=true) for purchase revenue not tied to any channel, with a revenue_breakdown summary (total_event_jpy/attributed_jpy/unattributed_jpy); pass attribution_model ('last_touch' default / 'first_touch' / 'linear' / 'time_decay') to switch how purchase revenue is attributed across channels — same models as the dashboard's attribution selector; only revenue_jpy/rps_jpy change (sessions/engagement/bot/spend/ROAS are model-independent), so compare models to see e.g. how much an awareness channel gains under first_touch vs last_touch. pass filter.channel (e.g. 'google','meta','organic_search') to drill into that channel's campaigns (utm_campaign) with RPS/AOV/CVR. 'page' returns per-page pageviews/unique visitors/avg time/bounce ranked by pageviews (limit default 20, max 200; query strings stripped, bots excluded; each row also carries GSC Google-search impressions/clicks/ctr/avg_position merged by normalized path — null when the page has no GSC row, and a DIFFERENT denominator from pageviews, see notes). 'session_attribute' returns the device / time-of-day (4h JST) / day-of-week (ISO) / new-vs-returning (with AOV) / country (top-15 by sessions + 'Other', ISO2 code, share_pct; from first-party session geo, 'Unknown' when IP unresolved) breakdowns in one call. site_id is OPTIONAL when OAuth-authenticated. Default period is the last 30 days; pass period='today'/'7d'/'90d' or a raw day count (1-365). `filter` only applies to dimension='channel'; `limit` only applies to dimension='page'. Pass optional country (ISO2, e.g. 'JP') and/or device ('mobile'/'desktop'/'tablet') to scope session-derived metrics across any dimension (omit = all). Under such a filter, dimension='channel' keeps ad spend/ROAS site-wide (no country/device dimension) and omits the Unattributed row + revenue_breakdown (see notes); dimension='page' rows include pageviews_change (period-over-period % vs the previous equal-length window, null = new page).

Return the latest competitor SEO snapshot for the site (FD-041): which keywords each tracked competitor DOMAIN ranks for on Google (Japan/ja), at what position, with monthly search_volume, cpc and etv (estimated monthly traffic — a visit estimate, not a monetary value), plus how each rank moved vs the previous snapshot. READ-ONLY — this tool never runs a research (that costs money and is triggered separately from the dashboard, the competitor-research Edge Function); it only reads what was already fetched. The response is summary-first (token-aware): each domain carries a constant-size `summary` (total_keywords, total_etv, volume_bands and rank_bands histograms, and vs_previous new/lost/improved/declined/same counts) that always reflects the FULL keyword set, while `keywords` returns only the top rows ranked by `sort` (etv default | volume | rank; default limit 10 per domain, max 100) with a `truncated` block (shown/matching_total/lost_total). rank is a POSITION: smaller is better, so a NEGATIVE rank_delta means the competitor's ranking IMPROVED (change ∈ new/improved/declined/same/unknown). Keywords the competitor ranked for before but lost are disclosed in `lost_keywords` (top 10 by previous etv), never dropped silently. Pass `domain` to focus one competitor, `min_volume` to drop low-volume keywords. When the site has NO completed research yet the response is { researched:false } with a `guidance` string explaining a research must be triggered from the dashboard first — this tool cannot start one. site_id is OPTIONAL when OAuth-authenticated. This is the external competitor lens (third-party SERP data); for YOUR OWN search performance use get_keyword_performance, and for your content playbook use get_content_actions.

Return a content 'playbook' for the site: every content page classified into ONE of five action buckets over a weekly-style window comparison (current window vs the immediately preceding window of equal length), ranked by search-opportunity × session gain so you can tell the user which page to GROW next and what to do: within the 'striking' bucket rows are ordered by expected_sessions_gain DESC (the band-CTR headroom that is the actionable lever there), while the other buckets keep real landing revenue DESC (largest revenue at stake first). This surfaces search intent to add sessions (grow the traffic denominator), NOT CVR — a page already winning on sessions/revenue but with zero clicks still shows up. Buckets: 'decaying' (search clicks actually fell, OR the page had real traffic (previous clicks ≥3) and its rank slid ≥2 positions from within the click zone while clicks did NOT grow → refresh/rewrite; a rank slide alone with growing/negligible clicks is NOT decay — search clicks are the primary signal, position only a leading indicator), 'striking' (has striking-distance queries at positions 4-20 with click upside but clicks still low → push those queries up; top 3 listed in striking_queries), 'rising' (clicks grew significantly → produce more of this, strengthen CTA), 'dormant' (has impressions but ~0 clicks and its main query is far below the click zone → big rewrite or consolidate; zero-pageview pure-rank pages surface here), 'stable' (none of the above → watch). Each page also carries current/previous clicks·impressions·avg_position, is_new, landing sessions/engaged/revenue_jpy, AI-referred sessions/revenue/sources, expected_sessions_gain (the window's expected incremental sessions from striking-band queries — a search click is ~1 session, so it is NOT re-converted via CTR; normalize to a monthly figure with the window length), and expected_revenue_gain (expected_sessions_gain × page RPS, returned ONLY when revenue>0 and sessions>=5 — display-only projection, never a sort key). The deterministic action mapping and all (provisional) thresholds come back in `criteria`; the model does the narrative interpretation (mcp-first). Rows with confidence='low' carry `caveats` — 'geo_winning_suspect' (AI Overview/citations likely substitute the click: a GEO win, don't break the page; cross-check get_ai_traffic), 'zero_click_suspect' (SERP-feature occupation or intent-mismatch/polysemous query: verify the live SERP first), 'ai_cited' (decaying but the AI citation is alive) — verify before acting on low-confidence rows; definitions in criteria.caveat_flags. The response is summary-first (token-aware): `bucket_summary` always holds the FULL pre-limit distribution (per-bucket count/revenue/clicks) plus `total_pages`, while `pages` returns only the top rows in priority order (default limit 15, max 200); pass bucket='striking' etc. to drill into one bucket, and check `truncated` — when present it tells how many rows were cut and how to fetch them. GSC-driven and Google-search only; data lags 1-2 days so the current window's right edge sits a few days back. When narrating a bucket to the user, scope it to Google search — say 'search traffic to this page is declining', NOT 'this page is declining'; the classification is a search-trend diagnosis, not overall page health, so a page labeled 'decaying' can be thriving on Direct/social/AI. Before calling a negative bucket (decaying/dormant) a problem, cross-check the row's landing sessions/revenue_jpy and ai_sessions. site_id is OPTIONAL when OAuth-authenticated. Default window is the last 7 days vs the prior 7; pass period='30d'/'90d' or a raw day count (2-365). Window date bounds are INCLUSIVE on both ends, so period=Nd actually spans N+1 calendar dates (the real range is in `window`); both windows share the same length, so the comparison stays symmetric. This is the cross-page action snapshot; for one page's time series use get_page_trend, and for AI-citation gaps use get_ai_traffic(mode='gaps').

Return search-query performance from Google Search Console for the given period. band='all' (default) returns per-query metrics — clicks/impressions/CTR/avg position/top landing page plus an estimated revenue per query (= 検索 organic RPS × clicks, a conservative estimate, 0 until the site has 検索 organic revenue), ranked by clicks (default limit 100). Each row also carries the period-over-period change vs the previous equal-length window: clicks_change (traffic) and est_revenue_change (money), both % deltas (null = the query is NEW, i.e. had no clicks/revenue last period — render as '新規', not 0%). Comparing the two surfaces RS's signature insight — e.g. clicks +74% but est_revenue −21% means traffic grew while money fell, something GA4/GSC cannot show side by side. band='striking' returns the SEO action list: queries 'striking distance' from the top (ranking ~4-20 with real impressions) where improving a few positions yields the biggest click/revenue gain, ranked by estimated revenue opportunity (incremental clicks × search-organic RPS, default limit 10); the methodology is fixed in code. site_id is OPTIONAL when OAuth-authenticated. Default period is the last 30 days; pass period='today'/'7d'/'90d' or a raw day count (1-365). Google-search only.

Return how ONE page's Google Search performance changed over time (FD-040) — the time-axis drill-down for a page surfaced by get_breakdown(dimension='page'). Given a `page` (a normalized path like '/news/rps-revenue-per-session-guide' or a full URL — both resolve), returns a `series` of day or week buckets, each with clicks, impressions, and impression-weighted avg_position, plus a `summary` (first/last/best/worst position, position_delta, click & impression totals). avg_position is a RANK: smaller is better, so a NEGATIVE position_delta means the page's ranking IMPROVED over the window (e.g. 12.0 → 9.0 = delta −3.0). Use this to verify whether SEO work on a page paid off (rank rose / clicks grew) or slipped. Buckets where the page never appeared in search are omitted (gaps), so the series can be shorter than the period. `granularity` defaults to 'day' for windows up to ~35 days and 'week' for longer (weekly smooths daily noise); pass it to override. site_id is OPTIONAL when OAuth-authenticated. Default period is the last 30 days; pass period='today'/'7d'/'90d' or a raw day count (1-365). Google-search only; data lags 1-2 days. This is per-page; for the cross-page snapshot use get_breakdown(dimension='page'), and for per-query (keyword) trends use get_keyword_performance.

Return the top 3 prioritized, pre-computed DIAGNOSES for the site over the given period — 'what should I act on this week', ranked by revenue impact. Unlike get_site_summary / get_kpi_summary / get_channel_breakdown (which return data), this applies a deterministic rule engine over KPI period-over-period changes, per-channel RPS/ROAS/saturation, and AI-assistant referral growth, and returns ranked findings (revenue-trend swings, high-efficiency channels to scale, over-allocated low-efficiency channels, loss-making/saturated ad channels, revenue concentration risk, emerging AI traffic) — each with a severity (risk/opportunity/watch), the numbers, and a recommended action. The priority judgment is fixed in code (not LLM-generated). site_id is OPTIONAL when OAuth-authenticated. Default period is 30 days; pass period='today'/'7d'/'90d' or a raw day count (1-365). Returns fewer than 3 when fewer rules fire (no padding).

List the sites this caller can analyze, in two groups. my_sites = the sites connected to the signed-in account (each with its display name + domain, so you can match phrases like "the production site" or "revenuescope.jp" without the user pasting a UUID); empty when the caller is not signed in. demo_sites = ready-made sample sites for trying RevenueScope before connecting your own — each is a fictional site with sample data, not a real customer. When signed in (OAuth), prefer my_sites and, if site_id is omitted, default analytics tools to the is_primary=true site. When NOT signed in, my_sites is empty: use a demo_sites site_id and tell the user the numbers come from a sample site, not their own.

Return a proposed monthly budget split across paid ad channels (Google Ads / Meta / TikTok Ads / Yahoo! Ads / LINE Ads etc.). site_id is OPTIONAL when the request is OAuth-authenticated. Path B (ad spend connected — any channel with spend>0 in the period): weight = ROAS × (1 − saturation) where ROAS is RS-measured revenue ÷ spend (FD-030 A-1, same as the dashboard — NOT platform-reported conversion_value). saturation is not derived yet (W17+), so channels without it are weighted by ROAS alone with no efficiency cap — stated in limitations. Path A (no ad spend): RPS-weighted proportional split with explicit ±20-30% caveats and a connect_incentive_message. Default period for the underlying ROAS/RPS data is 30 days; pass period='today' / '7d' / '90d' or a raw day count (1-365) to override. LLMs should pass `assumptions`, `limitations`, and `connect_incentive_message` through verbatim — they are hardcoded honest axis.

Return the full headline summary for a site and period in ONE call: the 5 KPIs (revenue, sessions, RPS, AOV, CVR) PLUS two engagement KPIs (avg_duration = average dwell time in seconds, bounce_rate = % single-page-exit sessions) each with value AND the period-over-period change vs the previous equal-length window, PLUS a daily revenue/sessions/conversions trend, PLUS ad-spend availability (connected_channels, ad_spend_data_status, ad_spend_channels_in_period) and the Path A/B recommendation. avg_duration/bounce_rate are useful for sites with no revenue yet (engagement view). Pass optional country (ISO2, e.g. 'JP') and/or device ('mobile'/'desktop'/'tablet') to scope the session-derived KPIs and trend to that segment (omit = all); ROAS stays site-wide (ad spend has no country/device dimension). This is what the dashboard's KPI cards + revenue-trend chart show, merged with the site's ad-spend context. Call this first when a user asks 'how is my site doing?'. site_id is OPTIONAL when OAuth-authenticated (server falls back to the primary site). Default period is the last 30 days; pass period='today'/'7d'/'90d' or a raw day count (1-365). change is a percentage for revenue/sessions/RPS/AOV/avg_duration and an absolute percentage-point delta for CVR and bounce_rate. For period='today' the comparison is today-so-far vs the SAME elapsed window yesterday (e.g. midnight→now vs midnight→same-time-yesterday), so 'previous' can read below yesterday's full-day total — that is expected, not a discrepancy. ad_spend_data_status / ad_spend_channels_in_period reflect spend data ACTUALLY present in the period (consistent with get_channel_breakdown); path_recommendation reflects whether the requested period holds any channel with spend>0 (Path B = ad spend connected), the same definition the other tools use. kpis.roas is the SITE-WIDE ROAS (RS-measured revenue ÷ ad spend over channels that have spend — Σrevenue ÷ Σspend, the same definition as the dashboard's overall ROAS and FD-030 A-1; the spend-weighted aggregate of get_breakdown's per-channel ROAS) with value/previous/change (前期比 from a current + previous 2-window computation); it is null on Path A / when the period has no ad spend (ROAS is undefined with zero spend), so render it only when present. When the PREVIOUS window has no spend, roas.previous and roas.change are null (unknown baseline, not 0.00x) — treat that as 'no prior-period comparison', never as a drop from zero.

Return AI-assistant (ChatGPT/Claude/Perplexity/Gemini/Copilot) traffic for the given period. mode='referred' (default) lists landing pages that received clicked AI traffic — per page × AI source: sessions, bounce rate (%, always computed; judge reliability via the sessions count), summed revenue, and last citation date (default limit 100); a view GA4/GSC cannot produce (GSC is Google-search only; GA4 lacks an AI-source breakdown). mode='gaps' returns where the site leaves AI value on the table as a ranked action list: (1) missed_citation_pages — content articles with real audience but ~0 AI traffic (push for AI citation / GEO), ranked by engagement-weighted reach; (2) under_monetized_ai_pages — pages WITH AI traffic engaging below the site's own AI norm (improve landing/CTA), ranked by AI arrivals lost below benchmark (default limit 10/list); methodology fixed in code. site_id is OPTIONAL when OAuth-authenticated. Default period is the last 30 days; pass period='today'/'7d'/'90d' or a raw day count (1-365). Scope is clicked citations only.