Metadata-Version: 2.4
Name: measure-tracking-qa-mcp
Version: 0.6.1
Summary: AI-powered implementation guides, dataLayer QA and tracking documentation over the Model Context Protocol.
Project-URL: Homepage, https://github.com/measure-mcp/measure-tracking-qa-mcp
Project-URL: Repository, https://github.com/measure-mcp/measure-tracking-qa-mcp
Author: Measure AI contributors
License: Apache-2.0
License-File: LICENSE
Keywords: analytics,datalayer,ga4,gtm,mcp,model-context-protocol,qa,tracking
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: measure-sdk<0.2,>=0.1.1
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'
Provides-Extra: pdf
Requires-Dist: pypdf>=4.0; extra == 'pdf'
Provides-Extra: sheets
Requires-Dist: google-api-python-client>=2.100.0; extra == 'sheets'
Provides-Extra: web
Requires-Dist: playwright>=1.45; extra == 'web'
Description-Content-Type: text/markdown

<div align="center">

# 🧪 Measure Tracking QA MCP

**AI-powered implementation guides, dataLayer QA and tracking documentation —
over the [Model Context Protocol](https://modelcontextprotocol.io).**

Read a tracking guide, audit a site's `dataLayer` against it, validate GA4
collection, score coverage and prepare a GTM plan — in natural language, from
Claude, ChatGPT, Codex, Gemini or any MCP client.

A product of the [Measure AI ecosystem](https://github.com/measure-mcp) ·
built on **[measure-sdk](https://github.com/measure-mcp/measure-sdk)**.

[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](pyproject.toml)
[![SDK](https://img.shields.io/badge/measure--sdk-%3E%3D0.1.1%2C%3C0.2-blue.svg)](https://github.com/measure-mcp/measure-sdk)

</div>

---

## What is Measure Tracking QA MCP?

Measurement is a hand-off chain: analytics writes a guide → developers implement
the `dataLayer` → analytics validates it → GTM sends events → GA4 collects them →
someone audits quality and documents the gaps. **This MCP automates and assists
that whole flow.** It reads your implementation guide, opens the real site,
compares what fires against what was specified, and produces a QA report, a
developer checklist, a stakeholder summary and a **Tracking Coverage Score**.

```text
"Read this tracking guide and validate if it is complete."
"Audit this website dataLayer against this Google Sheets guide."
"Find missing events in the checkout flow."
"Validate if add_to_cart includes all required ecommerce parameters."
"Compare dataLayer events vs GA4 network hits."
"Generate a QA report for development."
"Generate a GTM implementation plan from this tracking guide."
"Calculate the Tracking Coverage Score."
```

### Try it instantly (demo mode)

No site or sheet yet? Every tool works against realistic sample data:

```bash
MEASURE_TQA_DEMO=true measure-tracking-qa
```

## Relationship to Measure SDK

Like every Measure product, this depends on **only** `measure-sdk` — never on
other MCPs (if Analytics/Paid-Media MCPs are also connected, the model composes
them client-side; they never call each other).

| Provided by **measure-sdk** | Provided by **this repo** |
| --- | --- |
| OAuth, sessions, credential storage | Connectors: Google Sheets, Web QA (Playwright) |
| Config, logging, HTTP, retry | Guide / dataLayer / GA4 / GTM-plan / coverage engines |
| MCP utilities, base CLI (`measure login`) | MCP server + tracking tools + Tracking Coverage Score |
| Shared domain models & enums | Tracking models (`TrackingSpec`, `DataLayerEvent`, `Ga4Hit`) |

Result types — `AuditFinding`, `Report`, `HealthScore`, `Recommendation`,
`ExecutionPlan`, `ValidationResult` — come from the SDK and are never redefined.

## Install

```bash
pip install measure-tracking-qa-mcp          # pulls measure-sdk automatically
pip install "measure-tracking-qa-mcp[web]"   # + Playwright for live dataLayer QA
playwright install chromium                  # one-time browser download (web extra)
measure login                                # Google OAuth (Sheets, GTM, GA4)
measure-tracking-qa                          # start the MCP server (stdio)
```

## MCP tools (49)

| Group | Tools |
| --- | --- |
| **Discovery** | `list_tracking_connectors` |
| **Guide Intelligence** | `read_tracking_guide`, `validate_tracking_guide`, `normalize_tracking_spec`, `export_tracking_spec`, `create_tracking_guide_sheet` |
| **DataLayer QA** | `capture_datalayer_events`, `validate_datalayer_against_spec`, `find_missing_events`, `find_missing_parameters`, `find_invalid_parameter_types`, `find_unexpected_events` |
| **Web QA** | `start_web_qa_session`, `run_tracking_qa_flow`, `validate_checkout_tracking`, `validate_form_tracking`, `capture_ga4_network_hits`, `run_journey_qa`, `validate_ecommerce_journey` |
| **Reporting** | `generate_qa_report`, `generate_developer_checklist`, `generate_stakeholder_summary`, `generate_tracking_coverage_score` |
| **Documentation** | `create_qa_report_doc`, `create_tracking_guide_doc`, `create_tracking_summary_slides`, `export_implementation_spec` |
| **Design Intelligence** | `analyze_pdf_requirements`, `generate_tracking_spec_from_reference`, `analyze_figma_file`, `extract_user_actions_from_figma`, `generate_tracking_spec_from_design`, `generate_event_taxonomy` |
| **GA4 Validation** | `validate_ga4_requests`, `compare_spec_vs_ga4_hits`, `validate_ecommerce_items`, `suggest_custom_dimensions`, `generate_ga4_collection_report` |
| **GTM Planning** | `generate_gtm_implementation_plan`, `preview_gtm_changes`, `export_gtm_change_plan`, `generate_gtm_variables_plan`, `generate_gtm_triggers_plan`, `generate_gtm_tags_plan`, `validate_gtm_workspace`, `create_gtm_workspace_draft` |
| **Recommendations** | `generate_tracking_recommendations`, `prioritize_tracking_actions` |
| **Alerts** | `run_tracking_alert_now` |

Tools accept a guide three ways: an inline `spec` (JSON), a Google Sheet (`sheet_id`
or `MEASURE_TQA_DEFAULT_SHEET_ID`), or demo mode. dataLayer events come from a live
`url` (Playwright), an inline `events` list, or demo.

## Tracking Coverage Score

A standard **0-100** score (SDK `HealthScore`) weighting **Guide completeness 20%**,
**DataLayer compliance 30%**, **GA4 collection accuracy 20%**, **GTM implementation
quality 20%**, **Documentation quality 10%** — comparable across the ecosystem.

## What it validates

- **Event-level**: event exists, fires once, snake_case naming, documented trigger.
- **Parameter-level**: required present, correct type, non-empty, allowed enum values.
- **Ecommerce-level**: `items` array, `item_id`/`item_name`, `transaction_id` on
  purchase, duplicate-purchase detection (dataLayer **and** GA4 hits).
- **Collection**: dataLayer event → GA4 `/collect` hit (parsed from the network),
  spec → GA4 collection, dataLayer vs GA4 parity, GA4 property collected events.
- **Journey-level**: checkout-funnel event order across a multi-step journey.

## Supported sources

| Phase | Sources |
| --- | --- |
| **v0.1 (Guide + DataLayer QA)** | **Google Sheets** (guide matrix) ✅ · **Web QA / Playwright** (dataLayer + GA4 hits) ✅ · inline JSON specs ✅ |
| **v0.2 (Documentation)** | **Google Docs** ✅ · **Google Slides** ✅ · **Google Drive** ✅ |
| **v0.3 (Design Intelligence)** | **PDF** (pypdf) ✅ · **Figma** (API) ✅ → proposed specs |
| **v0.4 (GTM Planning)** | **Google Tag Manager** ✅ (read container, workspace draft + dry-run) |
| **v0.5 (GA4 Validation)** | **GA4 Admin** ✅ (custom dimensions) · **GA4 Data** ✅ (collected events) |
| **v0.6 (Journey QA)** | Multi-step journey + ecommerce funnel QA ✅ · AppTweak-style recorders 🛣️ |

## Architecture (Clean Architecture)

```text
src/measure_tracking_qa/
├── core/          # domain: TrackingSpec, EventSpec, DataLayerEvent, Ga4Hit, enums
├── config/        # settings (extends SDK CoreSettings; optional, non-secret)
├── connectors/    # infrastructure: google_sheets, web (Playwright), google_docs,
│                  #   google_slides, google_drive, gtm, ga4, figma, pdf
├── engines/       # application (pure): guides, datalayer, ga4_validation,
│                  #   gtm_planning, documentation, design, recommendations,
│                  #   alerts, health_score, web_qa
├── services/      # orchestration (connectors → engines)
├── validators/    # input validation → SDK ValidationResult
├── mcp/           # interface: server.py + tools/
└── cli/           # the measure-tracking-qa entry point
```

See [`docs/architecture/overview.md`](docs/architecture/overview.md).

## Security & disclaimer

This MCP is **read-only by default**: it reads, audits, recommends and documents.
Write actions are gated: writing a guide to a Sheet requires `confirm=true`, and
**it never publishes to GTM** — `generate_gtm_implementation_plan` only ever
returns a proposed `ExecutionPlan` for you to apply manually. Any future write
action follows **preview → dry-run → confirmation → audit**. See [SECURITY.md](SECURITY.md).

## Develop

```bash
git clone https://github.com/measure-mcp/measure-tracking-qa-mcp.git
cd measure-tracking-qa-mcp
uv sync --all-extras
uv run ruff check . && uv run mypy . && uv run pytest
```

## Ecosystem

| | |
| --- | --- |
| **measure-sdk** | Shared core: domain models, enums, Health Score, infra. |
| **measure-analytics-mcp** | GA4, GTM, BigQuery, Consent, Server-Side, Data Quality. |
| **measure-paid-media-mcp** | Google Ads, Meta, LinkedIn, TikTok, Microsoft, CM360. |
| **measure-organic-mcp** | Organic Growth (SEO · ASO · GEO). |
| **measure-tracking-qa-mcp** | This product (guides · dataLayer QA · tracking docs). |

See **[CHANGELOG.md](CHANGELOG.md)** · **[ROADMAP.md](ROADMAP.md)** ·
**[SECURITY.md](SECURITY.md)** · **[CONTRIBUTING.md](CONTRIBUTING.md)** ·
**[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)**.

## License

[Apache-2.0](LICENSE).
