Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Żid Interfaċċa ma' Apps MCP

Lezzjoni 6 / 14 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Meta żżid interfaċċa
  2. Il-prinċipju ta’ MCP Apps
  3. Naħa tas-server: iddikjara r-riżorsa u l-għodda
  4. Naħa tal-iframe: il-pont JSON-RPC
  5. Għażla ta’ preżentazzjoni
  6. Estensjonijiet speċifiċi għal ChatGPT
  7. Tliet tipi ta’ stat
  8. Politika tas-Sigurtà tal-Kontenut (CSP)
  9. Punti Ewlenin

Lezzjon miktuba mill-ġdid fit-3 ta’ Novembru 2026 ibbażata fuq il-paġna Add UI to your MCP server mid-dokumentazzjoni tal-Plugins ta’ OpenAI u l-kodiċi għal @modelcontextprotocol/ext-apps 1.7.5. Il-lezzjoni preċedenti kienet tiddeskrivi “widgets” (defineWidget) minn SDK li ma jeżistix; interfaċċa hija riżorsa ta’ MCP Apps irrenduta minn ChatGPT f’iframe. Sorsi: Add UI to your MCP server · MCP Apps Specification.

Meta żżid interfaċċa

L-interfaċċa hija fakultattiva. Żid waħda meta l-utent ikollu bżonn jeżamina, iqabbel, jimmodifika, jikkonferma, jew jibbrawsjja informazzjoni strutturata—u żomm l-għodod tiegħek utli mingħajrha, sabiex ChatGPT u Codex ikunu jistgħu jmexxu l-fluss tax-xogħol f’klijenti li ma jurux komponent.

Il-prinċipju ta’ MCP Apps

ChatGPT jimplimenta l-istandard miftuħ ta’ MCP Apps. Is-server jiddikjara riżorsa ta’ interfaċċa, identifikata minn URI ui://… u moqdija bit-tip MIME text/html;profile=mcp-app; għodda tħabbat magħha permezz ta’ _meta.ui.resourceUri. Meta din l-għodda tissejjaħ, ChatGPT juri r-riżorsa f’iframe, ħdejn il-konversazzjoni. Il-komponent jikkomunika mal-host permezz ta’ JSON-RPC bl-użu ta’ postMessage:

MessaġġRwol
ui/initialize imbagħad ui/notifications/initializedIftaħ id-djalogu mal-host
ui/notifications/tool-inputIrċievi l-argumenti tas-sejħa tal-għodda
ui/notifications/tool-resultIrċievi r-riżultat tal-għodda
tools/callSejjaħ għodda tas-server mill-interfaċċa
ui/messageIbgħat messaġġ ta’ segwitu fil-konversazzjoni
ui/update-model-contextInforma lill-mudell dwar selezzjoni jew modifika kurrenti

Naħa tas-server: iddikjara r-riżorsa u l-għodda

Ejja nerġgħu lura għas-server tan-noti mil-Lezzjoni 4. Il-pakkett @modelcontextprotocol/ext-apps (fil-verżjoni 1.x ma’ SDK v1) jipprovdi żewġ għajnuna: registerAppResource, li tapplika t-tip MIME korrett espost mill-kostanti RESOURCE_MIME_TYPE b'mod awtomatiku, u registerAppTool`, li teħtieġ il-metadejta tal-interfaċċa.

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

const URI_CARTE = "ui://widget/notes-v1.html"; // b'verżjoni: din hija ċavetta tal-cache
const carteHtml = readFileSync("public/notes-widget.html", "utf8");

// Żid ġewwa creerServeur(), ħdejn list_notes u 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.` }],
  })
);

Biss show_notes iġġorr l-interfaċċa. Dan huwa d-diżakkoppjament li OpenAI tirrakkomanda: kieku kull għodda kienet tirritorna mudell, ChatGPT kien jerġa’ jiġbed l-iframe wisq ta’ spiss. L-għodod tad-data (list_notes, add_note) ifittxu, jikkalkulaw, jew jimmodifikaw u jirritornaw biss ir-riżultat tagħhom; l-għodod tar-rendering jirċievu data finali u jirritornaw il-mudell. Il-mudell għalhekk jista’ jaħdem fuq id-data—jiffiltra, jikkrossa referenzi—qabel ma jiddeċiedi li juri, u l-karta tidher darba biss, b’kuntest ivverifikat. Indika d-dipendenza fid-deskrizzjoni tal-għodda tar-rendering, kif muri hawn fuq.

Naħa tal-iframe: il-pont JSON-RPC

Il-komponent joqgħod hawnhekk f’fajl HTML wieħed, mingħajr pass tal-bini. Jiftaħ id-djalogu mal-host, imbagħad juri kull riżultat ta’ għodda li jirċievi.

<!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; // qatt innerHTML fuq data riċevuta
            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>

Ir-riżultat riċevut huwa data mhux affidabbli: urih b’textContent, qatt billi tinjettah bħala HTML. Għal interfaċċa aktar rikka, l-istess pakkett jipprovdi klassi App fuq in-naħa tal-browser li tinkapsula dan il-pont (li tirċievi riżultati, isejħu għodod), biex tiġi integrata f’bundle mibni b’esbuild; ir-repożitorju tal-eżempji ta’ OpenAI juri komponenti React sħaħ.

Għażla ta’ preżentazzjoni

