Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Dodaj sučelje s MCP aplikacijama

Lekcija 6 od 14 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Kada dodati sučelje
  2. Načelo MCP aplikacija
  3. Na strani poslužitelja: deklariraj resurs i alat
  4. Na strani iframea: JSON-RPC most
  5. Odabir prezentacije
  6. Proširenja specifična za ChatGPT
  7. Tri vrste stanja
  8. Politika sigurnosti sadržaja (CSP)
  9. Ključne točke

Lekcija prepisana 3. studenog 2026. na temelju stranice Add UI to your MCP server iz dokumentacije o OpenAI priključcima i koda za @modelcontextprotocol/ext-apps 1.7.5. Prethodna lekcija opisivala je “widžete” (defineWidget) iz nepostojećeg SDK-a; sučelje je resurs MCP aplikacija koji ChatGPT prikazuje unutar iframea. Izvori: Add UI to your MCP server · MCP Apps Specification.

Kada dodati sučelje

Sučelje je opcionalno. Dodaj ga kada korisnik treba pregledati, usporediti, modificirati, potvrditi ili pregledavati strukturirane informacije – ali zadrži svoje alate korisnima i bez njega, kako bi ChatGPT i Codex mogli upravljati tijekom rada u klijentima koji ne prikazuju komponentu.

Načelo MCP aplikacija

ChatGPT implementira otvoreni standard MCP aplikacija. Poslužitelj deklarira resurs sučelja, identificiran URI-jem ui://… i poslužuje ga s MIME tipom text/html;profile=mcp-app; alat se na njega veže putem _meta.ui.resourceUri. Kada se taj alat pozove, ChatGPT prikazuje resurs u iframeu, pokraj razgovora. Komponenta komunicira s domaćinom putem JSON-RPC-a koristeći postMessage:

PorukaUloga
ui/initialize zatim ui/notifications/initializedOtvaranje dijaloga s domaćinom
ui/notifications/tool-inputPrimanje argumenata poziva alata
ui/notifications/tool-resultPrimanje rezultata alata
tools/callPozivanje alata poslužitelja iz sučelja
ui/messageSlanje poruke praćenja u razgovoru
ui/update-model-contextObavještavanje modela o trenutnom odabiru ili izmjeni

Na strani poslužitelja: deklariraj resurs i alat

Vratimo se poslužitelju bilješki iz Lekcije 4. Paket @modelcontextprotocol/ext-apps (u verziji 1.x sa SDK-om v1) nudi dva pomoćnika: registerAppResource, koji primjenjuje ispravan MIME tip izložen konstantom RESOURCE_MIME_TYPE prema zadanim postavkama, i registerAppTool, koji zahtijeva metapodatke sučelja.

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

const URI_CARTE = "ui://widget/notes-v1.html"; // verzionirano: ovo je ključ predmemorije
const carteHtml = readFileSync("public/notes-widget.html", "utf8");

// Dodaj unutar creerServeur(), pokraj list_notes i 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.` }],
  })
);

Samo show_notes nosi sučelje. To je odvajanje koje OpenAI preporučuje: da svaki alat vraća predložak, ChatGPT bi prečesto ponovno crtao iframe. Alati za podatke (list_notes, add_note) pretražuju, izračunavaju ili modificiraju i vraćaju samo svoj rezultat; alati za renderiranje primaju konačne podatke i vraćaju predložak. Model tako može raditi na podacima – filtrirati, križno referencirati – prije nego što odluči prikazati, a kartica se pojavljuje samo jednom, s verificiranim kontekstom. Naznači ovisnost u opisu alata za renderiranje, kao što je prikazano gore.

Na strani iframea: JSON-RPC most

Komponenta ovdje staje u jednu HTML datoteku, bez koraka izgradnje. Ona otvara dijalog s domaćinom, a zatim prikazuje svaki rezultat alata koji primi.

<!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; // never innerHTML on received data
            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>

Primljeni rezultat su nepouzdani podaci: prikaži ih s textContent, nikada ubacivanjem kao HTML. Za bogatije sučelje, isti paket nudi App klasu na strani preglednika koja encapsulira ovaj most (primanje rezultata, pozivanje alata), za integraciju u paket izgrađen s esbuildom; repozitorij s OpenAI primjerima prikazuje kompletne React komponente.

Odabir prezentacije

Započni s ugrađenim prikazom i zatraži više prostora samo ako to tijek rada zahtijeva:

