Премини към основното съдържание
Български— Изберете език
Меню

Добавяне на интерфейс с MCP Apps

Урок 6 от 14 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Кога да добавите интерфейс
  2. Принципът на MCP Apps
  3. От страна на сървъра: деклариране на ресурса и инструмента
  4. От страна на iframe: JSON-RPC мостът
  5. Избор на презентация
  6. Разширения, специфични за ChatGPT
  7. Три вида състояние
  8. Политика за сигурност на съдържанието (CSP)
  9. Ключови изводи

Урокът е пренаписан на 3 ноември 2026 г. въз основа на страницата Add UI to your MCP server от документацията на OpenAI за плъгини и кода за @modelcontextprotocol/ext-apps 1.7.5. Предишният урок описваше “уиджети” (defineWidget) от несъществуващ SDK; интерфейсът е ресурс на MCP Apps, рендиран от ChatGPT в iframe. Източници: Add UI to your MCP server · MCP Apps Specification.

Кога да добавите интерфейс

Интерфейсът е по избор. Добавете такъв, когато потребителят трябва да инспектира, сравнява, модифицира, потвърждава или разглежда структурирана информация – и запазете полезността на вашите инструменти без него, така че ChatGPT и Codex да могат да управляват работния поток в клиенти, които не показват компонент.

Принципът на MCP Apps

ChatGPT имплементира открития стандарт MCP Apps. Сървърът декларира ресурс за интерфейс, идентифициран чрез URI ui://… и сервиран с MIME типа text/html;profile=mcp-app; инструмент се прикрепя към него чрез _meta.ui.resourceUri. Когато този инструмент бъде извикан, ChatGPT показва ресурса в iframe, до разговора. Компонентът комуникира с хоста чрез JSON-RPC, използвайки postMessage:

СъобщениеРоля
ui/initialize, следвано от ui/notifications/initializedОтваряне на диалога с хоста
ui/notifications/tool-inputПолучаване на аргументите за извикване на инструмента
ui/notifications/tool-resultПолучаване на резултата от инструмента
tools/callИзвикване на сървърен инструмент от интерфейса
ui/messageИзпращане на последващо съобщение в разговора
ui/update-model-contextИнформиране на модела за текущ избор или модификация

От страна на сървъра: деклариране на ресурса и инструмента

Нека разгледаме отново сървъра за бележки от Урок 4. Пакетът @modelcontextprotocol/ext-apps (във версия 1.x със SDK v1) предоставя два помощника: registerAppResource, който прилага правилния MIME тип, изложен по подразбиране от константата RESOURCE_MIME_TYPE, и registerAppTool, който изисква метаданни за интерфейса.

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

const URI_CARTE = "ui://widget/notes-v1.html"; // с версии: това е ключ за кеш
const carteHtml = readFileSync("public/notes-widget.html", "utf8");

// Добавете вътре в creerServeur(), до list_notes и 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.` }],
  })
);

Само show_notes носи интерфейса. Това е разделянето, което OpenAI препоръчва: ако всеки инструмент връщаше шаблон, ChatGPT щеше да прерисува iframe твърде често. Инструментите за данни (list_notes, add_note) търсят, изчисляват или модифицират и връщат само резултата си; инструментите за рендиране получават крайни данни и връщат шаблона. По този начин моделът може да работи с данните – филтриране, кръстосана проверка – преди да реши да ги покаже, а картата се появява само веднъж, с проверен контекст. Посочете зависимостта в описанието на инструмента за рендиране, както е показано по-горе.

От страна на iframe: JSON-RPC мостът

Компонентът се побира тук в един единствен HTML файл, без стъпка на изграждане. Той отваря диалога с хоста, след което показва всеки резултат от инструмент, който получи.

<!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>

Полученият резултат е ненадеждни данни: показвайте го с textContent, никога чрез инжектирането му като HTML. За по-богат интерфейс същият пакет предоставя браузър клас App от страната на клиента, който капсулира този мост (получаване на резултати, извикване на инструменти), за да бъде интегриран в пакет, изграден с esbuild; хранилището с примери на OpenAI показва пълни React компоненти.

Избор на презентация

Започнете с вграденото показване и поискайте повече пространство само ако работният поток го изисква:

