Metadata-Version: 2.4
Name: first-party-data-cro-mcp
Version: 0.1.1
Summary: First-Party Data + CRO Intelligence MCP
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: license_status.py
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7.0
Dynamic: license-file

# First-Party Data + CRO Intelligence MCP

## Core Problem

Analytics, session behavior, ecommerce data, and A/B tests are fragmented, hiding conversion friction.

## What This Server Provides

This folder contains a production-minded MCP server scaffold with typed JSON tool responses, connector health metadata, OAuth-oriented configuration, rate-limit guards, stable error envelopes, and deterministic demo data until live vendor integrations are attached.

This server has received a production pass. It now includes local CRO intelligence models for funnels, page behavior, checkout friction, device gaps, product page performance, A/B test prioritization, and Core Web Vitals impact.

## Connectors

- Google Analytics 4 API via OAuth scope `analytics.readonly`; env prefix `GA4`
- Microsoft Clarity API via OAuth scope `insights.read`; env prefix `CLARITY`
- Hotjar API via OAuth scope `sites.read`; env prefix `HOTJAR`
- Shopify Analytics API via OAuth scope `read_analytics`; env prefix `SHOPIFY`
- Optimizely/VWO API via OAuth scope `experiments.read`; env prefix `EXPERIMENTS`
- Google PageSpeed API via OAuth scope `pagespeed.read`; env prefix `PAGESPEED`

## MCP Tools

- `get_conversion_funnel` - Step drop-off and conversion gaps.
- `get_rage_click_pages` - Pages with frustration signals.
- `get_product_page_performance` - PDP metrics ranked by add-to-cart, revenue, or speed.
- `get_checkout_friction_report` - Checkout abandonment diagnostics.
- `get_ab_test_recommendations` - Next tests with expected impact.
- `get_mobile_vs_desktop_gap` - Device conversion delta.
- `get_page_speed_impact` - Core Web Vitals and revenue impact.

## Current Local Capabilities

- Supports demo funnels for `home -> purchase` and `pdp -> purchase`.
- Ranks rage-click and dead-click friction with a deterministic score.
- Scores product detail pages by add-to-cart, revenue, conversion, speed, or friction.
- Identifies checkout step abandonment and likely causes.
- Recommends A/B tests from observed page signals.
- Estimates mobile conversion gap and page speed conversion drag.
- Returns stable error envelopes for unsupported funnels, missing pages, and invalid sort fields.

## Test

```powershell
python -m pytest .\tests -q -p no:cacheprovider
```

## Partial Platform Support

Customers only need to connect the analytics and CRO platforms they actually use. Missing GA4, Clarity, Hotjar, Shopify, experiments, or PageSpeed credentials do not prevent the server from starting or running local intelligence tools.

Use `get_live_connector_status` to see configured connectors. Use `test_ga4_connection`, `test_shopify_analytics_connection`, and `test_pagespeed_connection` for read-only live smoke checks when those platforms are connected.

## Running Locally

`powershell
python -m venv .venv
.\.venv\Scripts\pip install -e .
.\.venv\Scripts\python -m first_party_data_cro_mcp.server
`

## Claude Desktop Config

`json
{
  "mcpServers": {
    "first-party-data-cro": {
      "command": "python",
      "args": ["-m", "first_party_data_cro_mcp.server"],
      "cwd": "D:\CUSTOMS\EARNALL\MCP Servers\08-first-party-data-cro"
    }
  }
}
`

## Production Checklist

- Create OAuth 2.1 apps for each connector and set *_CLIENT_ID plus *_CLIENT_SECRET.
- Store refresh tokens in a secrets manager, never in repo files.
- Replace deterministic demo rows in server.py with API adapter calls.
- Persist raw snapshots and normalized warehouse tables for trend analysis.
- Add integration tests with recorded fixtures for every connector.
- Validate every tool in MCP Inspector before publishing.
- Deploy with a /health route through FastMCP streamable HTTP on Railway or Render.

<!-- mcp-name: io.github.atul0016/first-party-data-cro -->
