# MCP-szerver

> A Haszno MCP-szerver referenciája — telepítés, konfiguráció és mind az 51 megvalósított eszköz bemeneti sémákkal és példákkal.

## Áttekintés

A Haszno MCP-szerver (`haszno-mcp`) a Haszno API-t `haszno_*` eszközök formájában teszi elérhetővé bármely MCP-kompatibilis AI-agent-kliens számára: Claude Code, Claude Desktop, Cursor és mások. **stdio** csatornán kommunikál, a Model Context Protocol szabvány szerint.

Az MCP-szerver a hitelesítési adatait környezeti változókból vagy a `~/.config/haszno/config.json` konfigurációs fájlból olvassa. Ezt a fájlt a [CLI](cli.md) `haszno login` parancsa (vagy a `haszno_account_configure` eszköz) írja. A CLI ugyanezt a fájlt olvassa, így egy bejelentkezés mindkettőt beállítja; a jelzők és a környezeti változók elsőbbséget élveznek vele szemben.

> [!NOTE]
> Ez egy fejlesztői előzetes. A `https://haszno.com` hosztolt demó szintetikus mintaadatokat ad vissza. Az írási műveletek és a védett végpontok a demón `401`-et adnak vissza, hacsak nincs a Haszno csapatától kapott hozzáférésed.

---

## Átvitel

A szerver az `@modelcontextprotocol/sdk` csomag `StdioServerTransport` osztályát használja. Minden stdio-alapú szervereket támogató MCP-kliens kompatibilis.

---

## Telepítés

### Ajánlott: egylépéses telepítő

A skill repóban lévő egylépéses telepítő egyszerre telepíti az MCP-szervert, a CLI-t és az agent skillt:

```bash
curl -fsSL https://raw.githubusercontent.com/haszno-labs/haszno-skill/main/install.sh | bash
```

Mit csinál a szkript:

1. Klónozza a `haszno-mcp`-t (és a `haszno-cli`-t, `haszno-skill`-t) a `~/.haszno/` mappába.
2. Futtatja az `npm install && npm run build` parancsot az MCP-szerveren.
3. Regisztrálja a szervert a Claude Code-ban: `claude mcp add haszno --scope user -- node ~/.haszno/haszno-mcp/dist/index.js` (kihagyja, ha a `claude` parancs nem található).
4. Átmásolja a skill fájlokat a `~/.claude/skills/haszno/` mappába.

### Manuális telepítés

```bash
git clone https://github.com/haszno-labs/haszno-mcp ~/.haszno/haszno-mcp
cd ~/.haszno/haszno-mcp
npm install
npm run build
```

