Lisa liides MCP rakendustega
Sellel lehel
Õppetund kirjutati ümber 3. novembril 2026, tuginedes OpenAI pistikprogrammide dokumentatsiooni lehele Add UI to your MCP server ja paketi
@modelcontextprotocol/ext-appsversiooni 1.7.5 koodile. Eelmine õppetund kirjeldas “vidinaid” (defineWidget) olematust SDK-st; liides on MCP Apps ressurss, mida ChatGPT renderdab iframe’is. Allikad: Add UI to your MCP server · MCP Apps Specification.
Millal liides lisada
Liides on valikuline. Lisa see siis, kui kasutaja peab struktureeritud teavet kontrollima, võrdlema, muutma, kinnitama või sirvima – ja hoia oma tööriistad kasulikena ka ilma selleta, et ChatGPT ja Codex saaksid töövoogu juhtida klientides, mis komponenti ei kuva.
MCP Apps’i põhimõte
ChatGPT rakendab avatud MCP Apps’i standardit. Server deklareerib liidese ressursi, mille identifikaatoriks on URI ui://… ja mida serveeritakse MIME-tüübiga text/html;profile=mcp-app; tööriist seob selle endaga väljade _meta.ui.resourceUri kaudu. Kui seda tööriista kutsutakse, kuvab ChatGPT ressursi iframe’is vestluse kõrval. Komponent suhtleb hostiga JSON-RPC protokolli kasutades läbi postMessage:
| Sõnum | Roll |
|---|---|
ui/initialize ja seejärel ui/notifications/initialized | Dialoogi avamine hostiga |
ui/notifications/tool-input | Tööriista väljakutse argumentide vastuvõtmine |
ui/notifications/tool-result | Tööriista tulemuse vastuvõtmine |
tools/call | Serveri tööriista kutsumine liidesest |
ui/message | Järelsõnumi saatmine vestlusse |
ui/update-model-context | Mudeli teavitamine praegusest valikust või muutusest |
Serveri pool: ressursi ja tööriista deklareerimine
Vaatan üle 4. õppetunnist tuntud märkmete serveri. Pakett @modelcontextprotocol/ext-apps (versioonis 1.x koos SDK v1-ga) pakub kahte abifunktsiooni: registerAppResource, mis rakendab vaikimisi konstandi RESOURCE_MIME_TYPE kaudu õiget MIME-tüüpi, ja registerAppTool, mis nõuab liidese metaandmeid.
import { readFileSync } from "node:fs";
import {
registerAppResource,
registerAppTool,
RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
const URI_CARTE = "ui://widget/notes-v1.html"; // versioneeritud: see on vahemälu võti
const carteHtml = readFileSync("public/notes-widget.html", "utf8");
// Lisa funktsiooni creerServeur() sisse, kõrvuti list_notes ja add_note-ga
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.` }],
})
);
Ainult show_notes kannab liidest. See on lahutatus, mida OpenAI soovitab: kui iga tööriist tagaks malli, joonistaks ChatGPT iframe’i liiga sageli ümber. Andmetööriistad (list_notes, add_note) otsivad, arvutavad või muudavad ja tagavad ainult tulemuse; renderdamistööriistad saavad lõplikud andmed ja tagavad malli. Mudel saab seega andmetega töötada – filtreerida, ristviidata – enne kui otsustab need kuvada, ja kaart ilmub ainult üks kord, kinnitatud kontekstiga. Märsi sõltuvus renderdamistööriista kirjelduses, nagu ülalpool näidatud.
Iframe’i pool: JSON-RPC sild
Komponent mahub siia ühteainsasse HTML-faili ilma kompileerimiseta. See avab dialoogi hostiga ja kuvab seejärel iga saadud tööriista tulemuse.
<!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>
Saadud tulemus on usaldamatu andmevoog: kuva seda textContent abil, mitte kunagi HTML-i süstides. Rikkalikuma liidese jaoks pakub sama pakett brauseripoolset klassi App, mis kapseldab selle silla (tulemuste vastuvõtmine, tööriistade kutsumine) ja mida saab integreerida esbuildiga loodud kimpu; OpenAI näidishoidla sisaldab täielikke Reacti komponente.
Esitlusviisi valimine
Alusta sisest kuvatavast esitlusest ja küsi rohkem ruumi ainult siis, kui töövoog seda nõuab:
| Esitlusviis | Kasutus |
|---|---|
| Sisene kaart | Sihipärane tulemus, kinnitus, mõned toimingud ilma sügava navigeerimiseta |
| Sisene karussell | Sirvimine ja valimine mõne sarnase visuaalse variandi hulgast |
| Täisekraan | Mahukas ülesanne: kaart, redigeerimislõuend, üksikasjalik uurimine; ChatGPT sisendväli jääb kättesaadavaks |
| Pilt pildis (PiP) | Käimasolev tegevus, mis peab vestluse ajal nähtavaks jääma: otseülekanne, mäng, video |
ChatGPT-spetsiifilised laiendused
Kui MCP Apps’i voog on paigas, pakub ChatGPT laiendusi läbi window.openai, mida tuleks kasutada ainult selleks, mida standard ei kata. Levinud vajaduste puhul eelista standardit; ChatGPT aliased jäävad olemasolevate integratsioonide jaoks kättesaadavaks:
| Vajadus | MCP Apps’i standard | ChatGPT alias |
|---|---|---|
| Tööriista liidesega sidumine | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Argumentide vastuvõtmine | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Tulemuse vastuvõtmine | ui/notifications/tool-result | window.openai.toolOutput |
| Tööriista kutsumine | tools/call | window.openai.callTool |
| Järelsõnumi saatmine | ui/message | window.openai.sendFollowUpMessage |
Laiendused, millel puudub standardne vaste, hõlmavad integreeritud maksete tegemist (requestCheckout), faile (uploadFile, selectFiles, getFileDownloadUrl), hosti hallatavaid modaalaknaid (requestModal) ja komponendi oleku püsimist (widgetState, setWidgetState). Tuvasta iga võimalus enne selle kasutamist, kasutades vajadusel varulahendust – ja ära kunagi testi hosti nime, testi funktsiooni olemasolu:
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.";
}
Kolme liiki olekud
| Olek | Omanik | Eluiga | Näited |
|---|---|---|---|
| Äriandmed, tõese allikas | MCP server või väline teenus | Pikk | Ülesanded, piletid, dokumendid |
| Liidese olek, mööduv | Komponendi eksemplar | Kuvaamise kestus | Valitud rida, avatud paneel, sorteerimisjärjestus |
| Püsiv olek seansside vahel | Sinu hallatav salvestusruum | Vestluste ja seadmete vahel | Salvestatud filtrid, kuva režiim |
Äriandmed jäävad serverisse: liides kutsub tööriista, server valideerib ja uuendab, seejärel tagab viiteoleku, mida liides kuvab, säilitades samal ajal esitlusega seotu. Kui mudel peab teadma valikut, saada see läbi ui/update-model-context. window.openai.setWidgetState (sünkroonne, ilma await-ta) säilitab eksemplari oleku, mitte äriandmeid. Püsiv olek kuulub sinu salvestusruumi autentimise taga; välti localStorage-i, mis ei paku ei järjepidevust seadmete vahel ega usaldusväärsust isoleeritud iframe’is.
Sisuturbepoliitika (CSP)
Komponent deklareerib oma ressursi metaandmetes (_meta.ui.csp) täpsed domeenid, mida ta kasutab: connectDomains API-kõnede jaoks, resourceDomains skriptide, stiilide ja piltide jaoks ning frameDomains ainult siis, kui tuleb integreerida spetsiifilisi iframe’e – pesastatud raamid on vaikimisi blokeeritud. Hoia need loendid võimalikult kitsana: pistikprogrammi läbivaatus võrdleb deklareeritud poliitikat liidese tegeliku käitumisega. Ja kohtle ressursi URI-d vahemälu võtmena: iga HTML-i, JavaScripti või CSS-i mittesobiva muudatuse korral avalda uus URI ja uuenda tööriistu, mis sellele viitavad.
Kaks viimast detaili: host peegeldab kasutaja keelt väärtuses document.documentElement.lang, mida tuleks kasutada kuupäevade ja arvude tõlkimiseks ning vormindamiseks; ning teek @openai/apps-sdk-ui pakub nuppe, kaarte ja välju, mis sobituvad ChatGPT-ga, kui sa ei soovi kõike uuesti disainida.
Peamised punktid
- Liides on tüüpi
text/html;profile=mcp-appressurss aadressigaui://, mis on seotud tööriistaga väljade_meta.ui.resourceUrikaudu - Komponent suhtleb hostiga JSON-RPC abil (
ui/initialize,tools/call,ui/notifications/tool-result…) - Eralda andmetööriistad ja renderdamistööriistad: ainult renderdamistööriist kannab malli
window.openaipakub ainult laiendusi, mida tuleb enne kasutamist tuvastada- Äriandmed serveris, kitsas CSP, versioneeritud ressursi URI