Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Pridėti sąsają su MCP programėlėmis

Paskaita 6 iš 14 Atnaujinta 2026 m. lapkričio 3 d. Kūrėjas
Šiame puslapyje
  1. Kada pridėti sąsają
  2. MCP Apps principas
  3. Serverio pusė: deklaruok išteklių ir įrankį
  4. Iframe pusė: JSON-RPC tiltas
  5. Prezentacijos pasirinkimas
  6. „ChatGPT“ specifiniai plėtiniai
  7. Trys būsenų tipai
  8. Turinio saugumo politika (CSP)
  9. Svarbiausi punktai

Pamoka perrašyta 2026 m. lapkričio 3 d. remiantis „Add UI to your MCP server“ puslapiu iš „OpenAI Plugins“ dokumentacijos ir @modelcontextprotocol/ext-apps 1.7.5 versijos kodu. Ankstesnė pamoka aprašė „valdiklius“ (defineWidget) iš neegzistuojančio SDK; sąsaja yra MCP Apps ištekliai, kuriuos „ChatGPT“ atvaizduoja iframe rė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/initializedPradėti dialogą su šeimininku
ui/notifications/tool-inputGauti įrankio iškvietimo argumentus
ui/notifications/tool-resultGauti įrankio rezultatą
tools/callIškvieti serverio įrankį iš sąsajos
ui/messageSiųsti tolesnį pranešimą pokalbyje
ui/update-model-contextInformuoti 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:

PrezentacijaNaudojimas
Įterpta kortelėTikslinis rezultatas, patvirtinimas, keli veiksmai be gilaus naršymo
Įterpta karuselėNaršyti ir pasirinkti iš kelių panašių, vizualių opcijų
Visas ekranasTurtinga 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:

PoreikisMCP Apps standartas„ChatGPT“ aliasas
Prijungti įrankį prie sąsajos_meta.ui.resourceUri_meta["openai/outputTemplate"]
Gauti argumentusui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Gauti rezultatąui/notifications/tool-resultwindow.openai.toolOutput
Iškvieti įrankįtools/callwindow.openai.callTool
Siųsti tolesnį pranešimąui/messagewindow.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ūsenaSavininkasGyvavimo trukmėPavyzdžiai
Verslo duomenys, tiesos šaltinisMCP serveris arba išorinė tarnybaIlgaUžduotys, bilietai, dokumentai
Sąsajos būsena, laikinaKomponento egzemplioriusJo rodymo trukmėPasirinkta eilutė, atidarytas skydelis, rikiavimo tvarka
Ilgaamžė būsena tarp sesijųTavo valdoma saugyklaTarp 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 tipo text/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.openai teikia tik plėtinius, kuriuos reikia aptikti prieš naudojant
  • Verslo duomenys serveryje, siaura CSP, versijuotas išteklių URI