Metadata-Version: 2.4
Name: scope-analytics-mcp
Version: 0.1.10
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<2,>=1.6
Requires-Dist: httpx<1,>=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 to **set up** a Scope project, **install** Scope analytics in it, and **query** it
afterward. Scope is the AI analyst for AI products; this is its programmatic surface. It needs **no
key** to start: the agent links it to a project, and the person approves that in their browser.

## Tools

### Set up a project (no key needed)

| Tool | What it does |
|---|---|
| `scope_link_project` | Connects the MCP to a Scope project without anyone copying a key. Scope opens in the person's browser; they sign in (or sign up), **type** the code the agent shows, pick the project or create one, and approve. |
| `scope_link_wait` | Waits for that approval. From then on every tool works for the project in this session. The approved link gets its own secret key, named after the agent and the computer and revocable in Scope's Setup → Keys. The key is never shown. |
| `scope_save_key` | After asking the person, saves the key as `SCOPE_API_KEY` in the app's env file, never one git would commit. This MCP reads it from there the next time it starts in that folder. The app's server needs it in its environment when it starts — make sure its start command loads that file, and in production set it in the host's settings. |
| `scope_propose_setup` | Sends what the agent learned from the repo — what the product does, the websites it runs on, the GitHub repository, the people who should get the analyst's reports — as **suggestions**. Nothing changes until the person accepts them in Scope. |
| `scope_setup_status` | The project's setup checklist: what's done and what waits for the person. |
| `scope_slack_connect_link` | A link the person opens to connect Slack, so the analyst can post there. |

### Install (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 — for Python the zero-code `scope-run` path plus the code-based middleware (FastAPI/Flask/Django); for Node the zero-code `@scope-analytics/node` `--import` bootstrap. Honest about what isn't covered (edge runtimes, an LLM SDK Scope doesn't patch). |
| `scope_supported_integrations` | The authoritative auto-capture matrix: which LLM SDKs and methods are captured zero-code, by language and exact package name, which known ones are not (with the one-line adjustment where the provider speaks the OpenAI protocol), and which frameworks are covered through the SDK they call. Local, deterministic, no AI. |
| `scope_check_integration` | Per-package verdicts for the identifiers your agent found in the code — ✅ auto-captured / ✗ not auto-captured (with the manual path) / ? not an LLM integration — by exact match. |
| `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 (no key needed)

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. Add it with
no key at all; the first time your agent uses it, it links the project with `scope_link_project` and
you approve that in your browser.

### Claude Code

```bash
claude mcp add scope -- uvx scope-analytics-mcp
```

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

```json
{
  "mcpServers": {
    "scope": {
      "command": "uvx",
      "args": ["scope-analytics-mcp"]
    }
  }
}
```

Or one click with **Add to Cursor** on your project's **Setup → Get started** page in Scope — or paste
this into your browser's address bar:

```
cursor://anysphere.cursor-deeplink/mcp/install?name=scope&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJzY29wZS1hbmFseXRpY3MtbWNwIl19
```

### 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
```

### Optional settings (`env`)

- `SCOPE_API_KEY` — a project's secret key (`sk_...`). **Optional.** Without it the MCP uses the key a
  link saved in `.env.local` or `.env` in the folder it runs in, and otherwise asks your agent to link
  the project. Set it only to pin one project, and keep it out of project files (`.mcp.json`,
  `.cursor/mcp.json`) that get committed: `claude mcp add scope --env SCOPE_API_KEY="$SCOPE_API_KEY" --
  uvx scope-analytics-mcp` stores it in `~/.claude.json` in your home folder, never your repo; in Cursor,
  reference it from your environment with `"env": { "SCOPE_API_KEY": "${env:SCOPE_API_KEY}" }`. The
  install tools read your **public** key from the API; you don't configure it.
- `SCOPE_API_BASE` — backend base URL. 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).

> **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:
- *"Set up Scope for this project."* (→ link → install → suggestions → status)
- *"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 — the MCP works on one project at a time, the one its key belongs to: the key linked in the
> folder it runs in, or `SCOPE_API_KEY`. Each project stays cleanly tenant-isolated by its own key.)
