Scope Analytics

Ask the Scope analyst a natural-language question about this project's analytics. This is the headline tool: it runs Scope's full AI analyst over the project's data — events, LLM inputs/outputs (matched by meaning, not keywords), metrics, and prior investigations — and returns the analyst's reasoned answer, plus the written report when the question calls for one (a recap or digest of a period). Use it for open-ended "why / what / how" questions, e.g. "why did signups drop this week?", "what are users frustrated about?", "how is conversion trending?". (For raw event inspection use scope_query_events; for install coverage use scope_coverage_report.) This runs a real analysis server-side and can take up to a minute or two. It is READ-ONLY — it never changes the project's monitoring config or memory. Relay the answer to the user in your own words. Args: question: The natural-language analytics question to ask the analyst.

Check specific LLM SDK identifiers against Scope's auto-capture support — the deterministic per-item checker (read-only, LOCAL, no AI, no network). Enumerate the LLM SDK package names you see in the user's code — the exact dependency strings, e.g. openai, @anthropic-ai/sdk, cohere-ai, ai, google-genai — and pass them here. You get one verdict per identifier: auto-captured (zero-code) / not-auto-captured (with the manual path) / unrecognized. Matching is EXACT (no fuzzy or keyword matching), so pass the canonical package names as written in package.json / requirements; you, the agent, do the code→identifier reading, and this tool gives the authoritative verdict. Pass language ("python" or "node") whenever you know the project's runtime — omitting it returns verdicts for BOTH runtimes (e.g. bare "openai" reports Python and Node), which is noisier than needed for a single-language app. Companion to scope_supported_integrations (the full matrix): use the matrix to see everything; use this to check the specific packages you found. For a custom wrapper or dynamic provider selection a static check can't be sure about, install and then call scope_coverage_report (the live-data ground truth). Args: identifiers: Canonical LLM SDK package names found in the code, e.g. ["openai", "cohere-ai"]. language: Optional "python" or "node" to check only that runtime; omit to check both.

Report what Scope analytics is actually capturing for this project, and what's missing. Use this to answer "what does Scope cover for my app?" or after installing Scope to confirm the right layers are flowing. Returns an honest, tenant-scoped data-flow census: which event types and sources are arriving, whether events are quarantined (domain not allow-listed), identity stitching, deploy metadata, and plain-language notes on gaps. Then explain it to the user in your own words. It also lists any DOMAINS AWAITING APPROVAL — events from an unapproved domain are stored but not counted until the user approves it, a common reason a fresh install "looks broken." When that list is non-empty, help the user decide which domains are genuinely theirs and guide them to approve those in Scope. This tool only READS — approving a domain is a click the user makes in Scope's own UI; the MCP never changes settings itself (PRODUCT.md §16). Args: window_hours: Optional look-back window in hours (1–8760). If omitted, the backend uses its configured default window (currently ≈7 days).

Scan this codebase and report what Scope analytics would capture automatically — and what needs a manual step. Read-only and LOCAL (no network): reads dependency manifests (requirements.txt, pyproject.toml, package.json) and config files in the project root and its immediate subdirectories to detect the backend web framework, LLM SDKs, frontend framework, and deploy platform. Use this at install time to answer "what will Scope cover for my app?" from the CODEBASE (before events flow); pair it with scope_coverage_report, which answers the same from the live DATA once events arrive. Then tell the user, in your own words, what's covered and what isn't. Args: path: Project root to scan (defaults to the current directory).

Get one metric's full recipe — how the Scope analyst computed it last time (the events it selected, joins, window, attribution) plus its provenance and edit history. Read-only and deterministic (the exact recorded recipe, not a paraphrase). Use after scope_list_metrics to inspect exactly how a metric is defined — e.g. to reproduce it in your own code, or to check the analyst's methodology. Pass the exact metric name from scope_list_metrics. Args: name: The exact metric name (as shown by scope_list_metrics).

