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

# Ad Creative Intelligence MCP

## Core Problem

Creative fatigue is detected too late, after hook rates fall, CPM rises, and spend is wasted.

## 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 creative intelligence models for fatigue scoring, performance deltas, competitor creative patterns, brief generation, hook benchmarks, and winning-angle analysis.

## Connectors

- Meta Ads API via OAuth scope `ads_read`; env prefix `META_ADS`
- Meta Ad Library API via OAuth scope `ads_archive`; env prefix `META_LIBRARY`
- TikTok Ads API via OAuth scope `advertiser.read`; env prefix `TIKTOK_ADS`
- TikTok Creative Center API via OAuth scope `creative.read`; env prefix `TIKTOK_CREATIVE`
- Google Ads API via OAuth scope `adwords.readonly`; env prefix `GOOGLE_ADS`
- YouTube Data API via OAuth scope `youtube.readonly`; env prefix `YOUTUBE`

## MCP Tools

- `get_creative_health_report` - Active creative scorecard with fatigue risk.
- `detect_fatiguing_creatives` - Rank creatives likely to fatigue soon.
- `get_competitor_creatives` - Recent competitor creative examples and angles.
- `generate_creative_briefs` - Briefs grounded in winning patterns.
- `get_hook_benchmarks` - Hook-rate and thumb-stop benchmarks.
- `analyze_winning_angles` - Extract repeated claims, hooks, formats, and offers.

## Current Local Capabilities

- Scores creative fatigue from frequency, CTR decline, CVR decline, CPM rise, and spend pressure.
- Produces platform-specific creative health reports.
- Detects replacement priorities for fatigued creatives.
- Summarizes competitor creative angles without copying competitor phrasing.
- Generates creative briefs for top performers, fatigue replacements, or competitor gaps.
- Looks up hook-rate and thumb-stop benchmarks for supported industry/platform pairs.
- Extracts winning angles and formats from account-level creative signals.

## Test

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

## Partial Platform Support

Customers only need to connect the creative and media platforms they actually use. Missing Meta Ads, TikTok, Google Ads, Meta Library, or YouTube 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_ads_connection`, `test_tiktok_creative_connection`, and `test_youtube_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 ad_creative_intelligence_mcp.server
`

## Claude Desktop Config

`json
{
  "mcpServers": {
    "ad-creative-intelligence": {
      "command": "python",
      "args": ["-m", "ad_creative_intelligence_mcp.server"],
      "cwd": "D:\CUSTOMS\EARNALL\MCP Servers\03-ad-creative-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/ad-creative-intelligence -->
