# MCP dokumentace

MCP server Zaslat propojuje libovolného AI asistenta (Claude, ChatGPT, n8n i vlastní agenty) přímo se Zaslat. Asistent pak umí porovnávat ceny dopravců, zakládat a rušit zásilky, sledovat je a tisknout štítky – vše přirozeným jazykem.

## Proč MCP

Zaslat tradičně nabízí dvě rozhraní: **webovou aplikaci** pro lidi a **REST API** pro systémy. MCP je to třetí – vytvořené pro **AI asistenty, kteří jednají jménem konkrétního uživatele**.

Na rozdíl od REST API, které vyžaduje formální integraci a zapojení vývojáře, pokrývá MCP mezikroky, které dosud spadaly „mezi" obě rozhraní:

- zpracování adres v různých formátech z tabulek,
- převod objednávek z prostého textu e-mailu na zásilky,
- rychlé dotazy na cenu dopravy,
- jednorázové úkoly, jako je objednání svozu nebo opětovný tisk štítku, bez proklikávání aplikace.

MCP míří na **technicky zvídavé uživatele a provozní týmy**, které chtějí automatizovat expedici bez velkého integračního projektu. Funguje s libovolným asistentem podporujícím MCP – rozumí kontextu uživatele a respektuje jeho preference, například výchozí adresu odesílatele nebo oblíbené dopravce.

## Rychlý start

Postup pro **Claude.ai** nebo **Claude Desktop**:

1. Přejděte do **Settings → Connectors → Add custom connector**.
2. Zadejte URL: `https://mcp.zaslat.cz/mcp`
3. Zvolte **ověření přes OAuth** (budete přesměrováni na přihlášení do Zaslat).
4. Potvrďte přístup – tím je nastavení dokončeno.

:::tip

MCP server funguje s jakýmkoli klientem podporujícím protokol MCP, nejen s Claude. U ostatních klientů zadejte stejnou URL `https://mcp.zaslat.cz/mcp` a zvolte odpovídající způsob ověření.

:::

## Ověření

Server ověřuje přihlašovací údaje proti backendu Zaslat při inicializaci a poté je **znovu ověřuje každých 30 minut** po celou dobu trvání MCP relace.

### OAuth 2.1 (doporučeno)

Server zveřejňuje metadata autorizace na adrese:

```
GET https://mcp.zaslat.cz/.well-known/oauth-protected-resource
```

MCP klienti si autorizační server zjistí automaticky a provedou standardní **authorization-code flow s PKCE** proti `api.zaslat.cz`.

Požadované rozsahy oprávnění (scopes):

- `rates`
- `shipments:read`
- `shipments:write`

### API klíč

Bezobslužní klienti (n8n, skripty, vlastní agenti) předávají API klíč Zaslat v hlavičce `X-ApiKey`:

```http
POST /mcp HTTP/1.1
Host: mcp.zaslat.cz
X-ApiKey: <vas-api-klic>
Content-Type: application/json
```

