Cobra MCP Gateway – Eszköztár-katalógus

Alapfogalmak, mielőtt belevágna

Ez a dokumentum azt mutatja be, mit tud kérdezni az AI-asszisztensétől, amikor az a Cobra MCP Gateway-en keresztül éri el a Cobra-adatokat. Nem egy technikai API-referencia: nem kell ismernie egyetlen eszköz nevét sem ahhoz, hogy használja őket — az AI a kérdéséből választja ki, melyiket hívja. Azért készült, hogy tudja, mit érdemes kérdeznie, és mire számítson a válaszban, beleértve azt is, amikor egy eszköz nem azt adja, amit elsőre gondolna.

A regisztrációról, a portálról és a token beállításáról a Felhasználói kézikönyv szól — ez a dokumentum csak azt mutatja be, mi kérdezhető, ha a hozzáférés már be van állítva.

1. Cégválasztás

A Cobra MCP Gateway egyszerre mindig egy aktív céghez kapcsolódik. Ez a 3 eszköz kezeli, melyik ez.

get_current_company

• Mire jó: Megmondja, melyik cég van most aktívan kiválasztva.
• Kérdezze így: "Melyik cégben dolgozom éppen most?"
• Mit kap vissza: A cég azonosítója és neve.
• Korlátok: Ha még soha nem választott céget, ez az eszköz hibát ad, nem egy üres vagy alapértelmezett választ — előbb a select_company kell.

list_companies

• Mire jó: Felsorolja, milyen cégekhez férhet hozzá, amik közül választhat.
• Kérdezze így: "Milyen cégekhez van hozzáférésem?"
• Mit kap vissza: Cégek listája azonosítóval és névvel.
• Korlátok: A lista nem jogosultság szerint szűrt. Ha a rendszergazda menet közben módosítja, melyik cégek érhetők el, ennek érvényesítéséhez az MCP-szolgáltatást újra kell indítani — ha egy nemrég hozzáadott cég hiányzik, ez lehet az oka.

select_company

• Mire jó: Beállítja, melyik cég legyen aktív a további kérdésekhez.
• Kérdezze így: "Válts át a Minta Kft.-re."
• Mit kap vissza: A kiválasztott cég azonosítója és neve, megerősítésképp.
• Korlátok: Ennek a hívásnak tartós hatása van: a szerver beállításában is elmentődik — a következő alkalommal is ez a cég lesz aktív, amíg más céget nem választ. Nincs beépített ellenőrzés arra, hogy jogosult-e ehhez a céghez.

2. Kintlévőség és tartozás

get_due_payables

• Mire jó: A megadott napon (alapból: ma) pontosan azon a napon esedékes, ki nem fizetett szállítói tételeket adja vissza.
• Kérdezze így: "Milyen szállítói számláim járnak le ma?"
• Mit kap vissza: Partner neve, bizonylatszám, lejárati dátum, késedelem/eltérés napokban, teljes és fennmaradó összeg, pénznem.
• Korlátok: Ez nem egy időablak ("a következő 30 napban esedékes"), hanem kizárólag a megadott naptári napra eső lejáratú tételeket adja. Jövőbeli időszakhoz több hívás kell különböző dátumokkal.

get_due_receivables

• Mire jó: A megadott naptól kezdve (alapból: mától) a jövőben esedékes, még ki nem fizetett vevői számlákat listázza, felső időkorlát nélkül.
• Kérdezze így: "Milyen vevői számláim vannak, amik még nem jártak le, de hamarosan esedékesek?"
• Mit kap vissza: Partner neve, bizonylatszám és dátuma, lejárati dátum, hátralévő napok száma, eredeti és fennmaradó összeg, pénznem.
• Korlátok: A get_due_payables-tól eltérően nincs egy napra szűkítve — akár évekkel későbbi tételek is bekerülhetnek. Csak azok a vevői számlák jelennek meg, amelyeknél a partnernél be van kapcsolva az "egyenlegértesítés" beállítás — ha ez ki van kapcsolva, a partner nyitott számlái nem jelennek meg, még ha valójában léteznek is.

