VXP eszközbérlés: API és MCP

A vxp.hu eszközbérlés két dolgot tesz gépileg is elérhetővé: a katalógus lekérdezését és egy bérlési igénylés beküldését. Mindkettő ugyanazt tudja, amit a weboldal: az igénylés nem foglalás, nem ad vissza szabad időpontot vagy élő készletet. A beküldött igénylésből egy e-mail lesz a VXP-nél, a visszaigazolás emberi lépés.

Katalógus

Nyilvános, hitelesítés nélküli JSON-fájl, a weboldal katalógusával azonos adat. Bármilyen HTTP-kliensből lekérhető.

curl https://vxp.hu/api/eszkozberles/v1/katalogus.json

Szerkezet

A db a nyilvántartott darabszám, nem élő készlet: azt nem tudja megmondani, hogy egy adott napon szabad-e az eszköz.

{
  "verzio": 1,
  "frissitve": "2026-09-28",
  "penznem": "HUF",
  "eszkozok": [
    { "id": "obj-001", "nev": "Tamron 28-75 F2.8", "kategoria": "objektivek",
      "ar_nap": 3000, "db": 2, "kep": "https://vxp.hu/eszkozberles-kepek/obj-001.jpg" }
  ],
  "...": "..."
}

A 2026-09-28-as változat 196 eszközt, 21 kategóriát és 3 csomagot tartalmaz. Az adat ritkán változik; gyorsítótárazhatod, de a beküldés előtt érdemes frissen lekérni.

Igénylés beküldése

POST https://vxp.hu/api/eszkozberles/v1/igenyles_endpoint.php, JSON-törzzsel (Content-Type: application/json), legfeljebb 16 KB. Hitelesítés nem kell: ugyanaz a nyilvános lehetőség, mint a weboldal űrlapja. CORS-fejlécet nem ad, tehát böngészőből közvetlenül nem hívható; a saját szerveredről vagy MCP-ből használd.

Mezők

Az eszközök nevét és kategóriáját a szerver a saját katalógusából veszi az id alapján, a beküldött szöveget nem használja. Ismeretlen id esetén semmi nem megy el.

Biztonságos próba (nem küld igénylést)

Hibás e-mail-címmel a kérés a validáción elbukik, és semmi nem megy el:

curl -i -X POST https://vxp.hu/api/eszkozberles/v1/igenyles_endpoint.php \
  -H "Content-Type: application/json" \
  -d '{"name":"Próba","email":"nem-email"}'
# HTTP/1.1 400 ...  {"ok":false,"hiba":"..."}

Ez a próba is levon egyet az óránkénti 10 igénylési keretből, mert a keret a mezők ellenőrzése előtt fogy; csak a hibás JSON-törzsű kérés nem számít bele.

Valódi igénylés

Figyelem: a sikeres kérés valódi igénylést küld a VXP-nek. Csak valódi szándékkal futtasd.

curl -X POST https://vxp.hu/api/eszkozberles/v1/igenyles_endpoint.php \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kovács Anna",
    "email": "anna@example.com",
    "phone": "+36 30 123 4567",
    "tetelek": [ { "id": "obj-001", "db": 1 } ],
    "tol": "2026-11-14",
    "ig": "2026-11-16",
    "megjegyzes": "Forgatás Budapesten, péntek reggeli átvétellel."
  }'

Siker esetén: HTTP 200, {"ok":true}. Ez azt jelenti, hogy az igénylés megérkezett, nem azt, hogy az eszköz le van foglalva.

Hibakódok és korlátok

Hiba esetén a válasz {"ok":false,"hiba":"..."}. A hiba szöveg emberi olvasásra szól és változhat; programból a HTTP-státuszra építs.

Korlát: óránként legfeljebb 10 igénylés egy IP-címről. Ez a keret közös a REST-végpont és az MCP között.

MCP AI-asszisztenseknek

Az MCP (Model Context Protocol) segítségével egy AI-asszisztens (például Claude) közvetlenül böngészhet a katalógusban, és a felhasználó jóváhagyásával igénylést küldhet. A szerver távoli, Streamable HTTP átvitelű, hitelesítés nélküli; ugyanazt a két műveletet adja, mint fent, ugyanazokkal a szabályokkal és korlátokkal.

Cím: https://vxp.hu/api/eszkozberles/v1/mcp_endpoint.php

Eszközök

Hozzáadás a klienshez

Claude (claude.ai és Claude Desktop): Beállítások → Csatlakozók (Connectors) → Egyéni csatlakozó hozzáadása, majd a fenti cím. A pontos menüpontok a kliens verziójától függően eltérhetnek.

Claude Code:

claude mcp add --transport http vxp-eszkozberles https://vxp.hu/api/eszkozberles/v1/mcp_endpoint.php

Más MCP-kliensek (például Cursor, VS Code): távoli, HTTP-típusú szerverként add meg a címet. Egy jellemző beállítás:

{
  "mcpServers": {
    "vxp-eszkozberles": { "type": "http", "url": "https://vxp.hu/api/eszkozberles/v1/mcp_endpoint.php" }
  }
}

A beállítófájl neve és pontos alakja kliensenként eltér; a kliens saját dokumentációja az irányadó.

Kézi próba

Az MCP JSON-RPC 2.0 üzeneteket fogad POST-tal. Ezek a hívások nem küldenek igénylést:

curl -X POST https://vxp.hu/api/eszkozberles/v1/mcp_endpoint.php \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -X POST https://vxp.hu/api/eszkozberles/v1/mcp_endpoint.php \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"vxp_eszkozberles_katalogus","arguments":{"keres":"kamera"}}}'

Támogatott protokollverziók: 2025-06-18 és 2025-03-26. A szerver állapotmentes: nem nyit SSE-folyamot és nem használ munkamenetet, GET-re 405-öt ad. Böngészőből csak a vxp.hu saját oldaláról hívható (Origin-ellenőrzés). Korlát: óránként 300 MCP-kérés IP-címenként, ezen belül az igénylésekre a közös óránkénti 10.

Verziózás és kapcsolat

Az útvonalban szereplő v1 stabil: új, nem kötelező mező megjelenhet, de meglévő mező jelentése nem változik. Visszafelé nem kompatibilis változás új verziószámon (/v2/) érkezik, a v1 addig elérhető marad.

Kérdés az API-val kapcsolatban: berles@vxp.hu.