ПрезентацияУпотреба
Вградена картаЦелеви резултат, потвърждение, няколко действия, без дълбока навигация
Вградена каруселаРазглеждане и избор между няколко подобни, визуални опции
Цял екранБогата задача: карта, платно за редактиране, подробно проучване; входната област на ChatGPT остава налична
Picture-in-pictureТекуща дейност, която трябва да остане видима по време на разговора: сесия на живо, игра, видео

Разширения, специфични за ChatGPT

След като потокът на MCP Apps е на място, ChatGPT предлага разширения чрез window.openai, които да се използват само за това, което стандартът не покрива. За общи нужди предпочитайте стандарта; псевдонимите на ChatGPT остават налични за съществуващи интеграции:

НуждаСтандарт MCP AppsПсевдоним на ChatGPT
Прикрепяне на инструмент към интерфейс_meta.ui.resourceUri_meta["openai/outputTemplate"]
Получаване на аргументиui/initialize + ui/notifications/tool-inputwindow.openai.toolInput
Получаване на резултатui/notifications/tool-resultwindow.openai.toolOutput
Извикване на инструментtools/callwindow.openai.callTool
Изпращане на последващо съобщениеui/messagewindow.openai.sendFollowUpMessage

Разширенията без еквивалент в стандарта покриват интегрирано плащане (requestCheckout), файлове (uploadFile, selectFiles, getFileDownloadUrl), модълни прозорци, управлявани от хоста (requestModal), и запазване на състоянието на компонента (widgetState, setWidgetState). Откривайте всяка възможност, преди да я използвате, с резервен вариант, когато е възможно – и никога не тествайте името на хоста, тествайте функцията:

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

Три вида състояние

СъстояниеСобственикПродължителностПримери
Бизнес данни, източник на истинатаMCP сървър или външна услугаДългаЗадачи, тикети, документи
Състояние на интерфейса, ефемерноИнстанция на компонентаПродължителност на показването муИзбран ред, отворен панел, ред на сортиране
Трайно състояние между сесиитеХранилище, което контролиратеМежду разговорите и устройстватаЗапазени филтри, режим на показване

Бизнес данните остават на сървъра: интерфейсът извиква инструмент, сървърът валидира и актуализира, след което връща референтното състояние, което интерфейсът показва, запазвайки това, което се отнася до презентацията. Когато моделът трябва да знае за избор, изпратете го чрез ui/update-model-context. window.openai.setWidgetState (синхронно, без await) запазва състоянието на инстанция, а не бизнес данни. Трайното състояние отива във вашето хранилище, зад автентикация; избягвайте localStorage, което не предлага нито непрекъснатост между устройства, нито надеждност в изолиран iframe.

Политика за сигурност на съдържанието (CSP)

Компонентът декларира в метаданните на своя ресурс (_meta.ui.csp) точните домейни, които използва: connectDomains за API повиквания, resourceDomains за скриптове, стилове и изображения, frameDomains само ако трябва да интегрира специфични iframe – вложените рамки са блокирани по подразбиране. Поддържайте тези списъци възможно най-тесни: прегледът на плъгина сравнява декларираната политика с действителното поведение на интерфейса. И третирайте URI на ресурса като ключ за кеш: за всяка несъвместима промяна в HTML, JavaScript или CSS, публикувайте нов URI и актуализирайте инструментите, които се позовават на него.

Две последни подробности: хостът отразява езика на потребителя в document.documentElement.lang, който да се използва за превод и форматиране на дати и числа; и библиотеката @openai/apps-sdk-ui предоставя бутони, карти и полета, съвпадащи с ChatGPT, ако не искате да проектирате всичко отново.

Ключови изводи

  • Интерфейсът е ресурс ui:// от тип text/html;profile=mcp-app, прикрепен към инструмент чрез _meta.ui.resourceUri
  • Компонентът комуникира с хоста чрез JSON-RPC (ui/initialize, tools/call, ui/notifications/tool-result…)
  • Разделете инструментите за данни и инструментите за рендиране: само инструментът за рендиране носи шаблона
  • window.openai предоставя само разширения, които трябва да бъдат открити преди употреба
  • Бизнес данни на сървъра, тясна CSP, URI на ресурса с версии