Metadata-Version: 2.4
Name: measure-sdk
Version: 0.2.0
Summary: The shared core of the Measure MCP ecosystem: domain models, enums, Health Score, OAuth/auth, config, logging, Google clients, permissions, cost control, MCP utilities, adapters and the `measure` CLI.
Project-URL: Homepage, https://github.com/measure-mcp/measure-sdk
Project-URL: Repository, https://github.com/measure-mcp/measure-sdk
Project-URL: Issues, https://github.com/measure-mcp/measure-sdk/issues
Author: Measure MCP contributors
License: Apache-2.0
License-File: LICENSE
Keywords: bigquery,ga4,google-marketing-platform,mcp,measureops,model-context-protocol
Requires-Python: >=3.12
Requires-Dist: google-auth-oauthlib>=1.2.0
Requires-Dist: google-auth>=2.34.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic-settings>=2.4.0
Requires-Dist: pydantic>=2.8.0
Provides-Extra: bigquery
Requires-Dist: google-cloud-bigquery>=3.25.0; extra == 'bigquery'
Provides-Extra: dev
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Requires-Dist: types-requests; extra == 'dev'
Provides-Extra: ga4
Requires-Dist: google-analytics-admin>=0.22.0; extra == 'ga4'
Requires-Dist: google-analytics-data>=0.18.0; extra == 'ga4'
Provides-Extra: gtm
Requires-Dist: google-api-python-client>=2.100.0; extra == 'gtm'
Description-Content-Type: text/markdown

# measure-sdk

**The single shared library of the Measure MCP ecosystem.**

Every Measure MCP product (`measure-analytics-mcp`, `measure-paid-media-mcp`, …)
depends on this package and *only* this package. It carries the common domain
model and infrastructure so the products never duplicate either.

```python
from measure_sdk import AuditFinding, Report, HealthScore, CostEstimate, Severity
from measure_sdk.infra import PermissionPolicy, get_logger
from measure_sdk.mcp import build_server, ServerContext, tool_errors
```

## Two layers

### `measure_sdk.domain` — shared domain model

Canonical, reusable models and enums every MCP consumes instead of redefining:

| Group | Symbols |
| --- | --- |
| Findings & reports | `AuditFinding` (alias `Finding`), `Issue`, `Recommendation`, `Report` (alias `AuditReport`) |
| Health | `HealthScore`, `HealthCheck`, `Grade`, `compute_health_score`, `score_from_findings`, `grade_for` |
| Cost & validation | `CostEstimate`, `ValidationResult` |
| Alerts | `Alert`, `AlertType`, `Comparator`, `Channel`, `ChannelType`, `Condition` |
| Execution | `ExecutionPlan`, `PlannedChange`, `ChangeAction` |
| Resources | `Connection`, `Entity`, `Metric`, `PlatformResource` |
| Enums | `Severity`, `Priority`, `Category` |

The **Health Score** is a standard 0-100 measure (`from_checks` weighted average
or `from_findings` penalty model) so platform health is comparable across MCPs.

### `measure_sdk.infra` — shared infrastructure

| Module | Responsibility |
| --- | --- |
| `infra.config` | Typed settings from env / `.env` (Pydantic Settings). |
| `infra.logging` | Structured logging (console or JSON). |
| `infra.errors` | Exception hierarchy mapped to MCP tool errors. |
| `infra.auth` | OAuth-first credential resolution (ADC / service account / OAuth) + scopes, session, discovery. |
| `infra.permissions` | Read-only-by-default policy and write-confirmation gating. |
| `infra.cost_control` | Reusable cost-guardrail policy and byte humaniser. |
| `infra.audit` | Append-only audit log of every privileged action. |
| `infra.google` | Lazily-constructed, cached Google API clients. |

Plus `measure_sdk.mcp` (`build_server`, `ServerContext`, `tool_errors`, and the
shared auth tools `measure_login` / `auth_status` / `auth_doctor` every server
inherits), `measure_sdk.adapters` (OpenAI / Gemini ↔ MCP translation) and
`measure_sdk.cli` (the `measure login` / `measure doctor` command).

Nothing here ever persists credentials — secrets are resolved at runtime and held
only in memory.

## Authentication

Users sign in with their own Google account via the installed-app OAuth flow —
from inside the assistant (`measure_login`) or the CLI (`measure login`). See
**[docs/authentication.md](docs/authentication.md)** for the full setup
(create the OAuth client, consent screen, test users, scaling).
