Pridanie rozhrania s aplikáciami MCP
Na tejto strane
Lekcia prepísaná 3. novembra 2026 na základe stránky Add UI to your MCP server z dokumentácie OpenAI Plugins a kódu pre
@modelcontextprotocol/ext-apps1.7.5. Predchádzajúca lekcia popisovala „widgety“ (defineWidget) z neexistujúceho SDK; rozhranie je zdroj MCP Apps vykresľovaný ChatGPT v iframe. Zdroje: Add UI to your MCP server · MCP Apps Specification.
Kedy pridať rozhranie
Rozhranie je voliteľné. Pridaj ho, keď používateľ potrebuje skontrolovať, porovnať, upraviť, potvrdiť alebo prehliadať štruktúrované informácie – a zároveň udržuj svoje nástroje použiteľné aj bez neho, aby ChatGPT a Codex mohli viesť pracovný postup v klientoch, ktoré komponent nezobrazujú.
Princíp MCP Apps
ChatGPT implementuje otvorený štandard MCP Apps. Server deklaruje zdroj rozhrania, identifikovaný URI ui://… a obsluhovaný s MIME typom text/html;profile=mcp-app; nástroj sa k nemu pripojí cez _meta.ui.resourceUri. Keď sa tento nástroj zavolá, ChatGPT zobrazí zdroj v iframe vedľa konverzácie. Komponent komunikuje s hostiteľom cez JSON-RPC pomocou postMessage:
| Správa | Úloha |
|---|---|
ui/initialize a potom ui/notifications/initialized | Otvoriť dialóg s hostiteľom |
ui/notifications/tool-input | Prijatie argumentov volania nástroja |
ui/notifications/tool-result | Prijatie výsledku nástroja |
tools/call | Volanie nástroja servera z rozhrania |
ui/message | Odoslanie následnej správy v konverzácii |
ui/update-model-context | Informovanie modelu o aktuálnom výbere alebo úprave |
Strana servera: deklarácia zdroja a nástroja
Vráťme sa k serveru poznámok z lekcie 4. Balík @modelcontextprotocol/ext-apps (vo verzii 1.x so SDK v1) poskytuje dva pomocné nástroje: registerAppResource, ktorý aplikuje správny MIME typ exponovaný konštantou RESOURCE_MIME_TYPE predvolene, a registerAppTool, ktorý vyžaduje metadáta rozhrania.
import { readFileSync } from "node:fs";
import {
registerAppResource,
registerAppTool,
RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
const URI_CARTE = "ui://widget/notes-v1.html"; // verzia: toto je kľúč vyrovnávacej pamäte
const carteHtml = readFileSync("public/notes-widget.html", "utf8");
// Pridať dovnútra creerServeur(), vedľa list_notes a 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.` }],
})
);
Iba show_notes nesie rozhranie. Toto je oddelenie, ktoré OpenAI odporúča: keby každý nástroj vracal šablónu, ChatGPT by príliš často prekresľoval iframe. Nástroje pre dáta (list_notes, add_note) vyhľadávajú, počítajú alebo upravujú a vracajú iba svoj výsledok; nástroje na vykreslenie prijímajú finálne dáta a vracajú šablónu. Model tak môže pracovať s dátami – filtrovať, krížovo odkazovať – predtým, než sa rozhodne ich zobraziť, a karta sa objaví len raz, s overeným kontextom. Závislosť uveď v popise vykresľovacieho nástroja, ako je ukázané vyššie.
Strana iframe: mostík JSON-RPC
Komponent sem zapadne ako jeden HTML súbor bez kroku zostavenia (build). Otvorí dialóg s hostiteľom a potom zobrazí každý výsledok nástroja, ktorý prijme.
<!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; // nikdy innerHTML na prijatých dátach
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>
Prijatý výsledok sú nedôveryhodné dáta: zobrazuj ich pomocou textContent, nikdy nie vstrekovaním ako HTML. Pre bohatšie rozhranie poskytuje ten istý balík triedu App na strane prehliadača, ktorá zapuzdruje tento mostík (prijímanie výsledkov, volanie nástrojov) a má byť integrovaná do zväzku zostaveného pomocou esbuild; úložisko príkladov OpenAI ukazuje kompletné komponenty React.
Výber prezentácie
Začni s vloženým zobrazením a o viac priestoru požiadaj len vtedy, ak to pracovný postup vyžaduje:
| Prezentácia | Použitie |
|---|---|
| Vložená karta | Cielený výsledok, potvrdenie, niekoľko akcií bez hlbokej navigácie |
| Vložený karusel | Prehliadanie a výber z niekoľkých podobných vizuálnych možností |
| Celá obrazovka | Bohatá úloha: mapa, plátno na úpravy, podrobná explorácia; vstupná oblasť ChatGPT zostáva dostupná |
| Obraz v obraze (Picture-in-picture) | Prebiehajúca aktivita, ktorá musí zostať viditeľná počas konverzácie: živá relácia, hra, video |
Rozšírenia špecifické pre ChatGPT
Akonáhle je tok MCP Apps nastavený, ChatGPT ponúka rozšírenia cez window.openai, ktoré sa majú používať len na to, čo štandard nepokrýva. Pre bežné potreby uprednostni štandard; aliasy ChatGPT zostávajú dostupné pre existujúce integrácie:
| Potreba | Štandard MCP Apps | Alias ChatGPT |
|---|---|---|
| Pripojenie nástroja k rozhraniu | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Prijatie argumentov | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Prijatie výsledku | ui/notifications/tool-result | window.openai.toolOutput |
| Volanie nástroja | tools/call | window.openai.callTool |
| Odoslanie následnej správy | ui/message | window.openai.sendFollowUpMessage |
Rozšírenia bez ekvivalentu v štandarde pokrývajú integrovanú pokladňu (requestCheckout), súbory (uploadFile, selectFiles, getFileDownloadUrl), modálne okná spravované hostiteľom (requestModal) a perzistenciu stavu komponentu (widgetState, setWidgetState). Pred použitím detekuj každú schopnosť a ak je to možné, priprav náhradné riešenie – a nikdy netestuj názov hostiteľa, testuj funkciu:
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 druhy stavu
| Stav | Vlastník | Životnosť | Príklady |
|---|---|---|---|
| Obchodné dáta, zdroj pravdy | Server MCP alebo externá služba | Dlhá | Úlohy, tikety, dokumenty |
| Stav rozhrania, efemérny | Inštancia komponentu | Trvanie jeho zobrazenia | Vybraný riadok, otvorený panel, poradie triedenia |
| Trvalý stav medzi reláciami | Úložisko, ktoré kontroluješ | Medzi konverzáciami a zariadeniami | Uložené filtre, režim zobrazenia |
Obchodné dáta zostávajú na serveri: rozhranie zavolá nástroj, server overí a aktualizuje, potom vráti referenčný stav, ktorý rozhranie zobrazí, pričom si ponechá to, čo súvisí s prezentáciou. Keď model potrebuje vedieť o výbere, pošli mu ho cez ui/update-model-context. window.openai.setWidgetState (synchronné, bez await) zachováva stav inštancie, nie obchodné dáta. Trvalý stav ukladaj do svojho úložiska za autentifikáciou; vyhni sa localStorage, ktoré neposkytuje ani kontinuitu medzi zariadeniami, ani spoľahlivosť v izolovanom iframe.
Zásady bezpečnosti obsahu (CSP)
Komponent deklaruje vo svojich metadátach zdroja (_meta.ui.csp) presné domény, ktoré používa: connectDomains pre volania API, resourceDomains pre skripty, štýly a obrázky, frameDomains len ak musí integrovať špecifické iframe – vnorené rámce sú predvolene blokované. Udržuj tieto zoznamy čo najužšie: recenzia pluginu porovnáva deklarovanú politiku so skutočným správaním rozhrania. A zaobchádzaj s URI zdroja ako s kľúčom vyrovnávacej pamäte: pri každej nekompatibilnej zmene v HTML, JavaScripte alebo CSS publikuj nové URI a aktualizuj nástroje, ktoré naň odkazujú.
Dva posledné detaily: hostiteľ odráža jazyk používateľa v document.documentElement.lang, ktorý sa má použiť na preklad a formátovanie dátumov a čísel; a knižnica @openai/apps-sdk-ui poskytuje tlačidlá, karty a polia zodpovedajúce ChatGPT, ak nechceš všetko nanovo dizajnovať.
Kľúčové poznatky
- Rozhranie je zdroj
ui://typutext/html;profile=mcp-app, pripojený k nástroju cez_meta.ui.resourceUri - Komponent komunikuje s hostiteľom cez JSON-RPC (
ui/initialize,tools/call,ui/notifications/tool-result…) - Oddeľ nástroje pre dáta a nástroje na vykreslenie: šablónu nesie iba vykresľovací nástroj
window.openaiposkytuje iba rozšírenia, ktoré treba pred použitím detekovať- Obchodné dáta na serveri, úzka CSP, verziované URI zdroja