Pridėti sąsają su MCP programėlėmis
Šiame puslapyje
Pamoka perrašyta 2026 m. lapkričio 3 d. remiantis „Add UI to your MCP server“ puslapiu iš „OpenAI Plugins“ dokumentacijos ir
@modelcontextprotocol/ext-apps1.7.5 versijos kodu. Ankstesnė pamoka aprašė „valdiklius“ (defineWidget) iš neegzistuojančio SDK; sąsaja yra MCP Apps ištekliai, kuriuos „ChatGPT“ atvaizduojaiframerėmelyje. Šaltiniai: Add UI to your MCP server · MCP Apps Specification.
Kada pridėti sąsają
Sąsaja yra neprivaloma. Pridėk ją tada, kai naudotojui reikia peržiūrėti, palyginti, modifikuoti, patvirtinti arba naršyti struktūrizuotą informaciją – ir palik savo įrankius naudingus be jos, kad „ChatGPT“ ir „Codex“ galėtų valdyti darbo eigą klientuose, kurie nerodo komponento.
MCP Apps principas
„ChatGPT“ įgyvendina atvirą MCP Apps standartą. Serveris deklaruoja sąsajos išteklių, identifikuojamą ui://… URI ir pateikiamą su MIME tipu text/html;profile=mcp-app; įrankis prie jo prisijungia naudodamas _meta.ui.resourceUri. Kai šis įrankis iškviečiamas, „ChatGPT“ rodo išteklių iframe rėmelyje, šalia pokalbio. Komponentas bendrauja su šeimininku naudodamas JSON-RPC per postMessage:
| Žinutė | Vaidmuo |
|---|---|
ui/initialize, tada ui/notifications/initialized | Pradėti dialogą su šeimininku |
ui/notifications/tool-input | Gauti įrankio iškvietimo argumentus |
ui/notifications/tool-result | Gauti įrankio rezultatą |
tools/call | Iškvieti serverio įrankį iš sąsajos |
ui/message | Siųsti tolesnį pranešimą pokalbyje |
ui/update-model-context | Informuoti modelį apie dabartinį pasirinkimą arba pakeitimą |
Serverio pusė: deklaruok išteklių ir įrankį
Grįžkime prie užrašų serverio iš 4 pamokos. Paketas @modelcontextprotocol/ext-apps (1.x versijoje su SDK v1) pateikia du pagalbininkus: registerAppResource, kuris taiko tinkamą MIME tipą (pagal nutylėjimą naudoja konstantą RESOURCE_MIME_TYPE), ir registerAppTool, kuriam reikia sąsajos metaduomenų.
import { readFileSync } from "node:fs";
import {
registerAppResource,
registerAppTool,
RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
const URI_CARTE = "ui://widget/notes-v1.html"; // su versija: tai yra talpyklos raktas
const carteHtml = readFileSync("public/notes-widget.html", "utf8");
// Pridėkite funkcijoje creerServeur(), šalia list_notes ir 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.` }],
})
);
Tik show_notes turi sąsają. Tai yra atsiejimas, kurį rekomenduoja „OpenAI“: jei kiekvienas įrankis grąžintų šabloną, „ChatGPT“ per dažnai perpieštų iframe. Duomenų įrankiai (list_notes, add_note) ieško, skaičiuoja arba modifikuoja ir grąžina tik rezultatą; atvaizdavimo įrankiai gauna galutinius duomenis ir grąžina šabloną. Taigi modelis gali dirbti su duomenimis – filtruoti, susieti – prieš nuspręsdamas rodyti, o kortelė atsiranda tik vieną kartą, su patikrintu kontekstu. Nurodyk priklausomybę atvaizdavimo įrankio aprašyme, kaip parodyta aukščiau.
Iframe pusė: JSON-RPC tiltas
Komponentas telpa į vieną HTML failą be kūrimo žingsnio. Jis pradeda dialogą su šeimininku, tada atvaizduoja kiekvieną gautą įrankio rezultatą.
<!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; // niekada nenaudok innerHTML gaunamiems duomenims
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>
Gautas rezultatas yra nepatikimi duomenys: atvaizduok juos naudodamas textContent, niekada neinjekuodamas kaip HTML. Sudėtingesnei sąsajai tas pats paketas pateikia naršyklės pusės App klasę, kuri encapsuliuoja šį tiltą (gauna rezultatus, kviečia įrankius) ir gali būti integruota į ryšulį, sukurtą su „esbuild“; „OpenAI“ pavyzdžių saugykloje rasite pilnus „React“ komponentus.
Prezentacijos pasirinkimas
Pradėk nuo įterpto rodymo ir prašyk daugiau vietos tik tada, kai to reikalauja darbo eiga:
| Prezentacija | Naudojimas |
|---|---|
| Įterpta kortelė | Tikslinis rezultatas, patvirtinimas, keli veiksmai be gilaus naršymo |
| Įterpta karuselė | Naršyti ir pasirinkti iš kelių panašių, vizualių opcijų |
| Visas ekranas | Turtinga užduotis: žemėlapis, redagavimo drobė, detalus tyrinėjimas; „ChatGPT“ įvesties sritis lieka prieinama |
| Vaizdas vaizde (PiP) | Vykdoma veikla, kuri turi likti matoma pokalbio metu: tiesioginė sesija, žaidimas, vaizdo įrašas |
„ChatGPT“ specifiniai plėtiniai
Kai MCP Apps srautas jau veikia, „ChatGPT“ siūlo plėtinius per window.openai, kuriuos naudok tik tam, ko neapima standartas. Bendriems poreikiams teik pirmenybę standartui; „ChatGPT“ aliasai lieka prieinami esamiems integravimams:
| Poreikis | MCP Apps standartas | „ChatGPT“ aliasas |
|---|---|---|
| Prijungti įrankį prie sąsajos | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Gauti argumentus | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Gauti rezultatą | ui/notifications/tool-result | window.openai.toolOutput |
| Iškvieti įrankį | tools/call | window.openai.callTool |
| Siųsti tolesnį pranešimą | ui/message | window.openai.sendFollowUpMessage |
Plėtiniai, neturintys standarto ekvivalento, apima integruotą atsiskaitymą (requestCheckout), failus (uploadFile, selectFiles, getFileDownloadUrl), šeimininko valdomus modalinius langus (requestModal) ir komponento būsenos išsaugojimą (widgetState, setWidgetState). Prieš naudodamas aptik kiekvieną galimybę ir numatyk atsarginį variantą, jei įmanoma – niekada netikrink šeimininko pavadinimo, tikrink funkciją:
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.";
}
Trys būsenų tipai
| Būsena | Savininkas | Gyvavimo trukmė | Pavyzdžiai |
|---|---|---|---|
| Verslo duomenys, tiesos šaltinis | MCP serveris arba išorinė tarnyba | Ilga | Užduotys, bilietai, dokumentai |
| Sąsajos būsena, laikina | Komponento egzempliorius | Jo rodymo trukmė | Pasirinkta eilutė, atidarytas skydelis, rikiavimo tvarka |
| Ilgaamžė būsena tarp sesijų | Tavo valdoma saugykla | Tarp pokalbių ir įrenginių | Išsaugoti filtrai, rodymo režimas |
Verslo duomenys lieka serveryje: sąsaja iškviečia įrankį, serveris patikrina ir atnaujina, tada grąžina etaloninę būseną, kurią sąsaja atvaizduoja, išlaikydama tai, kas susiję su prezentacija. Kai modeliui reikia žinoti apie pasirinkimą, siųsk jį per ui/update-model-context. window.openai.setWidgetState (sinchroninis, be await) išsaugo egzemplioriaus būseną, o ne verslo duomenis. Ilgaamžė būsena turi būti tavo saugykloje, už autentifikacijos ribų; venk localStorage, kuris neužtikrina nei tęstinumo tarp įrenginių, nei patikimumo izoliuotame iframe.
Turinio saugumo politika (CSP)
Komponentas savo išteklių metaduomenyse (_meta.ui.csp) deklaruoja tikslias domenas, kurias naudoja: connectDomains API užklausoms, resourceDomains scenarijams, stiliams ir paveikslėliams, frameDomains tik tada, kai reikia integruoti specifinius iframe – įdėtieji rėmeliai pagal nutylėjimą blokuojami. Laikyk šiuos sąrašus kuo siauresnius: įskiepio peržiūra lygina deklaruotą politiką su faktiniu sąsajos elgesiu. Ir traktuok išteklių URI kaip talpyklos raktą: kiekvienam nesuderinamam HTML, JavaScript ar CSS pakeitimui paskelbk naują URI ir atnaujink įrankius, kurie į jį nuorodo.
Dar dvi detalės: šeimininkas atspindi naudotojo kalbą document.documentElement.lang, kurią naudok datoms ir skaičiams versti bei formatuoti; o @openai/apps-sdk-ui biblioteka pateikia mygtukus, korteles ir laukus, atitinkančius „ChatGPT“, jei nenori visko perteikti iš naujo.
Svarbiausi punktai
- Sąsaja yra
ui://išteklius tipotext/html;profile=mcp-app, prijungtas prie įrankio per_meta.ui.resourceUri - Komponentas bendrauja su šeimininku per JSON-RPC (
ui/initialize,tools/call,ui/notifications/tool-result…) - Atskirk duomenų ir atvaizdavimo įrankius: šabloną turi tik atvaizdavimo įrankis
window.openaiteikia tik plėtinius, kuriuos reikia aptikti prieš naudojant- Verslo duomenys serveryje, siaura CSP, versijuotas išteklių URI