Szerep-alapú eszköz-tár
A Nortinia AI Asszisztens egyetlen chat-felület, de a mögötte futó tool-katalógus szerepre szabott. Egy viewer nem ugyanazokat a műveleteket látja, mint egy admin, és egy super_admin sem kapja meg automatikusan a tenant-szintű korlátozott tool-okat. Ez a cikk leírja, hogyan működik az MCP scope guard, és milyen hibát kellett menet közben javítanunk.
A négy szerep
viewer
Csak olvasási műveletek. getInvoice, searchCustomer, listOrders, getAuditEvents — de semmi create, update, delete. A chat-mező mellett egy diszkrét ikon jelzi, hogy a felhasználó csak nézi a rendszert. Próbál a viewer egy mutációt? Az asszisztens udvariasan közli, hogy a szerep nem engedi, és felajánlja, hogy értesít egy editor-t.
editor
Mutációk preview-and-confirm fázissal. Minden write tool kétlépcsős: az asszisztens először egy diff-szerű összefoglalót mutat, és csak a felhasználó explicit megerősítése után fut le. Az editor látja a saját változtatásait az audit log-ban, de mások műveleteit nem.
admin
RBAC-műveletek (szerep csere, jogosultság-bővítés), audit-trail teljes nézet, tenant-konfiguráció módosítása, integrációk kezelése. Admin szerep felett a userManagement.* és audit.full tool-családok elérhetők. Itt a preview-and-confirm szigorúbb: minden destruktív műveletre (delete, role-downgrade) második megerősítés kell, írott okkal.
super_admin
Cross-tenant műveletek: Netorigo-belső szerep, ami minden ügyfél-fiókba beleláthat. Itt megjelennek a tenant.*, billing.crossTenant, featureFlag.global tool-családok. Ez a szerep audit-trail-ben dupla naplót hagy (tenant + Netorigo-belső), és minden cross-tenant tool-hívás külön notify-eseményt küld a tenant admin-jának.
A scope guard
Minden MCP tool deklarál egy requiredScopes listát. Például:
refund.initiate → ['payments:write', 'role:editor']
user.changeRole → ['users:write', 'role:admin']
tenant.delete → ['tenant:write', 'role:super_admin']
A chat-agent a beszélgetés kezdetén lekér egy szerep-token-t a felhasználó JWT-jéből, és a tools/list válasz csak azokat a tool-okat tartalmazza, amelyek scope-jai az adott token-nel teljesülnek. Más szóval: a viewer-nek nincs felsorolva a refund.initiate tool — nem tudja kérni, nem tudja látni.
A bug amit javítottunk
2026 májusban észrevettük, hogy super_admin szerep esetén a guard rosszul fogadta el a role:* wildcard-ot. Az implementáció egy korai változata azt csinálta, hogy ha a felhasználónak van role:super_admin token-je, akkor a tools/list válaszba minden tool bekerült — beleértve azokat is, amelyek explicit role:admin scope-ot kértek volna (és nem voltak duplán role:super_admin-osítva).
A gyakorlatban ez egy hetes szivárgás volt: egy super_admin felhasználó a chat-en keresztül látott olyan editor-szintű tool-okat is, amelyek nem voltak rá szabva. Mutációt nem lehetett vele csinálni (a guard a tool-call szintjén is ellenőriz), de a katalógus szivárgott.
A fix kétoldali: a tools/list szűrése most szigorú scope-match-et csinál (nem wildcard-permissive), és a tool-call szintű guard megduplázza az ellenőrzést. A super_admin-nak külön explicit role:admin token-mező is jár, ha admin-szintű tool-okat akar használni — ez egy szándékos UX-kompromisszum a biztonság javára.
Mit jelent a fejlesztés szempontjából
Új tool definiálásakor két dolog kötelező:
- Pontos scope-lista. Nem
role:*, hanem konkrét szerep. Ha egy tool-t több szerep is használhat, vagy-listával:['role:editor', 'role:admin']. - Per-scope unit-teszt. Minden új tool-nak van egy
tool.spec.ts-e, ami minden szerep-kombinációt próbál.
Ez lassítja a fejlesztést, de hat hónap után 1 bug-ot találtunk (a fenti), és azt is egy nappal a megjelenés után.
Miért nem egy fix tool-lista per szerep
Kipróbáltuk. Az első verzióban statikusan kódoltunk "viewer_tools.json", "editor_tools.json", stb. Karbantarthatatlan volt. Új tool = négy fájl szerkesztés. Tool-rename = négy fájl szerkesztés. Most a tool-katalógus a forrás, és a scope-szűrés runtime-on fut. Egyetlen igazság-forrás.
Mit hozunk legközelebb
A következő iteráció bevezet egy "granular scope" rendszert. Most a role:editor minden editor-szintű tool-ot enged. Hamarosan tudni fogjuk korlátozni szub-modulra: role:editor + module:finance csak finance-en belül enged write-ot, logistics-en nem. Ez nagy ügyfeleknél fontos lesz, ahol a finance és a warehouse csapat ugyanazt a Netorigo-instance-ot használja.