Pievienot saskarni ar MCP lietotnēm
Šajā lapā
Nodarbība pārrakstīta 2026. gada 3. novembrī, pamatojoties uz lapu Add UI to your MCP server no OpenAI spraudņu dokumentācijas un
@modelcontextprotocol/ext-apps1.7.5. kodu. Iepriekšējā nodarbībā aprakstīti “logrīki” (defineWidget) no neeksistējoša SDK; saskarne ir MCP Apps resurss, ko ChatGPT attēlo iframe rāmī. Avoti: Add UI to your MCP server · MCP Apps Specification.
Kad pievienot saskarni
Saskarne ir neobligāta. Pievieno to, ja lietotājam jāpārbauda, jāsalīdzina, jāmaina, jāapstiprina vai jāpārlūko strukturēta informācija — un saglabā savu rīku lietderību arī bez tās, lai ChatGPT un Codex varētu vadīt darbplūsmu klientos, kas neattēlo komponenti.
MCP Apps princips
ChatGPT ievieš atvērto MCP Apps standartu. Serveris deklarē saskarnes resursu, kas identificēts ar ui://… URI un tiek pasniegts ar MIME tipu text/html;profile=mcp-app; rīks tam pievienojas, izmantojot _meta.ui.resourceUri. Kad šis rīks tiek izsaukts, ChatGPT parāda resursu iframe rāmī blakus sarunai. Komponents sazinās ar resursdatoru, izmantojot JSON-RPC caur postMessage:
| Ziņojums | Loma |
|---|---|
ui/initialize, tad ui/notifications/initialized | Atvērt dialogu ar resursdatoru |
ui/notifications/tool-input | Saņemt rīka izsaukuma argumentus |
ui/notifications/tool-result | Saņemt rīka rezultātu |
tools/call | Izsaukt servera rīku no saskarnes |
ui/message | Nosūtīt turpmāku ziņojumu sarunā |
ui/update-model-context | Informēt modeli par pašreizējo atlasi vai izmaiņām |
Servera puse: deklarē resursu un rīku
Atgriezīsimies pie 4. nodarbības piezīmju servera. Pakotne @modelcontextprotocol/ext-apps (1.x versijā ar SDK v1) nodrošina divus palīglīdzekļus: registerAppResource, kas pēc noklusējuma piemēro pareizo MIME tipu, ko eksponē konstante RESOURCE_MIME_TYPE, un registerAppTool, kam nepieciešami saskarnes metadati.
import { readFileSync } from "node:fs";
import {
registerAppResource,
registerAppTool,
RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
const URI_CARTE = "ui://widget/notes-v1.html"; // ar versiju: tā ir kešatmiņas atslēga
const carteHtml = readFileSync("public/notes-widget.html", "utf8");
// Pievieno iekš creerServeur(), blakus list_notes un 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.` }],
})
);
Tikai show_notes nes saskarni. Tā ir atdalīšana, ko OpenAI iesaka: ja katrs rīks atgrieztu veidni, ChatGPT pārāk bieži pārzīmētu iframe rāmi. Datu rīki (list_notes, add_note) meklē, aprēķina vai modificē un atgriež tikai savu rezultātu; attēlošanas rīki saņem galīgos datus un atgriež veidni. Tādējādi modelis var strādāt ar datiem — filtrēt, krustot atsauces — pirms izlemt par attēlošanu, un kartīte parādās tikai vienreiz ar pārbaudītu kontekstu. Norādi atkarību attēlošanas rīka aprakstā, kā parādīts augstāk.
Iframe puse: JSON-RPC tilts
Komponents šeit iekļaujas vienā HTML failā bez veidošanas soļa. Tas atver dialogu ar resursdatoru, pēc tam attēlo katru saņemto rīka rezultātu.
<!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>
Saņemtais rezultāts ir neuzticami dati: attēlo tos, izmantojot textContent, nekad neievietojot tos kā HTML. Bagātīgākai saskarnei tā pati pakotne nodrošina pārlūkprogrammas puses App klasi, kas encapsulē šo tiltu (rezultātu saņemšana, rīku izsaukšana), lai to integrētu kopā ar esbuild veidotā saišķī; OpenAI piemēru repozitorijs parāda pilnus React komponentus.
Noformējuma izvēle
Sāc ar iekļauto attēlojumu un pieprasi vairāk vietas tikai tad, ja darbplūsma to prasa:
| Noformējums | Lietojums |
|---|---|
| Iekļauta kartīte | Mērķtiecīgs rezultāts, apstiprinājums, dažas darbības bez dziļas navigācijas |
| Iekļauta karuseļa galerija | Pārlūkošana un izvēle starp dažām līdzīgām, vizuālām opcijām |
| Pilnekrāna režīms | Bagāts uzdevums: karte, rediģēšanas audekls, detalizēta izpēte; ChatGPT ievades lauks paliek pieejams |
| Attēls attēlā (Picture-in-picture) | Notiekoša darbība, kam jāpaliek redzamai sarunas laikā: tiešraides sesija, spēle, video |
ChatGPT specifiskie paplašinājumi
Kad MCP Apps plūsma ir ieviesta, ChatGPT piedāvā paplašinājumus, izmantojot window.openai, kas lietojami tikai tam, ko standarts neparedz. Parastām vajadzībām dod priekšroku standartam; ChatGPT aliasi paliek pieejami esošajām integrācijām:
| Vajadzība | MCP Apps standarts | ChatGPT alias |
|---|---|---|
| Pievienot rīku saskarnei | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Saņemt argumentus | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Saņemt rezultātu | ui/notifications/tool-result | window.openai.toolOutput |
| Izsaukt rīku | tools/call | window.openai.callTool |
| Nosūtīt turpmāku ziņojumu | ui/message | window.openai.sendFollowUpMessage |
Paplašinājumiem bez standarta ekvivalenta ir iekļauta norēķinu veikšana (requestCheckout*), faili (uploadFile, selectFiles, getFileDownloadUrl), resursdatora pārvaldīti modālie logi (requestModal) un komponenta stāvokļa saglabāšana (widgetState, setWidgetState`). Pirms lietošanas nosaki katru iespēju un nodrošina rezerves risinājumu, ja iespējams — nekad netestē resursdatora nosaukumu, testē funkciju:
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.";
}
Trīs stāvokļu veidi
| Stāvoklis | Īpašnieks | Ilgmūžība | Piemēri |
|---|---|---|---|
| Biznesa dati, patiesības avots | MCP serveris vai ārējs serviss | Ilga | Uzdevumi, biļetes, dokumenti |
| Saskarnes stāvoklis, īslaicīgs | Komponenta instances | Tās attēlošanas ilgums | Atlasīta rinda, atvērts panelis, kārtošanas secība |
| Ilgstošs stāvoklis starp sesijām | Tava kontrolētā krātuve | Starp sarunām un ierīcēm | Saglabāti filtri, attēlošanas režīms |
Biznesa dati paliek serverī: saskarne izsauc rīku, serveris validē un atjaunina, pēc tam atgriež atsauces stāvokli, ko saskarne attēlo, saglabājot tikai to, kas attiecas uz noformējumu. Kad modelim jāzina atlase, nosūti to, izmantojot ui/update-model-context. window.openai.setWidgetState (sinhrons, bez await) saglabā instances stāvokli, nevis biznesa datus. Ilgstošs stāvoklis glabājas tavā krātuvē aiz autentifikācijas; izvairies no localStorage, kas nenodrošina nepārtrauktību starp ierīcēm nedz uzticamību izolētā iframe rāmī.
Satura drošības politika (CSP)
Komponents savos resursu metadatos (_meta.ui.csp) deklarē precīzos domēnus, ko tas izmanto: connectDomains API izsaukumiem, resourceDomains skriptiem, stiliem un attēliem, frameDomains tikai tad, ja tam jāintegrē specifiski iframe rāmji — ligzdoti rāmji pēc noklusējuma ir bloķēti. Saglabā šos sarakstus pēc iespējas šaurus: spraudņa pārskatīšana salīdzina deklarēto politiku ar saskarnes faktisko uzvedību. Un uzskati resursa URI par kešatmiņas atslēgu: katrai nesaderīgai izmaiņai HTML, JavaScript vai CSS publicē jaunu URI un atjaunini rīkus, kas uz to atsaucas.
Divas pēdējās detaļas: resursdators atspoguļo lietotāja valodu document.documentElement.lang, ko izmantot datumu un skaitļu tulkošanai un formatēšanai; un @openai/apps-sdk-ui bibliotēka nodrošina pogas, kartītes un laukus, kas atbilst ChatGPT, ja nevēlies visu pārdizainēt.
Galvenās atziņas
- Saskarne ir
ui://resurss ar tiputext/html;profile=mcp-app, kas pievienots rīkam, izmantojot_meta.ui.resourceUri - Komponents sazinās ar resursdatoru, izmantojot JSON-RPC (
ui/initialize,tools/call,ui/notifications/tool-result…) - Atdali datu rīkus un attēlošanas rīkus: tikai attēlošanas rīks nes veidni
window.openainodrošina tikai paplašinājumus, kas jānosaka pirms lietošanas- Biznesa dati serverī, šaura CSP, ar versiju kontrolēts resursa URI