WebMCP: eszközöket publikálni pixelek helyett

A WebMCP javasolt webes szabvány, amely lehetővé teszi, hogy egy oldal tipizált, hívható eszközöket publikáljon egy KI-ügynöknek, ahelyett hogy az ügynök a DOM-ból találgatná a szándékot. A javaslat kicsi, a böngészőtámogatás vékony, a tervezési döntés viszont helyes. Kezeld specifikációként, amit figyelni kell, és progresszív enhancementként feature detection mögött, nem pedig függőségként erre a negyedévre.

A Model Context Protocol mellett áll, nem ellene. Egy MCP-szerver bármely kliensnek, bárhol ad backend képességeket; a WebMCP egy bejelentkezett oldal élő, tabon belüli állapotát adja át egy böngészőbe integrált ügynöknek, és eltűnik, ha a tab bezáródik. Az érdekes mérnöki kérdés nem az, melyik protokoll nyer. Az, melyik teszi elérhetővé a meglévő frontend-logikát anélkül, hogy hozzá kellene írni egy szervert.

Mi ez

A specifikáció a W3C Web Machine Learning Community Groupban él, és a WebMCP explainer dokumentálja a GitHubon, ahol a Chrome és az Edge csapatai a látható implementálók. A Chrome 149-től origin trial mögött szállítja, helyi fejlesztési kapcsolóval a chrome://flags/#enable-webmcp-testing címen. Az API egy objektum a Document interfészen, és két formában létezik.

• document.modelContext biztosítja a registerTool(), getTools(), executeTool() függvényeket és egy toolchange eseményt.
• Egy eszköz egy névből, természetes nyelvű leírásból, a bemenetre szóló JSON sémából és az oldalon belül futó execute függvényből áll.
• A deklaratív API egy annotált űrlapot alakít eszközzé a toolname, tooldescription, toolparamdescription és toolautosubmit attribútumokkal.
• Az eszközök efemerek. Csak addig léteznek, amíg az oldal nyitva van, és az oldal saját sütijeivel és sessionjével futnak.
• Mindkét API a tools Permissions Policy alá esik, amely alapértelmezés szerint self, így a cross-origin iframe-ek kikapcsolnak, amíg a hoszt be nem állítja az allow="tools" attribútumot.
• Az eszközök metaadatai a modell kontextusablakában vannak, ezért a regisztrált eszközök száma oldalankénti büdzsé, nem csak kódkérdés.

Hogyan működik

A regisztrálás egy hívás az oldalszkriptből; a meghívást a böngésző közvetíti az ügynök és az oldal között. A böngésző soha nem ad DOM-kezelőt az ügynöknek. Parszolja az argumentumokat, meghívja az execute függvényt, és a visszatérési értéket tool eredményként adja vissza. Ez az egész ergonómiai történet egy mondatban: az oldal dönti el, mi hívható, a böngésző pedig azt, ki hívhatja.

A gyakorlati különbség az aktuáláshoz képest a hibakezelési ágon látszik. Egy kattintás egy rosszul renderelt elemen csendben elbukik, vagy a rossz handlert hívja meg. Egy rossz argumentummal érkező eszközhívás a saját validációnkba ütközik, és olyan üzenetet ad vissza, amit a modell el tud olvasni és használni. A Chrome útmutatója ezt kimondja, és azt javasolja, hogy a kódban szigorúan validáljunk, a séma viszont legyen laza, mert a séma elutasítása zsákutca az ügynök számára.

Első lépések

Az imperatív API az, amivel érdemes dolgozni, mert csak ez tud alkalmazásállapothoz nyúlni. Egy minimális read-only eszköz így néz ki.

// Feature-detect: the API is behind a flag or an origin trial.
if (typeof document.modelContext?.registerTool !== 'function') return;

const controller = new AbortController();

await document.modelContext.registerTool({
  name: 'get_order_status',
  description: 'Return the shipping status of one order for the signed-in customer.',
  inputSchema: {
    type: 'object',
    properties: {
      orderNumber: { type: 'string', description: 'Order number as shown in the order list.' },
    },
    required: ['orderNumber'],
    additionalProperties: false,
  },
  annotations: { readOnlyHint: true },
  execute: async ({ orderNumber }) => {
    const order = await orders.findForCustomer(orderNumber);
    // A message the model can act on beats a thrown Error.
    if (!order) return `No order ${orderNumber} is visible to this account.`;
    return `Order ${orderNumber}: ${order.status}, arriving ${order.eta}.`;
  },
}, { signal: controller.signal });

