scope-analytics-mcp 0.1.0__py3-none-any.whl

scope_analytics_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: scope-analytics-mcp
+Version: 0.1.0
+Summary: Scope MCP server — install + query tools for AI coding agents (the Scope analytics connector)
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.6
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+
+# Scope MCP server
+
+<!-- mcp-name: io.github.wally827/scope-analytics-mcp -->
+
+The unified Scope MCP server (PRODUCT.md §16) — one server an AI coding agent (Claude Code, Cursor,
+ChatGPT, …) uses both to **install** Scope analytics in a project and to **query** it afterward. Scope
+is the AI analyst for AI products; this is its programmatic surface.
+
+## Tools
+
+### Install / setup (run once, at install time)
+
+| Tool | What it does |
+|---|---|
+| `scope_detect_stack` | Scans the codebase (local, no key) and reports what Scope would auto-instrument for your stack — backend framework, LLM SDKs, frontend, deploy platform — plus honest non-coverage. |
+| `scope_install_frontend` | The exact frontend-SDK install steps tailored to your stack (build-time injection or the one-line script tag), with your project's **public** key embedded. |
+| `scope_install_backend` | The exact backend-SDK install steps for your stack — the zero-code `scope-run` path plus the code-based middleware (FastAPI/Flask/Django). Honest when a path isn't shipped yet (e.g. a Node backend). |
+| `scope_coverage_report` | Honest, tenant-scoped **data-flow** census: which event types/sources are flowing, quarantine state, identity stitching, deploy metadata, and notes on gaps. |
+| `scope_verify_installation` | Quick "are events flowing right now?" check, for right after install. |
+
+The install tools **propose** code changes; your agent shows them to you and applies them on your
+confirmation (detect-and-confirm). The Scope MCP never silently writes your files, and your **secret**
+key is never echoed into a snippet — only a placeholder.
+
+### Query (ongoing analysis)
+
+| Tool | What it does |
+|---|---|
+| `scope_ask` | Natural-language analytics question → the analyst's full reasoned answer (findings + recommendations). The catch-all; runs a real server-side agent loop (can take a minute). |
+| `scope_get_stats` | Headline counts — total events, unique users, the per-type breakdown, and a day-by-day trend — over an optional date range / event type. Instant and deterministic; the quick "what are the numbers?" before deciding whether to dig in. |
+| `scope_query_events` | The raw event feed (most recent first), optionally filtered by type/user. |
+| `scope_get_session` | One session's (or user's) events stitched across frontend + backend + LLM, in time order, with a small census. |
+| `scope_list_metrics` | The project's metric definitions — the analyst's recorded recipes ("how we computed it last time"). |
+| `scope_get_metric` | One metric's full recipe + provenance. |
+
+All query tools are **read-only** and tenant-scoped to your key's project. Use the deterministic
+primitives for instant lookups you compose yourself; use `scope_ask` for open-ended "why/what/how".
+
+## Configure (auth = your project SECRET key in the MCP config)
+
+`env` keys:
+- `SCOPE_API_KEY` — **required.** Your project's secret key (`sk_...`), from the Scope dashboard. (The
+  install tools also read your **public** key from the API; you don't configure it.)
+- `SCOPE_API_BASE` — backend base URL (default: the Scope backend).
+- `SCOPE_API_TIMEOUT` — request timeout seconds (default 90; the free-tier backend can cold-start, and
+  `scope_ask` runs a real agent loop, so its client floors the timeout at 180s).
+
+### Claude Code (`.mcp.json` or `claude mcp add`)
+
+Published as **`scope-analytics-mcp`** on PyPI — `uvx` fetches + runs it on demand (no manual install):
+
+```json
+{
+  "mcpServers": {
+    "scope": {
+      "command": "uvx",
+      "args": ["scope-analytics-mcp"],
+      "env": {
+        "SCOPE_API_KEY": "sk_...",
+        "SCOPE_API_BASE": "https://your-scope-backend"
+      }
+    }
+  }
+}
+```
+
+> **Running from a local checkout** (development): swap the command for your venv python and the import
+> name — `"command": "/path/to/mcp-server/venv/bin/python", "args": ["-m", "scope_mcp"]` (the import
+> package stays `scope_mcp`; the PyPI/`uvx` name is `scope-analytics-mcp`).
+
+Then ask your agent things like:
+- *"Use Scope to install analytics in this project."* (→ detect → install → verify)
+- *"What does Scope cover for my app?"* (→ coverage report)
+- *"Ask Scope why signups dropped this week."* (→ the analyst)
+- *"Show me what user `u_123` did in their last session."* (→ session)
+
+## Develop
+
+```bash
+python3.10 -m venv venv
+venv/bin/pip install -e ".[dev]"
+venv/bin/python -m pytest -q
+```
+
+> Not yet shipped (Track C): the sharing tools (`scope_list_reports`, `scope_get_report`, …) and
+> the cross-origin CORS opt-in action. (A multi-project `project_id` arg is intentionally *not*
+> planned — configure one MCP server per project so each is cleanly tenant-isolated by its own key.)

