Dodaj sučelje s MCP aplikacijama
Na ovoj stranici
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-apps1.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:
| Poruka | Uloga |
|---|---|
ui/initialize zatim ui/notifications/initialized | Otvaranje dijaloga s domaćinom |
ui/notifications/tool-input | Primanje argumenata poziva alata |
ui/notifications/tool-result | Primanje rezultata alata |
tools/call | Pozivanje alata poslužitelja iz sučelja |
ui/message | Slanje poruke praćenja u razgovoru |
ui/update-model-context | Obavješ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:
| Prezentacija | Upotreba |
|---|---|
| Ugrađena kartica | Ciljani rezultat, potvrda, nekoliko radnji, bez duboke navigacije |
| Ugrađeni karusel | Pregled i odabir među nekoliko sličnih, vizualnih opcija |
| Cijeli zaslon | Bogat zadatak: karta, platno za uređivanje, detaljno istraživanje; područje unosa ChatGPT-a ostaje dostupno |
| Slika-u-slici | Aktivnost 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:
| Potreba | Standard MCP aplikacija | ChatGPT alias |
|---|---|---|
| Vezanje alata na sučelje | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Primanje argumenata | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Primanje rezultata | ui/notifications/tool-result | window.openai.toolOutput |
| Pozivanje alata | tools/call | window.openai.callTool |
| Slanje poruke praćenja | ui/message | window.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
| Stanje | Vlasnik | Vijek trajanja | Primjeri |
|---|---|---|---|
| Poslovni podaci, izvor istine | MCP poslužitelj ili vanjska usluga | Dugo | Zadaci, tiketi, dokumenti |
| Stanje sučelja, efemerno | Instanca komponente | Trajanje njezina prikaza | Odabrani redak, otvorena ploča, redoslijed sortiranja |
| Trajno stanje kroz sesije | Pohrana kojom upravljaš | Između razgovora i uređaja | Spremljeni 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://tipatext/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.openainudi samo proširenja, koja treba detektirati prije upotrebe- Poslovni podaci na poslužitelju, uska CSP, verzionirani URI resursa