PrezentacijaUpotreba
Ugrađena karticaCiljani rezultat, potvrda, nekoliko radnji, bez duboke navigacije
Ugrađeni karuselPregled i odabir među nekoliko sličnih, vizualnih opcija
Cijeli zaslonBogat zadatak: karta, platno za uređivanje, detaljno istraživanje; područje unosa ChatGPT-a ostaje dostupno
Slika-u-sliciAktivnost u tijeku koja mora ostati vidljiva tijekom razgovora: sesija uživo, igra, video

Proširenja specifična za ChatGPT

Kada je tijek MCP aplikacija postavljen, ChatGPT nudi proširenja putem window.openai, koja treba koristiti samo za ono što standard ne pokriva. Za uobičajene potrebe, preferiraj standard; ChatGPT aliasi ostaju dostupni za postojeće integracije:

PotrebaStandard MCP aplikacijaChatGPT alias
Vezanje alata na sučelje_meta.ui.resourceUri_meta["openai/outputTemplate"]
Primanje argumenataui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Primanje rezultataui/notifications/tool-resultwindow.openai.toolOutput
Pozivanje alatatools/callwindow.openai.callTool
Slanje poruke praćenjaui/messagewindow.openai.sendFollowUpMessage

Proširenja bez ekvivalenta u standardu pokrivaju integriranu naplatu (requestCheckout), datoteke (uploadFile, selectFiles, getFileDownloadUrl), modalne prozore kojima upravlja domaćin (requestModal) i trajnost stanja komponente (widgetState, setWidgetState). Detektiraj svaku mogućnost prije korištenja, s povratnom opcijom kada je to moguće – i nikada ne testiraj ime domaćina, testiraj funkciju:

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 vrste stanja

StanjeVlasnikVijek trajanjaPrimjeri
Poslovni podaci, izvor istineMCP poslužitelj ili vanjska uslugaDugoZadaci, tiketi, dokumenti
Stanje sučelja, efemernoInstanca komponenteTrajanje njezina prikazaOdabrani redak, otvorena ploča, redoslijed sortiranja
Trajno stanje kroz sesijePohrana kojom upravljašIzmeđu razgovora i uređajaSpremljeni filteri, način prikaza

Poslovni podaci ostaju na poslužitelju: sučelje poziva alat, poslužitelj validira i ažurira, zatim vraća referentno stanje, koje sučelje prikazuje zadržavajući ono što se odnosi na prezentaciju. Kada model treba znati odabir, pošalji ga putem ui/update-model-context. window.openai.setWidgetState (sinkrono, bez await) čuva stanje instance, a ne poslovne podatke. Trajno stanje ide u tvoju pohranu, iza autentifikacije; izbjegavaj localStorage, koji ne nudi ni kontinuitet između uređaja ni pouzdanost u izoliranom iframeu.

Politika sigurnosti sadržaja (CSP)

Komponenta deklarira, u svojim metapodacima resursa (_meta.ui.csp), točne domene koje koristi: connectDomains za API pozive, resourceDomains za skripte, stilove i slike, frameDomains samo ako mora integrirati specifične iframeove – ugniježđeni okviri blokirani su prema zadanim postavkama. Drži ove popise što užima: pregled priključka uspoređuje deklariranu politiku sa stvarnim ponašanjem sučelja. I tretiraj URI resursa kao ključ predmemorije: za svaku nekompatibilnu promjenu u HTML-u, JavaScriptu ili CSS-u, objavi novi URI i ažuriraj alate koji se na njega pozivaju.

Dva konačna detalja: domaćin odražava korisnikov jezik u document.documentElement.lang, što treba koristiti za prijevod i formatiranje datuma i brojeva; a biblioteka @openai/apps-sdk-ui nudi gumbe, kartice i polja koja odgovaraju ChatGPT-u ako ne želiš ponovno dizajnirati sve.

Ključne točke

  • Sučelje je resurs ui:// tipa text/html;profile=mcp-app, vezan na alat putem _meta.ui.resourceUri
  • Komponenta komunicira s domaćinom putem JSON-RPC-a (ui/initialize, tools/call, ui/notifications/tool-result…)
  • Odvoj alate za podatke i alate za renderiranje: samo alat za renderiranje nosi predložak
  • window.openai nudi samo proširenja, koja treba detektirati prije upotrebe
  • Poslovni podaci na poslužitelju, uska CSP, verzionirani URI resursa