Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Interfész hozzáadása MCP-alkalmazásokkal

6. lecke 14 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Mikor érdemes interfészt hozzáadni?
  2. Az MCP Apps elv
  3. Szerveroldal: az erőforrás és az eszköz deklarálása
  4. Iframe oldal: a JSON-RPC híd
  5. Megjelenési forma választása
  6. ChatGPT-specifikus kiterjesztések
  7. Háromféle állapot
  8. Tartalombiztonsági házirend (CSP)
  9. Főbb megállapítások

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-apps 1.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:

ÜzenetSzerep
ui/initialize, majd ui/notifications/initializedPárbeszéd megnyitása a gazdagéppel
ui/notifications/tool-inputEszközhívás argumentumainak fogadása
ui/notifications/tool-resultEszköz eredményének fogadása
tools/callSzerveroldali eszköz hívása az interfészről
ui/messageKövető üzenet küldése a beszélgetésben
ui/update-model-contextA 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ésHasználat
Beágyazott kártyaCélzott eredmény, megerősítés, néhány művelet, mély navigáció nélkül
Beágyazott karusszelBö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ényMCP Apps szabványChatGPT alias
Eszköz csatlakoztatása egy interfészhez_meta.ui.resourceUri_meta["openai/outputTemplate"]
Argumentumok fogadásaui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Eredmény fogadásaui/notifications/tool-resultwindow.openai.toolOutput
Eszköz hívásatools/callwindow.openai.callTool
Követő üzenet küldéseui/messagewindow.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

ÁllapotTulajdonosÉlettartamPéldák
Üzleti adat, az igazság forrásaMCP szerver vagy külső szolgáltatásHosszúFeladatok, jegyek, dokumentumok
Interfész állapot, ephemeraKomponens példányMegjelenésének időtartamaKivá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öttMentett 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ás text/html;profile=mcp-app típussal, amely a _meta.ui.resourceUri ré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.openai csak kiterjesztéseket biztosít, amelyeket használat előtt észlelni kell
  • Üzleti adatok a szerveren, szűk CSP, verziókezelt erőforrás URI