Metadata-Version: 2.4
Name: creative-tagger-mcp
Version: 0.2.1
Summary: MCP server for Creative Tagger — taxonomy + library memory + strategist tools for any AI agent
Author: Stephen Lavender
License: MIT
Keywords: ads,creative,creative-intelligence,marketing,mcp,taxonomy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.0
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# Creative Tagger MCP Server

The MCP layer for [Creative Tagger](https://creativetagger.ai) — plug structured creative intelligence into any AI agent (Claude Desktop, Cursor, Windsurf, ChatGPT with MCP, etc.).

Status note (verified 2026-07-15): the production API and hosted remote MCP
surface are live, but PyPI still serves `creative-tagger-mcp==0.1.0`. This
README documents the repository's unpublished `0.2.1` release candidate. Use
`https://api.creativetagger.ai/mcp/` for the current hosted tool surface; do not
assume the installed `0.1.0` package includes the tools documented below.

Your AI of choice gets:

- **Taxonomy** — 21 standardized dimensions for any ad creative (video, image, carousel, landing page, long video, email)
- **Memory** — every analysis is saved to the user's library; the agent can search it, recall patterns, and pull individual results
- **Brand-custom taxonomy** — extend the standard taxonomy with each brand's founders, products, segments, aliases, and naming variables
- **Meta performance memory** — read-only Meta sync/status/tools so agents can reason over winners, unproven tags, demographic opportunities, and taxonomy gaps
- **Brain learnings** — auto-written account learnings in plain language, with agent-ready context for the next brief
- **Strategist** — recommendation + gap-analysis tools that reason over the user's library plus saved brand context (voice, audience, anti-patterns)
- **Competitive intelligence** — scan a competitor's Meta Ad Library through Creative Tagger's native Market access

## Quick Start

For clients that support remote MCP, connect the current hosted server:

```text
URL: https://api.creativetagger.ai/mcp/
Authorization: Bearer ct_your_key
```

The repository package is the stdio path for clients that require a local
command. Until `0.2.1` is published, installing from PyPI gives the older tool
surface:

```bash
# Install (PyPI currently resolves to 0.1.0)
pip install creative-tagger-mcp

# Run against production (default)
CREATIVE_TAGGER_API_KEY=ct_your_key creative-tagger-mcp

# Or against a local API
CREATIVE_TAGGER_URL=http://localhost:8000 \
CREATIVE_TAGGER_API_KEY=ct_your_key \
  creative-tagger-mcp
```

Get an API key at [app.creativetagger.ai](https://app.creativetagger.ai).

## Release Verification

Before publishing a new MCP version, build the artifacts and smoke-test the
wheel that will be uploaded to PyPI:

```bash
python -m build
python scripts/smoke_release.py
python -m twine check \
  dist/creative_tagger_mcp-0.2.1-py3-none-any.whl \
  dist/creative_tagger_mcp-0.2.1.tar.gz
```

The smoke test installs the wheel into a temporary virtualenv, verifies the
`creative-tagger-mcp` console entry point, checks the package version, and
confirms the V1 tool surface is present from the installed artifact.

## Publishing to PyPI

The release workflow publishes from GitHub Actions after it builds the package,
runs `scripts/smoke_release.py`, and passes `twine check`.

Recommended path:

```bash
git tag v0.2.1
git push origin v0.2.1
```

The workflow supports PyPI trusted publishing with GitHub OIDC. Configure the
PyPI publisher for repository `stephenlavender/creative-tagger-mcp`, workflow
`.github/workflows/publish.yml`, environment `pypi`, then push the version tag.

Exact PyPI trusted publisher values:

- PyPI project: `creative-tagger-mcp`
- Publisher: GitHub
- Owner: `stephenlavender`
- Repository: `creative-tagger-mcp`
- Workflow filename: `publish.yml`
- Environment name: `pypi`

If the workflow fails with `invalid-publisher`, PyPI does not have a trusted
publisher matching those claims yet. Add the publisher above, then rerun the
failed workflow or push the version tag again.

Fallback path: add a GitHub Actions repository secret named `PYPI_API_TOKEN`
containing a PyPI project token. The same workflow will use that token when it
is present.

Local fallback:

```bash
python -m build
python scripts/smoke_release.py
python -m twine check \
  dist/creative_tagger_mcp-0.2.1-py3-none-any.whl \
  dist/creative_tagger_mcp-0.2.1.tar.gz
python -m twine upload \
  dist/creative_tagger_mcp-0.2.1-py3-none-any.whl \
  dist/creative_tagger_mcp-0.2.1.tar.gz
```

Always select the exact release artifacts for a local upload. A reused checkout
may contain older valid distributions in `dist/`; never publish with
`twine upload dist/*`.

## Add to Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "creative-tagger": {
      "command": "creative-tagger-mcp",
      "env": {
        "CREATIVE_TAGGER_URL": "https://api.creativetagger.ai",
        "CREATIVE_TAGGER_API_KEY": "ct_your_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. The tools appear in the MCP picker.

## Tools

### `analyze_creative`
Analyze any ad creative and get structured classification across 21 dimensions.
```
{ "file_path": "./ad.mp4", "brand_name": "Brand" }
{ "url": "https://example.com/landing-page", "brand_name": "Brand" }
{ "html_content": "<html>...</html>", "brand_name": "Brand" }
```
Results auto-save to the user's library.

### `get_taxonomy`
Read taxonomy v2's versioned vocabulary or one dimension. The package returns
15 controlled dimensions, one derived/open `aspect_ratio` dimension, and two
intentionally dynamic, brand-specific dimensions. Aspect ratio includes common
canonical examples but sets `allow_other_values: true`: the API may derive any
reduced `WxH` ratio (such as `3x2` or `300x157`) or preserve a `W:H` ratio for
long video. The package does not infer enums from OpenAPI: several valid
classification fields are strings in that schema, so schema discovery would
silently return an incomplete taxonomy.
```
{}                                # all controlled + derived/open + dynamic dimensions
{ "dimension": "hook_type" }      # one dimension
{ "dimension": "aspect_ratio" }   # examples; other derived values remain valid
```
Taxonomy v2 splits three dimensions the old model mixed together: **media type**
(the auto-detected format — static image, video, carousel; never AI-classified),
**asset type** (production class: UGC, Studio, High Production, …), and
**visual format** (execution style: Talking Head, Demo, Testimonial, …).
`Static Image` and `Carousel` are media types and are no longer valid
`visual_format` values. `messaging_angle` is the canonical angle dimension.

### `list_library`
Browse saved analyses. Search by filename or hook, filter by format, messaging
angle, emotion, CTA, talent, offer, audio type, or seasonality, and sort by
joined performance.
```
{
  "limit": 50,
  "search": "BFCM",
  "format": "video",
  "angle": "Social Proof",
  "talent": "Founder",
  "sort": "roas"
}
```

### `get_library_patterns`
Cross-library pattern insights — concentration and diversity per dimension, plus rule-based diversification flags.

### `get_analysis`
Pull the full 21-dimension result for one library item.
```
{ "analysis_id": 42 }
```

### `recommend` ⭐
Ask the Creative Strategist a question grounded in the user's library + brand context.
```
{ "brand_name": "Acme", "question": "What kind of UGC should I test for Q4?" }
```
Returns concrete recommendations using taxonomy values + library observations.

### `analyze_gaps` ⭐
Identify concentration risk in the library and propose next creatives that diversify it.
```
{ "brand_name": "Acme" }
```

### `get_brand_context` / `set_brand_context`
Long-term memory per brand. Voice, target audience, top performers, anti-patterns, notes.
```
set_brand_context: {
  "brand_name": "Acme",
  "voice": "clinical, precise, no personality",
  "target_audience": "new moms 28-40, postpartum recovery",
  "top_performers": ["UGC TalkHead", "BeforeAfter visuals"],
  "anti_patterns": ["loud humor", "celebrity endorsement"],
  "notes": "Q4 focus: gift-shoppers + retention"
}
```
Strategist tools auto-include this context.

### `get_brand_taxonomy` / `set_brand_taxonomy_value` / `delete_brand_taxonomy_value` / `set_brand_entity` / `delete_brand_entity`
Customize the standard taxonomy for one brand without breaking cross-brand reporting.
```
set_brand_taxonomy_value: {
  "brand_name": "Acme",
  "dimension": "talent",
  "value": "Stephen Lavender / Founder",
  "aliases": ["Stephen", "founder"],
  "description": "Use when Stephen appears or is referenced"
}

set_brand_entity: {
  "brand_name": "Acme",
  "entity_type": "product",
  "name": "Creative Tagger",
  "aliases": ["CT", "tagger"]
}

delete_brand_taxonomy_value: {
  "brand_name": "Acme",
  "dimension": "talent",
  "value": "Old Founder Label"
}

delete_brand_entity: {
  "brand_name": "Acme",
  "entity_type": "product",
  "name": "Retired Product"
}
```

### `get_naming_variables` / `list_naming_templates` / `save_naming_template`
Manage saved naming templates from your agent. Templates support standard taxonomy
fields plus brand-custom variables like founder, product, offer, customer_segment,
icp, and campaign_label. Saved templates auto-apply to future `analyze_creative`
results.
```
save_naming_template: {
  "name": "default",
  "template": "{brand}_{founder}_{customer_segment}_{hook_type}_{cta}_{ratio}_{version}"
}
```

Use `preview_naming_template` to test a template before saving, and
`delete_naming_template` to remove one.

### `get_meta_status` / `sync_meta_performance`
Check or trigger read-only Meta performance memory. No campaign creation, no budget edits.
Creative Tagger must have an approved native Meta OAuth connection before
customer accounts can sync Meta performance.
Pass `attribution_windows` when the buyer uses a non-default Meta lookback
window and Creative Tagger should match Ads Manager exactly.
```
{
  "brand_name": "Acme",
  "date_preset": "last_30d",
  "attribution_windows": ["7d_click", "1d_view"]
}
```

### `get_creative_strategy_report`
Pull the same strategy matrix shown in Creative Tagger Reports. Defaults to
visual formats by messaging angles, with states for next tests, live learning,
winners, losers, fatigue, and gaps. Returns the decision queue plus an
`agent_context` payload that can be handed directly to an LLM for strategy work.
Supports creative-diagnostics metrics such as CTR, thumbstop, hook, hold, video
milestone rates, CPA, CVR, ROAS, revenue, spend, and funnel score. For
audience-mode reads, switch the axes to demographic dimensions such as
`demographic_age` and `demographic_gender`, or use the `demographic-read` or
`audience-signals` templates. Other built-in templates include
`creative-winners`, `fatigue-watch`, `coverage-gaps`, `hook-performance`, and
`persona-read`. Creative axes follow taxonomy v2: `visual_format` (execution
style), `asset_type` (production class), and `media_type` (auto-detected
format) are three separate dimensions, with `ad_type` kept as a deprecated
alias for `visual_format`. For mixed creative × audience reads, keep one
creative axis such as `messaging_angle`, `visual_format`, `hook`, `persona`,
or `offer_type` and
set the other axis to `demographic_segment` or `demographic_signal`. Add
`fatigue_minimum_calendar_days` when fatigue should only count after a long
enough live window, not just after a few close-together synced points. For
fatigue-aware reads, pass the same embedded watch controls the app/API support:
`watch_group_by`, `watch_metric`, `watch_signal_focus`,
`watch_trajectory_focus`, `watch_coverage_focus`, `watch_minimum_points`,
`watch_minimum_calendar_days`, `watch_maximum_gap_days`, and `watch_limit`.

```
{
  "brand_name": "Acme",
  "report_template": "next-tests",
  "rows": "visual_format",
  "columns": "messaging_angle",
  "metrics": "spend,ctr,thumbstop_rate,hook_rate,hold_rate,cpa"
}
```

```json
{
  "brand_name": "Acme",
  "report_template": "demographic-read",
  "rows": "demographic_age",
  "columns": "demographic_gender",
  "metrics": "spend,roas,ctr,cpa,conversions,revenue",
  "roas_target": 2.5,
  "fatigue_minimum_calendar_days": 7,
  "watch_group_by": "hook_type",
  "watch_metric": "cpa",
  "watch_signal_focus": "fatigued",
  "watch_trajectory_focus": "worsening",
  "watch_coverage_focus": "windowed_history",
  "watch_minimum_points": 2,
  "watch_minimum_calendar_days": 7,
  "watch_maximum_gap_days": 7,
  "watch_limit": 5,
  "start_date": "2026-05-01",
  "end_date": "2026-05-31"
}
```

```json
{
  "brand_name": "Acme",
  "report_template": "audience-signals",
  "rows": "demographic_signal",
  "columns": "demographic_segment",
  "metrics": "spend,roas,ctr,cpa,conversions,revenue",
  "date_preset": "last_30_days"
}
```

```json
{
  "brand_name": "Acme",
  "rows": "messaging_angle",
  "columns": "demographic_segment",
  "status_focus": "all",
  "metrics": "spend,roas,ctr,cpa,conversions,revenue",
  "fatigue_minimum_calendar_days": 7,
  "date_preset": "last_30_days"
}
```

### `get_brain_learnings`
Read the auto-written Brand Brain learnings generated from performance memory,
strategy cells, taxonomy winners/watchouts, and audience signals. Returns a
hero learning, concise stories, and an `agent_context` payload for the next
brief or strategist prompt. Use `kinds` when an agent only wants a focused slice
such as `conclusion`, `working,audience`, or `watch`. Add
`conclusion_statuses` to narrow conclusion stories to `winner`, `fatigued`, or
`loser` outcomes only, and `conclusion_recency_days` to keep only the most
recent conclusion window. Use `watch_group_by`, `watch_metric`,
`watch_signal_focus`, `watch_trajectory_focus`, `watch_coverage_focus`,
`watch_minimum_points`, `watch_minimum_calendar_days`, `watch_sources`, and
`fatigue_decay_threshold` when the watchouts should be written from a different
fatigue lens such as fatigued-only CPA by ad type, weak taxonomy patterns only,
CTR by hook, or stable ROAS by `demographic_segment`.
```
{
  "brand_name": "Acme",
  "date_preset": "last_30_days",
  "minimum_spend": 500,
  "learning_spend": 1500,
  "kinds": "conclusion,watch",
  "conclusion_statuses": "winner,fatigued",
  "conclusion_recency_days": 21,
  "watch_group_by": "ad_type",
  "watch_metric": "cpa",
  "watch_signal_focus": "fatigued",
  "watch_trajectory_focus": "worsening",
  "watch_coverage_focus": "windowed_history",
  "watch_minimum_points": 3,
  "watch_minimum_calendar_days": 7,
  "watch_sources": "timeseries,patterns",
  "fatigue_decay_threshold": 0.25,
  "limit": 6
}
```

### `save_brain_learnings`
Persist the current auto-written Brand Brain learnings into saved Brain notes
for a brand, using the same filtering controls as `get_brain_learnings`. Use
this after reviewing a conclusion/working/watch/audience/gap slice when the
user wants the best current learnings saved back into reusable strategist context.
```
{
  "brand_name": "Acme",
  "date_preset": "last_30_days",
  "minimum_spend": 500,
  "learning_spend": 1500,
  "kinds": "conclusion,watch",
  "conclusion_statuses": "winner,fatigued",
  "conclusion_recency_days": 21,
  "watch_group_by": "ad_type",
  "watch_metric": "cpa",
  "watch_signal_focus": "fatigued",
  "watch_trajectory_focus": "worsening",
  "watch_coverage_focus": "windowed_history",
  "watch_minimum_points": 3,
  "watch_minimum_calendar_days": 7,
  "watch_sources": "timeseries,patterns",
  "include_gaps_in_notes": false,
  "limit": 6
}
```

### `get_performance_timeseries`
Read saved performance curves for fatigue checks without opening the dashboard.
Returns dated points plus a fatigue signal for each grouped series, using the
same decay threshold as Creative Tagger's strategy matrix. Group by creative,
campaign, landing page, `analysis_id`, or audience slices like
`demographic_age`, `demographic_gender`, `demographic_segment`, and
`demographic_signal`, and inspect metrics like ROAS, CPA, CTR, CPM, thumbstop,
completion rate, or funnel score. Use `signal_focus` when an agent only wants
the current fatigue watchlist or only stable controls, and `trajectory_focus`
when the agent wants only worsening, improving, flat, or insufficient-data
series. Use `coverage_focus` to isolate call-ready, gappy, short-window, or
windowed-history curves. Add `minimum_calendar_days` when fatigue should only
count after a trend has been live long enough, not just after a few
close-together points.
```
{
  "brand_name": "Acme",
  "date_preset": "last_30d",
  "group_by": "ad_name",
  "metric": "roas",
  "signal_focus": "fatigued",
  "trajectory_focus": "worsening",
  "coverage_focus": "call_ready",
  "minimum_spend": 500,
  "minimum_points": 3,
  "minimum_calendar_days": 7,
  "fatigue_decay_threshold": 0.18,
  "limit": 5
}
```

Use `date_preset` for a standard lookback window, or pass explicit
`start_date` / `end_date` to override it.

### `export_performance_timeseries_context`
Return the reusable `agent_context` payload from performance time series. Use
this when another agent needs the fatigue decision queue, summary text, action
mix, top groups, and prompt-ready export without carrying the full chart payload.
It accepts the same inputs as `get_performance_timeseries`.
```
{
  "brand_name": "Acme",
  "date_preset": "last_30d",
  "group_by": "ad_name",
  "metric": "roas",
  "signal_focus": "fatigued",
  "trajectory_focus": "worsening",
  "coverage_focus": "call_ready",
  "minimum_spend": 500,
  "minimum_points": 3,
  "minimum_calendar_days": 7,
  "fatigue_decay_threshold": 0.18,
  "limit": 5
}
```

Internal migration/backfill tools are hidden from the default published MCP
surface. They require `CREATIVE_TAGGER_INTERNAL_BACKFILL_TOOLS=1` and should not
be used in customer flows or to avoid Meta approval.

### `get_meta_performance_summary`
Read saved Meta performance memory without triggering a sync.
```
{ "brand_name": "Acme" }
```
Returns account totals plus performance by standard taxonomy and brand-custom taxonomy.
Each aggregate can include `funnel_score` and a `funnel` explanation object for
capture -> hold -> bring-to-site -> convert diagnosis.

### `get_taxonomy_performance`
Find which tags scale, which are unproven, and which standard taxonomy values have
not been tested yet. Rows include ROAS, CTR, thumbstop, and funnel scores when
performance memory exists.
```
{ "brand_name": "Acme", "dimension": "hook_type", "spend_threshold": 500 }
```

### `get_prebuilt_reports`
Return ready-made Motion-style reports: best hooks, landing pages, messaging angles,
audiences, offers, CTAs, visual formats, and brand-custom values. Add
`start_date` / `end_date` when the report should only cover a specific synced
window.
```
{ "brand_name": "Acme", "report_id": "best_hooks", "limit": 8 }
{ "brand_name": "Acme", "report_id": "best_angles", "start_date": "2026-05-01", "end_date": "2026-05-31", "limit": 8 }
```

### `create_custom_report`
Build a custom report from selected standard or brand taxonomy dimensions and
rank the actual matched dimension combinations by ROAS, funnel score, spend,
CTR, or CPA. Use this for Motion-style views like best hook x landing page x
offer, founder x hook, audience x offer, or brand segment x product. Add
`start_date` and `end_date` when the report should isolate a specific test
window instead of the full synced history.
```
{
  "brand_name": "Acme",
  "dimensions": ["hook_type", "landing_page", "offer_type"],
  "layer": "all",
  "metric": "roas",
  "start_date": "2026-05-01",
  "end_date": "2026-05-31"
}
```
Rows can include `parts` and `values`, so the agent can explain a winning
combination instead of treating each tag independently.

### Saved custom reports
Save reusable report definitions, list them for a brand, rerun them by id, or
delete them when they are no longer needed. Saved reports can also persist a
custom `start_date` / `end_date` window for a specific launch or test period,
plus dashboard-style preset state such as `view_type`, `date_range`,
`group_by`, `metrics`, `filters`, `sort`, and `saved_metric_preset`.
```
{
  "brand_name": "Acme",
  "name": "Hook + LP + Offer",
  "dimensions": ["hook_type", "landing_page", "offer_type"],
  "view_type": "matrix",
  "date_range": "custom",
  "group_by": "dimension",
  "metrics": ["spend", "roas", "cpa", "ctr"],
  "filters": [{"field": "status", "value": "winner"}],
  "sort": "desc",
  "saved_metric_preset": "delivery",
  "start_date": "2026-05-01",
  "end_date": "2026-05-31"
}
{ "brand_name": "Acme" }
{ "report_id": 7 }
```
Tools: `save_custom_report`, `list_custom_reports`, `run_saved_custom_report`,
`delete_custom_report`.

### `predict_creative`
Score a saved analysis or draft attributes before it spends, using the brand's
own performance memory. Returns a fit score, per-tag ratings, and recommended
swaps.
```
{ "brand_name": "Acme", "attributes": { "hook_type": "Question", "cta": "Shop Now" } }
```

### `get_demographics_performance`
Read age x gender performance memory with opportunity and waste flags. Use
`date_preset` for a standard audience window, or `start_date` / `end_date` to
isolate a specific audience window.
```
{
  "brand_name": "Acme",
  "date_preset": "last_30_days",
  "start_date": "2026-05-01",
  "end_date": "2026-05-31"
}
```

### `export_demographics_context`
Return an agent-ready audience context payload from the saved demographics read.
Use this when another agent needs the top audience opportunities and waste
segments, blended totals, per-segment mixed creative x audience views, and a
prompt-ready summary without the full wrapper.
```
{
  "brand_name": "Acme",
  "date_preset": "last_30_days",
  "limit": 3
}
```

### `generate_brand_taxonomy`
Generate brand-specific messaging themes and intended audiences from the analyzed
creative library, then optionally save them to Brand Taxonomy Studio.
```
{ "brand_name": "Acme", "persist": true }
```

### `scan_competitor`
Classify a competitor's Meta Ad Library ads and get strategy breakdown.
```
{ "brand_name": "Acme", "page_name": "Hims & Hers", "limit": 25 }
```

Internal competitor-row backfill is also hidden from the default published MCP
surface. Customer-facing competitor intelligence should use `scan_competitor`
after native Meta Ad Library access is approved.

### `get_competitor_scan_history`
Read the saved Market scans/imports for a workspace without re-running Meta Ad
Library access. Useful when the agent needs the latest saved competitor hooks,
styles, or scan metadata before drafting briefs.
```
{ "brand_name": "Acme", "limit": 6 }
```

### `generate_naming`
Build naming strings from already-classified attributes (rarely needed — `analyze_creative` already includes naming).

## Architecture

```
Your AI agent  ←—stdio—→  creative-tagger-mcp  ←—HTTPS—→  api.creativetagger.ai
                                                              │
                                                              ├── Gemini 2.5 Flash (classifier)
                                                              ├── Claude Sonnet (fallback)
                                                              ├── SQLite (library + brand memory)
                                                              └── Meta Ad Library
```

You bring the agent. We provide the taxonomy, the memory, and the strategist.

## License

MIT
