Dodaj interfejs z aplikacjami MCP
Na tej stronie
Lekcja przepisana 3 listopada 2026 r. na podstawie strony Add UI to your MCP server z dokumentacji wtyczek OpenAI oraz kodu pakietu
@modelcontextprotocol/ext-appsw 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/initialized | Otwarcie dialogu z hostem |
ui/notifications/tool-input | Otrzymanie argumentów wywołania narzędzia |
ui/notifications/tool-result | Otrzymanie wyniku działania narzędzia |
tools/call | Wywołanie narzędzia serwerowego z poziomu interfejsu |
ui/message | Wysłanie wiadomości uzupełniającej w konwersacji |
ui/update-model-context | Poinformowanie 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:
| Prezentacja | Zastosowanie |
|---|---|
| Karta wbudowana | Ukierunkowany wynik, potwierdzenie, kilka akcji, bez głębokiej nawigacji |
| Karuzela wbudowana | Przeglądanie i wybieranie spośród kilku podobnych, wizualnych opcji |
| Pełny ekran | Bogate zadanie: mapa, płótno edycji, szczegółowa eksploracja; obszar wprowadzania ChatGPT pozostaje dostępny |
| Obraz w obrazie | Trwają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:
| Potrzeba | Standard Aplikacji MCP | Alias ChatGPT |
|---|---|---|
| Dołączenie narzędzia do interfejsu | _meta.ui.resourceUri | _meta["openai/outputTemplate"] |
| Otrzymanie argumentów | ui/initialize + ui/notifications/tool-input | window.openai.toolInput |
| Otrzymanie wyniku | ui/notifications/tool-result | window.openai.toolOutput |
| Wywołanie narzędzia | tools/call | window.openai.callTool |
| Wysłanie wiadomości uzupełniającej | ui/message | window.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
| Stan | Właściciel | Czas życia | Przykłady |
|---|---|---|---|
| Dane biznesowe, źródło prawdy | Serwer MCP lub usługa zewnętrzna | Długi | Zadania, zgłoszenia, dokumenty |
| Stan interfejsu, efemeryczny | Instancja komponentu | Czas jego wyświetlania | Zaznaczony wiersz, otwarty panel, kolejność sortowania |
| Stan trwały między sesjami | Przechowywanie, które kontrolujesz | Między konwersacjami i urządzeniami | Zapisane 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://typutext/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.openaidostarcza wyłącznie rozszerzenia, które należy wykryć przed użyciem- Dane biznesowe na serwerze, wąskie CSP, wersjonowane URI zasobu