API klíč si vygenerujete po přihlášení v aplikaci [**app.zaslat.cz**](https://app.zaslat.cz) v sekci **Nastavení → Integrace → API integrace**.

## Nástroje

MCP server nabízí patnáct nástrojů rozdělených do několika kategorií. Nástroje označené jako *pouze čtení* nijak nemění vaše data.

### Ceny a informace

| Nástroj | Popis | Mění data |
| --- | --- | --- |
| `get_rates` | Porovná ceny dopravců pro danou trasu a seznam balíků. | Ne |
| `get_profile` | Načte profil uživatele, výchozí adresu odesílatele a nastavení účtu. | Ne |
| `search_parcel_points` | Vyhledá nejbližší výdejní / podací místa podle adresy, PSČ nebo dopravce. | Ne |

### Správa zásilek

| Nástroj | Popis | Mění data |
| --- | --- | --- |
| `create_shipment` | Založí novou zásilku (Home2Home, Shop2Home, Home2Shop, Shop2Shop). | Ano |
| `cancel_shipment` | Zruší zásilku, kterou dopravce dosud nevyzvedl. | Ano |

### Přehled a sledování

| Nástroj | Popis | Mění data |
| --- | --- | --- |
| `list_shipments` | Vypíše zásilky s filtry a stránkováním. | Ne |
| `get_shipment_detail` | Kompletní detail zásilky včetně sledovacího čísla dopravce. | Ne |
| `track_shipment` | Stav sledování s historií událostí. | Ne |

### E-commerce integrace

| Nástroj | Popis | Mění data |
| --- | --- | --- |
| `list_integrations` | Vypíše napojené e-shopové integrace (Shopify, Upgates, eBay, …) a jejich stav. | Ne |
| `run_integration_sync` | Spustí import nových objednávek ze všech aktivních integrací do košíku zásilek. | Ano |
| `get_integration_logs` | Vrátí poslední záznamy logu dané integrace (výsledky importu, chyby). | Ne |

### Košík (rozpracované zásilky)

Košík obsahuje zásilky připravené k objednání — například importované z e-shopových integrací.
Nic v košíku není objednáno ani účtováno, dokud zásilky závazně neodešlete.

| Nástroj | Popis | Mění data |
| --- | --- | --- |
| `list_shipment_drafts` | Vypíše rozpracované zásilky v košíku. | Ne |
| `update_shipment_draft` | Upraví rozpracovanou zásilku: rozměry a hmotnost balíků, dopravce, datum svozu, referenční číslo nebo adresy. Zásilka zůstává v košíku neobjednaná. | Ano |
| `submit_shipment_drafts` | Závazně objedná vybrané zásilky z košíku (zpoplatněná operace), volitelně včetně objednání svozu kurýrem. | Ano |

### Štítky

| Nástroj | Popis | Mění data |
| --- | --- | --- |
| `print_label` | Vygeneruje přepravní štítek (odkaz na PDF nebo base64). | Ne |

## Typický pracovní postup

1. **`get_profile`** – načtení výchozí adresy odesílatele.
2. **`get_rates`** – porovnání cen dopravců.
3. **`search_parcel_points`** – vyhledání výdejního místa (Home2Shop / Shop2Shop).
4. **`create_shipment`** – založení zásilky u vybraného dopravce.
5. **`print_label`** – stažení štítku k tisku.
6. **`track_shipment`** – sledování stavu zásilky.

Pro e-shopy s napojenou integrací:

1. **`run_integration_sync`** – import nových objednávek z e-shopu do košíku.
2. **`list_shipment_drafts`** – kontrola importovaných zásilek.
3. **`update_shipment_draft`** – doplnění rozměrů, změna dopravce či opravy adres.
4. **`submit_shipment_drafts`** – závazné objednání vybraných zásilek.
5. **`print_label`** – tisk štítků.

## Ukázkové dotazy

**Porovnání cen**

- „Jaké jsou ceny dopravy pro balík 30×20×15 cm, 3 kg z Prahy do Brna?"
- „Porovnej ceny dopravců pro zásilku 5 kg do Bratislavy."
- „Kolik stojí poslat 2 balíky z Ostravy do Berlína?"

**Založení zásilky**

- „Pošli balík přes DPD Janu Novákovi, Příčná 5, Brno 602 00, 2 kg."
- „Vytvoř zásilku Zásilkovnou na výdejní místo 12345, příjemce Eva Malá, telefon 777123456."
- „Objednej PPL s dobírkou 500 Kč na účet 1234567890/0100."

**Sledování a přehled**

- „Kde je moje zásilka IZ123456?"
- „Zobraz mi posledních 10 zásilek."
- „Najdi všechny nedoručené zásilky DPD z minulého týdne."
- „Ukaž mi zásilky s nezaplacenou dobírkou za poslední měsíc."

**Štítky**

- „Vytiskni štítek pro zásilku IZ123456."
- „Potřebuji štítek A6 pro termotiskárnu."

**Hromadné odesílání**

- „(nahrání souboru Excel) Pošli všechny zásilky z tohoto souboru přes DPD."

**E-shop a košík**

- „Stáhni nové objednávky z mého e-shopu."
- „Ukaž mi, co mám v košíku."
- „Změň u zásilky pro pana Nováka dopravce na DPD."
- „Objednej všechny zásilky v košíku a rovnou objednej i svoz na zítra."
- „Proč se včera nenaimportovaly objednávky ze Shopify?"

**Zrušení**

- „Zruš zásilku IZ123456."

## Výchozí hodnoty a konvence

- **Výchozí rozměr balíku:** pokud rozměry neuvedete, použije se 20 × 20 × 20 cm, 1 kg. U **FedEx a UPS vždy uvádějte přesné rozměry** – každý centimetr ovlivňuje cenu.
- **ID zásilek:** zásilky Zaslat používají formát `IZxxxxx` (např. `IZ123456`). Liší se od sledovacího čísla dopravce – to získáte pomocí `get_shipment_detail`.
- **Kódy zemí:** ISO 3166-1 alpha-2 (`CZ`, `SK`, `DE`).
- **PSČ:** bez mezer (`60200`, nikoli `602 00`).

## Podpora

- E-mail: [admin@zaslat.cz](mailto:admin@zaslat.cz)