Metadata-Version: 2.4
Name: customer-retention-ltv-mcp
Version: 0.1.1
Summary: Customer Retention & LTV 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

# Customer Retention & LTV Intelligence MCP

## Core Problem

Brands scale campaigns that look profitable on first purchase but destroy long-term unit economics.

## 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 customer economics models for acquisition-channel LTV, gross-profit payback, churn-risk segmentation, repurchase cohorts, lifecycle flow performance, safe winback staging, and best-segment discovery.

## Connectors

- Shopify Admin API via OAuth scope `read_customers`; env prefix `SHOPIFY`
- Klaviyo API via OAuth scope `profiles:read`; env prefix `KLAVIYO`
- Postscript API via OAuth scope `sms.read`; env prefix `POSTSCRIPT`
- Yotpo Loyalty API via OAuth scope `loyalty.read`; env prefix `YOTPO`
- Google Ads API via OAuth scope `adwords.readonly`; env prefix `GOOGLE_ADS`
- Meta Ads API via OAuth scope `ads_read`; env prefix `META_ADS`

## MCP Tools

- `get_ltv_by_channel` - LTV by acquisition source over a configurable window.
- `get_churn_risk_segment` - Customers most likely to lapse.
- `get_repurchase_rate_by_channel` - Cohort repurchase rates by source.
- `get_email_flow_performance` - Revenue per recipient and drop-off.
- `trigger_winback_campaign` - Safely queue a win-back flow action.
- `get_best_performing_segments` - Highest-LTV customer profiles and traits.

## Current Local Capabilities

- Calculates LTV, gross-profit LTV, LTV:CAC, profit after CAC, and repurchase rate by channel.
- Finds high, medium, and low churn-risk lifecycle segments.
- Computes repurchase rate and revenue per customer for monthly cohorts.
- Reports email flow open, click, order, and revenue-per-recipient metrics.
- Stages winback campaigns for approval instead of sending automatically.
- Blocks low-risk customers from winback campaigns through a policy guardrail.
- Identifies best customer traits for acquisition and retention planning.

## Test

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

## Partial Platform Support

Customers only need to connect the retention platforms they actually use. Missing Shopify, Klaviyo, Postscript, Yotpo, Google Ads, or Meta Ads credentials do not prevent the server from starting or running local intelligence tools.

Use `get_live_connector_status` to see configured connectors. Use `test_shopify_retention_connection` and `test_klaviyo_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 customer_retention_ltv_mcp.server
`

## Claude Desktop Config

`json
{
  "mcpServers": {
    "customer-retention-ltv": {
      "command": "python",
      "args": ["-m", "customer_retention_ltv_mcp.server"],
      "cwd": "D:\CUSTOMS\EARNALL\MCP Servers\04-customer-retention-ltv"
    }
  }
}
`

## 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/customer-retention-ltv -->
