MCP-сервер (Model Context Protocol), который отображает интерактивные HTML-карточки в настольных чат-клиентах. Вместо стен текста в разговоре появляются вкладки, таблицы, диаграммы, формы, короткие видеоклипы, сворачиваемые секции и нумерованные планы. На хостах, поддерживающих расширение MCP Apps (SEP-1865), карточки отображаются прямо в разговоре как песочные iframe; другие хосты получают каждую карточку как самодостаточный встроенный HTML-ресурс.

Возможности

• Карточки-вкладки: просмотр разных контекстов одной темы рядом (по языку, по ОС, по уровню навыков), включая примеры кода с кнопками копирования.

• Карточки-таблицы: создание HTML-таблиц из явных строк или слабо разделённого сырого текста. Разделители определяются автоматически, столбцы выравниваются, а ячейки с URL становятся ссылками.

• Карточки-диаграммы: динамически генерируемые SVG-диаграммы (столбчатые, линейные, круговые и кольцевые) с легендами и сворачиваемой таблицей данных для доступности.

• Карточки-формы: формы, которые пользователь заполняет, чтобы дать разговору контекст и направление. Отправка возвращает значения в чат как следующий промпт.

• Зеркальные веб-формы: загрузка реальной страницы, пересоздание одной из её форм в виде карточки, затем отправка реальной формы сайта с введёнными пользователем значениями через submit_web_form.

• Видеокарточки: HTML-плееры <video> для коротких клипов.

• Анимационные карточки: анимированные клипы, созданные моделью, когда прямого URL видео нет — последовательные сцены текста, поэтапное появление маркированных списков, простые SVG-диаграммы, которые рисуют себя сами, и однолинейные графики, которые приближают диапазон данных, обсуждаемый в разговоре, — всё с элементами управления в стиле видео: воспроизведение/пауза, повтор и прогресс.

• Карточки «показать/скрыть»: сворачиваемые секции с элементами управления «показать всё/скрыть всё».

• Карточки-списки: вложенные упорядоченные списки с нумерацией 1., 1.1., 1.1.1. через CSS-счётчики.

• Карточки-документы: отображение markdown-документа (руководства или пошагового описания, написанного моделью) как одной интерактивной карточки со сворачиваемыми секциями, стилизованными таблицами и копируемым кодом.

• Карточки-экскурсии по коду: представление проекта как одной вкладки на каждый исходный файл, в порядке, заданном файлами (README и манифесты поднимаются вверх), с кодом, помеченным по языку, и кнопками копирования.

• Приём файлов, созданных моделью: чтение локальных текстовых файлов и распаковка zip-архивов, которые модель создала ранее в разговоре, чтобы её собственные результаты напрямую попадали в карточки без повторного ввода.

• Автоматическое разбиение на части: большие документы и проекты упаковываются в части, каждая из которых остаётся в пределах бюджета размера карточки, чтобы хосты никогда не обрезали слишком большой результат. Каждая часть отображается как отдельная карточка, а в результате точно указано, как получить следующую.

• Получение справочных материалов: fetch_reference загружает публичную страницу и возвращает структурированные данные (заголовки, текст, таблицы, изображения, ссылки, спецификации форм), готовые для передачи в инструменты карточек.

• Карточки-репетиторы: образовательные карточки могут помечать термины, которые показывают всплывающие подсказки после наведения курсора, и определять действия контекстного меню по правому клику, отправляющие предвиденные моделью промпты.

• Перемещаемый контент: блоки карточек можно перетаскивать для изменения порядка; перетаскивание блока из карточки переносит его как HTML, а у каждой карточки есть кнопка «Copy card», которая копирует автономный HTML для вставки в другие ответы или файлы.

• Переключатели заголовка: в заголовке каждой карточки есть кнопка </>, которая показывает или скрывает собственный HTML-код карточки в панели кода, и кнопка-шеврон рядом с ней, которая сворачивает карточку до строки заголовка и снова разворачивает её.

