Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Lisää käyttöliittymä MCP Appsilla

Oppitunti 6 / 14 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Milloin lisätä käyttöliittymä
  2. MCP Apps -periaate
  3. Palvelinpuoli: ilmoita resurssi ja työkalu
  4. Iframe-puoli: JSON-RPC-silta
  5. Esitystavan valinta
  6. ChatGPT-specifit laajennukset
  7. Kolmenlaiset tilat
  8. Content Security Policy
  9. Keskeiset asiat

Oppitunti kirjoitettu uudelleen 3. marraskuuta 2026 perustuen OpenAI:n liitännäisdokumentaation Add UI to your MCP server -sivuun ja @modelcontextprotocol/ext-apps 1.7.5 -koodiin. Edellinen oppitunti kuvasi olemattomasta SDK:sta peräisin olevia “widgettejä” (defineWidget); käyttöliittymä on MCP Apps -resurssi, jonka ChatGPT renderöi iframe-kehykseen. Lähteet: Add UI to your MCP server · MCP Apps Specification.

Milloin lisätä käyttöliittymä

Käyttöliittymä on valinnainen. Lisää se silloin, kun käyttäjän täytyy tarkastella, vertailla, muokata, vahvistaa tai selata jäsenneltyä tietoa – ja pidä työkalusi hyödyllisinä myös ilman sitä, jotta ChatGPT ja Codex voivat ohjata työnkulkua asiakasohjelmissa, jotka eivät näytä komponenttia.

MCP Apps -periaate

ChatGPT toteuttaa avoimen MCP Apps -standardin. Palvelin ilmoittaa käyttöliittymäresurssin, jonka tunnisteena on ui://…-URI ja joka tarjotaan MIME-tyypillä text/html;profile=mcp-app; työkalu liittää siihen _meta.ui.resourceUri:n kautta. Kun tätä työkalua kutsutaan, ChatGPT näyttää resurssin iframe-kehyksessä keskustelun vieressä. Komponentti kommunikoi isäntäsovelluksen kanssa JSON-RPC:llä käyttäen postMessage:

ViestiRooli
ui/initialize ja sen jälkeen ui/notifications/initializedAvaa vuoropuhelu isännän kanssa
ui/notifications/tool-inputVastaanota työkalukutsun argumentit
ui/notifications/tool-resultVastaanota työkalun tulos
tools/callKutsu palvelimen työkalua käyttöliittymästä
ui/messageLähetä jatkoviesti keskusteluun
ui/update-model-contextIlmoita mallille nykyinen valinta tai muutos

Palvelinpuoli: ilmoita resurssi ja työkalu

Katsotaanpa uudelleen oppitunnin 4 muistiinpanopalvelinta. Paketti @modelcontextprotocol/ext-apps (versiossa 1.x SDK v1:n kanssa) tarjoaa kaksi apuria: registerAppResource, joka soveltaa oletuksena RESOURCE_MIME_TYPE-vakion määrittämää oikeaa MIME-tyyppiä, ja registerAppTool, joka vaatii käyttöliittymämetatiedot.

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

const URI_CARTE = "ui://widget/notes-v1.html"; // versioitu: tämä on välimuistin avain
const carteHtml = readFileSync("public/notes-widget.html", "utf8");