scope_analytics_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+scope_mcp/__init__.py,sha256=NWgUB8axTkLUz6BHtW8plxOwqsGiB2HA6WKUQFNuB1M,186
+scope_mcp/__main__.py,sha256=3dYKHfmWsrdExFlTFlcR5a_icR9fAkn06Yh14TQkEd8,33
+scope_mcp/client.py,sha256=R6U_ZMO2Xp-y5KBJ4E76bGJ56anaFFN0B32zpLg4Qdo,7456
+scope_mcp/config.py,sha256=q8BiZ_XRLILVUEtCKOuJVKnYx-0N7yHv51a9_ikLcsc,1816
+scope_mcp/detect.py,sha256=xvjQdnu5w2O5Mq7YidKG2R4EH051ujFJ31Ig579Lclc,19709
+scope_mcp/format.py,sha256=nkN2UNYRITllEzRVi2CvaqGjHvl_aedOnQqvQ82Jilw,36995
+scope_mcp/install.py,sha256=1LL3iwLXQmS8rREvR-SmcLnj0zWgzOCzJgXbDxY_phQ,13552
+scope_mcp/integrations.py,sha256=XbW8YHNAsvzhNjPiaHBR6dlk_ASf2dp2P0umTFnup84,16612
+scope_mcp/server.py,sha256=mZcJ8VCsoE5J_cIWpxpe4aoVEgQms4MrEBsQV2Jzm_E,20691
+scope_analytics_mcp-0.1.0.dist-info/METADATA,sha256=iH6q0jRRDnfTCqEPeajbHH_P5VykC4fxrMXFjVVAfwg,5119
+scope_analytics_mcp-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+scope_analytics_mcp-0.1.0.dist-info/entry_points.txt,sha256=ox9WSauoFkQvzrK8qwe-5H89qflccobyvOI97eKzUpI,62
+scope_analytics_mcp-0.1.0.dist-info/top_level.txt,sha256=He4HrDQkHx_NcH71gc-gOOTLb3KDYtqbdEwcp85QW1I,10
+scope_analytics_mcp-0.1.0.dist-info/RECORD,,

scope_analytics_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

scope_analytics_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scope-analytics-mcp = scope_mcp.server:main

scope_analytics_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+scope_mcp

