Metadata-Version: 2.4
Name: unified-ad-intelligence-mcp
Version: 0.1.1
Summary: Unified Ad 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

# Unified Ad Intelligence MCP

## Core Problem

Each ad platform claims credit independently, causing duplicate conversion credit and wasted budget.

## 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 attribution intelligence models for cross-platform spend, platform-reported revenue, deduplicated revenue truth, Shopify revenue truth, marginal ROAS, budget allocation, cohort ROAS, and campaign anomaly detection.

## Connectors

- Google Ads API via OAuth scope `adwords.readonly`; env prefix `GOOGLE_ADS`
- Meta Marketing API via OAuth scope `ads_read`; env prefix `META_MARKETING`
- TikTok Ads API via OAuth scope `advertiser.read`; env prefix `TIKTOK_ADS`
- LinkedIn Campaign Manager API via OAuth scope `r_ads`; env prefix `LINKEDIN_ADS`
- Klaviyo API via OAuth scope `campaigns:read`; env prefix `KLAVIYO`
- Shopify Admin API via OAuth scope `read_orders`; env prefix `SHOPIFY`
- Pinterest Ads API via OAuth scope `ads:read`; env prefix `PINTEREST_ADS`

## MCP Tools

- `get_cross_platform_summary` - Summarize spend, attributed revenue, true revenue, and duplication risk across platforms.
- `get_true_roas` - Compare platform-reported ROAS against deduplicated revenue truth.
- `get_budget_recommendation` - Recommend budget shifts using marginal ROAS and confidence.
- `get_new_vs_returning_roas` - Split acquisition quality by new and returning customers.
- `detect_campaign_anomalies` - Detect spend spikes, CPA jumps, conversion drops, and tracking outages.

## Current Local Capabilities

- Compares platform-reported revenue against deduplicated true revenue.
- Calculates reported ROAS, true ROAS, overclaim amount, and overclaim rate.
- Recommends budget allocation by profit, acquisition, or scale goals.
- Splits ROAS by new versus returning customer revenue.
- Detects CPA jumps, spend spikes, conversion-rate drops, and tracking anomalies.
- Returns stable errors for unknown platforms, invalid goals, bad budgets, and invalid lookback windows.

## Test

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

## Partial Platform Support

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

Use `get_live_connector_status` to see configured connectors. Use `test_meta_marketing_connection` and `test_google_ads_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 unified_ad_intelligence_mcp.server
`

## Claude Desktop Config

`json
{
  "mcpServers": {
    "unified-ad-intelligence": {
      "command": "python",
      "args": ["-m", "unified_ad_intelligence_mcp.server"],
      "cwd": "D:\CUSTOMS\EARNALL\MCP Servers\01-unified-ad-intelligence"
    }
  }
}
`

## 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/unified-ad-intelligence -->
