Metadata-Version: 2.4
Name: scope-analytics-mcp
Version: 0.1.1
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. Optional; defaults to `https://api.scopeai.dev` (the Scope
  production backend). Override only for self-hosted / staging deployments.
- `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).

Published as **`scope-analytics-mcp`** on PyPI — `uvx` fetches + runs it on demand (no manual
install). It's a standard **stdio** server, so it drops into any MCP-capable coding agent;
`SCOPE_API_BASE` is optional (defaults to `https://api.scopeai.dev`).

### Claude Code (`.mcp.json` or `claude mcp add`)

```json
{
  "mcpServers": {
    "scope": {
      "command": "uvx",
      "args": ["scope-analytics-mcp"],
      "env": {
        "SCOPE_API_KEY": "sk_...",
        "SCOPE_API_BASE": "https://api.scopeai.dev"
      }
    }
  }
}
```

Or from the CLI: `claude mcp add scope --env SCOPE_API_KEY=sk_... -- uvx scope-analytics-mcp`

### Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`)

Identical stdio schema — drop the same `mcpServers` block into `~/.cursor/mcp.json` (global) or
`.cursor/mcp.json` (project). A one-click **Add to Cursor** deeplink is also available:

```
cursor://anysphere.cursor-deeplink/mcp/install?name=scope-analytics&config=<base64 of the inner server object — {command, args, env}, not the mcpServers wrapper>
```

### Codex CLI (`~/.codex/config.toml`)

```toml
[mcp_servers.scope]
command = "uvx"
args = ["scope-analytics-mcp"]
startup_timeout_sec = 30   # cushion for the first-run uvx fetch

[mcp_servers.scope.env]
SCOPE_API_KEY = "sk_..."
```

Or from the CLI: `codex mcp add scope --env SCOPE_API_KEY=sk_... -- uvx scope-analytics-mcp`

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