io.github.toshihiroshishido/revenuescope-mcp

list_sites

Return the sites available to this caller: my_sites (the authenticated user's own sites with display name + domain, so the assistant can match references like "the production site" or "revenuescope.jp" without the user copying a UUID) AND demo_sites (operator-provided showcase sites for exploring RevenueScope without connecting your own). When OAuth-authenticated, prefer my_sites and default analytics tools to the is_primary=true site when site_id is omitted. When NOT authenticated, my_sites is empty and you should use a demo_sites site_id (tell the user you are analyzing a sample/example site, not their own).

No parameters.

get_summary

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 is a separate last-7d recency signal and may read 'A' even when the period holds spend data. kpis.roas is the SITE-WIDE ROAS (total ad conversion value ÷ total ad spend over the period — same definition as get_breakdown's per-channel ROAS, the spend-weighted aggregate) with value/previous/change; 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.

get_breakdown

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). '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).

get_keyword_performance

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.

get_ai_traffic

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.

get_priority_insights

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).

suggest_budget_allocation

Return a proposed monthly budget split across paid channels (meta/google/tiktok). site_id is OPTIONAL when the request is OAuth-authenticated. Path B (ad spend connected): precise weight = ROAS × (1 − saturation) with expected ROAS uplift. 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.