get_overdue_payables

• Mire jó: A megadott napon (alapból: ma) már lejárt vagy aznap lejáró, ki nem fizetett szállítói tételeket adja vissza — ez a köznyelvi "lejárt tartozás" fogalomnak felel meg.
• Kérdezze így: "Milyen szállítói tartozásaim vannak, amiknek lejárt a fizetési határideje?"
• Mit kap vissza: Ugyanaz a szerkezet, mint a get_due_payables-nél.
• Korlátok: Csak nyitott, nem sztornózott tételek.

get_overdue_receivables

• Mire jó: A megadott napon (alapból: ma) már lejárt vagy aznap esedékes, ki nem fizetett vevői számlákat adja vissza.
• Kérdezze így: "Kinek van lejárt tartozása felénk, kit kell felszólítani fizetésre?"
• Mit kap vissza: Partner neve, bizonylatszám és dátuma, lejárati dátum, késedelem napokban, eredeti és fennmaradó összeg, pénznem.
• Korlátok: Ugyanaz az "egyenlegértesítés" szűrő érvényes, mint a get_due_receivables-nél. Ezen felül: a mai állapot szerint a lista csak azokat a partnereket mutatja, akiknek nincs beállítva hitelezési kategória — ha van, az ő lejárt vevő számlája ma nem jelenik meg itt. Ez a viselkedés meglepő és feltehetően nem szándékos üzleti szabály; fontos ügyfélnél inkább kérdezzen rá, mielőtt a listára támaszkodna.

3. Főkönyv

get_ledger_account_class_summary

• Mire jó: Főkönyvi számlaosztályonkénti (pl. eszközök, források) összesítő forgalmat és egyenleget ad egy adóévre.
• Kérdezze így: "Mennyi volt a 2026-os év forgalma számlaosztályonként?"
• Mit kap vissza: Osztálykód, osztály neve, tartozik/követel forgalom, egyenleg.
• Korlátok: Alapból a magyar könyvelési réteget nézi, a záró tételeket nem számolja bele (ez külön kérhető). Nem létező adóévnél a válasz üres lehet visszaellenőrzés nélkül — pontosítsa az évszámot, ha a válasz üresnek tűnik.

get_ledger_account_id

• Mire jó: Egy látható főkönyvi számlaszámhoz (pl. "311") megkeresi a rendszeren belüli azonosítót, amire más eszközöknek (pl. get_ledger_account_sheet) szükségük van.
• Kérdezze így: "Mi a belső azonosítója a 311-es főkönyvi számlának 2026-ban?"
• Mit kap vissza: A belső azonosító, a megadott számlakód, az adóév és a könyvelési réteg.
• Korlátok: Ez az azonosító csak az adott adóévre és rétegre érvényes — más évben újra le kell kérdezni. Ha a számla nem található, üres (null) azonosítót ad, nem hibát.

get_ledger_account_sheet

• Mire jó: Egy adott főkönyvi számla tételes kartonját (könyvelési sorok, futó egyenleggel) adja vissza egy időszakra.
• Kérdezze így: "Mutasd meg a 311-es számla kartonját 2026 első negyedévére."
• Mit kap vissza: Dátum, megnevezés, bizonylatszám, partner, tartozik/követel összeg, irány, futó egyenleg soronként.
• Korlátok: Bemenetként a get_ledger_account_id (vagy egy korábbi get_trial_balance sorának) belső azonosítóját várja, nem a látható számlaszámot közvetlenül — önmagában, számlaszámmal nem hívható.

get_trial_balance

• Mire jó: A cég teljes főkönyvi kivonatát adja — minden számlára nyitó, időszaki forgalmi és záró egyenleggel.
• Kérdezze így: "Kérek egy főkönyvi kivonatot a 2026-os évre."
• Mit kap vissza: Számlánként: számlaszám, megnevezés, nyitó/forgalmi/záró egyenleg (tartozik és követel bontásban is).
• Korlátok: Mindig minden számlát visszaad — nincs mód arra, hogy csak egyes számlákra szűkítse ezen az eszközön keresztül; ha csak néhány számla érdekli, a get_ledger_account_sheet a megfelelő eszköz.

