Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Přidání rozhraní s aplikacemi MCP

Lekce 6 z 14 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Kdy přidat rozhraní
  2. Princip MCP Apps
  3. Na straně serveru: deklarace zdroje a nástroje
  4. Na straně iframe: most JSON-RPC
  5. Výběr prezentace
  6. Rozšíření specifická pro ChatGPT
  7. Tři druhy stavu
  8. Zásady zabezpečení obsahu (CSP)
  9. Klíčové poznatky

Lekce přepsána 3. listopadu 2026 na základě stránky Add UI to your MCP server z dokumentace OpenAI Plugins a kódu pro @modelcontextprotocol/ext-apps 1.7.5. Předchozí lekce popisovala „widgety“ (defineWidget) z neexistujícího SDK; rozhraní je zdroj MCP Apps vykreslovaný ChatGPT v iframe. Zdroje: Add UI to your MCP server · MCP Apps Specification.

Kdy přidat rozhraní

Rozhraní je volitelné. Přidej ho, když uživatel potřebuje prohlížet, porovnávat, upravovat, potvrzovat nebo procházet strukturované informace – a zároveň udržuj své nástroje funkční i bez něj, aby ChatGPT a Codex mohly řídit pracovní postup v klientech, které komponentu nezobrazují.

Princip MCP Apps

ChatGPT implementuje otevřený standard MCP Apps. Server deklaruje zdroj rozhraní, identifikovaný URI ui://… a obsluhovaný s typem MIME text/html;profile=mcp-app; nástroj se k němu připojí přes _meta.ui.resourceUri. Když je tento nástroj zavolán, ChatGPT zobrazí zdroj v iframe vedle konverzace. Komponenta komunikuje s hostitelem prostřednictvím JSON-RPC pomocí postMessage:

ZprávaRole
ui/initialize a poté ui/notifications/initializedOtevření dialogu s hostitelem
ui/notifications/tool-inputPřijetí argumentů volání nástroje
ui/notifications/tool-resultPřijetí výsledku nástroje
tools/callVolání nástroje serveru z rozhraní
ui/messageOdeslání následné zprávy v konverzaci
ui/update-model-contextInformování modelu o aktuálním výběru nebo úpravě

Na straně serveru: deklarace zdroje a nástroje

Podívejme se znovu na server pro poznámky z lekce 4. Balíček @modelcontextprotocol/ext-apps (ve verzi 1.x s SDK v1) poskytuje dva pomocníky: registerAppResource, který ve výchozím nastavení aplikuje správný typ MIME exponovaný konstantou RESOURCE_MIME_TYPE, a registerAppTool, který vyžaduje metadata rozhraní.

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

const URI_CARTE = "ui://widget/notes-v1.html"; // verzováno: toto je klíč mezipaměti
const carteHtml = readFileSync("public/notes-widget.html", "utf8");

// Přidej uvnitř creerServeur(), vedle list_notes a 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.` }],
  })
);

Pouze show_notes nese rozhraní. To je oddělení, které OpenAI doporučuje: pokud by každý nástroj vracel šablonu, ChatGPT by příliš často překresloval iframe. Datové nástroje (list_notes, add_note) hledají, počítají nebo upravují a vracejí pouze svůj výsledek; nástroje pro vykreslování přijímají konečná data a vracejí šablonu. Model tak může pracovat s daty – filtrovat, křížově odkazovat – než se rozhodne pro zobrazení, a karta se objeví pouze jednou, s ověřeným kontextem. Závislost uveď v popisu nástroje pro vykreslování, jak je ukázáno výše.

Na straně iframe: most JSON-RPC

Komponenta sem zapadá jako jediný HTML soubor bez kroku sestavení. Otevře dialog s hostitelem a poté zobrazí každý přijatý výsledek nástroje.

<!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; // nikdy innerHTML na přijatá 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>

Přijatý výsledek jsou nedůvěryhodná data: zobrazuj je pomocí textContent, nikdy je nevkládej jako HTML. Pro bohatší rozhraní poskytuje stejný balíček třídu App na straně prohlížeče, která tento most zapouzdřuje (přijímání výsledků, volání nástrojů) a je určena k integraci do svazku sestaveného pomocí esbuild; úložiště příkladů OpenAI ukazuje kompletní komponenty React.

Výběr prezentace

