Добавяне на интерфейс с MCP Apps
На тази страница
Урокът е пренаписан на 3 ноември 2026 г. въз основа на страницата Add UI to your MCP server от документацията на OpenAI за плъгини и кода за
@modelcontextprotocol/ext-apps1.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-input | window.openai.toolInput |
| Получаване на резултат | ui/notifications/tool-result | window.openai.toolOutput |
| Извикване на инструмент | tools/call | window.openai.callTool |
| Изпращане на последващо съобщение | ui/message | window.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 на ресурса с версии