# upgates-com-mcp

MCP konektor pro **Upgates** e-shop API v2. Čtecí přístup k objednávkám,
fakturám, produktům, zákazníkům a konfiguraci e-shopu s pseudonymizací
osobních údajů.

Součást platformy [OpenMCP.cz](https://openmcp.cz).

> **Poznámka k historii:** konektor původně vznikl v TypeScriptu. Od
> `a8f71aa` (7/2026) je implementován v Pythonu nad `openmcp-sdk`; TS strom
> byl odstraněn a je dohledatelný v git historii.

## Rychlý start

```bash
python -m venv .venv && . .venv/bin/activate
pip install -e .
export OPENMCP_MODE=local-stdio
export UPGATES_API_URL="https://vas-eshop.admin.s17.upgates.com/api/v2"
export UPGATES_API_LOGIN="api-login"
export UPGATES_API_KEY="api-klic"
export OPENMCP_PII_SALT="$(openssl rand -hex 32)"
python -m connector
```

`pip` si `openmcp-sdk` stáhne z GitHubu podle commitu připnutého
v `pyproject.toml` — na PyPI SDK není, protože tam jméno patří
nesouvisejícímu projektu. Bez přístupu k GitHubu (nebo když chcete přesně
ten snapshot, se kterým se staví produkční image) použijte vendorovaný archiv
z repozitáře:

```bash
python release/materialize_sdk.py --root . --output /tmp/openmcp-sdk
pip install /tmp/openmcp-sdk -e .
```

API přístup se zakládá v **Upgates Admin → Doplňky → API**.

`OPENMCP_PII_SALT` je povinný — bez něj konektor záměrně nenastartuje. Tichý
fallback na náhodný salt by zrušil stabilitu pseudonymizačních tokenů
a projevilo by se to až po restartu.

## Nástroje (23)

Všechny jsou **pouze ke čtení**; konektor nezapisuje ani nemaže.

| Oblast | Nástroje |
|---|---|
| Objednávky | `list_orders`, `get_order_history`, `list_order_statuses` |
| Faktury | `list_invoices` |
| Produkty | `list_products`, `list_products_simple`, `list_categories`, `list_labels`, `list_availabilities`, `list_manufacturers`, `list_parameters`, `list_pricelists` |
| Zákazníci | `list_customers`, `list_carts` |
| Doprava a platby | `list_shipments`, `list_payments`, `list_vouchers` |
| E-shop | `get_shop_config`, `get_shop_owner`, `get_languages` |
| Webhooky | `list_webhooks`, `list_webhook_events` |
| Diagnostika | `get_api_status` |

Seznam musí odpovídat `display.tools` v `connector.yaml` — z něj platforma
klasifikuje oprávnění nástrojů.

## Osobní údaje

Údaje zákazníků (e-maily, telefony, jména, adresy, IČO/DIČ, bankovní spojení)
se před odesláním do modelu nahradí stabilními tokeny typu
`<EMAIL_3f9c1a2b4d5e>`. Token je jednosměrný HMAC — nedá se rozšifrovat zpět
a nikde nevzniká re-identifikační mapa.

Katalogová data (produkty, kategorie, ceny) se nepseudonymizují. Ochranu
osobních údajů nelze operátorskou konfigurací vypnout.

## Konfigurace

| Klíč | Typ | Popis |
|---|---|---|
| `api_url` | credential | základní URL API v2 e-shopu |
| `api_login` | credential | přihlašovací jméno API klíče |
| `api_key` | credential (secret) | API klíč |

V režimu `local-stdio` se čtou z env jako `UPGATES_<KEY>` velkými písmeny.

## Testy

```bash
python -m pytest tests -q
openmcp-sdk validate connector.yaml
```

## Dokumentace

- [`docs/anonymization.md`](docs/anonymization.md) — pseudonymizace
- [`docs/readonly.md`](docs/readonly.md) — read-only režim
- [`docs/defaults.md`](docs/defaults.md) — výchozí hodnoty a limity
- [`docs/tools.md`](docs/tools.md) — nástroje
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — postup a nároky na změny
- [`SECURITY.md`](SECURITY.md) — hlášení zranitelností

API specifikaci Upgates repozitář nešíří (viz `.gitignore`); aktuální verzi
najdete v [dokumentaci Upgates](https://www.upgates.cz/a/upgates-api).

## Licence

MIT — viz [LICENSE](LICENSE).