• Копируемые карточки: в контекстном меню каждой карточки есть встроенный пункт «Copy card», который копирует автономный HTML, повторяя кнопку в заголовке. Для визуального размещения get_insert_bookmarklet возвращает букмарклет, который показывает плавающий пункт «Insert Card» при правом клике и вставляет скопированную карточку в это место (локальный предпросмотр страницы; исчезает при перезагрузке).

Related MCP server: mcp-interactive-ui-server

Когда модели следует вызывать этот сервер

Сервер рекламирует себя для разговоров об исследованиях, образовании, профессиональных навыках, общих хобби-навыках (столярное дело, искусство и тому подобное), профессиональных темах, истории и новостях, а также смежных предметах, всякий раз, когда карточка передаёт информацию лучше, чем текст.

Установка

git clone https://github.com/jhauga/mcp-chat-cards.git
cd mcp-chat-cards
npm install
npm run build

Требуется Node.js 18.17 или новее.

Использование с Claude Desktop

Добавьте сервер в claude_desktop_config.json (Settings > Developer > Edit Config), указав путь к месту, куда вы клонировали репозиторий:

{
  "mcpServers": {
    "chat-cards": {
      "command": "node",
      "args": ["C:/path/to/mcp-chat-cards/dist/index.js"]
    }
  }
}

Перезапустите настольный клиент после сохранения. Та же команда stdio работает в любом MCP-хосте; для хостов, поддерживающих MCP UI-ресурсы, карточки отображаются как песочные iframe.

Инструменты

Пример: create_table_card

{
  "title": "JavaScript array methods",
  "headers": ["Method", "Purpose"],
  "rows": [
    ["map", "Transform each item"],
    ["filter", "Keep matching items"],
    ["reduce", "Fold items into one value"]
  ]
}

