Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Lisa liides MCP rakendustega

Õppetund 6 / 14 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Millal liides lisada
  2. MCP Apps’i põhimõte
  3. Serveri pool: ressursi ja tööriista deklareerimine
  4. Iframe’i pool: JSON-RPC sild
  5. Esitlusviisi valimine
  6. ChatGPT-spetsiifilised laiendused
  7. Kolme liiki olekud
  8. Sisuturbepoliitika (CSP)
  9. Peamised punktid

Õppetund kirjutati ümber 3. novembril 2026, tuginedes OpenAI pistikprogrammide dokumentatsiooni lehele Add UI to your MCP server ja paketi @modelcontextprotocol/ext-apps versiooni 1.7.5 koodile. Eelmine õppetund kirjeldas “vidinaid” (defineWidget) olematust SDK-st; liides on MCP Apps ressurss, mida ChatGPT renderdab iframe’is. Allikad: Add UI to your MCP server · MCP Apps Specification.

Millal liides lisada

Liides on valikuline. Lisa see siis, kui kasutaja peab struktureeritud teavet kontrollima, võrdlema, muutma, kinnitama või sirvima – ja hoia oma tööriistad kasulikena ka ilma selleta, et ChatGPT ja Codex saaksid töövoogu juhtida klientides, mis komponenti ei kuva.

MCP Apps’i põhimõte

ChatGPT rakendab avatud MCP Apps’i standardit. Server deklareerib liidese ressursi, mille identifikaatoriks on URI ui://… ja mida serveeritakse MIME-tüübiga text/html;profile=mcp-app; tööriist seob selle endaga väljade _meta.ui.resourceUri kaudu. Kui seda tööriista kutsutakse, kuvab ChatGPT ressursi iframe’is vestluse kõrval. Komponent suhtleb hostiga JSON-RPC protokolli kasutades läbi postMessage:

SõnumRoll
ui/initialize ja seejärel ui/notifications/initializedDialoogi avamine hostiga
ui/notifications/tool-inputTööriista väljakutse argumentide vastuvõtmine
ui/notifications/tool-resultTööriista tulemuse vastuvõtmine
tools/callServeri tööriista kutsumine liidesest
ui/messageJärelsõnumi saatmine vestlusse
ui/update-model-contextMudeli teavitamine praegusest valikust või muutusest

Serveri pool: ressursi ja tööriista deklareerimine

Vaatan üle 4. õppetunnist tuntud märkmete serveri. Pakett @modelcontextprotocol/ext-apps (versioonis 1.x koos SDK v1-ga) pakub kahte abifunktsiooni: registerAppResource, mis rakendab vaikimisi konstandi RESOURCE_MIME_TYPE kaudu õiget MIME-tüüpi, ja registerAppTool, mis nõuab liidese metaandmeid.