Ibda bid-display inline u itlob aktar spazju biss jekk il-fluss tax-xogħol jeħtieġu:

PreżentazzjoniUżu
Karta inlineRiżultat immirat, konferma, ftit azzjonijiet, mingħajr navigazzjoni fonda
Karosell inlineIbbrawsjja u agħżel fost ftit għażliet viżwali simili
Skrin sħiħKompitu rikk: mappa, kanvas tal-editjar, esplorazzjoni dettaljata; iż-żona tal-input ta’ ChatGPT tibqa’ disponibbli
Picture-in-pictureAttività li għaddejja li trid tibqa’ viżibbli waqt il-konversazzjoni: sessjoni ħajja, logħba, vidjo

Estensjonijiet speċifiċi għal ChatGPT

Ladarba l-fluss ta’ MCP Apps ikun fis-seħħ, ChatGPT joffri estensjonijiet permezz ta’ window.openai, biex jintużaw biss għal dak li l-istandard ma jkoprix. Għal ħtiġijiet komuni, ippreferi l-istandard; l-alias ta’ ChatGPT jibqgħu disponibbli għal integrazzjonijiet eżistenti:

ĦtieġaStandard ta’ MCP AppsAlias ta’ ChatGPT
Ħabbat għodda ma’ interfaċċa_meta.ui.resourceUri_meta["openai/outputTemplate"]
Irċievi argumentiui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Irċievi riżultatui/notifications/tool-resultwindow.openai.toolOutput
Sejjaħ għoddatools/callwindow.openai.callTool
Ibghat messaġġ ta’ segwituui/messagewindow.openai.sendFollowUpMessage

Estensjonijiet mingħajr ekwivalenti standard ikopru ħlas integrat (requestCheckout), fajls (uploadFile, selectFiles, getFileDownloadUrl), twieqi modali ġestiti mill-host (requestModal), u persistenza tal-istat tal-komponent (widgetState, setWidgetState). Skopri kull kapaċità qabel ma tużaha, b’fallback meta possibbli—u qatt ma ttestja l-isem tal-host, ittestja l-funzjoni:

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

Tliet tipi ta’ stat

StatSidTul tal-ħajjaEżempji
Data tan-negozju, sors tal-veritàServer MCP jew servizz esternTwilKompiti, tickets, dokumenti
Stat tal-interfaċċa, effimeruIstanza tal-komponentMatul id-display tiegħuRingiela magħżula, pannell miftuħ, ordni tas-sortjar
Stat durabbli bejn is-sessjonijietĦażna li tikkontrolla intBejn konversazzjonijiet u apparatiFiltri salvati, modalità tad-display

Id-data tan-negozju tibqa’ fuq is-server: l-interfaċċa ssejjaħ għodda, is-server jivvalida u jaġġorna, imbagħad jirritorna l-istat ta’ referenza, li l-interfaċċa turi waqt li żżomm dak li għandu x’jaqsam mal-preżentazzjoni. Meta l-mudell ikollu bżonn jaf dwar selezzjoni, ibgħatha permezz ta’ ui/update-model-context. window.openai.setWidgetState (sinkronu, mingħajr await) jippreserva l-istat ta’ istanza, mhux data tan-negozju. L-istat durabbli jmur fil-ħażna tiegħek, wara awtentikazzjoni; evita localStorage, li ma toffrix kontinwità bejn apparati u lanqas affidabbiltà f’iframe iżolat.

Politika tas-Sigurtà tal-Kontenut (CSP)

Il-komponent jiddikjara, fil-metadejta tar-riżorsa tiegħu (_meta.ui.csp), id-dominji eżatti li juża: connectDomains għal sejħiet API, resourceDomains għal skripts, stili, u immaġnijiet, frameDomains biss jekk irid jintegra iframes speċifiċi—frames imbejjna huma mblukkati b’mod awtomatiku. Żomm dawn il-listi kemm jista’ jkun dejqaq: ir-reviżjoni tal-plugin tqabbel il-politika ddikjarata mal-imġiba attwali tal-interfaċċa. U ttratta l-URI tar-riżorsa bħala ċavetta tal-cache: għal kull bidla inkompatibbli fl-HTML, JavaScript, jew CSS, ippubblika URI ġdida u aġġorna l-għodod li jirreferenzjawha.

Żewġ dettalji finali: l-host jirrifletti l-lingwa tal-utent f’document.documentElement.lang, biex tintuża għat-traduzzjoni u l-iffurmar ta’ dati u numri; u l-librerija @openai/apps-sdk-ui tipprovdi buttuni, karti, u oqsma li jaqblu ma’ ChatGPT jekk ma tridx terġa’ tfassal kollox.

Punti Ewlenin

  • Interfaċċa hija riżorsa ui:// tat-tip text/html;profile=mcp-app, imħabbta ma’ għodda permezz ta’ _meta.ui.resourceUri
  • Il-komponent jikkomunika mal-host permezz ta’ JSON-RPC (ui/initialize, tools/call, ui/notifications/tool-result…)
  • Separa l-għodod tad-data u l-għodod tar-rendering: biss l-għodda tar-rendering iġġorr il-mudell
  • window.openai jipprovdi biss estensjonijiet, li għandhom jiġu skoperti qabel l-użu
  • Data tan-negozju fuq is-server, CSP dejjaq, URI tar-riżorsa b’verżjoni