Приложение MCP Joke Button

Этот проект — крошечный MCP-сервер, который предоставляет один UI-элемент MCP App: единственную кнопку. При нажатии на кнопку приложение отправляет сообщение хосту с просьбой к ассистенту ответить одной короткой семейной шуткой.

В нём намеренно используются только встроенные модули Node.js. Зависимостей от сторонних пакетов во время выполнения нет.

Что он демонстрирует

• Версию основного протокола MCP 2026-07-28

• Stateless Streamable HTTP на одной конечной точке: /mcp

• server/discover, tools/list, tools/call, resources/list и resources/read

• Метаданные ресурсов UI MCP Apps с _meta.ui.resourceUri

• Виджет text/html;profile=mcp-app, совместимый с песочницей

• ui/initialize и ui/message через postMessage

Related MCP server: Jokes MCP Server

Требования

Установите Node.js версии 20 или новее с nodejs.org. Подойдёт и LTS-версия.

Вам не нужно запускать npm install; в этом проекте нет сторонних библиотек.

Запуск сервера

Откройте терминал в этой папке и выполните:

npm start

Вы должны увидеть:

MCP Joke Button server listening on http://127.0.0.1:8787/mcp
Preview the widget shell at http://127.0.0.1:8787/preview

Оставьте этот терминал открытым, пока тестируете.

Пока сервер работает, MCP-запросы логируются по методам. Для интерактивного рендеринга приложения в логе должно быть успешное чтение ресурса UI, примерно такое:

[mcp] request method=resources/read name=ui://joke-button/app.html
[mcp] response method=resources/read status=200

Установите MCP_LOG_REQUESTS=false, если хотите отключить эти журналы разработки.

Развёртывание на Heroku

Приложение Heroku joke-button развёрнуто по адресу:

https://joke-button-31cddc4bc964.herokuapp.com

Его MCP-конечная точка:

https://joke-button-31cddc4bc964.herokuapp.com/mcp

Разверните текущую ветку командой:

git push heroku HEAD:main

Быстрая локальная проверка

Откройте этот адрес в браузере:

http://127.0.0.1:8787/preview

Здесь только предпросмотр внешнего вида кнопки. Кнопка может попросить ИИ рассказать шутку только тогда, когда она отображается внутри хоста, совместимого с MCP Apps, например ChatGPT.

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

Во время разработки ChatGPT требуется HTTPS-URL для удалённого MCP-сервера. Держите npm start запущенным, затем откройте порт 8787 с помощью туннельного инструмента, такого как ngrok или Cloudflare Tunnel.

Пример с ngrok:

ngrok http 8787

Скопируйте HTTPS-URL пересылки и добавьте в конец /mcp, например:

https://example.ngrok.app/mcp

Затем подключите его в ChatGPT:

1. Откройте ChatGPT.

2. Откройте «Настройки».

3. Откройте «Безопасность и вход».

4. Включите режим разработчика, если он ещё не включён.

5. Откройте «Плагины». Если вы в десктопном приложении и не видите его в боковой панели, откройте https://chatgpt.com/plugins в браузере, войдя в ту же учётную запись.

6. Нажмите кнопку «плюс», чтобы добавить подключение к MCP-серверу разработчика.

7. Вставьте HTTPS-URL, оканчивающийся на /mcp.

8. Назовите его Joke Button.

9. Начните новый чат, выберите плагин в меню «Ещё» и спросите: Show the joke button.

10. Нажмите Tell a joke.

Для этого теста UI в ChatGPT вам не нужна настройка MCP servers. Эта настройка предназначена для локальной конфигурации MCP-хоста Codex, а не для добавления подключения плагина разработчика ChatGPT.

Если режим разработчика или кнопка «плюс» отсутствуют, проверьте, что десктопное приложение обновлено и что ваша учётная запись или рабочее пространство разрешает разработку плагинов.

Если приложение работает, ChatGPT должен получить сообщение от кнопки и ответить короткой шуткой.

Использование с Codex в десктопном приложении ChatGPT

Codex может подключаться к Streamable HTTP MCP-серверам из общих настроек MCP.

Настройка MCP servers появляется только в локальных клиентах с поддержкой Codex и может не отображаться в обычном представлении настроек чата ChatGPT. Если она доступна:

1. Держите npm start запущенным.

2. Откройте десктопное приложение ChatGPT.

3. Откройте «Настройки», затем «MCP servers».

4. Выберите «Add server».

5. Выберите «Streamable HTTP».

6. Назовите сервер joke_button.

7. Используйте этот URL:

http://127.0.0.1:8787/mcp

8. Сохраните, затем перезапустите, когда будет предложено.

9. В задаче Codex введите /mcp, чтобы убедиться, что сервер подключён.

10. Спросите Codex: Use the Joke Button MCP server.

Поддержка инструментов MCP в Codex может показывать текстовый запасной вариант вместо рендеринга iframe-интерфейса, в зависимости от поверхности. Для фактического интерфейса с одной кнопкой используйте ChatGPT с поддержкой UI MCP Apps.

Если настройка не видна, скопируйте пример конфигурации из codex-config.example.toml в .codex/config.toml доверенного проекта или в ваш пользовательский ~/.codex/config.toml, затем перезапустите десктопное приложение ChatGPT или клиент Codex.

Полезные URL

• Проверка работоспособности: http://127.0.0.1:8787/health

• MCP-конечная точка: http://127.0.0.1:8787/mcp

• Предпросмотр виджета: http://127.0.0.1:8787/preview

Замечания по безопасности

Сервер проверяет версию протокола MCP и зеркальные MCP-заголовки, требуемые транспортом Streamable HTTP версии 2026-07-28.

Для локальной разработки принимаются запросы без заголовка Origin, принимаются источники браузера с loopback-адреса, а также распространённые источники хостов OpenAI. Для другого источника хоста запустите сервер с:

$env:MCP_ALLOWED_ORIGINS="https://your-host.example"
npm start

Используйте аутентификацию перед тем, как открывать доступ к реальному MCP-серверу, который может обращаться к приватным данным или выполнять действия. Этот пример не делает ни того, ни другого.

Файлы проекта

• server.js: MCP-сервер без зависимостей

• public/joke-button.html: виджет UI MCP App

• codex-config.example.toml: пример конфигурации MCP для Codex