Začni s vloženým zobrazením a o více prostoru žádej pouze tehdy, pokud to pracovní postup vyžaduje:

PrezentacePoužití
Vložená kartaCílený výsledek, potvrzení, několik akcí bez hluboké navigace
Vložený karuselProcházení a výběr z několika podobných vizuálních možností
Celá obrazovkaNáročný úkol: mapa, plátno pro úpravy, podrobný průzkum; vstupní oblast ChatGPT zůstává dostupná
Obraz v obrazeProbíhající aktivita, která musí zůstat viditelná během konverzace: živá relace, hra, video

Rozšíření specifická pro ChatGPT

Jakmile je tok MCP Apps nastaven, nabízí ChatGPT rozšíření přes window.openai, která používej pouze pro to, co standard nepokrývá. Pro běžné potřeby upřednostni standard; aliasy ChatGPT zůstávají dostupné pro stávající integrace:

PotřebaStandard MCP AppsAlias ChatGPT
Připojení nástroje k rozhraní_meta.ui.resourceUri_meta["openai/outputTemplate"]
Přijetí argumentůui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Přijetí výsledkuui/notifications/tool-resultwindow.openai.toolOutput
Volání nástrojetools/callwindow.openai.callTool
Odeslání následné zprávyui/messagewindow.openai.sendFollowUpMessage

Rozšíření bez ekvivalentu ve standardu pokrývají integrované platby (requestCheckout), soubory (uploadFile, selectFiles, getFileDownloadUrl), modální okna spravovaná hostitelem (requestModal) a perzistenci stavu komponenty (widgetState, setWidgetState). Před použitím každou schopnost detekuj a pokud možno poskytni záložní řešení – nikdy netestuj název hostitele, testuj funkci:

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

Tři druhy stavu

StavVlastníkŽivotnostPříklady
Obchodní data, zdroj pravdyServer MCP nebo externí službaDlouháÚkoly, tickety, dokumenty
Stav rozhraní, efemérníInstance komponentyDoba jejího zobrazeníVybraný řádek, otevřený panel, pořadí řazení
Trvalý stav napříč relacemiÚložiště, které kontroluješMezi konverzacemi a zařízenímiUložené filtry, režim zobrazení

Obchodní data zůstávají na serveru: rozhraní zavolá nástroj, server validuje a aktualizuje, poté vrátí referenční stav, který rozhraní zobrazí, přičemž si ponechá pouze to, co souvisí s prezentací. Když model potřebuje znát výběr, odešli jej přes ui/update-model-context. window.openai.setWidgetState (synchronní, bez await) zachovává stav instance, nikoliv obchodní data. Trvalá data patří do tvého úložiště za autentizací; vyhni se localStorage, které nenabízí ani kontinuitu mezi zařízeními, ani spolehlivost v izolovaném iframe.

Zásady zabezpečení obsahu (CSP)

Komponenta ve svých metadatech zdroje (_meta.ui.csp) deklaruje přesné domény, které používá: connectDomains pro volání API, resourceDomains pro skripty, styly a obrázky, frameDomains pouze pokud musí integrovat specifická iframe – vnořená rámcová okna jsou ve výchozím nastavení blokována. Udržuj tyto seznamy co nejúžeji: revize pluginu porovnává deklarovanou politiku se skutečným chováním rozhraní. A zacházej s URI zdroje jako s klíčem mezipaměti: pro každou nekompatibilní změnu v HTML, JavaScriptu nebo CSS publikuj nové URI a aktualizuj nástroje, které na něj odkazují.

Dva poslední detaily: hostitel odráží jazyk uživatele v document.documentElement.lang, což použij pro překlad a formátování dat a čísel; a knihovna @openai/apps-sdk-ui poskytuje tlačítka, karty a pole odpovídající ChatGPT, pokud nechceš vše znovu navrhovat.

Klíčové poznatky

  • Rozhraní je zdroj ui:// typu text/html;profile=mcp-app, připojený k nástroji přes _meta.ui.resourceUri
  • Komponenta komunikuje s hostitelem prostřednictvím JSON-RPC (ui/initialize, tools/call, ui/notifications/tool-result…)
  • Odděl datové nástroje a nástroje pro vykreslování: šablonu nese pouze nástroj pro vykreslování
  • window.openai poskytuje pouze rozšíření, která je třeba před použitím detekovat
  • Obchodní data na serveru, úzká CSP, verzované URI zdroje