Lisää käyttöliittymä MCP Appsilla
Tällä sivulla
Oppitunti kirjoitettu uudelleen 3. marraskuuta 2026 perustuen OpenAI:n liitännäisdokumentaation Add UI to your MCP server -sivuun ja
@modelcontextprotocol/ext-apps1.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:
| Viesti | Rooli |
|---|---|
ui/initialize ja sen jälkeen ui/notifications/initialized | Avaa vuoropuhelu isännän kanssa |
ui/notifications/tool-input | Vastaanota työkalukutsun argumentit |
ui/notifications/tool-result | Vastaanota työkalun tulos |
tools/call | Kutsu palvelimen työkalua käyttöliittymästä |
ui/message | Lähetä jatkoviesti keskusteluun |
ui/update-model-context | Ilmoita 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:
| Esitystapa | Käyttö |
|---|---|
| Upotettu kortti | Kohdennettu tulos, vahvistus, muutama toiminto ilman syvää navigointia |
| Upotettu karuselli | Selaa ja valitse muutamasta samankaltaisesta visuaalisesta vaihtoehdosta |
| Kokoruutu | Rikas tehtävä: kartta, muokkausalusta, yksityiskohtainen tutkimus; ChatGPT:n syöttöalue pysyy käytettävissä |
| Picture-in-picture | Kä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:
| Tarve | MCP Apps -standardi | ChatGPT-alias |
|---|---|---|
| Liitä työkalu käyttöliittymään | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Vastaanota argumentit | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Vastaanota tulos | ui/notifications/tool-result | window.openai.toolOutput |
| Kutsu työkalu | tools/call | window.openai.callTool |
| Lähetä jatkoviesti | ui/message | window.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
| Tila | Omistaja | Elinikä | Esimerkkejä |
|---|---|---|---|
| Liiketoimintadata, totuuden lähde | MCP-palvelin tai ulkoinen palvelu | Pitkä | Tehtävät, tiketit, dokumentit |
| Käyttöliittymätila, ohimenevä | Komponentti-instanssi | Näyttökesto | Valittu rivi, avoin paneeli, lajittelujärjestys |
| Pysyvä tila istuntojen välillä | Hallinnoimasi tallennus | Keskustelujen 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 ontext/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.openaitarjoaa vain laajennuksia, jotka täytyy tunnistaa ennen käyttöä- Liiketoimintadata palvelimella, kapea CSP, versioitu resurssi-URI