// Unregister on route change. From Chrome 153 aborting no longer breaks a
// call that is already running.
controller.abort();

Három részlet fontosabb a többinél. A leírás az, amit a modell olvas el annak eldöntésére, hogy meghívja-e az eszközt, és a Chrome útmutatója 500 karakterre korlátozza. Az execute függvénynek azt a függvényt kellene újrahasznosítania, amit a látható gomb már meghív, hogy egyetlen kódút legyen, és a felület meg az eszköz ne mondjon ellent egymásnak. Az AbortSignal a leiratkozás útja, nem időzítő.

Deklaratív űrlapok

A deklaratív API egyszerű űrlapokra való, semmi másra. Annotáld az űrlapelemet, és a böngésző levezeti az eszköz definícióját a markupból és a mezőnevekből.

<form toolname="create_support_request"
      tooldescription="Submits a support request for the signed-in customer."
      action="/support"
      toolautosubmit>
  <label for="subject">Subject</label>
  <input id="subject" name="subject" type="text">

  <label for="reason">Reason</label>
  <select id="reason" name="reason" required
          toolparamdescription="Determines which team handles the request.">
    <option value="returns">Return a purchase</option>
    <option value="delivery">Where is my parcel</option>
    <option value="site">The website is broken</option>
  </select>

  <button type="submit">Submit</button>
</form>

A toolautosubmit nélkül az ügynök kitölti az űrlapot, és az ember megnyomja a küldést. Ez a helyes alapértelmezés mindenki számára, akinek költsége van a műveletnek. A attribútummal a böngésző küld és navigál, a respondWith() pedig a SubmitEvent eseményen lehetővé teszi, hogy az oldal eredményt adjon vissza a modellnek. Az agentInvoked jelzőflag megmondja az oldalnak, hogy melyik úton fut a folyamat.

Eszközök, amelyeket az ügynök kiválaszt

A közzétett best practice útmutató szokatlanul előíró, és érdemes szó szerint követni. A gondolatmenet: az eszköz leírása olyan kód, amelyet egy valószínűségi olvasó minden munkamenetben egyszer értelmez. A karakterbüdzsék azért léteznek, hogy a teljes katalógus ezen olvasó figyelmén belül maradjon.

A táblázat feletti tanács a nehezebbik fel: egy funkció eszközönként, ne legyenek átfedő eszközök, és a regisztrálás kötődjön az oldal állapotához egy minden oldalon betöltött statikus katalógus helyett. Az átfedő eszközök a leggyakoribb okai annak, hogy az ügynök a rosszat választja.

• Egy felelősség. Egy funkció eszközönként, és ne legyen második eszköz, ami szinte ugyanezt teszi.
• Regisztrálás az aktuális állapothoz. Szakítsd meg a controllert, amikor az útvonal vagy a dialógus változik, hogy az ügynök ne lásson már érvénytelen eszközöket.
• Fogadj nyers bemenetet. Ha valaki azt mondja 11:00 és 15:00 között, vedd a stringet, és normalizáld kódban. Ne a modell számoljon.
• Olvasható enum értékek. Az "express" jobb, mint a shipping_id = 1, mert a modell az értéket olvassa, nem az adatbázisodat.
• Használható hibát adj vissza. Írd le, mit kell tenni, nem azt, mi történt bent. Egy elbukó eszköznek is használhatónak kell maradnia.

Biztonság és annotációk

Az annotációk a fő határvonal, amivel egy oldal szabályozhatja, hogyan bánnak a hosztok az eszközeivel, és mind a négy alapértelmezés szerint hamis. Ez a biztonságos alapértelmezés, de azt is jelenti, hogy egy eszköz biztonsági tulajdonságai annyira őszinték, amennyire az őket regisztráló oldal.