Ezután regisztráld a kliensednél (lásd [Kliens-beállítás](#client-setup)).

---

## Kliens-beállítás

### Claude Code

```bash
claude mcp add haszno --scope user -- node ~/.haszno/haszno-mcp/dist/index.js
```

### Általános mcpServers JSON

Ezt a blokkot használd a `claude_desktop_config.json`-ban, `.cursor/mcp.json`-ban, vagy bármely más MCP-kliens-konfigurációban, amely elfogadja az `mcpServers` mezőt:

```json
{
  "mcpServers": {
    "haszno": {
      "command": "node",
      "args": ["~/.haszno/haszno-mcp/dist/index.js"],
      "env": {
        "HASZNO_API_URL": "https://haszno.com",
        "HASZNO_API_KEY": "your-api-key"
      }
    }
  }
}
```

> [!TIP]
> A `HASZNO_API_KEY` elhagyható a nyilvános demó használatához. Kulcs nélkül csak a [Mi működik hitelesítés nélkül](#auth-public) részben felsorolt eszközök működnek.

### npx változat

A csomagok nincsenek közzétéve az npm-tárban (mindkettőnél `"private": true` van a `package.json`-ban). Ha van Node 20+ és hálózati hozzáférésed, egy GitHub-forrásra hivatkozó `npx` parancs is működik:

```bash
claude mcp add haszno -- npx -y github:haszno-labs/haszno-mcp
```

---

## Konfiguráció

### Környezeti változók

| Változó | Leírás |
|---|---|
| `HASZNO_API_URL` | API-alapcím. Alapértelmezés: `https://haszno.com`. |
| `HASZNO_API_KEY` | API-kulcs, az `x-api-key` fejlécben küldve. |
| `HASZNO_BASIC` | `felhasználó:jelszó` a HTTP Basic hitelesítéshez. Csak akkor használja, ha nincs API-kulcs. |
| `ARFUTAR_API_URL` | Örökölt tartalék a `HASZNO_API_URL` helyett. |
| `ARFUTAR_API_KEY` | Örökölt tartalék a `HASZNO_API_KEY` helyett. |
| `ARFUTAR_BASIC` | Örökölt tartalék a `HASZNO_BASIC` helyett. |

### Konfigurációs fájl

Az MCP-szerver a `~/.config/haszno/config.json` fájlt olvassa, és ha az nem létezik, a `~/.config/arfutar/config.json` fájlt. A fájlt a CLI `haszno login` parancsa vagy a `haszno_account_configure` eszköz írja. A CLI-vel ellentétben az MCP-szerver nem ellenőrzi, hogy a mentett kulcs a használt URL-hez tartozik-e: ha az MCP-szervernél felülírod a `HASZNO_API_URL`-t, add meg mellé a `HASZNO_API_KEY`-t is.

```json
{
  "apiUrl": "https://haszno.com",
  "apiKey": "haszno_live_..."
}
```

Az `apiKey` helyett a fájlban `basicAuth` (`felhasználó:jelszó`) is állhat.

### Elsőbbség (legmagasabbtól a legalacsonyabbig)

1. `HASZNO_API_URL` / `HASZNO_API_KEY` / `HASZNO_BASIC` környezeti változók.
2. `ARFUTAR_API_URL` / `ARFUTAR_API_KEY` / `ARFUTAR_BASIC` környezeti változók (örökölt tartalék, csak akkor számít, ha a megfelelő `HASZNO_*` változó nincs beállítva).
3. `~/.config/haszno/config.json`.
4. `~/.config/arfutar/config.json`.

A konfigurációs fájlt a szerver csak akkor olvassa, ha a környezetből sem API-kulcs, sem Basic hitelesítési adat nem jön, és csak egyszer, induláskor. A fájl módosítása után indítsd újra az MCP-szervert. Az API-kulcs mindig az `x-api-key` fejlécben megy; a Basic adatokat csak API-kulcs hiányában használja.

> [!NOTE]
> A `haszno_feeds_outbound_info` és a `haszno_orders_create_demo` csak a `HASZNO_API_URL` / `ARFUTAR_API_URL` környezeti változót nézi, a konfigurációs fájl `apiUrl` mezőjét soha.

### Mi működik hitelesítés nélkül

A `https://haszno.com` ellen ezek az eszközök API-kulcs nélkül is működnek, és szintetikus demóadatot adnak vissza: `haszno_ping`, `haszno_account_get_stats`, `haszno_account_get_impact`, `haszno_account_get_settings`, `haszno_account_list_suppliers`, `haszno_orders_list`, `haszno_orders_get`, `haszno_proposals_list`, `haszno_proposals_market`, `haszno_import_list_list`, `haszno_peers_invite_list` és `haszno_blog_latest`. A `haszno_feeds_outbound_info` `fetch_summary` nélkül és a `haszno_account_configure` egyáltalán nem hív API-t.

Minden más eszköz — az összes írási eszköz, és olyan olvasó eszközök is, mint a `haszno_catalog_*`, a `haszno_catalogue_search`, a `haszno_connections_list`, a `haszno_ideas_list`, valamint a `haszno_rules_*` és `haszno_automation_get` olvasók — hitelesítés nélkül `401`-et ad.

---

## Megvalósított eszközök

A szerver pontosan **51 eszközt** regisztrál 11 területen. A tizenkettedik terület, a saját bolt termékei, még nincs megvalósítva — lásd [Tervezett eszközök](#planned).

| Terület | Eszközök |
|---|---|
| [Fiók és beállítások](#tools-account) | 7 |
| [Beszállítói katalógus](#tools-catalog) | 6 |
| [Partnerkatalógus-keresés és importlista](#tools-catalogue) | 4 |
| [Webshop-bekötések](#tools-connections) | 1 |
| [Árjavaslatok](#tools-proposals) | 5 |
| [Automatizálási szabályok](#tools-rules) | 12 |
| [Rendelések](#tools-orders) | 5 |
| [Termékötletek](#tools-ideas) | 4 |
| [Feedek](#tools-feeds) | 3 |
| [P2P partner-meghívók](#tools-peers) | 3 |
| [Blog / piaci betekintők](#tools-blog) | 1 |

### A confirm paraméter

A legtöbb írási eszköznek van `confirm` paramétere, de ez négyféleképpen viselkedhet. Hogy melyik érvényes, azt az adott eszköz paramétertáblája mondja meg:

- **`true` (literál):** a séma csak a `true` értéket fogadja el. Ha elhagyod vagy `false`-t adsz, a bemenet-ellenőrzés elbukik, és semmi nem megy el.
- **logikai, `false` esetén előnézet:** a `confirm` kötelező. `false` esetén az eszköz előnézetet ad, és nem hív API-t.
- **logikai, `false` esetén hiba:** a `confirm` kötelező. `false` esetén az eszköz „Safety gate” hibát ad, és nem hív API-t.
- **logikai, alapértelmezés `false`:** a `confirm` elhagyható. Ha elhagyod vagy `false`, az eszköz próbafuttatási összegzést ad, és nem hív API-t.

A jelvény azt mutatja, módosít-e adatot az eszköz: a **Csak olvasás** eszközök csak olvasnak (némelyiknek mégis kell `confirm: true`, mert fizetős AI-hívást indíthat), az **Írás** eszközök adatot módosítanak.

---

## Fiók és beállítások

| Eszköz | Mód | Leírás |
|---|---|---|
| `haszno_ping` | **Csak olvasás** | API-kapcsolat ellenőrzése. |
| `haszno_account_get_stats` | **Csak olvasás** | Irányítópult-pillanatkép: termék-, veszteséges, piac feletti, javítandó és rendelésszám. |
| `haszno_account_get_impact` | **Csak olvasás** | Haszon-mérő egy időablakra. |
| `haszno_account_get_settings` | **Csak olvasás** | Aktuális árazási szabályok. |
| `haszno_account_list_suppliers` | **Csak olvasás** | A bolt saját beszállítói bekötései. |
| `haszno_account_update_settings` | **Írás** | Árazási szabályok frissítése. |
| `haszno_account_configure` | **Írás** | API-hitelesítési adatok mentése a helyi konfigurációs fájlba (API-hívás nélkül). |

### haszno_ping

A `GET /api/health` végpontot hívja. **Csak olvasás**

**Mikor hívd meg:** minden más eszköz előtt, a kapcsolat ellenőrzésére.

**Bemeneti paraméterek:** nincs.

**Visszatérési érték:** siker esetén `{ ok: true }`.

**Példahívás:**

```json
{
  "name": "haszno_ping",
  "arguments": {}
}
```

---

### haszno_account_get_stats

A bolt irányítópult-pillanatképét adja vissza (`GET /api/stats`). **Csak olvasás**

**Mikor hívd meg:** napi állapotellenőrzés elején, vagy ha a felhasználó áttekintést kér.

**Bemeneti paraméterek:** nincs.

**Visszatérési érték:** egy objektum, amelynek mezői:

| Mező | Típus | Leírás |
|---|---|---|
| `products` | egész szám | A katalógusban lévő termékek száma. |
| `losing` | egész szám | Jelenleg önköltség alatt árazott termékek. |
| `overMarket` | egész szám | A legolcsóbb piaci versenytársnál drágább termékek. |
| `toFix` | egész szám | Függő árazási problémás termékek. |
| `orders` | egész szám | Beérkezett rendelések száma. |

**Példahívás:**

```json
{
  "name": "haszno_account_get_stats",
  "arguments": {}
}
```

---

### haszno_account_get_impact

A Haszno árazásának hatását adja vissza az utolsó N napra (`GET /api/impact`). **Csak olvasás**

**Mikor hívd meg:** ha a felhasználó többletprofitról, haszonjavulásról vagy az automatikus rendeléstovábbításról kérdez.

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `days` | egész szám, 1–365 | Nem | Visszatekintési ablak napokban. Ha elhagyod, az API 30-at használ. |

**Visszatérési érték:** `{ days, extraProfit, baseline, pctGain, orders, autoForwardedOrders }` — a pénzértékek bruttó HUF-ban.

**Példahívás:**

```json
{
  "name": "haszno_account_get_impact",
  "arguments": { "days": 7 }
}
```

---

### haszno_account_get_settings

A bolt árazási beállításait adja vissza (`GET /api/settings`). **Csak olvasás**

**Mikor hívd meg:** bármilyen árazási változtatás javaslása előtt, és mindig a `haszno_account_update_settings` előtt.

**Bemeneti paraméterek:** nincs.

**Visszatérési érték:** `{ undercutPct, minMarginPct, vatPct, automationPaused }`.

**Példahívás:**

```json
{
  "name": "haszno_account_get_settings",
  "arguments": {}
}
```

---

### haszno_account_list_suppliers

A bolt saját beszállítói bekötéseit adja vissza — azokat a beszállítókat, akiknek a katalógusát már importáltad (`GET /api/suppliers`). Ez nem a hálózati lista; ahhoz a `haszno_catalog_list_suppliers` kell. **Csak olvasás**

**Bemeneti paraméterek:** nincs.

**Visszatérési érték:** `{ id, name, orderMode, email, network, category, country, shopUrl, createdAt }` objektumok tömbje.

**Példahívás:**

```json
{
  "name": "haszno_account_list_suppliers",
  "arguments": {}
}
```

---

### haszno_account_update_settings

Lecseréli a bolt árazási szabályait (`PUT /api/settings`). Mindhárom számmező kötelező, ezért előbb olvasd ki az aktuális értékeket a `haszno_account_get_settings` eszközzel, és a nem változó értékeket is küldd vissza. **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `undercutPct` | szám, 0–100 | **Igen** | Hány százalékkal menjen a legolcsóbb piaci ár alá. |
| `minMarginPct` | szám, 0–100 | **Igen** | Minimális nettó haszonszázalék. |
| `vatPct` | szám, 0–100 | **Igen** | Áfakulcs a bruttó/nettó átváltáshoz (pl. `27`). |
| `confirm` | `true` (literál) | **Igen** | Értéke csak `true` lehet. |

**Visszatérési érték:** a frissített beállítások objektuma.

**Példahívás:**

```json
{
  "name": "haszno_account_update_settings",
  "arguments": { "undercutPct": 1, "minMarginPct": 12, "vatPct": 27, "confirm": true }
}
```

---

### haszno_account_configure

A hitelesítési adatokat a `~/.config/haszno/config.json` fájlba írja (`600`-as jogosultsággal), a fájlban már meglévő többi kulcsot megtartva. API-t nem hív. A futó szerver az induláskor betöltött adatokkal dolgozik tovább, ezért utána indítsd újra. **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `apiUrl` | sztring (URL) | **Igen** | API-alapcím, pl. `https://haszno.com`. |
| `apiKey` | sztring | Nem | API-kulcs, az `x-api-key` fejlécben küldve. |
| `basicAuth` | sztring, `felhasználó:jelszó` | Nem | HTTP Basic hitelesítési adatok. |
| `confirm` | `true` (literál) | **Igen** | Értéke csak `true` lehet. |

Az `apiKey` és a `basicAuth` közül pontosan egyet adj meg; ha mindkettőt vagy egyiket sem, az eszköz hibát ad.

**Visszatérési érték:** `{ saved: true, configFile, apiUrl, authMethod }`.

**Példahívás:**

```json
{
  "name": "haszno_account_configure",
  "arguments": { "apiUrl": "https://haszno.com", "apiKey": "haszno_live_...", "confirm": true }
}
```

---

## Beszállítói katalógus (`haszno_catalog_*`)

A partnerhálózat beszállítói, akiket a bolt beköthet. A `haszno_catalog_list_categories` és a `haszno_catalog_list_suppliers` is a `GET /api/network/suppliers` végpontot kéri le, és helyben szűr és lapoz.

| Eszköz | Mód | Leírás |
|---|---|---|
| `haszno_catalog_list_categories` | **Csak olvasás** | A partnerhálózat egyedi kategóriái. |
| `haszno_catalog_list_suppliers` | **Csak olvasás** | Hálózati beszállítók listája. |
| `haszno_catalog_supplier_products` | **Csak olvasás** | Egy beszállító termékkatalógusa. |
| `haszno_catalog_supplier_view` | **Csak olvasás** | Összesített viszonteladói piaci nézet egy beszállítóra. |
| `haszno_catalog_connect_supplier` | **Írás** | Hálózati beszállító bekötése és termékeinek importálása. |
| `haszno_catalog_sync_supplier` | **Írás** | Költség és készlet frissítése egy bekötött beszállítótól. |

### haszno_catalog_list_categories

**Csak olvasás**

**Mikor hívd meg:** ha érvényes `category` értékeket keresel a `haszno_catalog_list_suppliers` és a `haszno_catalog_supplier_products` eszközhöz.

**Bemeneti paraméterek:** nincs.

**Visszatérési érték:** `{ categories: string[] }`, ábécérendben.

**Példahívás:**

```json
{
  "name": "haszno_catalog_list_categories",
  "arguments": {}
}
```

---

### haszno_catalog_list_suppliers

**Csak olvasás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `category` | sztring | Nem | Szűrés kategóriára (kis- és nagybetűre érzéketlen, pontos egyezés). |
| `search` | sztring | Nem | Részsztring-keresés a beszállító nevében (kis- és nagybetűre érzéketlen). |
| `connected` | logikai | Nem | `true` esetén csak azok a beszállítók, akiktől a bolt már importál. A `false` nem szűr. |
| `page` | egész szám, min. 1 | Nem | Oldalszám. Alapértelmezés: `1`. |
| `limit` | egész szám, 1–100 | Nem | Elemek oldalanként. Alapértelmezés: `25`. |

**Visszatérési érték:** `{ suppliers: [{ id, name, category, country, connected, productCount, avgResellerMarginPct, shopUrl }], total, page, pages }`.

**Példahívás:**

```json
{
  "name": "haszno_catalog_list_suppliers",
  "arguments": { "category": "kert", "limit": 10 }
}
```

---

### haszno_catalog_supplier_products

Egy partner-beszállító katalógusának termékeit adja vissza (`GET /api/network/suppliers/:id/products`), helyben szűrve és lapozva. **Csak olvasás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `supplier_id` | egész szám | **Igen** | Beszállító-azonosító (a `haszno_catalog_list_suppliers` eszközből). |
| `search` | sztring | Nem | Részsztring-keresés terméknévben vagy SKU-ban (kis- és nagybetűre érzéketlen). |
| `category` | sztring | Nem | Szűrés termékkategóriára (kis- és nagybetűre érzéketlen). |
| `page` | egész szám, min. 1 | Nem | Oldalszám. Alapértelmezés: `1`. |
| `limit` | egész szám, 1–100 | Nem | Elemek oldalanként. Alapértelmezés: `25`. |

**Visszatérési érték:** `{ products: [{ id, sku, name, ean, category, wholesaleNet, rrpGross, stock, potentialMargin }], total, page, pages }`. A `wholesaleNet` nettó HUF; az `rrpGross` és a `potentialMargin.priceGross` bruttó HUF.

**Példahívás:**

```json
{
  "name": "haszno_catalog_supplier_products",
  "arguments": { "supplier_id": 3 }
}
```

---

### haszno_catalog_supplier_view

A beszállító adatait és termékenként összesített viszonteladói piaci statisztikát ad vissza (`GET /api/network/supplier-view/:supplierId`): `resellerCount`, `minGross` / `avgGross` / `maxGross`, `belowRrp`, `lossCount` és `saturation` (0–100). **Csak olvasás**

**Mikor hívd meg:** egy beszállító értékelésére, mielőtt bekötöd.

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `supplier_id` | egész szám | **Igen** | Beszállító-azonosító. |

**Példahívás:**

```json
{
  "name": "haszno_catalog_supplier_view",
  "arguments": { "supplier_id": 3 }
}
```

---

### haszno_catalog_connect_supplier

Beköt egy partner-beszállítót, és az összes termékét importálja a boltba (`POST /api/network/suppliers/:id/connect`). **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `supplier_id` | egész szám | **Igen** | Beszállító-azonosító. |
| `confirm` | logikai, `false` esetén előnézet | **Igen** | `true` végrehajtja; `false` előnézetet ad API-hívás nélkül. |

**Visszatérési érték:** `{ status, imported, skipped }`.

**Példahívás:**

```json
{
  "name": "haszno_catalog_connect_supplier",
  "arguments": { "supplier_id": 3, "confirm": true }
}
```

---

### haszno_catalog_sync_supplier

Szinkronizálja a beszerzési árakat és a készletet egy bekötött partner-beszállítótól (`POST /api/network/suppliers/:id/sync`). **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `supplier_id` | egész szám | **Igen** | Egy bekötött beszállító azonosítója. |
| `confirm` | logikai, `false` esetén előnézet | **Igen** | `true` végrehajtja; `false` előnézetet ad API-hívás nélkül. |

**Visszatérési érték:** `{ costChanges, stockOuts, total }`.

**Példahívás:**

```json
{
  "name": "haszno_catalog_sync_supplier",
  "arguments": { "supplier_id": 3, "confirm": true }
}
```

---

## Partnerkatalógus-keresés és importlista

| Eszköz | Mód | Leírás |
|---|---|---|
| `haszno_catalogue_search` | **Csak olvasás** | Keresés a partner-termékkatalógusban. |
| `haszno_import_list_list` | **Csak olvasás** | Az importlista elemei. |
| `haszno_import_list_add` | **Írás** | Katalógustermékek felvétele az importlistára. |
| `haszno_import_list_push` | **Írás** | Importlista-elemek kitolása egy bekötött webshopba. |

### haszno_catalogue_search

Keres a partner-termékkatalógusban (`GET /api/catalogue/products`). **Csak olvasás**

**Mikor hívd meg:** ha a felhasználó új, listázható termékeket keres.

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `q` | sztring | Nem | Szabad szöveges keresés terméknévben vagy kategóriában. |
| `cats` | sztring | Nem | Vesszővel elválasztott kategóriakulcsok. |
| `partner` | pozitív egész szám | Nem | Szűrés beszállító-/partnerazonosítóra. |
| `minMarginPct` | szám | Nem | Minimális haszonszázalék. |
| `maxPrice` | szám | Nem | Legmagasabb ajánlott fogyasztói ár, bruttó HUF. |
| `minPrice` | szám | Nem | Legalacsonyabb ajánlott fogyasztói ár, bruttó HUF. |
| `inStock` | logikai | Nem | `true` esetén csak készleten lévő termékek. |
| `hasImage` | logikai | Nem | `true` esetén csak képpel rendelkező termékek. |
| `country` | sztring | Nem | A beszállító országkódja, pl. `HU`, `DE`. |
| `sort` | `margin_desc` \| `price_asc` \| `price_desc` \| `name_asc` | Nem | Rendezés. Alapértelmezés: `name_asc`. |
| `page` | egész szám, min. 1 | Nem | Oldalszám. Alapértelmezés: `1`. |
| `pageSize` | egész szám, 1–100 | Nem | Elemek oldalanként. Alapértelmezés: `24`. |

**Visszatérési érték:** `{ items, total, facets }`.

**Példahívás:**

```json
{
  "name": "haszno_catalogue_search",
  "arguments": { "cats": "kert", "minMarginPct": 20, "inStock": true, "sort": "margin_desc" }
}
```

---

### haszno_import_list_list

Az importlista elemeit listázza — ez az átmeneti terület a katalógus és a webshop között (`GET /api/import-list`). **Csak olvasás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `status` | `varakozik` \| `kuldve` \| `kesz` \| `hiba` | Nem | Szűrés kitolási állapotra. |
| `partner` | pozitív egész szám | Nem | Szűrés beszállító-/partnerazonosítóra. |
| `q` | sztring | Nem | Szabad szöveges keresés terméknévben vagy SKU-ban. |

**Visszatérési érték:** `{ items, total }`.

**Példahívás:**

```json
{
  "name": "haszno_import_list_list",
  "arguments": { "status": "varakozik" }
}
```

---

### haszno_import_list_add

Katalógustermékeket vesz fel az importlistára (`POST /api/import-list`). Webshopban addig nem jön létre termék, amíg a `haszno_import_list_push` le nem fut. Ennek az eszköznek nincs `confirm` paramétere. **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `networkProductIds` | pozitív egészek tömbje, 1–100 elem | **Igen** | Katalógustermék-azonosítók (a `haszno_catalogue_search` eszközből). |

**Visszatérési érték:** `{ added, skipped }` — a `skipped` a listán már szereplő termékeket számolja.

**Példahívás:**

```json
{
  "name": "haszno_import_list_add",
  "arguments": { "networkProductIds": [101, 102, 103] }
}
```

---

### haszno_import_list_push

Importlista-elemeket tol ki egy bekötött webshopba. A bekötés állapota `kapcsolva` kell legyen (ellenőrizd a `haszno_connections_list` eszközzel). **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `ids` | pozitív egészek tömbje, legalább 1 | **Igen** | Importlista-elemek azonosítói (a `haszno_import_list_list` eszközből). |
| `targetConnectionId` | pozitív egész szám | Nem | Webshop-bekötés azonosítója. Ha megadod, az eszköz a `POST /api/connect/stores/:id/push` végpontot hívja, és `{ pushed, failed, errors }` értéket ad vissza. Nélküle a `POST /api/import-list/push` végpontot hívja, és `{ pushed }` értéket ad vissza. |
| `confirm` | logikai, `false` esetén előnézet | **Igen** | `true` végrehajtja; `false` előnézetet ad API-hívás nélkül. |

**Példahívás:**

```json
{
  "name": "haszno_import_list_push",
  "arguments": { "ids": [201, 202], "targetConnectionId": 5, "confirm": true }
}
```

---

## Webshop-bekötések

| Eszköz | Mód | Leírás |
|---|---|---|
| `haszno_connections_list` | **Csak olvasás** | Bekötött webshopok listája. |

### haszno_connections_list

A bolt webshop-bekötéseit listázza (`GET /api/connect/stores`); az állapotszűrést helyben végzi. **Csak olvasás**

**Mikor hívd meg:** a `haszno_import_list_push` előtt, a `targetConnectionId` megkereséséhez.

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `status` | `uj` \| `domain_ok` \| `kapcsolva` \| `hiba` | Nem | Szűrés a bekötés állapotára. |

**Visszatérési érték:** `{ connections: [{ id, platform, name, status, domain, lastError, connectedAt, lastSyncAt }] }`.

**Példahívás:**

```json
{
  "name": "haszno_connections_list",
  "arguments": { "status": "kapcsolva" }
}
```

---

## Árjavaslatok

| Eszköz | Mód | Leírás |
|---|---|---|
| `haszno_proposals_list` | **Csak olvasás** | Árjavaslatok listája. |
| `haszno_proposals_market` | **Csak olvasás** | Egy termék függő árjavaslatai piaci kontextussal. |
| `haszno_proposals_approve` | **Írás** | Árjavaslatok jóváhagyása és az árak alkalmazása. |
| `haszno_proposals_reject` | **Írás** | Árjavaslatok elutasítása. |
| `haszno_proposals_rollback` | **Írás** | Egy jóváhagyott köteg visszagörgetése. |

> [!WARNING]
> Amíg az automatizálás vészkapcsolója be van kapcsolva (a `haszno_automation_get` `paused: true` értéket ad), az API HTTP `409`-cel elutasítja az árjavaslatok jóváhagyását. Ha a `haszno_proposals_approve` `409`-cel bukik el, nézd meg a kapcsolót.

### haszno_proposals_list

Az árjavaslatokat listázza (`GET /api/proposals`). A termékszűrést és a lapozást helyben végzi. **Csak olvasás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `status` | `pending` \| `approved` \| `rejected` \| `rolled_back` | Nem | Szűrés állapotra. |
| `productId` | pozitív egész szám | Nem | Csak az adott termék árjavaslatai. |
| `limit` | egész szám, 1–100 | Nem | Legfeljebb ennyi árjavaslat. Alapértelmezés: `25`. |
| `offset` | egész szám, min. 0 | Nem | Ennyi árjavaslatot ugrik át. Alapértelmezés: `0`. |

**Visszatérési érték:** `{ _meta: { total, offset, limit, hasMore }, proposals: [{ id, productId, productName, productSku, oldPriceGross, proposedPriceGross, diffGross, reason, source, status, batchId, createdAt, decidedAt }] }`.

**Példahívás:**

```json
{
  "name": "haszno_proposals_list",
  "arguments": { "status": "pending" }
}
```

---

### haszno_proposals_market

Egy terméket ad vissza a jelenlegi, a javasolt és a piaci áraival, valamint a függő árjavaslataival, a legújabbal kezdve. A `GET /api/products` és a `GET /api/proposals?status=pending` végpontot olvassa. **Csak olvasás**

**Mikor hívd meg:** mielőtt egy termék árjavaslatait jóváhagyod vagy elutasítod.

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `productId` | pozitív egész szám | **Igen** | Termékazonosító (a `haszno_proposals_list` eszközből). |

**Visszatérési érték:** `{ product: { id, sku, name, supplierName, costNet, stock, listed, current, recommended, market, rrpGross }, pendingProposals: [...] }`.

**Példahívás:**

```json
{
  "name": "haszno_proposals_market",
  "arguments": { "productId": 42 }
}
```

---

### haszno_proposals_approve

Jóváhagyja az árjavaslatokat, és azonnal alkalmazza az árakat (`POST /api/proposals/approve`). Mentsd el a visszakapott `batchId` értéket — a `haszno_proposals_rollback` eszköznek szüksége van rá. **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `ids` | pozitív egészek tömbje | Nem | A jóváhagyandó árjavaslatok azonosítói. Ha elhagyod, **minden** függő árjavaslatot jóváhagy. |
| `confirm` | logikai, `false` esetén hiba | **Igen** | Értéke `true` kell legyen. |

**Visszatérési érték:** `{ batchId, applied, note }`.

**Példahívás:**

```json
{
  "name": "haszno_proposals_approve",
  "arguments": { "ids": [42, 43], "confirm": true }
}
```

---

### haszno_proposals_reject

Elutasítja az árjavaslatokat (`POST /api/proposals/reject`). Az árak nem változnak; az árjavaslatok `rejected` állapottal megmaradnak az előzményekben. **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `ids` | pozitív egészek tömbje, legalább 1 | **Igen** | Az elutasítandó árjavaslatok azonosítói. |
| `confirm` | logikai, `false` esetén hiba | **Igen** | Értéke `true` kell legyen. |

**Visszatérési érték:** `{ rejected, note }`.

**Példahívás:**

```json
{
  "name": "haszno_proposals_reject",
  "arguments": { "ids": [44], "confirm": true }
}
```

---

### haszno_proposals_rollback

Visszaállítja a jóváhagyott köteg előtti árakat (`POST /api/proposals/rollback`); az árjavaslatok állapota `rolled_back` lesz. **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `batchId` | nem üres sztring | **Igen** | A `haszno_proposals_approve` által visszaadott `batchId`. |
| `confirm` | logikai, `false` esetén hiba | **Igen** | Értéke `true` kell legyen. |

**Visszatérési érték:** `{ rolledBack, note }`.

**Példahívás:**

```json
{
  "name": "haszno_proposals_rollback",
  "arguments": { "batchId": "b-1234abcd", "confirm": true }
}
```

---

## Automatizálási szabályok

| Eszköz | Mód | Leírás |
|---|---|---|
| `haszno_rules_list_templates` | **Csak olvasás** | Beépített szabálysablonok. |
| `haszno_rules_list` | **Csak olvasás** | A bolt összes szabálya. |
| `haszno_rules_list_runs` | **Csak olvasás** | Szabályfuttatási napló. |
| `haszno_automation_get` | **Csak olvasás** | Az automatizálás vészkapcsolójának állapota. |
| `haszno_rules_create` | **Írás** | Szabály létrehozása. |
| `haszno_rules_update` | **Írás** | Szabály módosítása. |
| `haszno_rules_delete` | **Írás** | Szabály és futási előzményeinek törlése. |
| `haszno_rules_run` | **Írás** | Egy szabály kézi futtatása. |
| `haszno_rules_run_all` | **Írás** | Minden bekapcsolt `manual` szabály futtatása. |
| `haszno_rules_trigger` | **Írás** | Egy eseményre feliratkozott bekapcsolt szabályok futtatása. |
| `haszno_rules_undo_unlists` | **Írás** | Szabály által levett termékek visszalistázása. |
| `haszno_automation_set` | **Írás** | Az automatizálás szüneteltetése vagy folytatása. |

### haszno_automation_get

Az automatizálás globális vészkapcsolóját adja vissza (`GET /api/automation`). Amíg a `paused` értéke `true`, az árjavaslatok jóváhagyása HTTP `409`-et ad. **Csak olvasás**

**Bemeneti paraméterek:** nincs.

**Visszatérési érték:** `{ paused: boolean }`.

**Példahívás:**

```json
{
  "name": "haszno_automation_get",
  "arguments": {}
}
```

---

### haszno_rules_list_templates

A beépített szabálysablonokat listázza (`GET /api/rules/templates`), például `keszlet_or` (készlethiány-védelem), `arjavaslat` (árjavaslat piaci frissítéskor), `felar_savok` (felársávok) és `veszteseg_riasztas` (veszteségriasztás). **Csak olvasás**

**Bemeneti paraméterek:** nincs.

**Visszatérési érték:** minden sablon kulcsa, neve, leírása, eseménye, feltételei és műveletei.

**Példahívás:**

```json
{
  "name": "haszno_rules_list_templates",
  "arguments": {}
}
```

---

### haszno_rules_list

A bolt automatizálási szabályait listázza (`GET /api/rules`). **Csak olvasás**

**Bemeneti paraméterek:** nincs.

**Visszatérési érték:** minden szabály azonosítója, neve, bekapcsoltsága, eseménye, feltételei, műveletei, sablonkulcsa és létrehozási dátuma.

**Példahívás:**

```json
{
  "name": "haszno_rules_list",
  "arguments": {}
}
```

---

### haszno_rules_list_runs

A szabályfuttatási naplót adja vissza, a legújabbal kezdve (`GET /api/rule-runs`). A „Levéve” kezdetű összegzésű bejegyzések levételek, amelyeket a `haszno_rules_undo_unlists` visszacsinálhat. **Csak olvasás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `limit` | egész szám, 1–200 | Nem | Legfeljebb ennyi bejegyzés. Alapértelmezés: `25`. |

**Visszatérési érték:** bejegyzések futásazonosítóval, szabályazonosítóval, szabálynévvel, eseménnyel, termékazonosítóval (vagy `null`), összegzéssel és időbélyeggel.

**Példahívás:**

```json
{
  "name": "haszno_rules_list_runs",
  "arguments": { "limit": 10 }
}
```

---

### haszno_rules_create

Létrehoz egy szabályt (`POST /api/rules`). **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `name` | sztring, 1–120 karakter | **Igen** | A szabály neve. |
| `trigger` | sztring | **Igen** | `feed_import`, `market_price`, `manual` vagy egyéni sztring. |
| `actions` | `{ type, params? }` objektumok tömbje | **Igen** | Műveletek az illeszkedő termékeken. Ismert `type` értékek: `unlist`, `propose_price`, `notify`. A `params` objektum. |
| `conditions` | `{ field, op, value? }` objektumok tömbje | Nem | Mindnek teljesülnie kell. Az `op` értéke `lt`, `lte`, `gt`, `gte`, `eq`, `neq` vagy `changed`; a `value` szám, sztring vagy `null`. Ismert `field` értékek: `stock`, `marginPct`, `recommendedChange`, `priceGross`. |
| `enabled` | logikai | Nem | A szerveren alapértelmezésben `true`. |
| `template` | sztring vagy `null` | Nem | A sablon kulcsa, amelyből a szabály készült (a `haszno_rules_list_templates` eszközből). |
| `confirm` | `true` (literál) | **Igen** | Értéke csak `true` lehet. |

**Visszatérési érték:** a létrehozott szabály az `id` mezővel.

**Példahívás:**

```json
{
  "name": "haszno_rules_create",
  "arguments": {
    "name": "Unlist when out of stock",
    "trigger": "feed_import",
    "conditions": [{ "field": "stock", "op": "lte", "value": 0 }],
    "actions": [{ "type": "unlist" }],
    "confirm": true
  }
}
```

---

### haszno_rules_update

Módosít egy szabályt (`PATCH /api/rules/:id`). Csak az elküldött mezők változnak. **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `id` | egész szám | **Igen** | Szabályazonosító (a `haszno_rules_list` eszközből). |
| `name` | sztring, 1–120 karakter | Nem | Új név. |
| `enabled` | logikai | Nem | `true` aktív, `false` szüneteltetett. |
| `trigger` | sztring | Nem | Új esemény. |
| `conditions` | `{ field, op, value? }` objektumok tömbje | Nem | Az összes feltételt lecseréli. |
| `actions` | `{ type, params? }` objektumok tömbje | Nem | Az összes műveletet lecseréli. |
| `confirm` | `true` (literál) | **Igen** | Értéke csak `true` lehet. |

**Példahívás:**

```json
{
  "name": "haszno_rules_update",
  "arguments": { "id": 7, "enabled": false, "confirm": true }
}
```

---

### haszno_rules_delete

Véglegesen törli a szabályt és a teljes futási előzményét (`DELETE /api/rules/:id`). Nem vonható vissza; ha csak megállítanád, használd a `haszno_rules_update` eszközt `enabled: false` értékkel. **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `id` | egész szám | **Igen** | A törlendő szabály azonosítója. |
| `confirm` | `true` (literál) | **Igen** | Értéke csak `true` lehet. |

**Példahívás:**

```json
{
  "name": "haszno_rules_delete",
  "arguments": { "id": 7, "confirm": true }
}
```

---

### haszno_rules_run

Egy szabályt futtat az összes érintett terméken, az eseményétől függetlenül (`POST /api/rules/:id/run`). **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `id` | egész szám | **Igen** | Szabályazonosító. |
| `confirm` | `true` (literál) | **Igen** | Értéke csak `true` lehet. |

**Visszatérési érték:** `{ applied, skipped, errors }`.

**Példahívás:**

```json
{
  "name": "haszno_rules_run",
  "arguments": { "id": 7, "confirm": true }
}
```

---

### haszno_rules_run_all

Minden bekapcsolt, `manual` eseményű szabályt lefuttat (`POST /api/rules/run-all`). **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `confirm` | `true` (literál) | **Igen** | Értéke csak `true` lehet. |

**Visszatérési érték:** összesített `{ applied, skipped, errors }`.

**Példahívás:**

```json
{
  "name": "haszno_rules_run_all",
  "arguments": { "confirm": true }
}
```

---

### haszno_rules_trigger

Lefuttat minden bekapcsolt szabályt, amely az adott eseményre figyel (`POST /api/rules/trigger`). **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `trigger` | sztring | **Igen** | `feed_import`, `market_price`, `manual` vagy egyéni sztring. |
| `product_ids` | egészek tömbje | Nem | A futás ezekre a termékekre korlátozva. Ha elhagyod, minden érintett terméken fut. |
| `confirm` | `true` (literál) | **Igen** | Értéke csak `true` lehet. |

**Visszatérési érték:** összesített `{ applied, skipped, errors }`.

**Példahívás:**

```json
{
  "name": "haszno_rules_trigger",
  "arguments": { "trigger": "market_price", "confirm": true }
}
```

---

### haszno_rules_undo_unlists

Visszalistázza a szabály által levett termékeket, és a naplóbejegyzéseket visszavontként jelöli (`POST /api/rule-runs/undo`). Csak a „Levéve” kezdetű összegzésű, még vissza nem vont bejegyzésekre hat. **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `ids` | egészek tömbje | Nem | Naplóbejegyzés-azonosítók (a `haszno_rules_list_runs` eszközből). Ezt **vagy** a `rule_id` + `at` párost használd. |
| `rule_id` | egész szám | Nem | Az adott szabály összes levételét visszavonja az `at` időpontban. |
| `at` | sztring | Nem | A szabályfutás ISO-időbélyege, a `rule_id` mellé. |
| `confirm` | `true` (literál) | **Igen** | Értéke csak `true` lehet. |

**Visszatérési érték:** `{ relisted }`.

**Példahívás:**

```json
{
  "name": "haszno_rules_undo_unlists",
  "arguments": { "ids": [311, 312], "confirm": true }
}
```

---

### haszno_automation_set

Be- vagy kikapcsolja az automatizálás globális vészkapcsolóját (`PUT /api/automation`). Az aktuális állapot újbóli beállítása ártalmatlan. **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `paused` | logikai | **Igen** | `true` szünetelteti az automatizálást és blokkolja a jóváhagyásokat; `false` folytatja. |
| `confirm` | `true` (literál) | **Igen** | Értéke csak `true` lehet. |

**Visszatérési érték:** `{ paused }`.

**Példahívás:**

```json
{
  "name": "haszno_automation_set",
  "arguments": { "paused": true, "confirm": true }
}
```

---

## Rendelések

A pénzértékek egész forintok, bruttó. Rendelésállapotok: `received`, `forwarded`, `shipped`, `error`.

| Eszköz | Mód | Leírás |
|---|---|---|
| `haszno_orders_list` | **Csak olvasás** | Rendelések listája, a legújabbal kezdve. |
| `haszno_orders_get` | **Csak olvasás** | Egy rendelés tételekkel és eseménynaplóval. |
| `haszno_orders_ship` | **Írás** | Rendelés feladottnak jelölése. |
| `haszno_orders_receive` | **Írás** | Bejövő rendelés beküldése. |
| `haszno_orders_create_demo` | **Írás** | Véletlenszerű demórendelés (csak demo/staging/localhost környezetben). |

### haszno_orders_list

A `GET /api/orders` végpontot kéri le, és tömör sorokat ad vissza eseménynapló nélkül; az állapotszűrést és a korlátot helyben alkalmazza. **Csak olvasás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `status` | `received` \| `forwarded` \| `shipped` \| `error` | Nem | Szűrés állapotra. |
| `limit` | egész szám, 1–50 | Nem | Legfeljebb ennyi sor. Alapértelmezés: `25`. |

**Visszatérési érték:** `{ orders: [{ id, externalId, customerName, address, status, totalGross, supplierOrderId, trackingNumber, itemCount, createdAt }], total, showing }`.

**Példahívás:**

```json
{
  "name": "haszno_orders_list",
  "arguments": { "status": "forwarded" }
}
```

---

### haszno_orders_get

Egy rendelést ad vissza a tételeivel, eseménynaplójával, beszállítói rendelésazonosítójával és nyomkövetési számával. A `GET /api/orders` által visszaadott listában keres. **Csak olvasás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `id` | pozitív egész szám | **Igen** | Rendelésazonosító. |

**Példahívás:**

```json
{
  "name": "haszno_orders_get",
  "arguments": { "id": 123 }
}
```

---

### haszno_orders_ship

Feladottnak jelöl egy rendelést (`POST /api/orders/:id/ship`). `forwarded` állapotú rendelésekhez használd; egy már feladott rendelésen újra hívni biztonságos. **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `id` | pozitív egész szám | **Igen** | Rendelésazonosító. |
| `confirm` | `true` (literál) | **Igen** | Értéke csak `true` lehet. |

**Visszatérési érték:** a frissített rendelés.

**Példahívás:**

```json
{
  "name": "haszno_orders_ship",
  "arguments": { "id": 123, "confirm": true }
}
```

---

### haszno_orders_receive

Új rendelést küld a továbbítási folyamatba (`POST /api/webhooks/order`). Minden SKU-nak már léteznie kell a bolt termékei között. **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `externalId` | sztring, 1–64 karakter | **Igen** | A webshop saját rendelésazonosítója. |
| `customerName` | sztring, 1–120 karakter | **Igen** | A vevő teljes neve. |
| `address` | sztring, 1–300 karakter | **Igen** | Szállítási cím egy sztringként. |
| `items` | `{ sku, qty }` objektumok tömbje, legalább 1 | **Igen** | `sku`: nem üres sztring; `qty`: pozitív egész szám. |
| `confirm` | `true` (literál) | **Igen** | Értéke csak `true` lehet. |

**Visszatérési érték:** az új rendelés `{ id }` értéke.

**Példahívás:**

```json
{
  "name": "haszno_orders_receive",
  "arguments": {
    "externalId": "WC-9001",
    "customerName": "Kovács János",
    "address": "Budapest, Fő utca 1.",
    "items": [{ "sku": "DEMO-5", "qty": 2 }],
    "confirm": true
  }
}
```

---

### haszno_orders_create_demo

Véletlenszerű demórendelést hoz létre készleten lévő termékekből (`POST /api/demo/order`). **Írás**

> [!WARNING]
> Az eszköz csak akkor fut le, ha a `HASZNO_API_URL` (vagy az `ARFUTAR_API_URL`) környezeti változó tartalmazza a `demo`, `staging` vagy `localhost` szót. Ilyen változó nélkül a cím alapértelmezése `https://haszno.com`, így a hívást elutasítja. A konfigurációs fájl `apiUrl` mezőjét nem nézi.

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `confirm` | `true` (literál) | **Igen** | Értéke csak `true` lehet. |

**Visszatérési érték:** az új rendelés `{ id }` értéke.

**Példahívás:**

```json
{
  "name": "haszno_orders_create_demo",
  "arguments": { "confirm": true }
}
```

---

## Termékötletek

| Eszköz | Mód | Leírás |
|---|---|---|
| `haszno_ideas_list` | **Csak olvasás** | Trendpontszám és haszon szerint rangsorolt termékötletek. |
| `haszno_ideas_ai_shortlist` | **Csak olvasás** | Legfeljebb 5 termékből álló AI-válogatás (AI-költséggel járhat). |
| `haszno_ideas_ai_description` | **Csak olvasás** | AI-val írt termékleírás egy bolti termékhez (nem menti; AI-költséggel járhat). |
| `haszno_ideas_fill_keywords` | **Írás** | Hiányzó trendkulcsszavak kitöltése AI-val. |

### haszno_ideas_list

Lekéri a `GET /api/recommendations` végpontot, majd helyben szűr, trendpontszám és haszon szerint rendez, és korlátoz. **Csak olvasás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `min_score` | szám, 0–100 | Nem | Csak azok az elemek, amelyek `trendScore` értéke legalább ennyi. |
| `supplier` | sztring | Nem | Részsztring-egyezés a beszállító nevére (kis- és nagybetűre érzéketlen). |
| `limit` | egész szám, 1–100 | Nem | Legfeljebb ennyi elem. Alapértelmezés: `25`. |

**Visszatérési érték:** `{ anchor, geo, total, filtered, truncated, items: [{ rank, id, sku, name, supplier, stock, costNet_HUF, suggestedPriceGross_HUF, marginNet_HUF, marginPct, trendScore }] }`.

**Példahívás:**

```json
{
  "name": "haszno_ideas_list",
  "arguments": { "min_score": 50, "limit": 10 }
}
```

---

### haszno_ideas_ai_shortlist

Legfeljebb 5, a bolthoz legjobban illő terméket kér az AI-tól (`POST /api/recommendations/ai`). Adatot nem módosít, de fizetős AI-hívást indíthat; változatlan bemenetnél a szerver 24 órán át gyorsítótárazott eredményt ad (`cached: true`). **Csak olvasás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `confirm` | `true` (literál) | **Igen** | Értéke csak `true` lehet — elfogadod a lehetséges AI-költséget. |

**Visszatérési érték:** `{ summary, cached, picks: [{ productId, networkProductId, name, supplier, recommendedPriceGross_HUF, marginNet_HUF, marginPct, fit, aiReason }], usage }`.

**Példahívás:**

```json
{
  "name": "haszno_ideas_ai_shortlist",
  "arguments": { "confirm": true }
}
```

---

### haszno_ideas_ai_description

Magyar webshopos termékleírást generál a bolt egyik termékéhez (`POST /api/products/:id/ai-description`). A szöveget csak visszaadja, nem menti. Fizetős AI-hívást indít. **Csak olvasás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `product_id` | egész szám, min. 1 | **Igen** | A bolti termék azonosítója (a `haszno_ideas_list` eszközből). |
| `confirm` | `true` (literál) | **Igen** | Értéke csak `true` lehet — elfogadod az AI-költséget. |

**Visszatérési érték:** `{ product_id, description }`.

**Példahívás:**

```json
{
  "name": "haszno_ideas_ai_description",
  "arguments": { "product_id": 55, "confirm": true }
}
```

---

### haszno_ideas_fill_keywords

AI-val kitölti a Google Trends-kulcsszót minden olyan terméknél, amelynek még nincs, és el is menti (`POST /api/trends/keywords`). Ha nincs hiányzó kulcsszó, újrafuttatva `{ updated: 0 }` értéket ad. **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `confirm` | `true` (literál) | **Igen** | Értéke csak `true` lehet. |

**Visszatérési érték:** `{ updated }`.

**Példahívás:**

```json
{
  "name": "haszno_ideas_fill_keywords",
  "arguments": { "confirm": true }
}
```

---

## Feedek

| Eszköz | Mód | Leírás |
|---|---|---|
| `haszno_feeds_import_supplier` | **Írás** | Beszállítói termékfeed importálása (CSV vagy XML). |
| `haszno_feeds_import_market` | **Írás** | Piaci árak importálása CSV-ből. |
| `haszno_feeds_outbound_info` | **Csak olvasás** | A közzétett Árukereső- és Google Shopping-feedek címei. |

A feed tartalmát szövegként a `content` mezőben adhatod át, vagy az MCP-szerver beolvassa a `filePath` útvonalról. A `filePath` csak `.csv`, `.tsv`, `.txt` vagy `.xml` végű lehet, és nem lehet rejtett mappában (például `~/.ssh` vagy `~/.config`).

### haszno_feeds_import_supplier

Beszállítói katalógusfeedet importál (`POST /api/feeds/import`): létrehozza az új termékeket, SKU alapján frissíti a meglévőket, majd lefuttatja a `feed_import` szabályokat. **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `supplierId` | pozitív egész szám | **Igen** | Beszállító-azonosító. |
| `format` | `csv` \| `xml` | **Igen** | A feed formátuma. |
| `content` | sztring | Nem | A feed szövege. Ezt vagy a `filePath` mezőt add meg. |
| `filePath` | sztring | Nem | Helyi feedfájl útvonala. Ezt vagy a `content` mezőt add meg. |
| `confirm` | logikai, alapértelmezés `false` | Nem | `true` végrehajtja; elhagyva vagy `false` értékkel próbafuttatást ad API-hívás nélkül. |

**Visszatérési érték:** `{ created, updated, total }`.

**Példahívás:**

```json
{
  "name": "haszno_feeds_import_supplier",
  "arguments": { "supplierId": 3, "format": "csv", "content": "sku,name,price\nABC-1,Widget,2990", "confirm": true }
}
```

---

### haszno_feeds_import_market

Versenytársi piaci árakat importál CSV-ből (`POST /api/market-prices/import`), a sorokat SKU alapján párosítja a termékekhez, majd lefuttatja a `market_price` szabályokat. Ugyanazt a CSV-t újraimportálva ugyanazok az értékek állnak be. **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `content` | sztring | Nem | A CSV szövege. Ezt vagy a `filePath` mezőt add meg. |
| `filePath` | sztring | Nem | Helyi CSV-fájl útvonala. Ezt vagy a `content` mezőt add meg. |
| `confirm` | logikai, alapértelmezés `false` | Nem | `true` végrehajtja; elhagyva vagy `false` értékkel próbafuttatást ad API-hívás nélkül. |

**Visszatérési érték:** `{ matched, total }`.

**Példahívás:**

```json
{
  "name": "haszno_feeds_import_market",
  "arguments": { "content": "sku,market_price\nABC-1,2890", "confirm": true }
}
```

---

### haszno_feeds_outbound_info

A bolt nyilvános feedjeinek címét adja vissza: `<base>/feed/arukereso.xml` és `<base>/feed/google.xml`, ahol a `<base>` a `HASZNO_API_URL` / `ARFUTAR_API_URL` értéke, alapértelmezésben `https://haszno.com`. **Csak olvasás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `fetch_summary` | logikai, alapértelmezés `false` | Nem | `true` esetén mindkét feedet le is tölti, és mindegyikből elemszámot és 3 elemes mintát ad. `false` esetén nem küld HTTP-kérést. |

**Visszatérési érték:** `{ arukereso_url, google_url, note }`, vagy `fetch_summary: true` esetén `{ arukereso: { url, item_count, sample }, google: { url, item_count, sample } }` (ha egy feed nem tölthető le, a számok helyett `error` mező áll).

**Példahívás:**

```json
{
  "name": "haszno_feeds_outbound_info",
  "arguments": { "fetch_summary": true }
}
```

---

## P2P partner-meghívók

| Eszköz | Mód | Leírás |
|---|---|---|
| `haszno_peers_invite_list` | **Csak olvasás** | Az általad létrehozott meghívókódok. |
| `haszno_peers_invite_create` | **Írás** | Meghívó létrehozása egy beszállító megosztásához. |
| `haszno_peers_invite_accept` | **Írás** | Partnermeghívó elfogadása. |

### haszno_peers_invite_list

Az általad létrehozott meghívókódokat listázza (`GET /api/peers/invites`). **Csak olvasás**

**Bemeneti paraméterek:** nincs.

**Visszatérési érték:** `{ invites: [...] }`; minden meghívónak van `code`, `supplierId`, `expiresAt`, `acceptedBy` (függőben `null`) és `revokedAt` (aktívan `null`) mezője.

**Példahívás:**

```json
{
  "name": "haszno_peers_invite_list",
  "arguments": {}
}
```

---

### haszno_peers_invite_create

Egyszer használható meghívókódot hoz létre, amellyel egy másik Haszno-bolt hozzáfér az egyik beszállítód katalógusához (`POST /api/peers/invites`). **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `supplierId` | pozitív egész szám | **Igen** | A megosztandó beszállító. |
| `expiresAt` | sztring | **Igen** | Lejárat ISO 8601 formában, a jövőben. |
| `confirm` | logikai, `false` esetén előnézet | **Igen** | `true` végrehajtja; `false` előnézetet ad API-hívás nélkül. |

**Visszatérési érték:** `{ code, expiresAt, supplierId }`.

**Példahívás:**

```json
{
  "name": "haszno_peers_invite_create",
  "arguments": { "supplierId": 3, "expiresAt": "2027-01-01T00:00:00Z", "confirm": true }
}
```

---

### haszno_peers_invite_accept

Elfogad egy meghívókódot, és partnerkapcsolatot hoz létre (`POST /api/peers/invites/:code/accept`). A kód ezután érvénytelen. **Írás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `code` | nem üres sztring | **Igen** | A meghívó bolttól kapott kód. |
| `acceptorId` | sztring, 1–120 karakter | **Igen** | A boltod azonosítója. |
| `confirm` | logikai, `false` esetén előnézet | **Igen** | `true` végrehajtja; `false` előnézetet ad API-hívás nélkül. |

**Visszatérési érték:** az új kapcsolat: `{ id, supplierId, partner, createdAt }`.

**Példahívás:**

```json
{
  "name": "haszno_peers_invite_accept",
  "arguments": { "code": "INV-XYZ", "acceptorId": "my-shop", "confirm": true }
}
```

---

## Blog / piaci betekintők

| Eszköz | Mód | Leírás |
|---|---|---|
| `haszno_blog_latest` | **Csak olvasás** | A legfrissebb piaci betekintő bejegyzések. |

### haszno_blog_latest

A legutóbb közzétett piaci betekintő bejegyzéseket adja vissza (`GET /api/blog`). Az adatok legalább 5 bolt összesítéséből származnak; egyetlen bolt adata sem szerepel bennük. **Csak olvasás**

**Bemeneti paraméterek:**

| Név | Típus | Kötelező | Leírás |
|---|---|---|---|
| `period` | `het` \| `honap` | Nem | `het` heti, `honap` havi. Elhagyva mindkettő. |
| `limit` | egész szám, 1–10 | Nem | Bejegyzések száma. Alapértelmezés: `1`. |

**Visszatérési érték:** `{ posts, total }`; minden bejegyzésnek van `title`, `summary`, `bodyMd`, `period`, `periodStart`, `periodEnd`, `publishedAt` és opcionális `data` mezője.

**Példahívás:**

```json
{
  "name": "haszno_blog_latest",
  "arguments": { "period": "het", "limit": 3 }
}
```

---

## Tervezett eszközök

A saját bolti termékek eszközei szerepelnek a skill `references/tools.md` fájljában, de az MCP-szerver még egyiket sem regisztrálja. Meghívásuk „tool not found” hibát ad.

| Eszköz | **Tervezett** |
|---|---|
| `haszno_products_list` | A saját bolt termékeinek listázása ár- és haszonadatokkal. |
| `haszno_products_update` | Egy termék piaci adatainak vagy kézi árának frissítése. |
| `haszno_products_set_listing` | Termék listázása vagy levétele. |
| `haszno_products_apply_prices` | Javasolt árak alkalmazása kiválasztott termékekre. |
| `haszno_products_ai_description` | AI-termékleírás generálása. |

Amíg ezek az eszközök nem érhetők el, használd a [CLI](cli.md) megfelelőit: `haszno products list`, `haszno products update`, `haszno products listing`, `haszno products apply-prices`, `haszno products describe`.

---

## Kapcsolódó témák

- [CLI-referencia](cli.md) — ugyanezek a műveletek a terminálból.
- [Agent skill](skill.md) — munkafolyamat-receptek és biztonsági szabályok agentek számára.
- [Hitelesítés](authentication.md) — API-kulcs és demó-hozzáférési adatok részletei.
- [Hibák és sebességkorlátok](errors.md) — hibaséma és újrapróbálkozási útmutató.