// Lisää funktion creerServeur() sisälle, list_notesin ja add_noten viereen
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.` }],
  })
);

Vain show_notes sisältää käyttöliittymän. Tämä on OpenAI:n suosittelema irrottaminen: jos jokainen työkalu palauttaisi mallipohjan, ChatGPT piirtäisi iframe-kehyksen liian usein. Datatyökalut (list_notes, add_note) hakevat, laskevat tai muokkaavat ja palauttavat vain tuloksensa; renderöintityökalut vastaanottavat valmiin datan ja palauttavat mallipohjan. Malli voi näin ollen työskennellä datalla – suodattaa, ristiviitata – ennen kuin se päättää näyttää sen, ja kortti ilmestyy vain kerran varmennetussa kontekstissa. Ilmoita riippuvuus renderöintityökalun kuvauksessa, kuten yllä on esitetty.

Iframe-puoli: JSON-RPC-silta

Komponentti mahtuu tähän yhteen HTML-tiedostoon ilman käännösvaihetta. Se avaa vuoropuhelun isännän kanssa ja näyttää sitten jokaisen vastaanottamansa työkalutuloksen.

<!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; // älä koskaan käytä innerHTML:ää vastaanotetulle datalle
            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>

Vastaanotettu tulos on luottamatonta dataa: näytä se käyttämällä textContent:tä, älä koskaan injektoimalla sitä HTML:nä. Rikkaampaa käyttöliittymää varten sama paketti tarjoaa selainpuolen App-luokan, joka kapseloi tämän sillan (tulosten vastaanotto, työkalujen kutsuminen) ja integroidaan esbuildilla rakennettuun pakettiin; OpenAI:n esimerkkivarasto sisältää valmiita React-komponentteja.

Esitystavan valinta

Aloita upotetulla näytöllä ja pyydä lisää tilaa vain, jos työnkulku sitä vaatii:

EsitystapaKäyttö
Upotettu korttiKohdennettu tulos, vahvistus, muutama toiminto ilman syvää navigointia
Upotettu karuselliSelaa ja valitse muutamasta samankaltaisesta visuaalisesta vaihtoehdosta
KokoruutuRikas tehtävä: kartta, muokkausalusta, yksityiskohtainen tutkimus; ChatGPT:n syöttöalue pysyy käytettävissä
Picture-in-pictureKäynnissä oleva toiminta, jonka täytyy pysyä näkyvissä keskustelun aikana: live-istunto, peli, video

ChatGPT-specifit laajennukset

Kun MCP Apps -virta on paikallaan, ChatGPT tarjoaa laajennuksia window.openai:n kautta, joita tulee käyttää vain niihin tarpeisiin, joita standardi ei kata. Yleisiin tarpeisiin suosita standardia; ChatGPT-aliakset pysyvät saatavilla olemassa oleville integraatioille:

TarveMCP Apps -standardiChatGPT-alias
Liitä työkalu käyttöliittymään_meta.ui.resourceUri_meta["openai/outputTemplate"]
Vastaanota argumentitui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Vastaanota tulosui/notifications/tool-resultwindow.openai.toolOutput
Kutsu työkalutools/callwindow.openai.callTool
Lähetä jatkoviestiui/messagewindow.openai.sendFollowUpMessage

Laajennukset, joilla ei ole standardivastaavaa, kattavat integroidun kassan (requestCheckout), tiedostot (uploadFile, selectFiles, getFileDownloadUrl), isännän hallinnoimat modaalit (requestModal) ja komponenttitilan pysyvyyden (widgetState, setWidgetState). Tunnista jokainen ominaisuus ennen käyttöä ja tarjoa varasuunnitelma mahdollisuuksien mukaan – älä koskaan testaa isännän nimeä, testaa funktiota:

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.";
}

Kolmenlaiset tilat

TilaOmistajaElinikäEsimerkkejä
Liiketoimintadata, totuuden lähdeMCP-palvelin tai ulkoinen palveluPitkäTehtävät, tiketit, dokumentit
Käyttöliittymätila, ohimeneväKomponentti-instanssiNäyttökestoValittu rivi, avoin paneeli, lajittelujärjestys
Pysyvä tila istuntojen välilläHallinnoimasi tallennusKeskustelujen ja laitteiden välilläTallennetut suodattimet, näyttötila

Liiketoimintadata pysyy palvelimella: käyttöliittymä kutsuu työkalua, palvelin validoi ja päivittää, palauttaa sitten referenssitilan, jonka käyttöliittymä näyttää pitäen esitykseen liittyvät asiat. Kun mallin täytyy tietää valinnasta, lähetä se käyttämällä ui/update-model-context:tä. window.openai.setWidgetState (synkroninen, ei await:ia) säilyttää instanssin tilan, ei liiketoimintadataa. Pysyvä data menee omaan tallennukseesi todennuksen taakse; vältä localStorage:ää, joka ei tarjoa jatkuvuutta laitteiden välillä eikä luotettavuutta eristetyssä iframe-kehyksessä.

Content Security Policy

Komponentti ilmoittaa resurssimetatiedoissaan (_meta.ui.csp) tarkat verkkotunnukset, joita se käyttää: connectDomains API-kutsuille, resourceDomains skripteille, tyyleille ja kuville, frameDomains vain jos sen täytyy integroida tiettyjä iframe-kehyksiä – sisäkkäiset kehykset on estetty oletuksena. Pidä nämä listat mahdollisimman kapeina: liitännäisen tarkastus vertaa ilmoitettua käytäntöä käyttöliittymän todelliseen käyttäytymiseen. Ja kohtele resurssi-URI:ta välimuistinvaimena: jokaiselle HTML:n, JavaScriptin tai CSS:n yhteensopimattomalle muutokselle julkaise uusi URI ja päivitä siihen viittaavat työkalut.

Kaksi viimeistä yksityiskohtaa: isäntä heijastaa käyttäjän kielen kohteeseen document.documentElement.lang, jota tulee käyttää päivämäärien ja lukujen kääntämiseen ja muotoiluun; ja @openai/apps-sdk-ui-kirjasto tarjoaa painikkeita, kortteja ja kenttiä, jotka vastaavat ChatGPT:n tyyliä, jos et halua suunnitella kaikkea uudelleen.

Keskeiset asiat

  • Käyttöliittymä on ui://-resurssi, jonka tyyppi on text/html;profile=mcp-app, ja se liitetään työkaluun _meta.ui.resourceUri:n kautta
  • Komponentti kommunikoi isännän kanssa JSON-RPC:llä (ui/initialize, tools/call, ui/notifications/tool-result…)
  • Erota datatyökalut ja renderöintityökalut: vain renderöintityökalu sisältää mallipohjan
  • window.openai tarjoaa vain laajennuksia, jotka täytyy tunnistaa ennen käyttöä
  • Liiketoimintadata palvelimella, kapea CSP, versioitu resurssi-URI