MCP-UI SDK

📦 Model Context Protocol UI SDK

mcp-ui стал первопроходцем в концепции интерактивного UI поверх MCP, открыв возможность создавать богатые веб-интерфейсы для AI-инструментов. Вместе с Apps SDK паттерны, разработанные здесь, напрямую повлияли на спецификацию MCP Apps, которая стандартизировала доставку UI через протокол.

Пакеты @mcp-ui/* реализуют стандарт MCP Apps. @mcp-ui/client — рекомендуемый SDK для MCP Apps Hosts.

Пакеты @mcp-ui/ полностью соответствуют спецификации MCP Apps и готовы к использованию в продакшене.*

💡 Что такое mcp-ui?

mcp-ui — SDK, реализующий стандарт MCP Apps для UI поверх MCP. Включает:

• @mcp-ui/server (TypeScript): создание UI-ресурсов через createUIResource. Совместим с registerAppTool и registerAppResource из @modelcontextprotocol/ext-apps/server.
• @mcp-ui/client (TypeScript): рендеринг UI инструментов через AppRenderer (MCP Apps) или UIResourceRenderer (устаревшие MCP-UI хосты).
• mcp_ui_server (Ruby): создание UI-ресурсов на Ruby.
• mcp-ui-server (Python): создание UI-ресурсов на Python.

Паттерн MCP Apps связывает инструменты с их UI через _meta.ui.resourceUri. Хосты получают и отображают UI вместе с результатами инструментов.

✨ Основные концепции

Паттерн MCP Apps (рекомендуется)

Стандарт MCP Apps связывает инструменты с их UI через _meta.ui.resourceUri:

import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { createUIResource } from '@mcp-ui/server';

// 1. Создаём UI-ресурс
const widgetUI = await createUIResource({
  uri: 'ui://my-server/widget',
  content: { type: 'rawHtml', htmlString: '<h1>Widget</h1>' },
  encoding: 'text',
});

// 2. Регистрируем обработчик ресурса
registerAppResource(server, 'widget_ui', widgetUI.resource.uri, {}, async () => ({
  contents: [widgetUI.resource]
}));

// 3. Регистрируем инструмент с _meta-ссылкой
registerAppTool(server, 'show_widget', {
  description: 'Show widget',
  inputSchema: { query: z.string() },
  _meta: { ui: { resourceUri: widgetUI.resource.uri } }  // Связывает инструмент → UI
}, async ({ query }) => {
  return { content: [{ type: 'text', text: `Query: ${query}` }] };
});

Хосты обнаруживают _meta.ui.resourceUri, получают UI через resources/read и рендерят его с помощью AppRenderer.

UIResource (формат передачи данных)

Базовая структура для UI-контента:

interface UIResource {
  type: 'resource';
  resource: {
    uri: string;       // например, ui://component/id
    mimeType: 'text/html;profile=mcp-app';
    text?: string;      // HTML-контент
    blob?: string;      // HTML-контент в кодировке Base64
  };
}

• uri: уникальный идентификатор в схеме ui://
• mimeType: text/html;profile=mcp-app — стандартный MIME-тип MCP Apps
• text vs. blob: обычный текст или контент в кодировке Base64

Клиентские компоненты

AppRenderer (MCP Apps)

Для MCP Apps хостов используйте AppRenderer для рендеринга UI инструментов:

import { AppRenderer } from '@mcp-ui/client';

function ToolUI({ client, toolName, toolInput, toolResult }) {
  return (
    <AppRenderer
      client={client}
      toolName={toolName}
      sandbox={{ url: sandboxUrl }}
      toolInput={toolInput}
      toolResult={toolResult}
      onOpenLink={async ({ url }) => window.open(url)}
      onMessage={async (params) => console.log('Message:', params)}
    />
  );
}

Основные пропсы:

• client: опциональный MCP-клиент для автоматического получения ресурсов
• toolName: имя инструмента, для которого рендерится UI
• sandbox: конфигурация песочницы с URL прокси
• toolInput / toolResult: аргументы и результаты инструмента
• onOpenLink / onMessage: обработчики запросов от UI

UIResourceRenderer (устаревший MCP-UI)

Для устаревших хостов, встраивающих ресурсы в ответы инструментов:

import { UIResourceRenderer } from '@mcp-ui/client';

<UIResourceRenderer
  resource={mcpResource.resource}
  onUIAction={(action) => console.log('Action:', action)}
/>

Пропсы:

• resource: объект ресурса с uri, mimeType и контентом (text/blob)
• onUIAction: колбэк для обработки действий инструмента, промпта, ссылки, уведомления и intent