Dodajanje vmesnika z aplikacijami MCP
Na tej strani
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-apps1.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čilo | Vloga |
|---|---|
ui/initialize nato ui/notifications/initialized | Odpre dialog z gostiteljem |
ui/notifications/tool-input | Prejme argumente klica orodja |
ui/notifications/tool-result | Prejme rezultat orodja |
tools/call | Pokliče strežniško orodje iz vmesnika |
ui/message | Pošlje nadaljnje sporočilo v pogovor |
ui/update-model-context | Obvesti 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:
| Predstavitev | Uporaba |
|---|---|
| Vgrajena kartica | Ciljni rezultat, potrditev, nekaj dejanj, brez globoke navigacije |
| Vgrajen vrtiljak | Brskanje in izbira med nekaj podobnimi, vizualnimi možnostmi |
| Celozaslonski način | Bogata naloga: zemljevid, platno za urejanje, podrobno raziskovanje; vnosno območje ChatGPT ostane na voljo |
| Slika-v-sliki | Dejavnost 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:
| Potreba | Standard aplikacij MCP | Vzdevek ChatGPT |
|---|---|---|
| Pripni orodje vmesniku | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Prejmi argumente | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Prejmi rezultat | ui/notifications/tool-result | window.openai.toolOutput |
| Pokliči orodje | tools/call | window.openai.callTool |
| Pošlji nadaljnje sporočilo | ui/message | window.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
| Stanje | Lastnik | Življenjska doba | Primeri |
|---|---|---|---|
| Poslovni podatki, vir resnice | Strežnik MCP ali zunanja storitev | Dolga | Naloge, listki, dokumenti |
| Stanje vmesnika, prehodno | Primerek komponente | Trajanje njenega prikaza | Izbrana vrstica, odprta plošča, vrstni red razvrščanja |
| Trajno stanje med sejami | Shramba, ki jo nadzoruješ | Med pogovori in napravami | Shranjeni 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://tipatext/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.openaiponuja le razširitve, ki jih je treba zaznati pred uporabo- Poslovni podatki na strežniku, ozka CSP, različičen URI vira