Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Cuir comhéadan le Aipeanna MCP leis

Ceacht 6 as 14 Nuashonraithe 3 Samhain 2026 Forbróir
Ar an leathanach seo
  1. Cathas comhéadan a chur leis
  2. Prionsabal Aipeanna MCP
  3. Taobh an fhreastalaí: dearbhaigh an acmhainn agus an uirlis
  4. Taobh an iframe: an droichead JSON-RPC
  5. Cur i láthair a roghnú
  6. Leathnúcháin ar leith ChatGPT
  7. Trí chineál stáit
  8. Beartas Slándála Inneachair (CSP)
  9. Príomhphointí

An ceacht athscríofa ar an 3 Samhain, 2026 bunaithe ar an leathanach Add UI to your MCP server ó dhoiciméadú Breiseáin OpenAI agus ar an gcód do @modelcontextprotocol/ext-apps 1.7.5. Thug an ceacht roimhe seo cur síos ar “giuirléidí” (defineWidget) ó SDK nach raibh ann riamh; is acmhainn Aipeanna MCP é comhéadan a thaispeántar ag ChatGPT in iframe. Foinse: Add UI to your MCP server(https://developers.openai.com/plugins/build/chatgpt-ui) · MCP Apps Specification.

Cathas comhéadan a chur leis

Tá an comhéadan roghnach. Cuir ceann leis nuair a theastaíonn ón úsáideoir faisnéis struchtúrtha a iniúchadh, a chur i gcomparáid, a mhodhnú, a dheimhniú, nó a bhrabhsáil—agus coinnigh do uirlisí úsáideach gan é, ionas gur féidir le ChatGPT agus Codex an sruth oibre a stiúradh i gcliaint nach dtaispeánann comhpháirt.

Prionsabal Aipeanna MCP

Cuireann ChatGPT an caighdeán oscailte Aipeanna MCP i bhfeidhm. Dearbhaíonn an freastalaí acmhainn comhéadain, arna sainaithint ag URI ui://… agus arna seirbheáil leis an gcineál MIME text/html;profile=mcp-app; ceanglaíonn uirlis leis trí _meta.ui.resourceUri. Nuair a ghlaotar ar an uirlis seo, taispeánann ChatGPT an acmhainn in iframe, in aice leis an gcomhrá. Déanann an chomhpháirt cumarsáid leis an óstach trí JSON-RPC ag baint úsáide as postMessage:

TeachtaireachtRól
ui/initialize ansin ui/notifications/initializedOscail an dialóg leis an óstach
ui/notifications/tool-inputFaigh argóintí glao na huirlise
ui/notifications/tool-resultFaigh toradh na huirlise
tools/callGlaoigh ar uirlis freastalaí ón gcomhéadan
ui/messageSeol teachtaireacht leantach sa chomhrá
ui/update-model-contextCuir an tsamhail ar an eolas faoi roghnú nó modhnú reatha

Taobh an fhreastalaí: dearbhaigh an acmhainn agus an uirlis

Déanaimis athbhreithniú ar an bhfreastalaí nótaí ó Cheacht 4. Soláthraíonn an pacáiste @modelcontextprotocol/ext-apps (i leagan 1.x le SDK v1) dhá chúntóir: registerAppResource, a chuireann an cineál MIME ceart i bhfeidhm a nochtar ag an tairiseach RESOURCE_MIME_TYPE de réir réamhshocraithe, agus registerAppTool`, a éilíonn meiteashonraí an chomhéadain.

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

const URI_CARTE = "ui://widget/notes-v1.html"; // leaganaithe: is eochair taisce é seo
const carteHtml = readFileSync("public/notes-widget.html", "utf8");

// Cuir isteach i gcreerServeur(), in aice le list_notes agus 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.` }],
  })
);

Ní iompraíonn ach show_notes an comhéadan. Is é seo an díchúpláil a mholann OpenAI: dá dtabharfadh gach uirlis teimpléad ar ais, athdhrawódh ChatGPT an iframe rómhinic. Déanann uirlisí sonraí (list_notes, add_note) cuardach, ríomh, nó modhnú agus ní thugann siad ach a dtoradh ar ais; faigheann uirlisí renderála sonraí críochnaithe agus filleann siad an teimpléad. Mar sin, is féidir leis an tsamhail oibriú ar na sonraí—scagadh, tras-tagairt—sula gcinneann sí taispeáint, agus ní fheictear an cárta ach uair amháin, le comhthéacs fíoraithe. Léirigh an spleáchas i dtuairisc na huirlise renderála, mar a thaispeántar thuas.

Taobh an iframe: an droichead JSON-RPC

Oireann an chomhpháirt anseo i gcomhad HTML amháin, gan aon chéim tógála. Osclaíonn sí an dialóg leis an óstach, ansin taispeánann sí gach toradh uirlise a fhaigheann sí.

<!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; // ná húsáid innerHTML riamh ar shonraí faighte
            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>

Is sonraí neamhiontaofa iad an toradh a fhaightear: taispeáin iad le textContent, riamh trí iad a instealladh mar HTML. Le haghaidh comhéadain níos saibhre, soláthraíonn an pacáiste céanna rang App taobh an bhrabhsálaí a chuimsíonn an droichead seo (ag fáil torthaí, ag glaoch ar uirlisí), le comhtháthú i mbunleac a tógadh le esbuild; taispeánann stór samplaí OpenAI comhpháirteanna React iomlána.

Cur i láthair a roghnú

Tosaigh leis an taispeáint inline agus iarr spás breise ach amháin má éilíonn an sruth oibre é:

