WebMCP

protokol pro propojení webu s AI

navigator.modelContext.registerTool()

Jakub Novák

navigator.modelContext.registerTool() je metoda rozhraní WebMCP, kterou web registruje jednotlivý nástroj (tool) dostupný pro AI agenty. Web tím říká prohlížeči: „tohle umím udělat a takhle to zavolej.“ Agent – ať už asistent zabudovaný v prohlížeči, nebo napojená aplikace – pak může nástroj zavolat přímo, místo aby web ovládal naslepo přes klikání a screenshoty.

K čemu to slouží

WebMCP zavádí na objektu window.navigator nové rozhraní modelContext. Přes něj web deklaruje funkce, které smí používat AI agent. Přístup k těmto nástrojům zprostředkovává prohlížeč – ten může vyžádat souhlas uživatele, řídit oprávnění a volat nástroje jeden po druhém. Rozhraní je dostupné pouze na HTTPS stránkách.

Klíčová výhoda: nástroj implementujete v běžném JavaScriptu. Pokud už váš web má funkci, která něco dělá (přidá položku, odešle formulář, vyhledá produkt), často stačí ji jen „obalit“ jako tool a zpřístupnit agentům. Žádný samostatný server, žádná druhá codebase.

Co metoda přijímá

registerTool() dostane objekt popisující jeden nástroj se čtyřmi částmi:

  • name – unikátní jméno nástroje (např. add-todo).
  • description – popis v přirozeném jazyce, podle kterého agent pozná, k čemu nástroj je.
  • inputSchema – JSON schéma vstupních parametrů (typy, popisy, povinná pole).
  • execute – callback funkce, která nástroj skutečně provede. Může být asynchronní a vrátit Promise.

Příklad

Registrace nástroje, který přidá položku do seznamu úkolů:

if ("modelContext" in window.navigator) {
  window.navigator.modelContext.registerTool({
    name: "add-todo",
    description: "Přidá novou položku do seznamu úkolů",
    inputSchema: {
      type: "object",
      properties: {
        text: { type: "string", description: "Text položky" }
      },
      required: ["text"]
    },
    execute: ({ text }, agent) => {
      addTodoItem(text);   // vaše stávající funkce, která přidá úkol a překreslí UI
      return {
        content: [
          { type: "text", text: `Úkol "${text}" byl přidán.` }
        ]
      };
    }
  });
}

Funkce execute dostane rozbalené parametry (zde { text }) a druhý argument agent. Vrací strukturovanou odpověď s polem content, kterou agent dostane jako výsledek volání.

Vyžádání souhlasu uživatele

U citlivých akcí (nákup, platba, smazání) lze přes objekt agent vyžádat potvrzení uživatele uprostřed běhu nástroje pomocí agent.requestUserInteraction():

async function buyProduct({ product_id }, agent) {
  const confirmed = await agent.requestUserInteraction(async () => {
    return confirm(`Koupit produkt ${product_id}?`);
  });

  if (!confirmed) {
    throw new Error("Nákup zrušen uživatelem.");
  }

  executePurchase(product_id);
  return `Produkt ${product_id} byl zakoupen.`;
}

window.navigator.modelContext.registerTool({
  name: "buyProduct",
  description: "Zakoupí produkt podle jeho product_id.",
  inputSchema: {
    type: "object",
    properties: {
      product_id: { type: "string", description: "Identifikátor produktu" }
    },
    required: ["product_id"]
  },
  execute: buyProduct
});

registerTool vs. provideContext

WebMCP nabízí dva způsoby registrace nástrojů. provideContext({ tools: [...] }) nastaví celou sadu nástrojů najednou – každé další volání předchozí sadu smaže a nahradí. To se hodí pro single-page aplikace, které podle stavu UI nabízejí různé nástroje. Naproti tomu registerTool() a unregisterTool(name) přidávají a odebírají jednotlivé nástroje, aniž by resetovaly celý stav.

Na co si dát pozor

  • registerTool() vyhodí InvalidStateError, pokud nástroj se stejným jménem už existuje, je neplatné inputSchema, nebo je name či description prázdný řetězec.
  • Rozhraní funguje jen na HTTPS a jen v top-level kontextu (záložka prohlížeče), ne „headless“ bez viditelného okna.
  • Vždy ohlídejte synchronizaci UI – stav stránky se má aktualizovat bez ohledu na to, zda akci vyvolal člověk, nebo agent.
  • Pro velké množství nebo výpočetně náročné volání je vhodné práci přesunout do workeru, aby se neblokovalo hlavní vlákno.

Vztah k MCP

WebMCP záměrně kopíruje primitiva protokolu MCP (tools, resources, prompts), takže nástroje deklarované přes WebMCP umí použít libovolný MCP-kompatibilní agent s minimální překladovou vrstvou. Rozdíl je v tom, že WebMCP běží přímo v prohlížeči v relaci návštěvníka – nepotřebuje samostatný server ani autentizaci a tok volání zprostředkovává prohlížeč, který tak může vynucovat bezpečnostní pravidla webové platformy.

—

by

Jakub Novák