scope_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Scope MCP server — install + (later) query + sharing tools for AI coding agents (PRODUCT.md §16)."""
+from .server import main, mcp
+
+__all__ = ["main", "mcp"]
+__version__ = "0.1.0"

scope_mcp/__main__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+main()

scope_mcp/client.py

@@ -0,0 +1,166 @@
+"""Thin async HTTP client around Scope's Developer API v1 (secret-key auth).
+
+The MCP tools call this; it owns auth, error translation, and nothing else. Kept separate from the
+server so it is trivially unit-testable with httpx's MockTransport (no network, no MCP runtime)."""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .config import ScopeConfig
+
+
+class ScopeApiError(Exception):
+    """A user-actionable failure talking to the Scope API (surfaced verbatim to the agent)."""
+
+
+# The analyst tool (scope_ask) runs a real server-side LLM agent loop — far slower than the census
+# endpoints. Give it a generous timeout floor (still overridable UPWARD via SCOPE_API_TIMEOUT).
+ASK_TIMEOUT_SECONDS = 180.0
+
+
+class ScopeApiClient:
+    def __init__(self, config: ScopeConfig, *, transport: Optional[httpx.AsyncBaseTransport] = None):
+        self._config = config
+        self._transport = transport  # tests inject httpx.MockTransport
+
+    def _require_api_key(self) -> None:
+        if not self._config.api_key:
+            raise ScopeApiError(
+                "SCOPE_API_KEY is not set. Add your project's secret key (sk_...) to the MCP server's "
+                "env config."
+            )
+
+    def _parse(self, r: httpx.Response) -> Dict[str, Any]:
+        """Shared response handling: secret-key/status translation + JSON parse. Used by every verb
+        so error messages stay identical across tools."""
+        if r.status_code == 401:
+            raise ScopeApiError(
+                "Authentication failed (401). SCOPE_API_KEY must be a valid project SECRET key (sk_...)."
+            )
+        if r.status_code == 403:
+            raise ScopeApiError(
+                "Forbidden (403). The Developer API needs a SECRET key (sk_...), not a public key (pk_...)."
+            )
+        if r.status_code >= 400:
+            detail = _safe_detail(r)
+            raise ScopeApiError(f"Scope API error {r.status_code}: {detail}")
+        try:
+            return r.json()
+        except ValueError:
+            raise ScopeApiError(f"Scope API returned a non-JSON response ({r.status_code}).")
+
+    async def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        self._require_api_key()
+        url = f"{self._config.api_base}{path}"
+        headers = {"Authorization": f"Bearer {self._config.api_key}"}
+        clean = {k: v for k, v in (params or {}).items() if v is not None}
+        try:
+            async with httpx.AsyncClient(timeout=self._config.timeout, transport=self._transport) as c:
+                r = await c.get(url, headers=headers, params=clean)
+        except httpx.TimeoutException:
+            raise ScopeApiError(
+                f"Scope API timed out after {self._config.timeout:.0f}s calling {path}. The backend "
+                "may be cold-starting (free tier) — try again."
+            )
+        except httpx.HTTPError as e:
+            raise ScopeApiError(f"Could not reach the Scope API at {self._config.api_base}: {e}")
+        return self._parse(r)
+
+    async def _post(
+        self, path: str, json_body: Dict[str, Any], *, timeout: Optional[float] = None
+    ) -> Dict[str, Any]:
+        self._require_api_key()
+        url = f"{self._config.api_base}{path}"
+        headers = {"Authorization": f"Bearer {self._config.api_key}"}
+        eff_timeout = timeout if timeout is not None else self._config.timeout
+        try:
+            async with httpx.AsyncClient(timeout=eff_timeout, transport=self._transport) as c:
+                r = await c.post(url, headers=headers, json=json_body)
+        except httpx.TimeoutException:
+            raise ScopeApiError(
+                f"Scope API timed out after {eff_timeout:.0f}s calling {path}. The analyst can take a "
+                "while on a complex question (and the free-tier backend may be cold-starting) — try "
+                "again, or raise SCOPE_API_TIMEOUT."
+            )
+        except httpx.HTTPError as e:
+            raise ScopeApiError(f"Could not reach the Scope API at {self._config.api_base}: {e}")
+        return self._parse(r)
+
+    async def coverage_report(self, *, window_hours: Optional[int] = None) -> Dict[str, Any]:
+        return await self._get("/api/v1/installation/coverage", {"window_hours": window_hours})
+
+    async def verify_installation(self, *, window_minutes: Optional[int] = None) -> Dict[str, Any]:
+        return await self._get("/api/v1/installation/verify", {"window_minutes": window_minutes})
+
+    async def query_events(
+        self,
+        *,
+        limit: Optional[int] = None,
+        event_type: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        return await self._get(
+            "/api/v1/analytics/events",
+            {"limit": limit, "event_type": event_type, "user_id": user_id},
+        )
+
+    async def ask(self, query: str) -> Dict[str, Any]:
+        """Ask the Scope analyst a natural-language question (POST /analytics/insights).
+
+        Runs the full agent server-side (a real LLM loop), so it's far slower than the census
+        endpoints — we give it a longer timeout floor (still overridable upward via SCOPE_API_TIMEOUT).
+        The endpoint runs the agent with user_present=False, so it is READ-ONLY (no durable writes)."""
+        timeout = max(self._config.timeout, ASK_TIMEOUT_SECONDS)
+        return await self._post("/api/v1/analytics/insights", {"query": query}, timeout=timeout)
+
+    async def get_session(
+        self,
+        *,
+        session_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Fetch one session's (or user's) events stitched across FE/BE/LLM, time-ascending."""
+        return await self._get(
+            "/api/v1/analytics/sessions",
+            {"session_id": session_id, "user_id": user_id, "limit": limit},
+        )
+
+    async def list_metrics(self) -> Dict[str, Any]:
+        """List the project's Metric Registry entries (names + one-line definitions)."""
+        return await self._get("/api/v1/analytics/metrics")
+
+    async def get_metric(self, name: str) -> Dict[str, Any]:
+        """Fetch one metric's full recipe + provenance by exact name."""
+        return await self._get("/api/v1/analytics/metrics/detail", {"name": name})
+
+    async def get_stats(
+        self,
+        *,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        event_type: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Fetch headline analytics counts + a daily trend (GET /analytics/stats). Dates are ISO
+        strings (e.g. "2026-05-01" or a full timestamp); the backend parses them."""
+        return await self._get(
+            "/api/v1/analytics/stats",
+            {"start_date": start_date, "end_date": end_date, "event_type": event_type},
+        )
+
+    async def get_project(self) -> Dict[str, Any]:
+        """Fetch the authenticated project (incl. its public key; the secret is never returned).
+        Used by scope_install_frontend to embed the project's pk_ in the install snippet."""
+        return await self._get("/api/v1/projects/current")
+
+
+def _safe_detail(r: httpx.Response) -> str:
+    try:
+        body = r.json()
+        if isinstance(body, dict):
+            return str(body.get("error") or body.get("detail") or body)[:300]
+    except ValueError:
+        pass
+    return r.text[:300]

scope_mcp/config.py

@@ -0,0 +1,41 @@
+"""Configuration for the Scope MCP server (PRODUCT.md §16 auth model: API key in MCP config)."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+# v1 default points at the verified staging backend (where the Coverage Report endpoints are live).
+# Production users override via SCOPE_API_BASE. (Pre-launch: there is no canonical prod host yet.)
+DEFAULT_API_BASE = "https://scopeai-backend-staging.onrender.com"
+
+
+@dataclass
+class ScopeConfig:
+    """Resolved from the MCP client's env block (the `env` map in the MCP config)."""
+    api_key: str
+    api_base: str
+    timeout: float
+    # Optional Scope DASHBOARD (frontend) base URL, e.g. https://app.scope.example. When set, the
+    # coverage tool can hand the user a clickable deep-link to approve pending domains (PRODUCT.md
+    # §16 — the MCP proposes; the user confirms in Scope's own UI). Optional because there is no
+    # canonical pre-launch dashboard host; when unset we fall back to an in-words instruction.
+    dashboard_url: Optional[str] = None
+
+    @classmethod
+    def from_env(cls) -> "ScopeConfig":
+        return cls(
+            api_key=os.getenv("SCOPE_API_KEY", "").strip(),
+            api_base=os.getenv("SCOPE_API_BASE", DEFAULT_API_BASE).strip().rstrip("/"),
+            timeout=_float_env("SCOPE_API_TIMEOUT", 90.0),
+            dashboard_url=(os.getenv("SCOPE_DASHBOARD_URL", "").strip().rstrip("/") or None),
+        )
+
+
+def _float_env(name: str, default: float) -> float:
+    """Parse a float env var, falling back to default on a missing/garbage value (never crash at
+    import — a bad SCOPE_API_TIMEOUT shouldn't take the whole MCP server down)."""
+    try:
+        return float(os.getenv(name, default))
+    except (TypeError, ValueError):
+        return default