MCP eszközök a Butabot weboldalon – új konfiguráció, buktatók és a megoldás

A Butabot Drupal oldal frissült a legújabb Drupal verzióra, és mostantól távoli MCP (Model Context Protocol) szerverként működik a https://butabot.aboros.com/mcp címen. A szervert Claude egyéni konnektorként (custom connector) éri el, így a tartalmak kezelése közvetlenül egy Claude beszélgetésből is elvégezhető, a Drupal admin felület megnyitása nélkül.

Ez a cikk bemutatja az új eszközkészletet, azt, hogy mi változott az előző konfigurációhoz képest, és azt is, milyen akadályokba ütköztünk, amíg az írási műveletek végül működni kezdtek.

Az új eszközkészlet

Az előző cikkben bemutatott széles készlethez képest az új konfiguráció szűkebb és célzottabb: kilenc eszköz, amelyek mind tartalomentitásokon dolgoznak.

Felderítés és séma

• entity_metadata – Egy entitás metaadatainak lekérése, akár betöltött entitás, akár típus és azonosító alapján
• entity_field_value_definitions – Egy entitástípus és bundle (pl. node / article) mezőinek értéksémája és beállításai

Olvasás

• entity_list – Entitások listázása szűréssel, rendezéssel és mezőválasztással; oldalanként 1–50 elem, offset alapú lapozással
• entity_load_by_id – Konkrét entitás betöltése típus és azonosító alapján
• entity_field_values – Mezőértékek lekérése egy betöltött entitásból, opcionálisan csak a megadott mezőkre

Létrehozás és módosítás

• entity_create – Entitás létrehozása és mentése egyetlen lépésben
• entity_update – Meglévő entitás módosítása és mentése egyetlen lépésben, azonosító alapján. Foltként (patch) működik: csak a megadott mezők változnak, a többi változatlan marad, és opcionális revízió-naplóüzenettel új revízió jön létre
• entity_revision_add – Új, még nem mentett revízió egy meglévő entitáshoz, opcionális revízió-naplóüzenettel
• entity_save – Előkészített entitás vagy revízió mentése

Handle-alapú működés

Az eszközök nem a teljes entitást adják vissza, hanem egy handle-t (pl. handle:7f65fb0a-…), amely a betöltött vagy előkészített entitásra mutat. Ezt lehet továbbadni a következő eszköznek, például entity_load_by_id → entity_field_values, vagy entity_load_by_id → entity_revision_add → entity_save. Az entity_create és az entity_update nem igényel handle-t, mindkettő egyetlen hívásban végez.

Mi változott az előző konfigurációhoz képest?

• Új eszközök: entity_create, entity_update és entity_metadata
• Kikerült a struktúrakezelés: bundle-ök és mezők létrehozása vagy módosítása
• Kikerült a felhasználókezelés: szerepkörök kezelése, fiókok tiltása és feloldása
• Kikerültek a rendszerműveletek: system_status, naplózás, üzenetek és e-mail küldés
• Kikerült továbbá: a jsonapi_read, az entity_load_by_property, az entity_stub és a field_set_value

A field_set_value szerepét az entity_update vette át: egy hívásban több mező is módosítható, revízióval együtt. Törlésre továbbra sincs eszköz. A szűkebb kör cserébe biztonságosabb: a konnektor tartalmat kezel, a webhely szerkezetéhez és a felhasználókhoz nem nyúl.

A buktatók

Az olvasás az első pillanattól működött, az írás viszont több, egymást elfedő hibán akadt el:

1. Hozzáférés megtagadva. Az entity_create hívás „Access denied for tool tool_belt:entity_create” hibát adott.
2. Érvénytelen szövegformátum. A törzsmező basic_html formátumát a validáció „not a valid choice” hibával elutasította, pedig a gépi név helyes volt. Ugyanez a hiba jelent meg a régi cikk törzsének olvasásakor is.
3. Hiányzó információ a sémában. Az eszköz sémája a formátumot csak „szöveg vagy null” típusként írta le, az engedélyezett értékek listája nem látszott. Amikor a törzsmezőn egyetlen formátumot engedélyeztünk, a mezőbeállításokban már megjelent az allowed_formats: ["basic_html"], de a hívás továbbra is elbukott.
4. Egymást elfedő hibák. A formátum ellenőrzése a hozzáférés ellenőrzése előtt futott, így formátummal a jogosultsági hiba nem is látszott. Csak formátum nélkül derült ki, hogy valójában két külön probléma van.
5. A jogosultság-módosítások hatástalanok voltak. A szerepkörök és a formátum jogosultságainak módosítása, majd az újrahitelesítés sem változtatott semmin.
6. Időzítés. Az új scope az újrahitelesítés után került be, a token scope-jai viszont a kiadás pillanatában rögzülnek, ezért még egy újrahitelesítésre volt szükség.
7. Nem szerkeszthető alapmezők. Végül a langcode és a status mezőt a konnektor felhasználója nem állíthatta be, így az alapértelmezett értékek érvényesültek – az első tesztcikk ezért rögtön közzétételre került.
8. Hiányzó módosító eszköz. Meglévő tartalom mezőit eleinte egyetlen eszköz sem tudta módosítani, ezért egy elgépelés vagy formázási hiba javításához új cikket kellett létrehozni. Ezt az entity_update eszköz hozzáadása oldotta meg – ez a cikk már ezzel lett frissítve.

A valódi ok

A gyors beállításhoz használt recept kizárólag olvasásra képes eszközöket tett elérhetővé, és a hozzá tartozó OAuth scope-ok is erre voltak korlátozva. Egyik scope sem engedélyezett létrehozást vagy módosítást.

Simple OAuth esetén a kérés jogosultságait a token scope-jai határozzák meg, nem pusztán a felhasználó szerepkörei. Ezért a szerepkörökhöz adott jogosultságok nem jutottak el a konnektorig. A formátumhiba is ugyanerre vezethető vissza: a Drupal a szövegformátum engedélyezett értékeit az aktuális felhasználó jogosultságai alapján állítja össze, így egy jogosultság nélküli kérés számára egyetlen formátum sem volt érvényes.

A megoldás

• Új scope létrehozása, amely nem egyetlen jogosultsághoz kötődik, hanem egy teljes Drupal szerepkört (content_editor) ad a tokennek
• A konnektor újrahitelesítése a scope hozzáadása után, hogy az új token már tartalmazza azt
• A cikk tartalomtípus alapértelmezett állapotának átállítása nem közzétettre, hogy az MCP-n keresztül létrehozott tartalom piszkozatként induljon
• Az entity_update eszköz hozzáadása, hogy a meglévő tartalom is javítható legyen

Ezután az entity_create basic_html formátummal hiba nélkül működött, és az entity_field_values is helyesen olvasta a törzsmezőt a formátummal együtt.

Tanulságok

• Ha egy OAuth-védett MCP szerveren valami „nem működik”, először a token scope-jait érdemes ellenőrizni, nem a szerepköröket.
• A scope-módosítások csak új tokenre hatnak, ezért utánuk mindig újra kell hitelesíteni.
• A félrevezető validációs hiba („not a valid choice”) valójában jogosultsági problémát takarhat.
• Érdemes a kérést lebontani (pl. formátum nélkül próbálni), hogy az egymást elfedő hibák külön látszódjanak.
• A gyors beállítást segítő receptek alapértelmezett, szűk jogosultságai biztonságosak, de az írási műveletekhez tudatosan bővíteni kell őket.
• Létrehozás mellé módosítási lehetőség is kell, különben minden apró javítás új, duplikált tartalmat eredményez.

Összegzés

Az új konfiguráció kevesebb, de tisztább, tartalomközpontú eszközt ad. A legnagyobb kihívást nem maguk az eszközök jelentették, hanem az OAuth scope-ok és a Drupal jogosultságok együttműködése. Ez a cikk már a javított beállítással, egy Claude beszélgetésből készült: az entity_create hozta létre, és az entity_update frissítette.