Przejdź do głównej treści
Polski— Wybierz język
Menu

Dodaj interfejs z aplikacjami MCP

Lekcja 6 z 14 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Kiedy dodać interfejs
  2. Zasada działania Aplikacji MCP
  3. Strona serwera: deklaracja zasobu i narzędzia
  4. Strona iframe: most JSON-RPC
  5. Wybór prezentacji
  6. Rozszerzenia specyficzne dla ChatGPT
  7. Trzy rodzaje stanu
  8. Polityka bezpieczeństwa treści (CSP)
  9. Kluczowe wnioski

Lekcja przepisana 3 listopada 2026 r. na podstawie strony Add UI to your MCP server z dokumentacji wtyczek OpenAI oraz kodu pakietu @modelcontextprotocol/ext-apps w wersji 1.7.5. Poprzednia lekcja opisywała „widżety“ (defineWidget) z nieistniejącego SDK; interfejs to zasób Aplikacji MCP renderowany przez ChatGPT w elemencie iframe. Źródła: Add UI to your MCP server · Specyfikacja Aplikacji MCP.

Kiedy dodać interfejs

Interfejs jest opcjonalny. Dodaj go, gdy użytkownik musi sprawdzić, porównać, zmodyfikować, potwierdzić lub przeglądać ustrukturyzowane informacje – i spraw, by Twoje narzędzia były użyteczne również bez niego, dzięki czemu ChatGPT i Codex będą mogły prowadzić proces w klientach, które nie wyświetlają komponentu.

Zasada działania Aplikacji MCP

ChatGPT implementuje otwarty standard Aplikacji MCP. Serwer deklaruje zasób interfejsu, identyfikowany przez URI ui://… i obsługiwany z typem MIME text/html;profile=mcp-app; narzędzie dołącza się do niego poprzez _meta.ui.resourceUri. Gdy to narzędzie zostanie wywołane, ChatGPT wyświetla zasób w elemencie iframe, obok konwersacji. Komponent komunikuje się z hostem poprzez JSON-RPC za pomocą postMessage:

WiadomośćRola
ui/initialize, a następnie ui/notifications/initializedOtwarcie dialogu z hostem
ui/notifications/tool-inputOtrzymanie argumentów wywołania narzędzia
ui/notifications/tool-resultOtrzymanie wyniku działania narzędzia
tools/callWywołanie narzędzia serwerowego z poziomu interfejsu
ui/messageWysłanie wiadomości uzupełniającej w konwersacji
ui/update-model-contextPoinformowanie modelu o bieżącym zaznaczeniu lub modyfikacji

Strona serwera: deklaracja zasobu i narzędzia

Wróćmy do serwera notatek z Lekcji 4. Pakiet @modelcontextprotocol/ext-apps (w wersji 1.x z SDK v1) dostarcza dwie funkcje pomocnicze: registerAppResource, która domyślnie stosuje poprawny typ MIME udostępniany przez stałą RESOURCE_MIME_TYPE, oraz registerAppTool, która wymaga metadanych interfejsu.

import { readFileSync } from "node:fs";
import {
  registerAppResource,
  registerAppTool,
  RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";

const URI_CARTE = "ui://widget/notes-v1.html"; // wersjonowane: to klucz pamięci podręcznej
const carteHtml = readFileSync("public/notes-widget.html", "utf8");

// Dodaj wewnątrz creerServeur(), obok 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.` }],
  })
);

Tylko show_notes posiada interfejs. To właśnie rozspojenie zalecane przez OpenAI: gdyby każde narzędzie zwracało szablon, ChatGPT zbyt często odświeżałby element iframe. Narzędzia danych (list_notes, add_note) wyszukują, obliczają lub modyfikują i zwracają wyłącznie swój wynik; narzędzia renderujące otrzymują gotowe dane i zwracają szablon. Model może więc pracować na danych – filtrować, krzyżować odniesienia – zanim zdecyduje się na wyświetlenie, a karta pojawi się tylko raz, ze zweryfikowanym kontekstem. Wskaż zależność w opisie narzędzia renderującego, jak pokazano powyżej.

Strona iframe: most JSON-RPC

Komponent mieści się tutaj w pojedynczym pliku HTML, bez etapu budowania. Otwiera on dialog z hostem, a następnie wyświetla każdy otrzymany wynik działania narzędzia.

<!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; // nigdy innerHTML na otrzymanych danych
            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>

Otrzymany wynik to dane niezaufane: wyświetlaj je za pomocą textContent, nigdy poprzez wstrzykiwanie ich jako HTML. Dla bogatszego interfejsu ten sam pakiet dostarcza klasę App po stronie przeglądarki, która inkapsuluje ten most (odbieranie wyników, wywoływanie narzędzi), do zintegrowania z pakietem zbudowanym przy użyciu esbuild; repozytorium przykładów OpenAI pokazuje kompletne komponenty React.

Wybór prezentacji