list_tax_years

• Mire jó: Felsorolja a cégnél rögzített adóéveket.
• Kérdezze így: "Milyen adóévek vannak rögzítve ennél a cégnél?"
• Mit kap vissza: Adóév azonosítója, évszáma, neve.
• Korlátok: Nem kötelező előfeltétele a fenti főkönyvi eszközöknek (azok évszámmal, pl. 2026, dolgoznak) — inkább akkor hasznos, ha nem tudja pontosan, mely évek léteznek a rendszerben.

4. Bizonylatok és mellékletek

Az "avatar" fogalom itt kulcsfontosságú (lásd fent): ha egy böngésző-lekérdezésből vagy egy másik eszköz válaszából kap egy avatarId-t, ez a csoport erre épül.

find_documents

• Mire jó: Bizonylatok keresése bizonylatszám vagy név alapján, opcionálisan bizonylattípusra szűrve.
• Kérdezze így: "Keresd meg a 2026/00123-as számú számlát."
• Mit kap vissza: Találatonként: bizonylat-azonosító (avatarId), bizonylattípus, bizonylatszám/név.
• Korlátok: Legfeljebb 500 találatot ad alapból (max. 5000 kérhető), a legújabbak elöl — sok egyezésnél a régebbi találatok kimaradhatnak, ha nem szűkíti a keresést.

get_document_relations

• Mire jó: Egy bizonylathoz kapcsolódó összes másik bizonylatot mutatja meg (pl. rendeléshez a teljesítést és a számlát), így bejárható a bizonylatlánc.
• Kérdezze így: "Milyen bizonylatok kapcsolódnak ehhez a rendeléshez — van hozzá már számla vagy teljesítés?"
• Mit kap vissza: A kiindulási bizonylat adatai, majd a kapcsolódó bizonylatok listája a kapcsolat típusával.
• Korlátok: Nincs korlátozás a visszaadott kapcsolatok számára — nagyon sok kapcsolattal rendelkező bizonylatnál a válasz hosszú lehet.

list_attachments

• Mire jó: Egy bizonylathoz tartozó csatolmányokat sorolja fel (nevekkel, méretekkel), letöltés nélkül.
• Kérdezze így: "Milyen csatolmányai vannak ennek a bizonylatnak?"
• Mit kap vissza: Csatolmányonként: fájlnév, méret, típus, dátumok, és egy azonosító, amivel a download_attachment ténylegesen letölti.
• Korlátok: A listázás önmagában nem korlátozza a nagy fájlokat — azok is megjelennek itt, csak a tényleges letöltésnél ütközhet méretkorlátba.

download_attachment

• Mire jó: Egy adott csatolmány tényleges tartalmának letöltése (a list_attachments-ből ismert azonosítóval).
• Kérdezze így: "Töltsd le nekem ennek a számlának a PDF-jét."
• Mit kap vissza: A fájl neve, típusa, mérete és tartalma.
• Korlátok: Méretkorlát: 8 MB. Ha a csatolmány ennél nagyobb, a letöltés hibával elutasul, tartalom nem érkezik. (Ez a korlát csak asztali/helyi módban állítható a beállítás-fájlból; a webes portálon keresztüli, gateway-módú kapcsolatnál ez fixen 8 MB.)

upload_attachment

• Mire jó: Egy fájl feltöltése csatolmányként egy már létező bizonylathoz.
• Kérdezze így: "Csatold ezt a PDF-et ehhez a számlához."
• Mit kap vissza: A feltöltött csatolmány adatai (név, méret, azonosító).
• Korlátok: Méretkorlát: 8 MB. Csak bizonyos bizonylattípusokhoz engedélyezett (pl. számla, pénzügyi bizonylat, rendelés, ajánlat, teljesítés, raktármozgás, munkalap, szerződés, feladat, eseménynapló). Ehhez a bizonylat módosítási joga is kell, nem elég az olvasási jog.

