Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Pridanie rozhrania s aplikáciami MCP

Lekcia 6 z 14 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Kedy pridať rozhranie
  2. Princíp MCP Apps
  3. Strana servera: deklarácia zdroja a nástroja
  4. Strana iframe: mostík JSON-RPC
  5. Výber prezentácie
  6. Rozšírenia špecifické pre ChatGPT
  7. Tri druhy stavu
  8. Zásady bezpečnosti obsahu (CSP)
  9. Kľúčové poznatky

Lekcia prepísaná 3. novembra 2026 na základe stránky Add UI to your MCP server z dokumentácie OpenAI Plugins a kódu pre @modelcontextprotocol/ext-apps 1.7.5. Predchádzajúca lekcia popisovala „widgety“ (defineWidget) z neexistujúceho SDK; rozhranie je zdroj MCP Apps vykresľovaný ChatGPT v iframe. Zdroje: Add UI to your MCP server · MCP Apps Specification.

Kedy pridať rozhranie

Rozhranie je voliteľné. Pridaj ho, keď používateľ potrebuje skontrolovať, porovnať, upraviť, potvrdiť alebo prehliadať štruktúrované informácie – a zároveň udržuj svoje nástroje použiteľné aj bez neho, aby ChatGPT a Codex mohli viesť pracovný postup v klientoch, ktoré komponent nezobrazujú.

Princíp MCP Apps

ChatGPT implementuje otvorený štandard MCP Apps. Server deklaruje zdroj rozhrania, identifikovaný URI ui://… a obsluhovaný s MIME typom text/html;profile=mcp-app; nástroj sa k nemu pripojí cez _meta.ui.resourceUri. Keď sa tento nástroj zavolá, ChatGPT zobrazí zdroj v iframe vedľa konverzácie. Komponent komunikuje s hostiteľom cez JSON-RPC pomocou postMessage:

SprávaÚloha
ui/initialize a potom ui/notifications/initializedOtvoriť dialóg s hostiteľom
ui/notifications/tool-inputPrijatie argumentov volania nástroja
ui/notifications/tool-resultPrijatie výsledku nástroja
tools/callVolanie nástroja servera z rozhrania
ui/messageOdoslanie následnej správy v konverzácii
ui/update-model-contextInformovanie modelu o aktuálnom výbere alebo úprave

Strana servera: deklarácia zdroja a nástroja

Vráťme sa k serveru poznámok z lekcie 4. Balík @modelcontextprotocol/ext-apps (vo verzii 1.x so SDK v1) poskytuje dva pomocné nástroje: registerAppResource, ktorý aplikuje správny MIME typ exponovaný konštantou RESOURCE_MIME_TYPE predvolene, a registerAppTool, ktorý vyžaduje metadáta rozhrania.

