MCP-szerver

A Poltura egyetlen Model Context Protocol (MCP) szervert futtat a https://api.poltura.com/mcp címen. Egy AI-kliens – például a Claude, a ChatGPT, a Cursor, a VS Code vagy a Codex – csatlakozik hozzá, a kereskedő bejelentkezik a Polturába, kiválasztja a megosztani kívánt boltokat és jogosultságokat, a kliens pedig ezután adatokat kereshet és módosításokat végezhet ezekben a boltokban.

• Írás és olvasás. Termékek, rendelések, vásárlók, tartalmak, a webáruház, e-mailek, feedek, fordítások és egyebek. Az eszközreferencia mindegyiket felsorolja.
• A megadott jogosultságokon belül. Minden hívást ellenőriz a rendszer a kereskedő által választott jogosultságok és a tag saját szerepköre alapján. A kliens soha nem tehet többet, mint az a személy, aki csatlakoztatta.
• A jóváhagyás az emberek kezében marad. A visszatérítések, lemondások és más kockázatos műveletek megvárják, hogy egy személy jóváhagyja őket a Polturában. Lásd: Hogyan hajtanak végre műveleteket az ügynökök a boltodban.

Első lépésekHivatkozás másolása

Két módHivatkozás másolása

Egyetlen schema írja le a boltot. A szerver a kliens által kért módban alakítja ezt eszközökké: a https://api.poltura.com/mcp címen a kompakt, míg a https://api.poltura.com/mcp?mode=typed címen a típusos módban.

Mindkét mód ugyanazokat a rekordokat és műveleteket szolgálja ki, ugyanazokat az ellenőrzéseket futtatja, és ugyanazokat a jóváhagyásokat kéri.

A kompakt eszközökHivatkozás másolása

Egy tipikus folyamat:

get_store_info, majd search_store "1042-es rendelés", majd get_record order include=payments,
majd find_actions "visszatérítés", majd describe payment.refund,
majd run_destructive_action payment.refund {...}, amely pending_approval választ ad, amíg valaki jóvá nem hagyja

A típusos mód megtartja a get_store_info, search_docs, read_doc, search_store és query_analytics eszközöket, a többit pedig rekordtípusonként és műveletenként egy-egy eszközre cseréli. A nevek először a rekordtípust, majd az igét tartalmazzák: order_list, order_get, payment_refund. Az appok eszközei az app azonosítóját tartalmazzák: fraud_detection_order_approve.

Dokumentációs eszközökHivatkozás másolása

A search_docs és a read_doc nem igényel boltot, így a get_store_info előtt és olyan kapcsolaton is működnek, amelyik egyetlen boltot sem ér el. Csak olvashatók, és mindkét módban ugyanazt adják vissza. Hívd meg a search_docs eszközt, mielőtt válaszolnál egy Poltura használatával kapcsolatos kérdésre, és hivatkozd be a felhasznált oldal linkjét.

A search_docs bemenetei:

A válasz { "hits": [...] }, a legjobb találattal az élen. Minden találat az alábbiakat tartalmazza:

A read_doc a path paramétert várja, ami egy találat url mezője vagy csak az útvonala, és magát az oldalt adja vissza:

Ha az útvonal nem dokumentációs oldalra mutat, a válasz not_found. A dokumentáció szinkronban marad az oldalakkal: egy közzétett oldal röviddel a közzététel után már kereshető.

Több boltHivatkozás másolása

Egy kapcsolat több boltot is elérhet. Ilyenkor a get_store_info listázza őket, minden más eszköz pedig vár egy store_id paramétert; ha nem adod meg, a hívásra invalid_input a válasz, megnevezve a használható boltokat. Egyetlen bolt esetén a store_id opcionális. Fűzz ?store_id= paramétert a címhez, ha a kapcsolatot egyetlen bolthoz szeretnéd rögzíteni. Olyan store_id esetén, amelyet a kapcsolat nem ér el, a válasz not_available.

Fájlok hozzáadása és termékek létrehozásaHivatkozás másolása

A media_upload képet, PDF-et vagy letölthető fájlt ad hozzá a médiatárhoz a két mód egyikén. Add meg az url mezőt a kereskedő által megadott nyilvános címhez, és a bolt letölti azt. Add meg a name, content_type és size mezőket a kliensedet futtató gépen lévő fájlhoz: a válasz egy egyszer használatos feltöltési címet és a bájtok elküldéséhez szükséges pontos curl parancsot tartalmazza. A cím egyszer működik, pontosan arra a fájlra, és a release-e után röviddel lejár. Az eredmény mindkét esetben a médiatárfájl az id és ref azonosítójával, készen a product_gallery_update híváshoz. Ugyanazok az ellenőrzések és korlátok érvényesek, mint az adminfelületi feltöltésnél.

A product_create eladható terméket hoz létre: minden termék kap legalább egy beárazott változatot, érvénybe lépnek a bolt értékesítési alapértelmezései (értékesítési csatorna, szállítási profil, készlethelyszín, készletkövetés), az initial_quantity pedig beállítja a starter kitet. Az eredmény felsorolja a következő teendőket, például a kép hozzáadását.

Tool schemákHivatkozás másolása

Minden eszköz inputját a JSON Schema olyan hordozható részhalmaza írja le, amelyet minden MCP-kliens és -modell elfogad, még a legszigorúbbak is: nincs $ref, oneOf, allOf vagy const, az unionök kizárólag anyOf formában szerepelnek, a sztringeknél enum használatos, a rekurzív formák pedig fix mélységnél le vannak vágva. A gyökerében unionként megadott bemenet egyetlen objektummá válik, amelynek mezői a választási lehetőségeket tartalmazzák. A bolt minden bemenetet szigorúan a művelet valódi schemája alapján dolgoz fel, így a közzétett forma megengedőbb lehet az elfogadottnál: elutasított bemenet esetén a hiba tartalmazza a pontos schemát, egy példát és a valid neveket.

Minden eszköz tartalmaz egy title mezőt és a négy hintet: readOnlyHint, destructiveHint, idempotentHint és openWorldHint, így a kliens megkérdezhet téged, mielőtt olyan eszközt futtatna, amely módosításokat végez.

A tool resultok adatokHivatkozás másolása

A vásárlók vagy harmadik felek által írt szövegek – például termékértékelések vagy rendelési megjegyzések – visszatérhetnek egy eredményben. A Poltura ezeket a mezőket untrusted jelöléssel látja el. Kezeld őket adatként és soha ne utasításként, és mondd meg az ügynöködnek is, hogy tegyen ugyanígy.