import { readFileSync } from "node:fs";
import {
  registerAppResource,
  registerAppTool,
  RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";

const URI_CARTE = "ui://widget/notes-v1.html"; // versioneeritud: see on vahemälu võti
const carteHtml = readFileSync("public/notes-widget.html", "utf8");

// Lisa funktsiooni creerServeur() sisse, kõrvuti list_notes ja add_note-ga
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.` }],
  })
);

Ainult show_notes kannab liidest. See on lahutatus, mida OpenAI soovitab: kui iga tööriist tagaks malli, joonistaks ChatGPT iframe’i liiga sageli ümber. Andmetööriistad (list_notes, add_note) otsivad, arvutavad või muudavad ja tagavad ainult tulemuse; renderdamistööriistad saavad lõplikud andmed ja tagavad malli. Mudel saab seega andmetega töötada – filtreerida, ristviidata – enne kui otsustab need kuvada, ja kaart ilmub ainult üks kord, kinnitatud kontekstiga. Märsi sõltuvus renderdamistööriista kirjelduses, nagu ülalpool näidatud.

Iframe’i pool: JSON-RPC sild

Komponent mahub siia ühteainsasse HTML-faili ilma kompileerimiseta. See avab dialoogi hostiga ja kuvab seejärel iga saadud tööriista tulemuse.

<!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>

Saadud tulemus on usaldamatu andmevoog: kuva seda textContent abil, mitte kunagi HTML-i süstides. Rikkalikuma liidese jaoks pakub sama pakett brauseripoolset klassi App, mis kapseldab selle silla (tulemuste vastuvõtmine, tööriistade kutsumine) ja mida saab integreerida esbuildiga loodud kimpu; OpenAI näidishoidla sisaldab täielikke Reacti komponente.

Esitlusviisi valimine

Alusta sisest kuvatavast esitlusest ja küsi rohkem ruumi ainult siis, kui töövoog seda nõuab:

EsitlusviisKasutus
Sisene kaartSihipärane tulemus, kinnitus, mõned toimingud ilma sügava navigeerimiseta
Sisene karussellSirvimine ja valimine mõne sarnase visuaalse variandi hulgast
TäisekraanMahukas ülesanne: kaart, redigeerimislõuend, üksikasjalik uurimine; ChatGPT sisendväli jääb kättesaadavaks
Pilt pildis (PiP)Käimasolev tegevus, mis peab vestluse ajal nähtavaks jääma: otseülekanne, mäng, video

ChatGPT-spetsiifilised laiendused

Kui MCP Apps’i voog on paigas, pakub ChatGPT laiendusi läbi window.openai, mida tuleks kasutada ainult selleks, mida standard ei kata. Levinud vajaduste puhul eelista standardit; ChatGPT aliased jäävad olemasolevate integratsioonide jaoks kättesaadavaks:

VajadusMCP Apps’i standardChatGPT alias
Tööriista liidesega sidumine_meta.ui.resourceUri_meta["openai/outputTemplate"]
Argumentide vastuvõtmineui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Tulemuse vastuvõtmineui/notifications/tool-resultwindow.openai.toolOutput
Tööriista kutsuminetools/callwindow.openai.callTool
Järelsõnumi saatmineui/messagewindow.openai.sendFollowUpMessage

Laiendused, millel puudub standardne vaste, hõlmavad integreeritud maksete tegemist (requestCheckout), faile (uploadFile, selectFiles, getFileDownloadUrl), hosti hallatavaid modaalaknaid (requestModal) ja komponendi oleku püsimist (widgetState, setWidgetState). Tuvasta iga võimalus enne selle kasutamist, kasutades vajadusel varulahendust – ja ära kunagi testi hosti nime, testi funktsiooni olemasolu:

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.";
}

Kolme liiki olekud

OlekOmanikEluigaNäited
Äriandmed, tõese allikasMCP server või väline teenusPikkÜlesanded, piletid, dokumendid
Liidese olek, mööduvKomponendi eksemplarKuvaamise kestusValitud rida, avatud paneel, sorteerimisjärjestus
Püsiv olek seansside vahelSinu hallatav salvestusruumVestluste ja seadmete vahelSalvestatud filtrid, kuva režiim

Äriandmed jäävad serverisse: liides kutsub tööriista, server valideerib ja uuendab, seejärel tagab viiteoleku, mida liides kuvab, säilitades samal ajal esitlusega seotu. Kui mudel peab teadma valikut, saada see läbi ui/update-model-context. window.openai.setWidgetState (sünkroonne, ilma await-ta) säilitab eksemplari oleku, mitte äriandmeid. Püsiv olek kuulub sinu salvestusruumi autentimise taga; välti localStorage-i, mis ei paku ei järjepidevust seadmete vahel ega usaldusväärsust isoleeritud iframe’is.

Sisuturbepoliitika (CSP)

Komponent deklareerib oma ressursi metaandmetes (_meta.ui.csp) täpsed domeenid, mida ta kasutab: connectDomains API-kõnede jaoks, resourceDomains skriptide, stiilide ja piltide jaoks ning frameDomains ainult siis, kui tuleb integreerida spetsiifilisi iframe’e – pesastatud raamid on vaikimisi blokeeritud. Hoia need loendid võimalikult kitsana: pistikprogrammi läbivaatus võrdleb deklareeritud poliitikat liidese tegeliku käitumisega. Ja kohtle ressursi URI-d vahemälu võtmena: iga HTML-i, JavaScripti või CSS-i mittesobiva muudatuse korral avalda uus URI ja uuenda tööriistu, mis sellele viitavad.

Kaks viimast detaili: host peegeldab kasutaja keelt väärtuses document.documentElement.lang, mida tuleks kasutada kuupäevade ja arvude tõlkimiseks ning vormindamiseks; ning teek @openai/apps-sdk-ui pakub nuppe, kaarte ja välju, mis sobituvad ChatGPT-ga, kui sa ei soovi kõike uuesti disainida.

Peamised punktid

  • Liides on tüüpi text/html;profile=mcp-app ressurss aadressiga ui://, mis on seotud tööriistaga väljade _meta.ui.resourceUri kaudu
  • Komponent suhtleb hostiga JSON-RPC abil (ui/initialize, tools/call, ui/notifications/tool-result…)
  • Eralda andmetööriistad ja renderdamistööriistad: ainult renderdamistööriist kannab malli
  • window.openai pakub ainult laiendusi, mida tuleb enne kasutamist tuvastada
  • Äriandmed serveris, kitsas CSP, versioneeritud ressursi URI