Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Pievienot saskarni ar MCP lietotnēm

Nodarbība 6 no 14 Atjaunota 2026. gada 3. novembris Programmētājs
Šajā lapā
  1. Kad pievienot saskarni
  2. MCP Apps princips
  3. Servera puse: deklarē resursu un rīku
  4. Iframe puse: JSON-RPC tilts
  5. Noformējuma izvēle
  6. ChatGPT specifiskie paplašinājumi
  7. Trīs stāvokļu veidi
  8. Satura drošības politika (CSP)
  9. Galvenās atziņas

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-apps 1.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ņojumsLoma
ui/initialize, tad ui/notifications/initializedAtvērt dialogu ar resursdatoru
ui/notifications/tool-inputSaņemt rīka izsaukuma argumentus
ui/notifications/tool-resultSaņemt rīka rezultātu
tools/callIzsaukt servera rīku no saskarnes
ui/messageNosūtīt turpmāku ziņojumu sarunā
ui/update-model-contextInformē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ējumsLietojums
Iekļauta kartīteMērķtiecīgs rezultāts, apstiprinājums, dažas darbības bez dziļas navigācijas
Iekļauta karuseļa galerijaPārlūkošana un izvēle starp dažām līdzīgām, vizuālām opcijām
Pilnekrāna režīmsBagā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ībaMCP Apps standartsChatGPT alias
Pievienot rīku saskarnei_meta.ui.resourceUri_meta["openai/outputTemplate"]
Saņemt argumentusui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Saņemt rezultātuui/notifications/tool-resultwindow.openai.toolOutput
Izsaukt rīkutools/callwindow.openai.callTool
Nosūtīt turpmāku ziņojumuui/messagewindow.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šnieksIlgmūžībaPiemēri
Biznesa dati, patiesības avotsMCP serveris vai ārējs servissIlgaUzdevumi, biļetes, dokumenti
Saskarnes stāvoklis, īslaicīgsKomponenta instancesTās attēlošanas ilgumsAtlasīta rinda, atvērts panelis, kārtošanas secība
Ilgstošs stāvoklis starp sesijāmTava kontrolētā krātuveStarp sarunām un ierīcēmSaglabā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 tipu text/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.openai nodrošina tikai paplašinājumus, kas jānosaka pirms lietošanas
  • Biznesa dati serverī, šaura CSP, ar versiju kontrolēts resursa URI