Zacznij od wyświetlania wbudowanego i żądaj większej przestrzeni tylko wtedy, gdy wymaga tego proces:

PrezentacjaZastosowanie
Karta wbudowanaUkierunkowany wynik, potwierdzenie, kilka akcji, bez głębokiej nawigacji
Karuzela wbudowanaPrzeglądanie i wybieranie spośród kilku podobnych, wizualnych opcji
Pełny ekranBogate zadanie: mapa, płótno edycji, szczegółowa eksploracja; obszar wprowadzania ChatGPT pozostaje dostępny
Obraz w obrazieTrwająca aktywność, która musi pozostać widoczna podczas konwersacji: sesja na żywo, gra, wideo

Rozszerzenia specyficzne dla ChatGPT

Gdy przepływ Aplikacji MCP jest już wdrożony, ChatGPT oferuje rozszerzenia poprzez window.openai, które należy używać tylko do tego, czego nie obejmuje standard. Dla typowych potrzeb preferuj standard; aliasy ChatGPT pozostają dostępne dla istniejących integracji:

PotrzebaStandard Aplikacji MCPAlias ChatGPT
Dołączenie narzędzia do interfejsu_meta.ui.resourceUri_meta["openai/outputTemplate"]
Otrzymanie argumentówui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Otrzymanie wynikuui/notifications/tool-resultwindow.openai.toolOutput
Wywołanie narzędziatools/callwindow.openai.callTool
Wysłanie wiadomości uzupełniającejui/messagewindow.openai.sendFollowUpMessage

Rozszerzenia bez odpowiednika w standardzie obejmują zintegrowane płatności (requestCheckout), pliki (uploadFile, selectFiles, getFileDownloadUrl), okna modalne zarządzane przez hosta (requestModal) oraz trwałość stanu komponentu (widgetState, setWidgetState). Wykrywaj każdą możliwość przed jej użyciem, stosując mechanizm zastępczy, gdy to możliwe – i nigdy nie testuj nazwy hosta, testuj funkcję:

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.";
}

Trzy rodzaje stanu

StanWłaścicielCzas życiaPrzykłady
Dane biznesowe, źródło prawdySerwer MCP lub usługa zewnętrznaDługiZadania, zgłoszenia, dokumenty
Stan interfejsu, efemerycznyInstancja komponentuCzas jego wyświetlaniaZaznaczony wiersz, otwarty panel, kolejność sortowania
Stan trwały między sesjamiPrzechowywanie, które kontrolujeszMiędzy konwersacjami i urządzeniamiZapisane filtry, tryb wyświetlania

Dane biznesowe pozostają na serwerze: interfejs wywołuje narzędzie, serwer waliduje i aktualizuje, a następnie zwraca stan referencyjny, który interfejs wyświetla, zachowując to, co dotyczy prezentacji. Gdy model musi znać zaznaczenie, wyślij je poprzez ui/update-model-context. window.openai.setWidgetState (synchroniczne, bez await) zachowuje stan instancji, a nie dane biznesowe. Stan trwały umieszczaj we własnym przechowywaniu, za autoryzacją; unikaj localStorage, które nie oferuje ani ciągłości między urządzeniami, ani niezawodności w izolowanym elemencie iframe.

Polityka bezpieczeństwa treści (CSP)

Komponent deklaruje w metadanych zasobu (_meta.ui.csp) dokładne domeny, z których korzysta: connectDomains dla wywołań API, resourceDomains dla skryptów, stylów i obrazów, frameDomains tylko wtedy, gdy musi integrować określone elementy iframe – zagnieżdżone ramki są domyślnie blokowane. Utrzymuj te listy jak najwęższe: przegląd wtyczki porównuje zadeklarowaną politykę z rzeczywistym zachowaniem interfejsu. Traktuj URI zasobu jako klucz pamięci podręcznej: przy każdej niezgodnej zmianie w HTML, JavaScript lub CSS opublikuj nowe URI i zaktualizuj narzędzia, które się do niego odwołują.

Dwa ostatnie szczegóły: host odzwierciedla język użytkownika w document.documentElement.lang, co należy wykorzystać do tłumaczenia i formatowania dat oraz liczb; biblioteka @openai/apps-sdk-ui dostarcza przyciski, karty i pola pasujące do ChatGPT, jeśli nie chcesz projektować wszystkiego od nowa.

Kluczowe wnioski

  • Interfejs to zasób ui:// typu text/html;profile=mcp-app, dołączony do narzędzia poprzez _meta.ui.resourceUri
  • Komponent komunikuje się z hostem poprzez JSON-RPC (ui/initialize, tools/call, ui/notifications/tool-result…)
  • Rozdziel narzędzia danych i narzędzia renderujące: tylko narzędzie renderujące przenosi szablon
  • window.openai dostarcza wyłącznie rozszerzenia, które należy wykryć przed użyciem
  • Dane biznesowe na serwerze, wąskie CSP, wersjonowane URI zasobu