import { readFileSync } from "node:fs";
import {
  registerAppResource,
  registerAppTool,
  RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";

const URI_CARTE = "ui://widget/notes-v1.html"; // verzia: toto je kľúč vyrovnávacej pamäte
const carteHtml = readFileSync("public/notes-widget.html", "utf8");

// Pridať dovnútra creerServeur(), vedľa list_notes a add_note
registerAppResource(server, "notes-widget", URI_CARTE, {}, async () => ({
  contents: [{ uri: URI_CARTE, mimeType: RESOURCE_MIME_TYPE, text: carteHtml }],
}));

registerAppTool(
  server,
  "show_notes",
  {
    title: "Show notes",
    description:
      "Displays notes in a card. To show only a subset, call list_notes first.",
    inputSchema: {},
    outputSchema: schemaNotes,
    annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
    _meta: { ui: { resourceUri: URI_CARTE } },
  },
  async () => ({
    structuredContent: { notes },
    content: [{ type: "text", text: `${notes.length} note(s) displayed.` }],
  })
);

Iba show_notes nesie rozhranie. Toto je oddelenie, ktoré OpenAI odporúča: keby každý nástroj vracal šablónu, ChatGPT by príliš často prekresľoval iframe. Nástroje pre dáta (list_notes, add_note) vyhľadávajú, počítajú alebo upravujú a vracajú iba svoj výsledok; nástroje na vykreslenie prijímajú finálne dáta a vracajú šablónu. Model tak môže pracovať s dátami – filtrovať, krížovo odkazovať – predtým, než sa rozhodne ich zobraziť, a karta sa objaví len raz, s overeným kontextom. Závislosť uveď v popise vykresľovacieho nástroja, ako je ukázané vyššie.

Strana iframe: mostík JSON-RPC

Komponent sem zapadne ako jeden HTML súbor bez kroku zostavenia (build). Otvorí dialóg s hostiteľom a potom zobrazí každý výsledok nástroja, ktorý prijme.

<!doctype html>
<html lang="en">
  <head><meta charset="utf-8" /><title>Notes</title></head>
  <body>
    <ul id="liste"></ul>
    <script type="module">
      const liste = document.querySelector("#liste");
      const enAttente = new Map();
      let dernierId = 0;

      const envoyer = (message) =>
        window.parent.postMessage({ jsonrpc: "2.0", ...message }, "*");
      const requete = (method, params) =>
        new Promise((resolve, reject) => {
          const id = ++dernierId;
          enAttente.set(id, { resolve, reject });
          envoyer({ id, method, params });
        });

      const afficher = (resultat) => {
        const notes = resultat?.structuredContent?.notes ?? [];
        liste.replaceChildren(
          ...notes.map((note) => {
            const li = document.createElement("li");
            li.textContent = note.text; // nikdy innerHTML na prijatých dátach
            return li;
          })
        );
      };

      window.addEventListener("message", (event) => {
        if (event.source !== window.parent) return;
        const msg = event.data;
        if (msg?.jsonrpc !== "2.0") return;
        if (typeof msg.id === "number" && enAttente.has(msg.id)) {
          const { resolve, reject } = enAttente.get(msg.id);
          enAttente.delete(msg.id);
          msg.error ? reject(msg.error) : resolve(msg.result);
        } else if (msg.method === "ui/notifications/tool-result") {
          afficher(msg.params);
        }
      });

      await requete("ui/initialize", {
        appInfo: { name: "notes-widget", version: "0.1.0" },
        appCapabilities: {},
        protocolVersion: "2026-01-26",
      });
      envoyer({ method: "ui/notifications/initialized", params: {} });
    </script>
  </body>
</html>

Prijatý výsledok sú nedôveryhodné dáta: zobrazuj ich pomocou textContent, nikdy nie vstrekovaním ako HTML. Pre bohatšie rozhranie poskytuje ten istý balík triedu App na strane prehliadača, ktorá zapuzdruje tento mostík (prijímanie výsledkov, volanie nástrojov) a má byť integrovaná do zväzku zostaveného pomocou esbuild; úložisko príkladov OpenAI ukazuje kompletné komponenty React.

Výber prezentácie

Začni s vloženým zobrazením a o viac priestoru požiadaj len vtedy, ak to pracovný postup vyžaduje:

PrezentáciaPoužitie
Vložená kartaCielený výsledok, potvrdenie, niekoľko akcií bez hlbokej navigácie
Vložený karuselPrehliadanie a výber z niekoľkých podobných vizuálnych možností
Celá obrazovkaBohatá úloha: mapa, plátno na úpravy, podrobná explorácia; vstupná oblasť ChatGPT zostáva dostupná
Obraz v obraze (Picture-in-picture)Prebiehajúca aktivita, ktorá musí zostať viditeľná počas konverzácie: živá relácia, hra, video

Rozšírenia špecifické pre ChatGPT

Akonáhle je tok MCP Apps nastavený, ChatGPT ponúka rozšírenia cez window.openai, ktoré sa majú používať len na to, čo štandard nepokrýva. Pre bežné potreby uprednostni štandard; aliasy ChatGPT zostávajú dostupné pre existujúce integrácie:

PotrebaŠtandard MCP AppsAlias ChatGPT
Pripojenie nástroja k rozhraniu_meta.ui.resourceUri_meta["openai/outputTemplate"]
Prijatie argumentovui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Prijatie výsledkuui/notifications/tool-resultwindow.openai.toolOutput
Volanie nástrojatools/callwindow.openai.callTool
Odoslanie následnej správyui/messagewindow.openai.sendFollowUpMessage

Rozšírenia bez ekvivalentu v štandarde pokrývajú integrovanú pokladňu (requestCheckout), súbory (uploadFile, selectFiles, getFileDownloadUrl), modálne okná spravované hostiteľom (requestModal) a perzistenciu stavu komponentu (widgetState, setWidgetState). Pred použitím detekuj každú schopnosť a ak je to možné, priprav náhradné riešenie – a nikdy netestuj názov hostiteľa, testuj funkciu:

const openai = typeof window !== "undefined" ? window.openai : undefined;
if (openai?.requestModal) {
  await openai.requestModal({ template: "ui://widget/details-v1.html" });
} else {
  document.body.textContent = "This host does not support modal windows.";
}

Tri druhy stavu

StavVlastníkŽivotnosťPríklady
Obchodné dáta, zdroj pravdyServer MCP alebo externá službaDlháÚlohy, tikety, dokumenty
Stav rozhrania, efemérnyInštancia komponentuTrvanie jeho zobrazeniaVybraný riadok, otvorený panel, poradie triedenia
Trvalý stav medzi reláciamiÚložisko, ktoré kontroluješMedzi konverzáciami a zariadeniamiUložené filtre, režim zobrazenia

Obchodné dáta zostávajú na serveri: rozhranie zavolá nástroj, server overí a aktualizuje, potom vráti referenčný stav, ktorý rozhranie zobrazí, pričom si ponechá to, čo súvisí s prezentáciou. Keď model potrebuje vedieť o výbere, pošli mu ho cez ui/update-model-context. window.openai.setWidgetState (synchronné, bez await) zachováva stav inštancie, nie obchodné dáta. Trvalý stav ukladaj do svojho úložiska za autentifikáciou; vyhni sa localStorage, ktoré neposkytuje ani kontinuitu medzi zariadeniami, ani spoľahlivosť v izolovanom iframe.

Zásady bezpečnosti obsahu (CSP)

Komponent deklaruje vo svojich metadátach zdroja (_meta.ui.csp) presné domény, ktoré používa: connectDomains pre volania API, resourceDomains pre skripty, štýly a obrázky, frameDomains len ak musí integrovať špecifické iframe – vnorené rámce sú predvolene blokované. Udržuj tieto zoznamy čo najužšie: recenzia pluginu porovnáva deklarovanú politiku so skutočným správaním rozhrania. A zaobchádzaj s URI zdroja ako s kľúčom vyrovnávacej pamäte: pri každej nekompatibilnej zmene v HTML, JavaScripte alebo CSS publikuj nové URI a aktualizuj nástroje, ktoré naň odkazujú.

Dva posledné detaily: hostiteľ odráža jazyk používateľa v document.documentElement.lang, ktorý sa má použiť na preklad a formátovanie dátumov a čísel; a knižnica @openai/apps-sdk-ui poskytuje tlačidlá, karty a polia zodpovedajúce ChatGPT, ak nechceš všetko nanovo dizajnovať.

Kľúčové poznatky

  • Rozhranie je zdroj ui:// typu text/html;profile=mcp-app, pripojený k nástroju cez _meta.ui.resourceUri
  • Komponent komunikuje s hostiteľom cez JSON-RPC (ui/initialize, tools/call, ui/notifications/tool-result…)
  • Oddeľ nástroje pre dáta a nástroje na vykreslenie: šablónu nesie iba vykresľovací nástroj
  • window.openai poskytuje iba rozšírenia, ktoré treba pred použitím detekovať
  • Obchodné dáta na serveri, úzka CSP, verziované URI zdroja