get_avatar_document_url

• Mire jó: Egy bizonylathoz megnyitható hivatkozást (linket) ad — nem tölt le semmilyen tartalmat, csak egy linket.
• Kérdezze így: "Add meg ennek a bizonylatnak a linkjét, hogy elküldhessem emailben egy kollégának."
• Mit kap vissza: A bizonylathoz tartozó, megnyitható webcím.
• Korlátok: Ez nem egyenlő a download_attachment-tel — ez a bizonylat rekordjára mutat, nem egy konkrét csatolmány fájltartalmára. A jogosultságot a link megnyitásakor a Cobra Conto kliens ellenőrzi újra.

open_avatar_document

• Mire jó: Egy bizonylatot közvetlenül megnyit a Cobra Conto asztali programban, azon a gépen, ahol az MCP szerver fut.
• Kérdezze így: "Nyisd meg nekem ezt a számlát a Cobrában."
• Mit kap vissza: Megerősítés, hogy a program elindult.
• Korlátok: Csak asztali (helyi) üzemmódban működik, mert ténylegesen elindítja a Cobra Conto programot — webes/portálos kapcsolatnál nem érhető el, helyette a get_avatar_document_url használandó.

resolve_avatar_id

• Mire jó: Egy avatarId-t átvált a bizonylat saját típusán belüli azonosítójára, és megmondja a bizonylat típusát is.
• Kérdezze így: ritkán kérdezi ezt közvetlenül a felhasználó — inkább az AI hívja a háttérben, amikor egy másik eszközhöz kell átalakítania egy azonosítót.
• Mit kap vissza: A bizonylat saját azonosítója, típusa, és hogy mely böngészőkkel kérdezhető le tovább.
• Korlátok: Ha az azonosító nem oldható fel, egyértelmű hibát ad (nem nullát vagy üres választ) — ez szándékos, hogy egy hibás azonosító ne vezessen csendben rossz adatra.

list_voucher_files

• Mire jó: Bizonylattípusonként felsorolja azokat az "állományokat" (bizonylattömböket), amelyekhez hozzáférése van.
• Kérdezze így: "Milyen számla-állományaim vannak ebben a cégben?"
• Mit kap vissza: Az elérhető állományok azonosítóval és névvel.
• Korlátok: Amihez nincs jogosultsága, az csendben kimarad a listából. Néhány bizonylattípusnál (bank, munkalap, raktár) kötelező megadni az adóévet vagy a raktárt is.

5. Készlet

list_stocks

• Mire jó: Felsorolja azokat a raktárakat, amelyekhez hozzáférése van, és megmondja, használható-e egy adott dátumon.
• Kérdezze így: "Melyik raktárakba tudok ma szállítólevelet kiállítani?"
• Mit kap vissza: Raktár azonosítója, neve, és hogy az adott napon (alapból: ma) használható-e.
• Korlátok: Csak azok a raktárak jelennek meg, amikhez legalább egy bizonylattömbön keresztül van jogosultsága. A "nem használható" jelzés két különböző okot takarhat (nincs bizonylattömb az adott évre, vagy van, de nincs rá joga) — a válasz nem különbözteti meg a kettőt.

list_stock_activities

• Mire jó: Felsorolja a készlet-mozgások lehetséges indokait (jogcímeit), pl. bevételezés vagy kiadás okait.
• Kérdezze így: "Milyen kiadási jogcímekkel adhatok ki készletet egy szállítólevélen?"
• Mit kap vissza: Jogcím azonosítója, neve, iránya (bevételezés/kiadás).
• Korlátok: Alapból mindkét irányt (be és ki) mutatja együtt; ha csak az egyikre kíváncsi, ezt érdemes a kérdésben pontosítani.

list_product_categories

• Mire jó: Felsorolja a termékkategóriákat, amik szerint a termék-lista szűrhető.
• Kérdezze így: "Milyen termékkategóriák vannak?"
• Mit kap vissza: Kategória azonosítója és neve.
• Korlátok: Kizárólag a termékek kategóriáit adja — más bizonylattípus kategóriáihoz nem ez az eszköz kell.

