Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Dodajanje vmesnika z aplikacijami MCP

Lekcija 6 od 14 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Kdaj dodati vmesnik
  2. Načelo aplikacij MCP
  3. Strežniška stran: razglasitev vira in orodja
  4. Stran iframe: most JSON-RPC
  5. Izbira predstavitve
  6. Razširitve, specifične za ChatGPT
  7. Tri vrste stanja
  8. Varnostna politika vsebine (CSP)
  9. Ključne ugotovitve

Lekcija na novo napisana 3. novembra 2026 na podlagi strani Add UI to your MCP server iz dokumentacije o vtičnikih OpenAI in kode za @modelcontextprotocol/ext-apps 1.7.5. Prejšnja lekcija je opisovala “gradnike” (defineWidget) iz neobstoječega SDK-ja; vmesnik je vir aplikacij MCP, ki ga ChatGPT izriše v elementu iframe. Viri: Add UI to your MCP server · MCP Apps Specification.

Kdaj dodati vmesnik

Vmesnik je neobvezen. Dodaj ga, ko uporabnik potrebuje pregled, primerjavo, spremembo, potrditev ali brskanje po strukturiranih informacijah – hkrati pa ohrani svoja orodja uporabna tudi brez njega, da lahko ChatGPT in Codex vodita delovni tok v odjemalcih, ki komponente ne prikazujejo.

Načelo aplikacij MCP

ChatGPT izvaja odprti standard aplikacij MCP. Strežnik razglasi vir vmesnika, identificiran z URI-jem ui://… in postrežen z vrsto MIME text/html;profile=mcp-app; orodje se nanj poveže prek _meta.ui.resourceUri. Ko je to orodje poklicano, ChatGPT prikaže vir v elementu iframe, ob pogovoru. Komponenta komunicira z gostiteljem prek JSON-RPC z uporabo postMessage:

SporočiloVloga
ui/initialize nato ui/notifications/initializedOdpre dialog z gostiteljem
ui/notifications/tool-inputPrejme argumente klica orodja
ui/notifications/tool-resultPrejme rezultat orodja
tools/callPokliče strežniško orodje iz vmesnika
ui/messagePošlje nadaljnje sporočilo v pogovor
ui/update-model-contextObvesti model o trenutni izbiri ali spremembi

Strežniška stran: razglasitev vira in orodja

Ponovno si oglejmo strežnik za zapiske iz lekcije 4. Paket @modelcontextprotocol/ext-apps (v različici 1.x s SDK v1) ponuja dva pomožnika: registerAppResource, ki privzeto uporabi pravilno vrsto MIME, izpostavljeno s konstanto RESOURCE_MIME_TYPE, in registerAppTool, ki zahteva metapodatke vmesnika.

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

const URI_CARTE = "ui://widget/notes-v1.html"; // različica: to je ključ predpomnilnika
const carteHtml = readFileSync("public/notes-widget.html", "utf8");

// Dodaj znotraj creerServeur(), poleg list_notes in 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 vmesnik. To je ločevanje, ki ga priporoča OpenAI: če bi vsako orodje vrnilo predlogo, bi ChatGPT prepogosto ponovno izrisal iframe. Podatkovna orodja (list_notes, add_note) iščejo, izračunavajo ali spreminjajo in vrnejo le svoj rezultat; orodja za izris prejmejo končne podatke in vrnejo predlogo. Model tako lahko dela s podatki – filtrira, križno preverja – preden se odloči za prikaz, kartica pa se pojavi le enkrat, s preverjenim kontekstom. Odvisnost navedi v opisu orodja za izris, kot je prikazano zgoraj.

Stran iframe: most JSON-RPC

Komponenta se prilega sem v eno samo datoteko HTML, brez koraka gradnje. Odpre dialog z gostiteljem, nato prikaže vsak rezultat orodja, ki ga prejme.

<!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>

Prejeti rezultat je nezaupljiv podatek: prikaži ga z textContent, nikoli z injiciranjem kot HTML. Za bogatejši vmesnik isti paket ponuja razred App na strani brskalnika, ki encapsulira ta most (prejemanje rezultatov, klicanje orodij) in ga je treba integrirati v sveženj, zgrajen z esbuild; skladišče primerov OpenAI prikazuje popolne komponente React.

Izbira predstavitve

Začni z vgrajenim prikazom in zahtevaj več prostora le, če to zahteva delovni tok:

