Přidání rozhraní s aplikacemi MCP
Na této stránce
Lekce přepsána 3. listopadu 2026 na základě stránky Add UI to your MCP server z dokumentace OpenAI Plugins a kódu pro
@modelcontextprotocol/ext-apps1.7.5. Předchozí lekce popisovala „widgety“ (defineWidget) z neexistujícího SDK; rozhraní je zdroj MCP Apps vykreslovaný ChatGPT v iframe. Zdroje: Add UI to your MCP server · MCP Apps Specification.
Kdy přidat rozhraní
Rozhraní je volitelné. Přidej ho, když uživatel potřebuje prohlížet, porovnávat, upravovat, potvrzovat nebo procházet strukturované informace – a zároveň udržuj své nástroje funkční i bez něj, aby ChatGPT a Codex mohly řídit pracovní postup v klientech, které komponentu nezobrazují.
Princip MCP Apps
ChatGPT implementuje otevřený standard MCP Apps. Server deklaruje zdroj rozhraní, identifikovaný URI ui://… a obsluhovaný s typem MIME text/html;profile=mcp-app; nástroj se k němu připojí přes _meta.ui.resourceUri. Když je tento nástroj zavolán, ChatGPT zobrazí zdroj v iframe vedle konverzace. Komponenta komunikuje s hostitelem prostřednictvím JSON-RPC pomocí postMessage:
| Zpráva | Role |
|---|---|
ui/initialize a poté ui/notifications/initialized | Otevření dialogu s hostitelem |
ui/notifications/tool-input | Přijetí argumentů volání nástroje |
ui/notifications/tool-result | Přijetí výsledku nástroje |
tools/call | Volání nástroje serveru z rozhraní |
ui/message | Odeslání následné zprávy v konverzaci |
ui/update-model-context | Informování modelu o aktuálním výběru nebo úpravě |
Na straně serveru: deklarace zdroje a nástroje
Podívejme se znovu na server pro poznámky z lekce 4. Balíček @modelcontextprotocol/ext-apps (ve verzi 1.x s SDK v1) poskytuje dva pomocníky: registerAppResource, který ve výchozím nastavení aplikuje správný typ MIME exponovaný konstantou RESOURCE_MIME_TYPE, a registerAppTool, který vyžaduje metadata rozhraní.
import { readFileSync } from "node:fs";
import {
registerAppResource,
registerAppTool,
RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
const URI_CARTE = "ui://widget/notes-v1.html"; // verzováno: toto je klíč mezipaměti
const carteHtml = readFileSync("public/notes-widget.html", "utf8");
// Přidej uvnitř creerServeur(), vedle 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.` }],
})
);
Pouze show_notes nese rozhraní. To je oddělení, které OpenAI doporučuje: pokud by každý nástroj vracel šablonu, ChatGPT by příliš často překresloval iframe. Datové nástroje (list_notes, add_note) hledají, počítají nebo upravují a vracejí pouze svůj výsledek; nástroje pro vykreslování přijímají konečná data a vracejí šablonu. Model tak může pracovat s daty – filtrovat, křížově odkazovat – než se rozhodne pro zobrazení, a karta se objeví pouze jednou, s ověřeným kontextem. Závislost uveď v popisu nástroje pro vykreslování, jak je ukázáno výše.
Na straně iframe: most JSON-RPC
Komponenta sem zapadá jako jediný HTML soubor bez kroku sestavení. Otevře dialog s hostitelem a poté zobrazí každý přijatý výsledek nástroje.
<!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 přijatá 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>
Přijatý výsledek jsou nedůvěryhodná data: zobrazuj je pomocí textContent, nikdy je nevkládej jako HTML. Pro bohatší rozhraní poskytuje stejný balíček třídu App na straně prohlížeče, která tento most zapouzdřuje (přijímání výsledků, volání nástrojů) a je určena k integraci do svazku sestaveného pomocí esbuild; úložiště příkladů OpenAI ukazuje kompletní komponenty React.
Výběr prezentace
Začni s vloženým zobrazením a o více prostoru žádej pouze tehdy, pokud to pracovní postup vyžaduje:
| Prezentace | Použití |
|---|---|
| Vložená karta | Cílený výsledek, potvrzení, několik akcí bez hluboké navigace |
| Vložený karusel | Procházení a výběr z několika podobných vizuálních možností |
| Celá obrazovka | Náročný úkol: mapa, plátno pro úpravy, podrobný průzkum; vstupní oblast ChatGPT zůstává dostupná |
| Obraz v obraze | Probíhající aktivita, která musí zůstat viditelná během konverzace: živá relace, hra, video |
Rozšíření specifická pro ChatGPT
Jakmile je tok MCP Apps nastaven, nabízí ChatGPT rozšíření přes window.openai, která používej pouze pro to, co standard nepokrývá. Pro běžné potřeby upřednostni standard; aliasy ChatGPT zůstávají dostupné pro stávající integrace:
| Potřeba | Standard MCP Apps | Alias ChatGPT |
|---|---|---|
| Připojení nástroje k rozhraní | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Přijetí argumentů | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Přijetí výsledku | ui/notifications/tool-result | window.openai.toolOutput |
| Volání nástroje | tools/call | window.openai.callTool |
| Odeslání následné zprávy | ui/message | window.openai.sendFollowUpMessage |
Rozšíření bez ekvivalentu ve standardu pokrývají integrované platby (requestCheckout), soubory (uploadFile, selectFiles, getFileDownloadUrl), modální okna spravovaná hostitelem (requestModal) a perzistenci stavu komponenty (widgetState, setWidgetState). Před použitím každou schopnost detekuj a pokud možno poskytni záložní řešení – nikdy netestuj název hostitele, testuj funkci:
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.";
}
Tři druhy stavu
| Stav | Vlastník | Životnost | Příklady |
|---|---|---|---|
| Obchodní data, zdroj pravdy | Server MCP nebo externí služba | Dlouhá | Úkoly, tickety, dokumenty |
| Stav rozhraní, efemérní | Instance komponenty | Doba jejího zobrazení | Vybraný řádek, otevřený panel, pořadí řazení |
| Trvalý stav napříč relacemi | Úložiště, které kontroluješ | Mezi konverzacemi a zařízeními | Uložené filtry, režim zobrazení |
Obchodní data zůstávají na serveru: rozhraní zavolá nástroj, server validuje a aktualizuje, poté vrátí referenční stav, který rozhraní zobrazí, přičemž si ponechá pouze to, co souvisí s prezentací. Když model potřebuje znát výběr, odešli jej přes ui/update-model-context. window.openai.setWidgetState (synchronní, bez await) zachovává stav instance, nikoliv obchodní data. Trvalá data patří do tvého úložiště za autentizací; vyhni se localStorage, které nenabízí ani kontinuitu mezi zařízeními, ani spolehlivost v izolovaném iframe.
Zásady zabezpečení obsahu (CSP)
Komponenta ve svých metadatech zdroje (_meta.ui.csp) deklaruje přesné domény, které používá: connectDomains pro volání API, resourceDomains pro skripty, styly a obrázky, frameDomains pouze pokud musí integrovat specifická iframe – vnořená rámcová okna jsou ve výchozím nastavení blokována. Udržuj tyto seznamy co nejúžeji: revize pluginu porovnává deklarovanou politiku se skutečným chováním rozhraní. A zacházej s URI zdroje jako s klíčem mezipaměti: pro každou nekompatibilní změnu v HTML, JavaScriptu nebo CSS publikuj nové URI a aktualizuj nástroje, které na něj odkazují.
Dva poslední detaily: hostitel odráží jazyk uživatele v document.documentElement.lang, což použij pro překlad a formátování dat a čísel; a knihovna @openai/apps-sdk-ui poskytuje tlačítka, karty a pole odpovídající ChatGPT, pokud nechceš vše znovu navrhovat.
Klíčové poznatky
- Rozhraní je zdroj
ui://typutext/html;profile=mcp-app, připojený k nástroji přes_meta.ui.resourceUri - Komponenta komunikuje s hostitelem prostřednictvím JSON-RPC (
ui/initialize,tools/call,ui/notifications/tool-result…) - Odděl datové nástroje a nástroje pro vykreslování: šablonu nese pouze nástroj pro vykreslování
window.openaiposkytuje pouze rozšíření, která je třeba před použitím detekovat- Obchodní data na serveru, úzká CSP, verzované URI zdroje