6. Böngészők és lekérdezések

Ez a legnagyobb csoport: a Cobra előre elkészített listáinak (böngészőinek) és az egyedi, rendszergazda által jóváhagyott lekérdezéseknek (service query) a lekérdezésére és feltárására szolgáló eszközök. Tipikus sorrend: milyen listák/lekérdezések vannak → milyen szűrőkkel kérdezhetők le → futtatás.

list_browsers

• Mire jó: Felsorolja az elérhető böngészőket (listákat), amikhez hozzáférése van.
• Kérdezze így: "Milyen listákat tudok lekérdezni a Cobrában?"
• Mit kap vissza: Böngésző kulcsa, kategóriája (törzsadat vagy bizonylat), rövid leírása.
• Korlátok: Amihez nincs jogosultsága, az csendben kimarad a listából — ha egy böngészőt nem talál itt, ez nem különbözteti meg, hogy nem létezik, vagy csak nincs rá joga.

describe_browser

• Mire jó: Megmutatja, milyen szűrőparaméterekkel kérdezhető le egy adott böngésző, és van-e hozzá további részlet (tételsorok, egyedi jellemzők).
• Kérdezze így: "Milyen szűrőkkel tudom lekérdezni a kimenő számlákat?"
• Mit kap vissza: A böngésző szűrőinek listája (név, típus, kötelező-e, alapérték), és jelzés, van-e tételsora vagy egyedi jellemzője.
• Korlátok: Ha nincs jogosultsága az adott böngészőhöz, ez az eszköz — a list_browsers-től eltérően — explicit hibát ad, nem hallgat el semmit.

run_browser

• Mire jó: Lefuttatja a böngészőt a megadott szűrőkkel, és a találatokat közvetlenül a beszélgetésbe adja.
• Kérdezze így: "Listázd ki azokat a partnereket, akiknek a neve »Kovács«-csal kezdődik."
• Mit kap vissza: Oszlopok és sorok, a találatok száma.
• Korlátok: Alapból legfeljebb 500 sort ad (max. 5000 kérhető) — ha ennél több találat van, a válasz jelzi, hogy vágott, és érdemes szűkíteni a kérdést.

export_browser

• Mire jó: Ugyanaz, mint a run_browser, de az eredményt fájlba menti a beszélgetésbe való kiírás helyett.
• Kérdezze így: "Mentsd el az idei kimenő számlákat egy Excel-fájlba."
• Mit kap vissza: Asztali módban a mentett fájl elérési útja és mérete; webes (portálos) kapcsolatnál egy letölthető fájl.
• Korlátok: Támogatott formátumok: TXT, CSV, XLSX, XML, JSON. Webes kapcsolatnál 8 MB-os méretkorlát van — túllépésnél hibát kap, nem csonkított fájlt. Asztali (helyi) módban nincs bájt-alapú méretkorlát, csak sorszám-korlát (alapból 100 000 sor) — ha ezt túllépi, szintén hibával leáll.

get_browser_child_rows

• Mire jó: Egy böngésző-találat (pl. egy számla) alárendelt sorait adja vissza — jellemzően a tételsorokat.
• Kérdezze így: "Milyen tételei vannak ennek a számlának?"
• Mit kap vissza: A tételsorok, oszlopokkal.
• Korlátok: Csak a run_browser eredményéből kapott azonosítóval hívható, nem avatarId-val. Legfeljebb 200 bizonylatra kérdezhető egyszerre, és a visszaadott sorok száma összesen legfeljebb 2000 lehet. Csatolmányok, eseménynapló-bejegyzések és egyedi jellemzők nem jönnek itt vissza.

get_browser_record_properties

