Interfész hozzáadása MCP-alkalmazásokkal
Ezen az oldalon
Lecke átírva: 2026. november 3. az OpenAI Bővítmények dokumentációjának Add UI to your MCP server oldala és a
@modelcontextprotocol/ext-apps1.7.5 kódja alapján. Az előző lecke egy nem létező SDK „widgetjeiről“ (defineWidget) írt; az interfész egy MCP Apps erőforrás, amelyet a ChatGPT egy iframe-ben jelenít meg. Források: UI hozzáadása az MCP szerverhez · MCP Apps specifikáció.
Mikor érdemes interfészt hozzáadni?
Az interfész opcionális. Akkor adj hozzá ilyet, ha a felhasználónak strukturált információkat kell megvizsgálnia, összehasonlítania, módosítania, megerősítenie vagy böngésznie – de az eszközöknek interfész nélkül is használhatónak kell maradniuk, így a ChatGPT és a Codex vezérelheti a munkafolyamatot olyan kliensekben is, amelyek nem jelenítenek meg komponenst.
Az MCP Apps elv
A ChatGPT megvalósítja a nyílt MCP Apps szabványt. A szerver deklarál egy interfész erőforrást, amelyet egy ui://… URI azonosít, és text/html;profile=mcp-app MIME-típussal szolgál ki; egy eszköz a _meta.ui.resourceUri segítségével csatlakozik hozzá. Amikor ezt az eszközt meghívják, a ChatGPT az erőforrást egy iframe-ben jeleníti meg, a beszélgetés mellett. A komponens JSON-RPC protokollal kommunikál a gazdagéppel a postMessage segítségével:
| Üzenet | Szerep |
|---|---|
ui/initialize, majd ui/notifications/initialized | Párbeszéd megnyitása a gazdagéppel |
ui/notifications/tool-input | Eszközhívás argumentumainak fogadása |
ui/notifications/tool-result | Eszköz eredményének fogadása |
tools/call | Szerveroldali eszköz hívása az interfészről |
ui/message | Követő üzenet küldése a beszélgetésben |
ui/update-model-context | A modell tájékoztatása az aktuális kiválasztásról vagy módosításról |
Szerveroldal: az erőforrás és az eszköz deklarálása
Nézzük újra a 4. leckéből ismerős jegyzetszervert. A @modelcontextprotocol/ext-apps csomag (az 1.x verzió az SDK v1-gyel) két segédfüggvényt biztosít: a registerAppResource-t, amely alapértelmezetten alkalmazza a RESOURCE_MIME_TYPE konstans által meghatározott helyes MIME-típust, és a registerAppTool-t, amelyhez az interfész metaadatai szükségesek.
import { readFileSync } from "node:fs";
import {
registerAppResource,
registerAppTool,
RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
const URI_CARTE = "ui://widget/notes-v1.html"; // verziókezelt: ez egy gyorsítótár-kulcs
const carteHtml = readFileSync("public/notes-widget.html", "utf8");
// Hozzáadás a creerServeur() függvényen belül, a list_notes és add_note mellett
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.` }],
})
);
Csak a show_notes rendelkezik interfésszel. Ez az a leválasztás, amelyet az OpenAI ajánl: ha minden eszköz sablont adna vissza, a ChatGPT túl gyakran rajzolná újra az iframe-et. Az adateszközök (list_notes, add_note) keresnek, számítanak vagy módosítanak, és csak az eredményt adják vissza; a megjelenítő eszközök megkapják a végleges adatokat, és visszaadják a sablont. Így a modell dolgozhat az adatokon – szűrhet, keresztbenhivatkozhat –, mielőtt a megjelenítés mellett dönt, és a kártya csak egyszer jelenik meg, ellenőrzött kontextussal. Jelöld a függőséget a megjelenítő eszköz leírásában, ahogy fent látható.
Iframe oldal: a JSON-RPC híd
A komponens egyetlen HTML-fájlba illeszthető, build lépés nélkül. Megnyitja a párbeszédet a gazdagéppel, majd megjeleníti a kapott egyes eszközeredményeket.
<!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; // soha ne használj innerHTML-t fogadott adatokon
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>
A fogadott eredmény megbízhatatlan adat: textContent segítségével jelenítsd meg, soha ne injektáld HTML-ként. Egy gazdagabb interfészhez ugyanez a csomag egy böngészőoldali App osztályt biztosít, amely kapszulázza ezt a hidat (eredmények fogadása, eszközök hívása), és beépíthető egy esbuild-del készített csomagba; az OpenAI példatára teljes React-komponenseket mutat be.
Megjelenési forma választása
Kezdd a beágyazott megjelenítéssel, és csak akkor kérj több helyet, ha a munkafolyamat megköveteli:
| Megjelenés | Használat |
|---|---|
| Beágyazott kártya | Célzott eredmény, megerősítés, néhány művelet, mély navigáció nélkül |
| Beágyazott karusszel | Böngészés és választás néhány hasonló, vizuális lehetőség közül |
| Teljes képernyő | Gazdag feladat: térkép, szerkesztővászon, részletes felfedezés; a ChatGPT beviteli területe elérhető marad |
| Picture-in-picture (Kép a képben) | Folyamatban lévő tevékenység, amelynek láthatónak kell maradnia a beszélgetés alatt: élő munkamenet, játék, videó |
ChatGPT-specifikus kiterjesztések
Ha az MCP Apps folyamat helyre került, a ChatGPT kiterjesztéseket kínál a window.openai objektumon keresztül, amelyeket csak olyan esetekben használj, amelyeket a szabvány nem fed le. A gyakori igényekhez предпочтedd a szabványt; a ChatGPT aliasok továbbra is elérhetők a meglévő integrációkhoz:
| Igény | MCP Apps szabvány | ChatGPT alias |
|---|---|---|
| Eszköz csatlakoztatása egy interfészhez | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Argumentumok fogadása | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Eredmény fogadása | ui/notifications/tool-result | window.openai.toolOutput |
| Eszköz hívása | tools/call | window.openai.callTool |
| Követő üzenet küldése | ui/message | window.openai.sendFollowUpMessage |
A szabvánnyal nem rendelkező kiterjesztések lefedik az integrált fizetést (requestCheckout), a fájlokat (uploadFile, selectFiles, getFileDownloadUrl), a gazdagép által kezelt modális ablakokat (requestModal) és a komponens állapotának megőrzését (widgetState, setWidgetState). Minden képességet használat előtt észlelned kell, lehetőleg tartalék megoldással – és soha ne a gazdagép nevét teszteld, hanem a függvényt:
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.";
}
Háromféle állapot
| Állapot | Tulajdonos | Élettartam | Példák |
|---|---|---|---|
| Üzleti adat, az igazság forrása | MCP szerver vagy külső szolgáltatás | Hosszú | Feladatok, jegyek, dokumentumok |
| Interfész állapot, ephemera | Komponens példány | Megjelenésének időtartama | Kiválasztott sor, nyitott panel, rendezési sorrend |
| Tartós állapot munkamenetek között | Általad kezelt tároló | Beszélgetések és eszközök között | Mentett szűrők, megjelenítési mód |
Az üzleti adatok a szerveren maradnak: az interfész hív egy eszközt, a szerver érvényesít és frissít, majd visszaadja a referenciaállapotot, amelyet az interfész megjelenít, miközben megtartja a megjelenítésre vonatkozó elemeket. Ha a modellnek tudnia kell egy kiválasztásról, küldd el azt a ui/update-model-context üzenettel. A window.openai.setWidgetState (szinkron, await nélkül) megőrzi egy példány állapotát, nem az üzleti adatokat. A tartós állapot a saját tárolódban legyen, hitelesítés mögött; kerüld a localStorage használatát, amely sem folytonosságot nem biztosít az eszközök között, sem megbízhatóságot egy izolált iframe-ben.
Tartalombiztonsági házirend (CSP)
A komponens deklarálja az erőforrás metaadataiban (_meta.ui.csp) a pontos domaineket, amelyeket használ: connectDomains az API-hívásokhoz, resourceDomains a szkriptekhez, stílusokhoz és képekhez, frameDomains pedig csak akkor, ha specifikus iframe-eket kell integrálnia – a beágyazott kereteket alapértelmezetten blokkolja a rendszer. Tartsd ezeket a listákat a lehető legszűkebbre: a bővítmények felülvizsgálata összehasonlítja a deklarált házirendet az interfész tényleges viselkedésével. És kezeld az erőforrás URI-t gyorsítótár-kulcsként: minden olyan incompatibilis változtatásnál a HTML-ben, JavaScriptben vagy CSS-ben, tegyél közzé egy új URI-t, és frissítsd a hivatkozó eszközöket.
Két utolsó részlet: a gazdagép tükrözi a felhasználó nyelvét a document.documentElement.lang attribútumban, amelyet a dátumok és számok lefordításához és formázásához használhatsz; az @openai/apps-sdk-ui könyvtár pedig gombokat, kártyákat és mezőket biztosít, amelyek illeszkednek a ChatGPT-hez, ha nem szeretnél mindent újra tervezni.
Főbb megállapítások
- Az interfész egy
ui://erőforrástext/html;profile=mcp-apptípussal, amely a_meta.ui.resourceUrirévén csatlakozik egy eszközhöz - A komponens JSON-RPC protokollal kommunikál a gazdagéppel (
ui/initialize,tools/call,ui/notifications/tool-result…) - Válaszd szét az adateszközöket és a megjelenítő eszközöket: csak a megjelenítő eszköz hordozza a sablont
- A
window.openaicsak kiterjesztéseket biztosít, amelyeket használat előtt észlelni kell - Üzleti adatok a szerveren, szűk CSP, verziókezelt erőforrás URI