Результат: текстовое резюме плюс встроенный ресурс (ui://mcp-chat-cards/<id>, text/html), содержащий полный документ карточки.

Пример: create_form_card

{
  "title": "Study preferences",
  "promptTemplate": "Teach {{topic}} with {{style}} examples.",
  "fields": [
    { "name": "topic", "label": "Topic", "required": true },
    { "name": "style", "type": "select", "options": ["practical", "theoretical"] }
  ]
}

Когда пользователь отправляет карточку, заполненный шаблон публикуется на хосте как следующий промпт. Если хост не потребляет сообщение, карточка показывает текст промпта с кнопкой копирования в качестве запасного варианта.

Пример: подключение файлов, созданных моделью

Предположим, ранее в разговоре модель собрала небольшой проект и передала project.zip плюс руководство GUIDE.md. Вместо того чтобы пользователь вручную распаковывал и читал их, модель превращает их в интерактивные карточки двумя вызовами:

{ "path": "C:/Users/jane/Downloads/GUIDE.md" }

отправленный в create_markdown_card, отображает всё руководство как одну карточку: первый H1 становится заголовком, каждая секция H2 сворачивается в «показать/скрыть», таблицы получают стиль карточки, а каждый блок кода в кавычках получает кнопку копирования.

{
  "title": "Project source tour",
  "archivePath": "C:/Users/jane/Downloads/project.zip",
  "intro": "Read the guide card first, then follow these files in order."
}

отправленный в create_code_tour_card, распаковывает архив в памяти и отображает по одной вкладке на каждый текстовый файл, в порядке README, манифест, затем исходный код, каждый с пометкой языка и кнопкой копирования. Явные files сохраняют порядок, заданный вызывающим (README и манифесты поднимаются в начало), так что продуманный порядок обучения — модель данных, затем ошибки, затем точка входа — отображается как написано, а не в алфавитном порядке. Кэши сборки (target/, node_modules/) и двоичные записи пропускаются автоматически. Используйте unpack_archive или read_local_file сначала, когда модели нужно просмотреть содержимое, прежде чем решать, какие карточки создавать.

Когда документ или проект превышает бюджет размера карточки (по умолчанию около 32 000 символов разметки карточки, настраивается через MCP_CHAT_CARDS_CARD_BUDGET), инструмент разбивает его по естественным границам — секции H2 для документов, целые файлы для экскурсий — и возвращает часть 1 с инструкцией вида «вызовите create_code_tour_card снова с part: 2». Модель повторяет вызов, пока каждая часть не будет отображена как отдельная карточка, а слишком большие отдельные файлы обрезаются с видимым уведомлением.

Бюджет измеряется по стоимости файла после рендеринга, а не по его длине на диске: исходный код экранируется в HTML в панели вкладки, где один < становится четырьмя символами, поэтому несколько файлов, насыщенных разметкой, могут стоить гораздо больше, чем их сырой размер. Каждый готовый результат затем измеряется ещё раз относительно потолка хоста (около 40 000 символов сериализованного результата, настраивается через MCP_CHAT_CARDS_RESULT_LIMIT). Карточка, которая всё ещё слишком велика и не может разделиться сама — например, таблица с тысячами строк — возвращает действенную ошибку с указанием превышения, а не слишком большой результат, который хост молча отказался бы отображать.

Пример: зеркальная веб-форма

1. mirror_web_form с { "url": "https://example.com/newsletter" } отображает форму подписки страницы как карточку.

2. Пользователь заполняет её и отправляет; карточка возвращает структурированные данные в чат.

3. Модель проверяет значения с пользователем, затем вызывает submit_web_form с этими данными, чтобы отправить реальную форму, и сообщает HTTP-результат.

Как отображаются карточки

Сервер поддерживает два пути доставки, которые хост выбирает автоматически:

Встроенно в разговор (MCP Apps, SEP-1865). Сервер заранее объявляет один UI-шаблонный ресурс по адресу ui://mcp-chat-cards/card.html с MIME-типом text/html;profile=mcp-app, и каждый инструмент карточек ссылается на него через _meta.ui.resourceUri и объявляет схему вывода (хосты отбрасывают structuredContent у инструментов без схемы, оставляя карточке нечего рисовать). Хосты, поддерживающие расширение Apps (включая недавние сборки Claude Desktop), отображают шаблон встроенно в чат как песочный iframe, выполняют рукопожатие ui/initialize и доставляют ему результат инструмента. Шаблон защищается от частей, которые молча выходят из строя: он объявляет ui/notifications/initialized как по таймауту, так и по ответу на рукопожатие (хост удерживает результат инструмента, пока не увидит объявление), находит полезную нагрузку карточки глубоким поиском, а не по одному фиксированному вложению, сообщает ui/notifications/size-changed после каждой отрисовки и при изменении размера, чтобы iframe принимал свою реальную высоту, и принимает тему хоста (включая полную тёмную палитру). Взаимодействия с карточкой передаются обратно через JSON-RPC postMessage: отправки форм и действия контекстного меню становятся запросами ui/message (следующий промпт разговора), ссылки идут через ui/open-link, а телеметрия использует уведомления журналирования.

Автономный документ как запасной вариант. Для клиентов, не объявивших расширение Apps, каждый результат содержит ссылку на ui://mcp-chat-cards/html/<card-id>. Чтение этого ресурса возвращает ту же карточку в виде автономного HTML-документа (встроенные CSS и JS, строгая Content-Security-Policy, без внешних скриптов). Хосты без поддержки Apps, но с рендерингом в стиле MCP-UI, показывают этот документ в изолированной панели; там карточка отправляет сообщения в стиле MCP-UI (prompt, notify, link).

Документ намеренно не встраивается в результат инструмента. Его тема и среда выполнения байт-в-байт идентичны в каждой карточке, поэтому встраивание повторяло бы около 16 КБ шаблонного кода на каждый вызов: это вытесняло контекст вызывающей стороны и было основной причиной, по которой обычная карточка могла превысить лимит результата хоста и не отображаться вовсе. Установите MCP_CHAT_CARDS_EMBED_HTML=1, чтобы восстановить встроенную копию для хоста, который не может следовать по ссылке на ресурс. Сервер хранит последние 24 отрендеренные карточки для чтения.

Единая форма результата

Каждый инструмент карточки возвращает одни и те же три элемента, независимо от вида карточки:

Поверхность рендеринга

Карточки отображаются встроенно в боковой панели десктопного приложения Claude. Другие поверхности (мобильные и веб) получают текстовое резюме и структурированные данные, но не отрисовывают карточку, поэтому каждое резюме написано так, чтобы быть самостоятельным, а инструментам предписано также озвучивать вывод карточки в разговоре.

Текстовые поля — это обычный текст

Каждое текстовое поле, которое принимает инструмент — заголовки, метки, значения ячеек, подсказки репетитора — является обычным текстом и экранируется сервером ровно один раз. Вызывающие стороны не должны предварительно экранировать: передавайте Predict, Spot & Fix, а не Predict, Spot & Fix.

Входные данные никогда не декодируются предварительно, ни в одном поле. Вызывающий, который всё же передаёт &, получит карточку, отображающую шесть символов &, потому что именно это руководство, документирующее HTML, экранирование или шаблонизацию, хочет показать своему читателю. Правило одинаково везде, поэтому одна и та же строка отображается идентично в ячейке таблицы, вкладке, таблице Markdown и примере кода.

Сырой HTML учитывается только в полях с именем html (секции create_tab_card и create_reveal_card), где он санируется: скрипты, обработчики событий, фреймы, формы и опасные URL удаляются, а форматирование вроде <b> и <i> сохраняется. Во всех остальных местах — включая HTML, написанный внутри документа create_markdown_card — теги отображаются как буквальный текст, поэтому для форматирования там используйте синтаксис Markdown. Экранированный блочный HTML оборачивается в абзац, подразумеваемый структурой Markdown, а не вставляется между соседними элементами как свободный текст; HTML-комментарии удаляются, а не показываются, поскольку директива <!-- markdownlint-disable --> — это не проза.

Где разрешаются пути

create_markdown_card(path), create_code_tour_card(archivePath), read_local_file и unpack_archive разрешают пути в файловой системе машины, на которой работает этот сервер. Когда сервер доступен через удалённый мост, это не песочница вызывающей стороны: файл, сгенерированный моделью на её стороне, здесь не существует. В этом случае передавайте содержимое встроенно (markdown, files). Путь из чужой операционной системы — например, /home/demo-user/project.zip, отправленный на сервер под Windows, — отклоняется с ошибкой, указывающей на несоответствие, а не разрешается на диск, где его никогда не было; то же касается путей Windows, отправленных на POSIX-сервер, и неразвёрнутых путей ~/. Установите MCP_CHAT_CARDS_FS_ROOT, чтобы ограничить локальные чтения одним каталогом.

Заметки об интерактивности и ограничениях

• Перетаскивание упорядочивает блоки внутри одной карточки. Перетаскивание блока за пределы карточки переносит его HTML в данных перетаскивания; вставка в другой ответ требует поддержки хоста, которую десктопные чат-клиенты обычно пока не предоставляют.

• «Копировать карточку» копирует автономный HTML-документ, чтобы карточку можно было воспроизвести в другом ответе, файле или вкладке браузера.

• Подсказки репетитора появляются после наведения на отмеченный термин примерно на 1,2 секунды; карточка также уведомляет хост, чтобы модель могла продолжить, пока пользователь изучает. Каждый термин отмечается один раз на карточку (при пересечении двух выигрывает самый длинный), дубликаты в списке терминов игнорируются, а разметка никогда не происходит внутри примеров кода, нативных всплывающих подсказок или подсказки другого термина. Сопоставление чувствительно к регистру, поэтому подсказка, написанная для PATH, не прикрепляется к файловой системе path; установите caseInsensitive: true для термина, чтобы сопоставлять любой регистр. Передайте tutorTermsInCode: true в create_code_tour_card, чтобы включить код.

• Каждый результат карточки содержит structuredContent.parts как { current, total, hasMore }, поэтому одна проверка полноты работает для всех типов карточек. Пока hasMore истинно, часть содержимого скрыта, и вызывающий снова вызывает тот же инструмент с part: current + 1. Только create_markdown_card и create_code_tour_card могут разделяться; все остальные карточки всегда сообщают { current: 1, total: 1, hasMore: false }. Отрисованный заголовок сохраняет читаемый суффикс (part 1 of 2) для читателя.

• Порог разделения измеряется по отрисованным символам, а не по входным данным, которые пишет вызывающий. Экранирование непредсказуемо расширяет исходный текст — <, >, & и кавычки превращаются в четыре-шесть символов каждая — поэтому полезная нагрузка, которая выглядит значительно ниже бюджета, может его превысить, а более крупная на вид — нет. Читайте parts.hasMore, а не предсказывайте по размеру ввода. Документ Markdown без заголовков H2 не имеет границы разделения и всегда отображается одной частью.

• Контекстные действия по правому клику определяются моделью для каждой карточки; {{selection}} в промпте действия заменяется выделенным текстом пользователя.

Безопасность

• Инструменты локальных файлов (read_local_file, unpack_archive, а также входные пути/архивы для карточек документов и туров по коду) читают только текст, ограничивают размеры, отклоняют бинарные файлы и ограничивают извлечение архивов (количество записей, размер каждого файла и общий объём). Установите MCP_CHAT_CARDS_FS_ROOT, чтобы ограничить все локальные чтения одним каталогом.

• Исходящие запросы ограничены URL http(s), разрешающимися в публичные адреса. Localhost, RFC 1918, link-local, CGNAT и эквивалентные диапазоны IPv6 блокируются, перенаправления повторно проверяются, размеры тел ограничены, а запросы имеют тайм-аут. Устанавливайте MCP_CHAT_CARDS_ALLOW_PRIVATE=1 только если вам действительно нужны внутрисетевые запросы.

• Весь текст, предоставленный моделью и пользователем, экранируется в HTML; полученный сторонний HTML санируется (скрипты, обработчики событий, фреймы, формы и опасные URL удаляются).

• Карточки поставляются со строгой CSP и не загружают внешних скриптов, таблиц стилей или шрифтов.

• submit_web_form следует вызывать только со значениями, которые пользователь ввёл в зеркальной форме карточки или явно подтвердил.

Отладка карточек в Claude Desktop

Если карточка монтируется, но остаётся пустой, сбой обычно молчалив, поэтому шаблон записывает всё в консоль:

1. Включите режим разработчика в Claude Desktop (Настройки, Разработчик), затем откройте инструменты разработчика webview для разговора.

2. Отфильтруйте консоль по [mcp-chat-cards]. Каждое JSON-RPC-сообщение, которое карточка отправляет и получает, логируется с направлением (tx/rx), поэтому отсутствующий ответ на рукопожатие или недоставленный результат инструмента виден сразу.

3. Выполните window.__mccDebug() в этой консоли для снимка: версия шаблона, было ли объявлено initialized, отрисовалась ли карточка, отрендеренный HTML карточки и последние 50 сообщений протокола. Вставьте его вывод при сообщении о проблеме рендеринга.

Дополнительные порты

Папка extension/ содержит дополнительные порты инструментов карточек для других хостов. Оба автономны — они не импортируют из src/ или dist/, и MCP-сервер на них не влияет.

• extension/github/ — расширение GitHub Copilot canvas с именем chat-cards. Агент управляет теми же видами карточек (вкладки, таблицы, диаграммы, формы, показать/скрыть, последовательные списки, документы Markdown, видео) через действия canvas, а отправленные формы возвращаются в разговор как промпты. Его README описывает список действий, отличия от MCP-инструментов и то, как папка соотносится с макетом вклада awesome-copilot.

• extension/claude/ — шаблон артефакта Claude: одна автономная HTML-страница, чей блок спецификации карточки Claude заполняет и публикует как артефакт. Формы и действия по правому клику создают промпты, которые пользователь копирует обратно в разговор.

Разработка

npm run build      # compile TypeScript to dist/
npm test           # run the vitest suite (unit + in-memory MCP integration)
npm run coverage   # run tests with V8 coverage
npm run dev        # compile in watch mode

Лицензия

MIT. См. LICENSE.