Reconstruct one session (or one user's activity) across the frontend, backend, and LLM layers, in time order. Read-only. Scope stitches events from all three layers by session, so this returns a single chronological timeline — page views, clicks, backend calls, and LLM calls interleaved — plus a small census (counts by type/source, time span). Use it to see exactly what a user did in a session, or to correlate a session with the code you're looking at. Provide session_id and/or user_id (a user_id also picks up events linked later by identity stitching). Args: session_id: The session to reconstruct (e.g. from scope_query_events output). user_id: A user whose events to gather (matches identity-stitched events too). limit: Max events to return, time-ascending (1–1000; default 200).

Get this project's headline analytics — total events, unique users, the per-type breakdown, and a day-by-day trend. Read-only, deterministic, and instant (no analysis run). This is the quick "what are the numbers?" tool: use it to size activity or eyeball a trend (growth, a drop-off, a spike) before deciding whether to dig in. Narrow it with a date range and/or a single event type. For the day-by-day counts of one metric over a window this is ideal; for raw rows use scope_query_events, for install/data-flow health use scope_coverage_report, and for an open-ended "why did it change?" hand off to scope_ask. Args: start_date: Optional inclusive start, ISO ("2026-05-01" or a full timestamp). Omit for all time. end_date: Optional inclusive end, ISO. Omit for "up to now". event_type: Optional filter to a single event type (e.g. page_view). Omit for all types.

Give the exact steps to install Scope's BACKEND SDK for this project's stack. Read-only and LOCAL (no network). Scans the codebase and returns the canonical backend install — for Python, the zero-code `scope-run` path plus the code-based middleware for the detected framework (FastAPI/Flask/Django); for Node, the zero-code `@scope-analytics/node` `--import` bootstrap. Honest about gaps: edge runtimes need the manual wrapper and background workers need scope-run too — it says so rather than emit a command that won't work. The secret key is always a placeholder (never echoed). Apply the steps with the user's confirmation (detect-and-confirm), then run scope_verify_installation. Args: path: Project root to scan (defaults to the current directory).

Give the exact steps to install Scope's FRONTEND SDK for this project's stack. Read-only and LOCAL except for one lookup (it fetches this project's public key to embed in the snippet). Scans the codebase to tailor the recommendation (build-time injection for apps with a build step; the one-line script tag for any HTML), and embeds the project's public key (pk_…, safe for client HTML) when available. Use at install time, then APPLY the steps for the user with their confirmation (detect-and-confirm), and run scope_verify_installation to confirm events flow. Args: path: Project root to scan (defaults to the current directory).

List this project's metric definitions — the analyst's recorded recipes for how it computed each metric before (names + one-line definitions). Read-only and instant (no analysis run). Scope's analyst keeps a registry of "how we computed this metric last time" so results stay consistent across questions. Use this to see which metrics exist before asking about them; call scope_get_metric for a metric's full recipe. (These are memory, not rules — the analyst can refine them.)

Query this project's raw analytics events (most recent first). Read-only. Use to inspect what's actually being captured — e.g. the last few LLM calls or page views. For open-ended "why/what" analysis, the Scope analyst (scope_ask) is better; this is the raw feed. Args: event_type: Optional filter by event type. Event-type names are app-specific — call scope_coverage_report first to see which ones this project actually has (e.g. page_view, api_call, llm_call). limit: Max events to return (1–1000; default 20). user_id: Optional filter to a single user's events.

List exactly which LLM SDKs/providers Scope auto-captures (zero-code), by language and canonical package name — the authoritative coverage matrix. Read-only, LOCAL, deterministic (no network, no AI). Use this to answer "does Scope automatically capture my LLM calls?" Enumerate the LLM SDK packages and method calls you see in the user's code, then match them against this list by EXACT package/ method name. Anything NOT listed as auto-captured is NOT auto-captured — Scope still captures everything else (frontend events, backend requests/errors), and an unlisted provider can be captured with a manual scope.track_event(...) call. This is the static source of truth; for a custom wrapper or dynamic provider selection a static check can't be sure about, install and then call scope_coverage_report, which reports from LIVE data which providers are actually arriving. Pair this with scope_detect_stack (which scans the codebase and tells you what was found); this tool tells you, authoritatively, what each of those findings means for coverage.

Quick check that Scope is receiving events from this project right now. Use right after installing Scope to confirm the pipe is live. Returns whether any events arrived in the recent window and how long ago the most recent event was. Args: window_minutes: Optional recent window in minutes (1–1440). If omitted, the backend uses its configured default window (currently ≈60 min).