Żid Interfaċċa ma' Apps MCP
F'din il-paġna
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-apps1.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/initialized | Iftaħ id-djalogu mal-host |
ui/notifications/tool-input | Irċievi l-argumenti tas-sejħa tal-għodda |
ui/notifications/tool-result | Irċievi r-riżultat tal-għodda |
tools/call | Sejjaħ għodda tas-server mill-interfaċċa |
ui/message | Ibgħat messaġġ ta’ segwitu fil-konversazzjoni |
ui/update-model-context | Informa 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żentazzjoni | Użu |
|---|---|
| Karta inline | Riżultat immirat, konferma, ftit azzjonijiet, mingħajr navigazzjoni fonda |
| Karosell inline | Ibbrawsjja 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-picture | Attività 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ġa | Standard ta’ MCP Apps | Alias ta’ ChatGPT |
|---|---|---|
| Ħabbat għodda ma’ interfaċċa | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Irċievi argumenti | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Irċievi riżultat | ui/notifications/tool-result | window.openai.toolOutput |
| Sejjaħ għodda | tools/call | window.openai.callTool |
| Ibghat messaġġ ta’ segwitu | ui/message | window.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
| Stat | Sid | Tul tal-ħajja | Eżempji |
|---|---|---|---|
| Data tan-negozju, sors tal-verità | Server MCP jew servizz estern | Twil | Kompiti, tickets, dokumenti |
| Stat tal-interfaċċa, effimeru | Istanza tal-komponent | Matul id-display tiegħu | Ringiela magħżula, pannell miftuħ, ordni tas-sortjar |
| Stat durabbli bejn is-sessjonijiet | Ħażna li tikkontrolla int | Bejn konversazzjonijiet u apparati | Filtri 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-tiptext/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.openaijipprovdi 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