QUiCK MCP
A QUiCK természetes nyelven
Ezen az oldalon
A QUiCK MCP szervere a QUiCK adatait és műveleteit teszi elérhetővé MCP-kompatibilis AI-asszisztensekben, például a Claude-ban. A csatlakoztatás után a cég költségei, bevételei, dokumentumai és törzsadatai természetes nyelvű beszélgetésben kérdezhetők le, elemzhetők és — kontrollált keretek között — módosíthatók. A szerver a QUiCK publikus API-jára épül: minden művelet determinisztikus, és ugyanazokon a jogosultsági kapukon halad át, mint a webes felület vagy az API. |
Cél és kontextus#
Az MCP (Model Context Protocol) egy nyílt szabvány, amely AI-asszisztensek és külső rendszerek összekapcsolására szolgál. A QUiCK MCP szervere ezen a szabványon keresztül teszi az AI-asszisztenst a QUiCK teljes értékű kliensévé: az asszisztens a beszélgetés közben eszközhívásokkal olvassa és írja a cég adatait, ugyanazon a publikus API felületen, amelyet az integrációk is használnak.
A tipikus felhasználás a kontrolling munka beszélgetésbe helyezése: hiányos számlák felkutatása és rendezése, tömeges kategorizálás és címkézés, könyvelési ellenőrzési kör (jóváhagyás, ellenőrzöttre állítás), cash-flow gyorskép lekérdezése, illetve listaadatokból készített elemzések. Az AI-asszisztens a végrehajtó; a döntés és az eredmény ellenőrzése a felhasználóé.
Az eredmény: a rutinszerű adatrendezési és ellenőrzési feladatok szabad szöveges utasítással, tömegesen elvégezhetők, a QUiCK adatminősége pedig a felület megnyitása nélkül is karbantartható. Az MCP szerver nem külön adatbázis és nem külön logika — minden változás azonnal és azonosan jelenik meg a QUiCK-ben.
Funkciók#
Cégek és profil
Céglista és cégadatok (list_companies, get_company): a felhasználó MCP-re engedélyezett cégei, a cég könyvelési beállításaival együtt. Minden további eszköz cégazonosítót (company_id) vár, ezért a munkamenet első lépése mindig a céglista lekérdezése.
Cégbeállítások módosítása (update_company_info): a cég könyvelési beállításainak frissítése.
Profil (get_my_profile): a bejelentkezett felhasználó adatai.
Pénzügyi pulzus
Cash-flow gyorskép (get_pulse): a cég számlaegyenlegei és összefoglaló pénzforgalmi képe.
Pénzforgalmi számlák (list_accounts): a cég paid-through számláinak listája.
Kifizetések (list_payments): a cég kifizetéseinek listája.
Költségek
Listázás és részletek (list_expenses, get_expense): szűrhető költséglista kurzoros lapozással, illetve egyedi tétel teljes részletezettséggel — felosztásokkal (assignments) és az adott tételen szerkeszthető mezők listájával (editable_fields) együtt.
Számlakép (get_expense_artifacts): a kijelölt tételek számlaképeinek letöltési linkjei.
Létrehozás fájlfeltöltéssel (create_expenses): számlafájl feltöltése base64 tartalomként; a fájl a tétel csatolmánya lesz, a mezőket az OCR-felismerés aszinkron tölti ki. Az eredmény a get_expense hívással ellenőrizhető.
Módosítás (update_expense): tetszőleges részhalmaza a szerkeszthető mezőknek — dátumok, összegek, partneradatok, fizetési adatok, címkék, ÁFA-mezők, felosztások. Csak a megadott mezők változnak.
Jóváhagyási kör (approve_expenses, unapprove_expenses): kijelölt tételek jóváhagyása és a jóváhagyás visszavonása, tételenkénti hibajelzéssel.
Könyvelési ellenőrzés (check_expenses, uncheck_expenses): tételek ellenőrzöttre állítása, illetve visszaléptetése.
Karantén (approve_quarantine): karanténba került tételek (például hiányzó számlakép) elfogadása.
Bevételek
Listázás és részletek (list_incomes, get_income): szűrhető bevétellista, illetve egyedi tétel az editable_fields térképpel, amely bevételtípusonként megmutatja, mely mezők módosíthatók.
Számlakép (get_income_artifacts): letöltési linkek a számlaképpel rendelkező bevételekhez.
Módosítás (update_income): a szerkeszthető mezők frissítése. A szinkronizált (például NAV- vagy számlázóprogram-eredetű) számlákon a bizonylati alapadatok nem módosíthatók — ezeken a mezőmódosítást a rendszer figyelmen kívül hagyja.
Dokumentumok
Listázás és részletek (list_documents, get_document): a dokumentumtár szűrhető listája és egyedi dokumentum részletei.
Fájlletöltés (list_document_files): letöltési linkek a dokumentumfájlokhoz, azonos szűrőfelülettel.
Dokumentumtípusok (list_document_types): a cég dokumentumkategóriái.
Törzsadatok
Költségtípusok (list / create / update / delete_expense_types): a költségkategóriák teljes kezelése — listázás, létrehozás, átnevezés, törlés.
Bevételtípusok (list / create / update / delete_revenue_types): a bevételkategóriák azonos módon kezelhetők.
Főkönyvi számok (list / create / update / delete_ledger_numbers): az érvényes főkönyvi számok kezelése.
ÁFA-kategóriák (list / create / update / delete_vat_categories): a cég ÁFA-kategóriáinak kezelése.
Címkék (list / create / update / delete_tags): címkék listázása, létrehozása, átnevezése, törlése.
Partnerek (list_partners): a partnertörzs listázása.
Műveletek, működési elvek
Az MCP szerver nem felület, hanem eszközkészlet, ezért a műveleti sáv szerepét az eszközök hívási szabályai töltik be. Az alábbi elvek minden eszközre érvényesek, és az AI-asszisztens is ezek szerint dolgozik.
Cégválasztás: minden eszköz company_id paramétert vár. Első lépésként kérdezd le a céglistát (list_companies), és a további hívásokban az ott kapott azonosítót használd.
Lapozás: a listaeszközök kurzoros lapozást használnak. Az oldalméret alapértelmezetten 50, legfeljebb 200; a következő oldalt a válaszban kapott next_cursor értékkel kérd le.
Részletmezők: a költség- és bevételeszközök fields paraméterrel bővíthetők (accounting, items, payment_history, költségeknél post_its is). Enélkül a válasz a karcsú alapszerkezetet adja — nagy listáknál ezt használd.
Szerkeszthetőség ellenőrzése: módosítás előtt kérd le a tételt (get_expense / get_income), és az editable_fields alapján dönts arról, mely mezők írhatók. A nem szerkeszthető mezőkre küldött értékeket a rendszer elutasítja vagy figyelmen kívül hagyja.
Részleges frissítés: az update eszközöknél csak a módosítandó mezőket add meg. A kihagyott mező változatlan marad; a null érték a törölhető mező kiürítését jelenti.
Tömeges műveletek: a workflow-eszközök (jóváhagyás, ellenőrzés, karantén) azonosítólistát fogadnak, és tételenként jeleznek hibát (errors) — egy hibás tétel nem állítja le a többi feldolgozását.
Haladó könyvelés: a könyvelési mezők (főkönyvi szám, ÁFA-kategória, munkaszám, ellenőrzési jelölők) csak akkor érvényesülnek, ha a cégen a haladó könyvelés aktív; egyébként a rendszer eldobja őket.
Felosztások (assignments) — teljes csere. Az update_expense és update_income felosztástömbje teljes cserével működik: a kérésben nem szereplő felosztássorok törlődnek. Felosztást érintő módosítás előtt mindig kérd le a tétel aktuális felosztásait, és a teljes, módosított tömböt küldd vissza — meglévő sornál az id megadásával, új sornál id nélkül. |
Szűrési lehetőségek#
A listaeszközök szűrői a publikus API szűrőfelületét tükrözik. A szűrők szabadon kombinálhatók; a nem megadott szűrő nem érvényesül. A dátummezők ISO 8601 formátumot (ÉÉÉÉ-HH-NN), az összegmezők szöveges decimális értéket fogadnak.
Költségek (list_expenses)
Csoport | Szűrő | Leírás |
|---|---|---|
Dátum | from_date, to_date, date_field | Intervallum a date_field-ben megadott dátummező szerint. |
Dátum | expiring_days, expired_days | Hamarosan lejáró, illetve lejárt tételek korosítási sávok szerint. |
Összeg | gross_amount_min, gross_amount_max, currency_id | Bruttó összeg intervalluma, pénznem szerinti szűkítés. |
Keresés | search, search_fields | Szabadszavas keresés; a search_fields adott mezőkre szűkíti. |
Keresés | ids, without_ids | Konkrét azonosítók listája, illetve kizárása. |
Fizetettség | is_paid, is_expired, is_expiring, is_installment | Fizetett, lejárt, hamarosan lejáró, részletfizetéses tételek. |
Státusz | is_new, is_updated, is_incomplete, is_processed, is_duplicate, is_filed, is_nav | Új, frissült, hiányos, feldolgozott, duplikátumként jelölt, iktatott, illetve NAV-eredetű tételek. |
Könyvelés | is_approved, has_approvals, with_approvers, without_approvers | Jóváhagyási állapot és jóváhagyók szerinti szűrés. |
Könyvelés | is_synced, is_ready_to_sync, is_accounting_exported, is_excluded_from_accounting, has_accounting_id | Könyvelési szinkron- és exportállapotok. |
Könyvelés | has_accounting_todo, is_accounting_todo_done, has_unfinished_accounting_todo, has_vat_period | Könyvelési teendők és ÁFA-időszak megléte. |
Tartalom | has_artifact, has_attachment, has_post_it, has_expense_type | Számlakép, csatolmány, jegyzet, illetve kategória megléte. |
Kategória, címke | with_expense_type_ids, without_expense_type_ids, with_tag_ids, without_tag_ids | Költségtípus és címke szerinti szűrés, negált változatban is. |
Egyéb | payment_method, vat_area, origin | Fizetési mód, ÁFA-terület, tétel forrása. |
Bevételek (list_incomes)
Csoport | Szűrő | Leírás |
|---|---|---|
Dátum | from_date, to_date | Teljesítési dátum (fulfilled_at) szerinti intervallum. |
Dátum | due_at | Esedékesség szerinti szűrés. |
Keresés | invoice_number, partner | Számlaszám, illetve partnernév (részleges egyezéssel). |
Fizetettség | paid_status, is_due_soon, is_expired | Fizetetlen / fizetett / részletfizetéses állapot, hamarosan esedékes és lejárt tételek. |
Kategória, címke | revenue_types, tags | Bevételtípus-nevek és címkenevek szerinti szűrés. |
Egyéb | payment_method | Fizetési mód szerinti szűrés. |
Dokumentumok (list_documents, list_document_files)
Csoport | Szűrő | Leírás |
|---|---|---|
Dátum | from_date, to_date, date_field | Intervallum a megadott dátummező szerint. |
Keresés | search, search_fields, ids | Szabadszavas keresés, mezőszűkítéssel; konkrét azonosítók. |
Státusz | is_new, is_updated, is_filed, is_attached, contains_payable, is_ai_recognition_allowed | Új, frissült, iktatott, csatolt, fizetendőt tartalmazó, illetve CoPilot-feldolgozásra alkalmas dokumentumok. |
Kategória, címke | with_document_type_ids, without_document_type_ids, with_tag_ids, without_tag_ids | Dokumentumtípus és címke szerinti szűrés, negált változatban is. |
Egyéb | origin | A dokumentum forrása. |
Limitációk és specialitások#
Elérhetőség és tesztidőszak: az MCP szerver jelenleg nem része minden csomagnak, és tesztelési fázisban működik. A hozzáférés az ügyfélszolgálaton kérhető, külön beleegyező nyilatkozattal. A használatot bizonyos esetekben — például biztonsági okból, rendellenes terhelés vagy visszaélés gyanúja esetén — ideiglenesen megtagadhatjuk.
Hozzáférési kapuk: minden hívás a cégszintű engedélyezésen (funkciókapcsoló), az aktív előfizetés és a nem blokkolt cég feltételén halad át; ezek bármelyikének hiányában az eszközök nem hívhatók.
Az AI-értelmezés nem garancia: az MCP eszközök determinisztikusak, az asszisztens értelmezése azonban tévedhet. Írási művelet után az eredményt a QUiCK-ben ellenőrizni kell; az adatok helyességéért a felhasználó felel.
Törlés: költség- és bevételtétel az MCP szerveren keresztül nem törölhető. Törlés kizárólag törzsadatokra (költség- és bevételtípus, főkönyvi szám, ÁFA-kategória, címke) érhető el.
Felosztások teljes cseréje: az assignments tömb frissítése destruktív — a kérésből kimaradó felosztássorok törlődnek. Lásd a Műveletek fejezet figyelmeztetését.
Szinkronizált számlák: a bizonylati alapadatok (számlaszám, dátumok, összegek, partneradatok) csak könyvelési bizonylatokon szerkeszthetők; szinkronizált számlákon ezek a mezők nem módosíthatók.
Haladó könyvelési mezők: a főkönyvi szám, ÁFA-kategória, munkaszám és ellenőrzési mezők csak haladó könyveléssel rendelkező cégeknél érvényesülnek.
OCR aszinkron: a create_expenses hívással feltöltött fájlok mezőit a felismerés utólag tölti ki; a hívás sikere önmagában nem jelenti a mezők kitöltöttségét.
Lapozási korlát: listánként legfeljebb 200 elem kérhető le egy oldalon; a számlakép-lekérdezések (artifacts) nem lapozottak.
Riport-aggregáció: dedikált Havi eredmény vagy kimutatás-eszköz nincs; összefoglalót a get_pulse ad, részletes elemzéshez a listaadatokból kell aggregálni.