PredstavitevUporaba
Vgrajena karticaCiljni rezultat, potrditev, nekaj dejanj, brez globoke navigacije
Vgrajen vrtiljakBrskanje in izbira med nekaj podobnimi, vizualnimi možnostmi
Celozaslonski načinBogata naloga: zemljevid, platno za urejanje, podrobno raziskovanje; vnosno območje ChatGPT ostane na voljo
Slika-v-slikiDejavnost v teku, ki mora ostati vidna med pogovorom: seja v živo, igra, video

Razširitve, specifične za ChatGPT

Ko je tok aplikacij MCP vzpostavljen, ChatGPT ponuja razširitve prek window.openai, ki jih uporabiš le za tisto, kar standard ne pokriva. Za običajne potrebe raje uporabi standard; vzdevki ChatGPT ostajajo na voljo za obstoječe integracije:

PotrebaStandard aplikacij MCPVzdevek ChatGPT
Pripni orodje vmesniku_meta.ui.resourceUri_meta["openai/outputTemplate"]
Prejmi argumenteui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Prejmi rezultatui/notifications/tool-resultwindow.openai.toolOutput
Pokliči orodjetools/callwindow.openai.callTool
Pošlji nadaljnje sporočiloui/messagewindow.openai.sendFollowUpMessage

Razširitve brez enakovrednega standarda pokrivajo integrirano plačilo (requestCheckout), datoteke (uploadFile, selectFiles, getFileDownloadUrl), modalna okna, ki jih upravlja gostitelj (requestModal), in trajnost stanja komponente (widgetState, setWidgetState). Pred uporabo zaznaj vsako zmožnost, po potrebi z nadomestilom – in nikoli ne testiraj imena gostitelja, testiraj funkcijo:

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

StanjeLastnikŽivljenjska dobaPrimeri
Poslovni podatki, vir resniceStrežnik MCP ali zunanja storitevDolgaNaloge, listki, dokumenti
Stanje vmesnika, prehodnoPrimerek komponenteTrajanje njenega prikazaIzbrana vrstica, odprta plošča, vrstni red razvrščanja
Trajno stanje med sejamiShramba, ki jo nadzoruješMed pogovori in napravamiShranjeni filtri, način prikaza

Poslovni podatki ostanejo na strežniku: vmesnik pokliče orodje, strežnik potrdi in posodobi, nato vrne referenčno stanje, ki ga vmesnik prikaže, ob ohranitvi vsega, kar se nanaša na predstavitev. Ko model potrebuje informacijo o izbiri, jo pošlji prek ui/update-model-context. window.openai.setWidgetState (sinhrono, brez await) ohranja stanje primerka, ne poslovnih podatkov. Trajno stanje shrani v svojo shrambo, za avtentikacijo; izogibaj se localStorage, ki ne ponuja niti neprekinjenosti med napravami niti zanesljivosti v izoliranem iframe.

Varnostna politika vsebine (CSP)

Komponenta v metapodatkih svojega vira (_meta.ui.csp) razglasi točne domene, ki jih uporablja: connectDomains za klice API, resourceDomains za skripte, sloge in slike, frameDomains le, če mora integrirati specifične iframe – gnezdeni okvirji so privzeto blokirani. Te sezname ohrani čim ožje: pregled vtičnika primerja razglašeno politiko z dejanskim vedenjem vmesnika. In obravnavaj URI vira kot ključ predpomnilnika: za vsako nezdružljivo spremembo HTML, JavaScript ali CSS objavi nov URI in posodobi orodja, ki se nanj sklicujejo.

Še dve podrobnosti: gostitelj odraža uporabnikov jezik v document.documentElement.lang, kar uporabiš za prevajanje in oblikovanje datumov in števil; knjižnica @openai/apps-sdk-ui pa ponuja gumbe, kartice in polja, ki ustrezajo ChatGPT, če ne želiš na novo oblikovati vsega.

Ključne ugotovitve

  • Vmesnik je vir ui:// tipa text/html;profile=mcp-app, pripet orodju prek _meta.ui.resourceUri
  • Komponenta komunicira z gostiteljem prek JSON-RPC (ui/initialize, tools/call, ui/notifications/tool-result…)
  • Loči podatkovna orodja in orodja za izris: le orodje za izris nosi predlogo
  • window.openai ponuja le razširitve, ki jih je treba zaznati pred uporabo
  • Poslovni podatki na strežniku, ozka CSP, različičen URI vira