Salt la conținutul principal
Română— Alege o limbă
Meniu

Adăugarea unei interfețe cu aplicații MCP

Lecția 6 din 14 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Când să adăugați o interfață
  2. Principiul aplicațiilor MCP
  3. Partea de server: declararea resursei și a instrumentului
  4. Partea iframe: puntea JSON-RPC
  5. Alegerea unei prezentări
  6. Extensii specifice ChatGPT
  7. Trei tipuri de stare
  8. Politica de securitate a conținutului (CSP)
  9. Puncte cheie

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-apps 1.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:

MesajRol
ui/initialize apoi ui/notifications/initializedDeschiderea dialogului cu gazda
ui/notifications/tool-inputPrimirea argumentelor apelului instrumentului
ui/notifications/tool-resultPrimirea rezultatului instrumentului
tools/callApelarea unui instrument de server din interfață
ui/messageTrimiterea unui mesaj de follow-up în conversație
ui/update-model-contextInformarea 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:

PrezentareUtilizare
Card inlineUn rezultat țintit, o confirmare, câteva acțiuni, fără navigare profundă
Carusel inlineNavigare și alegere printre câteva opțiuni similare, vizuale
Ecran completO sarcină bogată: hartă, canvas de editare, explorare detaliată; zona de input ChatGPT rămâne disponibilă
Picture-in-pictureO 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:

NevoieStandard MCP AppsAlias ChatGPT
Atașarea unui instrument la o interfață_meta.ui.resourceUri_meta["openai/outputTemplate"]
Primirea argumentelorui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Primirea rezultatuluiui/notifications/tool-resultwindow.openai.toolOutput
Apelarea unui instrumenttools/callwindow.openai.callTool
Trimiterea unui mesaj de follow-upui/messagewindow.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

StareProprietarDurată de viațăExemple
Date de business, sursa adevăruluiServer MCP sau serviciu externLungăSarcini, tichete, documente
Starea interfeței, efemerăInstanța componenteiDurata afișării saleRând selectat, panou deschis, ordine de sortare
Stare durabilă între sesiuniStocare pe care o controlațiÎntre conversații și dispozitiveFiltre 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 tip text/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.openai oferă doar extensii, de detectat înainte de utilizare
  • Date de business pe server, CSP restrâns, URI de resursă versionat