• readOnlyHint az eszköz csak olvas, nem változtat semmit. Tedd rá minden kereső funkcióra.
• untrustedContentHint a visszatérési érték felhasználó által generált vagy külső adatot tartalmaz, és korlátozni kell, mielőtt eléri a modellt.
• consequentialHint a hívás foglal, fizet, küld vagy töröl. A kliensek megerősítést kényszeríthetnek ki vele.
• debugging Chrome 156-tól jelöli fejlesztői eszköznek, hogy az általános ügynökök kiszűrhessék.

A Chrome biztonsági útmutatója a közvetett prompt injekciót megoldatlannak tekinti. A modellek valószínűségiek, dokumentáltak az agentikus rendszerek elleni ismételhető támadások, és egy eszköz visszatérési értéke olyan csatorna, amelyet egy támadó írhat. Az ajánlott mitigációk az annotációk, a karakterbüdzsék és az origin izoláció, vagyis kárcsökkentés, nem megoldás. Ugyanez az oldal megjegyzi, hogy egy host engedélyekkel rendelkező extension az oldalt WebMCP nélkül is tetszőleges JavaScripttel irányíthatja.

Hol marad el

A gyengeségek jönnek először, mert ezek miatt ez figyelendő tétel, nem függőség. A támogatás gyakorlatilag egyetlen motorkészülékcsaládra korlátozódik. A specifikáció saját állapotfájlja origin trialt sorol fel a Chrome 149-ben és az Edge 150-ben, kísérleti támogatást a Brave Leo chatben, támogatást a ChatGPT Desktopban, valamint standards-position bejegyzéseket a Firefoxban és a WebKitben, implementáció nélkül. Emellett a Chrome dokumentációja a headless böngészős munkát a hatókörön kívül helyezi, figyelmeztet, hogy az összetett felületeket át kell alakítani az alkalmazás- és felületállapot szinkronban tartásához, és megjegyzi, hogy a klienseknek meg kell látogatniuk egy oldalt, hogy felfedezzék az eszközeit. Nincs nyilvántartás, nincs manifest, nincs index.

A felfedezhetőségi pont megérdemli a kiemelést, mert lerombolja a szokásos üzleti érvelést. Egy backend MCP-szervert megtalálhat egy olyan ügynök is, amely soha nem látja az oldalt. Egy WebMCP eszközt nem. Az egyetlen reális felfedezési út ma egy felhasználó, aki megnyitja az oldalt. A WebMCP tehát egy már elkezdődött munkamenet minőségéért verseng, nem a hatókörért.

Ítélet

A WebMCP egy jól rajzolt API egy valós problémára, és jobban rajzolva, mint ahogy a legtöbb csapat maga megépítené. Még nem függőség. Építsd az eszközréteget feature check mögé, tartsd a emberi felületet elsődleges útként, és térj vissza, ha megjelenik a második motor, vagy ha a deklaratív fele már nem csak Chromium-egyedüli. A részletekhez az oldal ügynékkészített weboldal deklarált eszközökkel című útmutatója ad részletes betekintést.

1. Vedd fel termékfelületeken, ahol egy bejelentkezett felhasználó és egy ügynök ugyanazt az oldalt látja: foglalás, checkout, támogatási kérelmek, beállítások.
2. Hagyd ki az egyszerű olvasási feladatoknál. Az oldal Markdown-másolata olcsóbb, és nem is kell böngésző.
3. Hagyd ki, ha a folyamatid túlnyomórészt olyan űrlapok, amelyeket nem tudsz annotálni, vagy ha nem tudod szinkronban tartani a felületet az eszközúttal.
4. Ne építs MCP-szervert arra az elvárásra, hogy a WebMCP lecseréli. Különböző rétegek, és a hasznos architektúra mindkettőt használja.
5. A karakterbüdzséket és az egy-funkció-egy-eszköz szabályt kemény korlátnak kezeld a katalógusra, nem javaslatnak.

Források

1. Chrome for Developers: WebMCP (get started)
2. Chrome for Developers: Imperative API
3. Chrome for Developers: Declarative API
4. Chrome for Developers: WebMCP versus MCP
5. Chrome for Developers: WebMCP tool security
6. Chrome for Developers: Build effective tools
7. WebMCP explainer and specification draft
8. WebMCP implementation status