Cur i láthairÚsáid
Cárta inlineToradh spriocdhírithe, deimhniú, cúpla gníomh, gan nascleanúint dhomhain
Carúsail inlineBrabhsáil agus roghnaigh rogha amháin as roinnt roghanna cosúla, amhairc
LánscáileánTasc saibhir: mapa, canbhás eagarthóireachta, iniúchadh mionsonraithe; fanann an limistéar ionchuir ChatGPT ar fáil
Pictiúr-i-bpictiúrGníomhaíocht leanúnach a chaithfidh fanacht infheicthe le linn an chomhrá: seisiún beo, cluiche, físeán

| Forbairtí sonrach do ChatGPT |

Nuair a bheidh sruth Aipeanna MCP i bhfeidhm, cuireann ChatGPT forbairtí ar fáil trí window.openai, le húsáid ach amháin don rud nach gcumhdaíonn an caighdeán. Do riachtanais choitianta, roghnaigh an caighdeán; tá ainmneacha leasacha ChatGPT ar fáil fós do chomhtháthuithe atá ann cheana:

RiachtanasCaighdeán Aipeanna MCPAinm Leasach ChatGPT
Uirlis a cheangal le comhéadan_meta.ui.resourceUri_meta["openai/outputTemplate"]
Argóintí a fháilui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Toradh a fháilui/notifications/tool-resultwindow.openai.toolOutput
Glaoch ar uirlistools/callwindow.openai.callTool
Teachtaireacht leantach a sheoladhui/messagewindow.openai.sendFollowUpMessage

Cumhdaíonn forbairtí gan coibhéis chaighdeánach seiceáil amach comhtháite (requestCheckout), comhaid (uploadFile, selectFiles, getFileDownloadUrl), fuinneoga modal arna mbainistiú ag an óstach (requestModal), agus marthanacht stáit comhpháirte (widgetState, setWidgetState). Brath gach cumas sula n-úsáideann tú é, le cúltaca nuair is féidir—agus ná déan tástáil ar ainm an óstaigh, déan tástáil ar an bhfeidhm:

const openai = typeof window !== "undefined" ? window.openai : undefined;
if (openai?.requestModal) {
  await openai.requestModal({ template: "ui://widget/details-v1.html" });
} else {
  document.body.textContent = "Ní thacaíonn an t-óstach seo le fuinneoga modal.";
}

Leathnúcháin ar leith ChatGPT

Trí chineál stáit

StátÚinéirSaolréSamplaí
Sonraí gnó, foinse na fírinneFreastalaí MCP nó seirbhís sheachtrachFadaTascanna, ticéid, doiciméid
Stát comhéadain, sealadachSampla comhpháirteFad a thaispeántar éSraith roghnaithe, painéal oscailte, ord sórtála
Stát marthanach thar seisiúinStóráil atá faoi do smachtIdir comhráite agus gléasannaScagairí sábháilte, mód taispeána

Fanann sonraí gnó ar an bhfreastalaí: glaonn an comhéadan ar uirlis, déanann an freastalaí bailíochtú agus nuashonrú, ansin filleann sé an stát tagartha, a thaispeánann an comhéadan agus é ag coinneáil gach rud a bhaineann le cur i láthair. Nuair a theastaíonn ón tsamhail a fháil amach faoi roghnú, seol é trí ui/update-model-context. Caomhnaíonn window.openai.setWidgetState (sioncrónach, gan await) stát sampla, ní sonraí gnó. Téann stát marthanach i do stóráil féin, taobh thiar d’fhíordheimhniú; seachain localStorage, nach dtugann leanúnachas idir gléasanna ná iontaofacht in iframe leithlisithe.

Beartas Slándála Inneachair (CSP)

Dearbhaíonn an chomhpháirt, i meiteashonraí a hacmhainne (_meta.ui.csp), na fearainn díreacha a úsáideann sí: connectDomains le haghaidh glaonna API, resourceDomains le haghaidh scripteanna, stíleanna, agus íomhánna, frameDomains ach amháin má chaithfidh sí iframes sonracha a chomhtháthú—cuirtear bac ar fhrámaí neadaithe de réir réamhshocraithe. Coinnigh na liostaí seo chomh cúng agus is féidir: déanann athbhreithniú an bhreiseáin comparáid idir an beartas dearbhaithe agus iompar iarbhír an chomhéadain. Agus déileáil leis an URI acmhainne mar eochair taisce: do gach athrú neamh-chomhoiriúnach ar an HTML, JavaScript, nó CSS, foilseigh URI nua agus nuashonraigh na huirlisí a thagraíonn dó.

Dá mhionsonra dheireanacha: léiríonn an t-óstach teanga an úsáideora i document.documentElement.lang, le húsáid chun dátaí agus uimhreacha a aistriú agus a fhormáidiú; agus soláthraíonn an leabharlann @openai/apps-sdk-ui cnaipí, cártaí, agus réimsí a mheaitseálann ChatGPT mura dteastaíonn uait gach rud a athdhearadh.

Príomhphointí

  • Is acmhainn ui:// de chineál text/html;profile=mcp-app é comhéadan, ceangailte le huirlis trí _meta.ui.resourceUri
  • Déanann an chomhpháirt cumarsáid leis an óstach trí JSON-RPC (ui/initialize, tools/call, ui/notifications/tool-result…)
  • Scar uirlisí sonraí agus uirlisí renderála: ní iompraíonn ach an uirlis renderála an teimpléad
  • Ní sholáthraíonn window.openai ach forbairtí, le brath sula n-úsáidtear iad
  • Sonraí gnó ar an bhfreastalaí, CSP cúng, URI acmhainne leaganaithe