Cuir comhéadan le Aipeanna MCP leis
Ar an leathanach seo
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-apps1.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:
| Teachtaireacht | Ról |
|---|---|
ui/initialize ansin ui/notifications/initialized | Oscail an dialóg leis an óstach |
ui/notifications/tool-input | Faigh argóintí glao na huirlise |
ui/notifications/tool-result | Faigh toradh na huirlise |
tools/call | Glaoigh ar uirlis freastalaí ón gcomhéadan |
ui/message | Seol teachtaireacht leantach sa chomhrá |
ui/update-model-context | Cuir 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 inline | Toradh spriocdhírithe, deimhniú, cúpla gníomh, gan nascleanúint dhomhain |
| Carúsail inline | Brabhsáil agus roghnaigh rogha amháin as roinnt roghanna cosúla, amhairc |
| Lánscáileán | Tasc saibhir: mapa, canbhás eagarthóireachta, iniúchadh mionsonraithe; fanann an limistéar ionchuir ChatGPT ar fáil |
| Pictiúr-i-bpictiúr | Gní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:
| Riachtanas | Caighdeán Aipeanna MCP | Ainm Leasach ChatGPT |
|---|---|---|
| Uirlis a cheangal le comhéadan | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Argóintí a fháil | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Toradh a fháil | ui/notifications/tool-result | window.openai.toolOutput |
| Glaoch ar uirlis | tools/call | window.openai.callTool |
| Teachtaireacht leantach a sheoladh | ui/message | window.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éir | Saolré | Samplaí |
|---|---|---|---|
| Sonraí gnó, foinse na fírinne | Freastalaí MCP nó seirbhís sheachtrach | Fada | Tascanna, ticéid, doiciméid |
| Stát comhéadain, sealadach | Sampla comhpháirte | Fad a thaispeántar é | Sraith roghnaithe, painéal oscailte, ord sórtála |
| Stát marthanach thar seisiúin | Stóráil atá faoi do smacht | Idir comhráite agus gléasanna | Scagairí 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áltext/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.openaiach forbairtí, le brath sula n-úsáidtear iad - Sonraí gnó ar an bhfreastalaí, CSP cúng, URI acmhainne leaganaithe