Adăugarea unei interfețe cu aplicații MCP
Pe această pagină
Lecție rescrisă la 3 noiembrie 2026 pe baza paginii Add UI to your MCP server din documentația OpenAI Plugins și a codului pentru
@modelcontextprotocol/ext-apps1.7.5. Lecția anterioară descria „widget-uri“ (defineWidget) dintr-un SDK inexistent; o interfață este o resursă MCP Apps randată de ChatGPT într-un iframe. Surse: Add UI to your MCP server · MCP Apps Specification.
Când să adăugați o interfață
Interfața este opțională. Adăugați una atunci când utilizatorul trebuie să inspecteze, să compare, să modifice, să confirme sau să navigheze prin informații structurate—și mențineți utilitatea instrumentelor dumneavoastră și fără aceasta, astfel încât ChatGPT și Codex să poată gestiona fluxul de lucru în clienții care nu afișează o componentă.
Principiul aplicațiilor MCP
ChatGPT implementează standardul deschis MCP Apps. Serverul declară o resursă de interfață, identificată printr-un URI ui://… și servită cu tipul MIME text/html;profile=mcp-app; un instrument se atașează la aceasta prin _meta.ui.resourceUri. Când acest instrument este apelat, ChatGPT afișează resursa într-un iframe, lângă conversație. Componenta comunică cu gazda prin JSON-RPC folosind postMessage:
| Mesaj | Rol |
|---|---|
ui/initialize apoi ui/notifications/initialized | Deschiderea dialogului cu gazda |
ui/notifications/tool-input | Primirea argumentelor apelului instrumentului |
ui/notifications/tool-result | Primirea rezultatului instrumentului |
tools/call | Apelarea unui instrument de server din interfață |
ui/message | Trimiterea unui mesaj de follow-up în conversație |
ui/update-model-context | Informarea modelului despre o selecție sau modificare curentă |
Partea de server: declararea resursei și a instrumentului
Să reluăm serverul de note din Lecția 4. Pachetul @modelcontextprotocol/ext-apps (în versiunea 1.x cu SDK v1) oferă două funcții helper: registerAppResource, care aplică tipul MIME corect expus de constanta RESOURCE_MIME_TYPE în mod implicit, și registerAppTool, care necesită metadatele interfeței.
import { readFileSync } from "node:fs";
import {
registerAppResource,
registerAppTool,
RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
const URI_CARTE = "ui://widget/notes-v1.html"; // versionat: aceasta este o cheie de cache
const carteHtml = readFileSync("public/notes-widget.html", "utf8");
// De adăugat în interiorul creerServeur(), lângă list_notes și 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.` }],
})
);
Doar show_notes poartă interfața. Aceasta este decuplarea recomandată de OpenAI: dacă fiecare instrument ar returna un șablon, ChatGPT ar redesena iframe-ul prea des. Instrumentele de date (list_notes, add_note) caută, calculează sau modifică și returnează doar rezultatul lor; instrumentele de randare primesc datele finale și returnează șablonul. Astfel, modelul poate lucra asupra datelor—filtrare, corelare—înainte de a decide afișarea, iar cardul apare o singură dată, cu un context verificat. Indicați dependența în descrierea instrumentului de randare, așa cum se arată mai sus.
Partea iframe: puntea JSON-RPC
Componenta se încadrează aici într-un singur fișier HTML, fără pas de build. Aceasta deschide dialogul cu gazda, apoi afișează fiecare rezultat de instrument pe care îl primește.
<!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>
Rezultatul primit este date neconfirmate: afișați-l cu textContent, niciodată injectându-l ca HTML. Pentru o interfață mai bogată, același pachet oferă o clasă App latoarea browserului care încapsulează această punte (primirea rezultatelor, apelarea instrumentelor), de integrat într-un bundle construit cu esbuild; repository-ul de exemple OpenAI arată componente React complete.
Alegerea unei prezentări
Începeți cu afișarea inline și solicitați mai mult spațiu doar dacă fluxul de lucru o impune:
| Prezentare | Utilizare |
|---|---|
| Card inline | Un rezultat țintit, o confirmare, câteva acțiuni, fără navigare profundă |
| Carusel inline | Navigare și alegere printre câteva opțiuni similare, vizuale |
| Ecran complet | O sarcină bogată: hartă, canvas de editare, explorare detaliată; zona de input ChatGPT rămâne disponibilă |
| Picture-in-picture | O activitate în curs care trebuie să rămână vizibilă în timpul conversației: sesiune live, joc, video |
Extensii specifice ChatGPT
Odată ce fluxul MCP Apps este pus la punct, ChatGPT oferă extensii prin window.openai, de utilizat doar pentru ceea ce standardul nu acoperă. Pentru nevoile comune, preferați standardul; aliasurile ChatGPT rămân disponibile pentru integrările existente:
| Nevoie | Standard MCP Apps | Alias ChatGPT |
|---|---|---|
| Atașarea unui instrument la o interfață | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Primirea argumentelor | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Primirea rezultatului | ui/notifications/tool-result | window.openai.toolOutput |
| Apelarea unui instrument | tools/call | window.openai.callTool |
| Trimiterea unui mesaj de follow-up | ui/message | window.openai.sendFollowUpMessage |
Extensiile fără un echivalent standard acoperă checkout-ul integrat (requestCheckout), fișierele (uploadFile, selectFiles, getFileDownloadUrl), ferestrele modale gestionate de gazdă (requestModal) și persistența stării componentei (widgetState, setWidgetState). Detectați fiecare capacitate înainte de a o utiliza, cu un fallback când este posibil—și nu testați niciodată numele gazdei, testați funcția:
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.";
}
Trei tipuri de stare
| Stare | Proprietar | Durată de viață | Exemple |
|---|---|---|---|
| Date de business, sursa adevărului | Server MCP sau serviciu extern | Lungă | Sarcini, tichete, documente |
| Starea interfeței, efemeră | Instanța componentei | Durata afișării sale | Rând selectat, panou deschis, ordine de sortare |
| Stare durabilă între sesiuni | Stocare pe care o controlați | Între conversații și dispozitive | Filtre salvate, mod de afișare |
Datele de business rămân pe server: interfața apelează un instrument, serverul validează și actualizează, apoi returnează starea de referință, pe care interfața o afișează păstrând ceea ce ține de prezentare. Când modelul trebuie să cunoască o selecție, trimiteți-o prin ui/update-model-context. window.openai.setWidgetState (sincron, fără await) păstrează starea unei instanțe, nu datele de business. Starea durabilă merge în stocarea dumneavoastră, în spatele autentificării; evitați localStorage, care nu oferă nici continuitate între dispozitive, nici fiabilitate într-un iframe izolat.
Politica de securitate a conținutului (CSP)
Componenta declară, în metadatele resursei sale (_meta.ui.csp), domeniile exacte pe care le utilizează: connectDomains pentru apelurile API, resourceDomains pentru scripturi, stiluri și imagini, frameDomains doar dacă trebuie să integreze iframe-uri specifice—iframe-urile imbricate sunt blocate implicit. Mențineți aceste liste cât mai restrânse posibil: revizuirea plugin-ului compară politica declarată cu comportamentul real al interfeței. Și tratați URI-ul resursei ca pe o cheie de cache: pentru fiecare modificare incompatibilă a HTML, JavaScript sau CSS, publicați un nou URI și actualizați instrumentele care fac referință la acesta.
Două detalii finale: gazda reflectă limba utilizatorului în document.documentElement.lang, de utilizat pentru traducerea și formatarea datelor și numerelor; iar biblioteca @openai/apps-sdk-ui oferă butoane, carduri și câmpuri care se potrivesc cu ChatGPT dacă nu doriți să redesenați totul.
Puncte cheie
- O interfață este o resursă
ui://de tiptext/html;profile=mcp-app, atașată la un instrument prin_meta.ui.resourceUri - Componenta comunică cu gazda prin JSON-RPC (
ui/initialize,tools/call,ui/notifications/tool-result…) - Separați instrumentele de date de cele de randare: doar instrumentul de randare poartă șablonul
window.openaioferă doar extensii, de detectat înainte de utilizare- Date de business pe server, CSP restrâns, URI de resursă versionat