• Mire jó: Egy böngésző-találathoz rögzített egyedi ("property") jellemzők tényleges értékeit adja vissza.
• Kérdezze így: "Milyen egyedi jellemzőket rögzítettünk ehhez a termékhez?"
• Mit kap vissza: Jellemzőnként: név, típus, érték.
• Korlátok: A Cobra felülete alapból csak a jellemzők egy részét mutatja a képernyőn — ez az eszköz többet is visszaadhat, mint amennyi a Cobra felületén elsőre látszik.

list_browser_properties

• Mire jó: Megmutatja, milyen egyedi jellemzők léteznek egyáltalán egy adott böngészőn (nem konkrét rekordhoz, hanem magához a listatípushoz kötve).
• Kérdezze így: "Milyen egyedi jellemzőket lehet rögzíteni egy partnerhez?"
• Mit kap vissza: A jellemzők neve és típusa.
• Korlátok: A jellemző-készlet cégenként eltérő és bővülhet — ez az eszköz mindig élőben kérdez rá, nem egy fix listát ad.

list_channels

• Mire jó: Felsorolja a kommunikációs csatorna típusokat (pl. email, telefon), amikkel más lekérdezéseket (pl. kontakt-lista) lehet szűrni.
• Kérdezze így: ritkán kérdezik önmagában — inkább egy előkészítő lépés, mielőtt pl. "listázd az email kapcsolattartókat" jellegű kérdésre válaszol az AI.
• Mit kap vissza: Csatorna azonosítója és neve.
• Korlátok: Nincs bemeneti paraméter, mindig a teljes listát adja.

list_service_queries

• Mire jó: Felsorolja azokat az egyedi (rendszergazda által jóváhagyott) lekérdezéseket, amikhez hozzáférése van.
• Kérdezze így: "Milyen egyedi lekérdezéseket tudok futtatni, amiknek a nevében szerepel, hogy »forgalom«?"
• Mit kap vissza: Lekérdezés azonosítója, neve, megjegyzése.
• Korlátok: A jogosultsági szűrés egy belső, korlátozott darabszámon (alapból 500) átnézett listán történik — ha sok lekérdezés van a rendszerben, elképzelhető, hogy egy Önnek jogosult, de a névsorrendben hátrébb eső lekérdezés nem jelenik meg.

describe_service_query

• Mire jó: Megmutatja egy adott egyedi lekérdezés paramétereit, mielőtt lefuttatná.
• Kérdezze így: "Milyen paraméterei vannak a »Havi forgalom partnerenként« lekérdezésnek?"
• Mit kap vissza: A lekérdezés neve, megjegyzése, és a paraméterek listája.
• Korlátok: Ha nincs jogosultsága ehhez a konkrét lekérdezéshez, egyértelmű hibát kap.

run_service_query

• Mire jó: Lefuttatja az egyedi lekérdezést a megadott paraméterekkel.
• Kérdezze így: "Futtasd le a »Havi forgalom partnerenként« lekérdezést erre a hónapra."
• Mit kap vissza: Oszlopok és sorok.
• Korlátok: Alapból legfeljebb 500 sort ad (max. 5000) — ha ennél több lenne, a többletet csendben levágja, és jelzi, hogy a válasz csonkolt (ezzel szemben az export_browser inkább hibával leáll, nem vág csendben).

7. Napló

get_event_logs

• Mire jó: Lekéri az ügyfél-/partnerkapcsolati eseménynapló-bejegyzéseket egy dátumtartományra, opcionális szöveges kereséssel.
• Kérdezze így: "Milyen eseménynapló-bejegyzések keletkeztek július 1. és július 31. között, amiben szerepel a »szerződés« szó?"
• Mit kap vissza: Eseményenként: dátum, esemény neve és megjegyzése, típus, kapcsolódó partner/kontakt/ügyintéző neve.
• Korlátok: A dátumtartomány mindkét vége kötelező — nincs alapértelmezett tartomány. Ezen az eszközön keresztül nem lehet egy konkrét partnerre, kontaktra vagy ügyintézőre szűkíteni — csak utólagos szöveges kereséssel lehet közelíteni. Nincs sor-korlát sem — nagyon széles dátumtartománynál a válasz nagyon hosszú lehet.