# Criteo MCP server

MCP server, ktorý dáva AI agentovi (Claude Code) tooly na správu Criteo kampaní.
Návrh toolov a vysvetlenie Criteo: `D:\claude_grizly\criteo\`

## Čo je v priečinku

| Súbor | Načo je |
|---|---|
| `server.py` | Samotný MCP server — tooly na kampane, ad sety, kreatívy, audiences, report |
| `criteo_api.py` | Komunikácia s Criteo API (token, requesty) — server.py ho používa |
| `prompt-priklady.md` | Ťahák: ako zadávať úlohy agentovi v prompte (kampane, kreatívy — čo musí prompt obsahovať) |
| `.env.example` | Šablóna konfigurácie — skopíruj ako `.env` a vyplň |
| `.env` | Tvoje tajné kľúče (vytvoríš si sám, NIKDY nezdieľať) |
| `requirements.txt` | Zoznam potrebných knižníc |

## Inštalácia (raz)

### Krok 1 — Nainštaluj knižnice

Otvor CMD alebo PowerShell (jedno kde, príkaz je nezávislý od priečinka) a spusti:

```
D:\Programy\anaconda3\Scripts\pip.exe install fastmcp python-dotenv
# requests uz v Anaconde je, netreba
# ak je vsetko ok, na konci vypise "Successfully installed fastmcp-..." a dalsie balicky
# ak vypise "already satisfied" - uz je nainstalovane, nic netreba, pokracuj dalej
```

### Krok 2 — Vytvor .env s kľúčmi

1. V priečinku `D:\claude_grizly\criteo-mcp\` skopíruj súbor `.env.example` a premenuj kópiu na `.env` (len `.env`, bez `.example`)
2. Otvor `.env` v Poznámkovom bloku
3. Doplň `CRITEO_CLIENT_ID` a `CRITEO_CLIENT_SECRET` — hodnoty máš v .txt súbore stiahnutom z Criteo Partners portálu (Create new key)
4. `CRITEO_ADVERTISER_ID` zatiaľ môžeš nechať prázdne — test v kroku 3 ti poradí

### Krok 3 — Otestuj spojenie (bez MCP)

V CMD/PowerShell spusti:

```
cd D:\claude_grizly\criteo-mcp
D:\Programy\anaconda3\python.exe server.py --test
# test ide po krokoch a povie ti, co chyba:
#   "Token OK. Appka ma pristup k X inzerentom" + zoznam ID  -> kluce funguju
#       -> ak CRITEO_ADVERTISER_ID v .env este nemas, skopiruj ID zo zoznamu a dopln ho
#   "POZOR: ziadny inzerent - chyba consent krok"            -> Partners portal -> appka
#                                                               -> Generate new URL -> schvalit
#   "CHYBA ... invalid_client"                               -> preklep v client_id/secret v .env
#   "OK - nasiel som X kampani" + zoznam                     -> vsetko kompletne funguje
```

### Krok 4 — Pripoj do Claude Code

V CMD/PowerShell v priečinku projektu, kde chceš server používať (napr. `D:\claude_grizly`):

```
cd D:\claude_grizly
claude mcp add criteo -- D:\Programy\anaconda3\python.exe D:\claude_grizly\criteo-mcp\server.py
# vypise potvrdenie "Added stdio MCP server criteo..."
# server sa aktivuje pri dalsom spusteni claude v tomto priecinku
```

Overenie: spusti `claude`, napíš `/mcp` — v zozname má byť `criteo` so statusom connected.

## Použitie

V Claude Code potom stačí písať po ľudsky, agent si tooly zavolá sám:

- „vypíš mi criteo kampane" → `list_campaigns`
- „aké ad sety má kampaň X a koľko míňajú" → `list_ad_sets` + `get_report`
- „vytvor kampaň podľa šablóny..." → `create_campaign` + `create_ad_set`

### Viac inzerentských účtov

Účet má prístup k viacerým inzerentom (advertiser). Funguje to takto:

- `CRITEO_ADVERTISER_ID` v `.env` = **default** — použije sa, keď v zadaní účet nespomenieš (daj tam ten, s ktorým robíš najčastejšie)
- každý tool má voliteľný parameter `advertiser_id` — v zadaní stačí povedať „...pre účet XYZ" a agent si ID nájde cez tool `list_advertisers` a použije ho
- príklad: „vypíš kampane pre všetkých inzerentov" → agent zavolá `list_advertisers` a potom `list_campaigns` pre každého
- pozor: `CRITEO_DATASET_ID` (katalóg) patrí ku konkrétnemu inzerentovi — pri práci s iným účtom agent zistí jeho datasetId cez `list_ad_sets`

⚠ Write tooly (create/update/start) menia reálny účet a míňajú reálne peniaze.
Odporúčanie: nové ad sety nechávaj vypnuté (vytvárajú sa vypnuté automaticky),
skontroluj ich v Commerce Growth UI a až potom spusti.

## Časté chyby

| Prejav | Príčina | Riešenie |
|---|---|---|
| `invalid_client` | preklep v client_id/secret | skopíruj hodnoty z .txt znova, bez medzier |
| prázdny zoznam kampaní, ale token OK | chýba consent | Partners portál → appka → Generate new URL → schváliť účet |
| HTTP 401 počas práce | expirovaný token | nič — server si ho obnoví sám; ak sa opakuje stále, over kľúče |
| HTTP 403 | appke chýba oprávnenie (domain permission) | oprávnenia sa po aktivácii nedajú meniť → nová appka + consent |
| HTTP 400 s popisom poľa | zle poslaný request | prečítaj hlášku — server chyby prenáša doslovne, agent podľa nej opraví volanie |
| `Chýba dataset_id` pri create_ad_set | server nepozná ID katalógu | spusti `list_ad_sets` — existujúce ad sety majú `datasetId`; hodnotu daj do `.env` |

## Kreatívy

Server vie vytvoriť všetky 3 API formáty kreatív (príklady promptov: `prompt-priklady.md`):

- `create_image_creative` — statické bannery (upload jpg/png z disku, aj celý priečinok naraz)
- `create_dynamic_creative` — produktové bannery z feedu (zadávaš len farby, CTA texty, logo)
- `create_adaptive_creative` — AI bannery z brand podkladov (logo, texty, 6 farieb; voliteľne fotky/video)

Kreatívu potom prepojí s ad setom `create_ad`. **Showcase** reklamy cez API nejdú — len ručne v Commerce Growth UI.

## Čo zatiaľ nevie / neoverené

- `list_audiences`, `set_ad_set_audience` — implementované podľa dokumentácie, ale neoverené na reálnom účte; pri prvom použití môžu potrebovať doladenie (chybové hlášky presne povedia čo)
- `create_dynamic_creative`, `create_adaptive_creative` — implementované podľa dokumentácie, na reálnom účte zatiaľ neodskúšané; ak API vráti 400, hláška povie presne ktoré pole treba opraviť