MCP Joke Button App

这个项目是一个微型 MCP 服务器，它暴露一个 MCP App UI：一个按钮。当按钮被点击时，应用会向宿主发送一条消息，要求助手用一个简短的、适合家庭的笑话作答。

它特意只使用 Node.js 内置模块。没有任何运行时包依赖。

它演示了什么

• MCP 核心协议版本 2026-07-28

• 在单个端点 /mcp 上的无状态 Streamable HTTP

• server/discover、tools/list、tools/call、resources/list 和 resources/read

• 带有 _meta.ui.resourceUri 的 MCP Apps UI 资源元数据

• 一个沙箱友好的 text/html;profile=mcp-app 小部件

• 通过 postMessage 的 ui/initialize 和 ui/message

Related MCP server: Jokes MCP Server

要求

从 nodejs.org 安装 Node.js 20 或更高版本。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 部署

joke-button Heroku 应用部署在：

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）中渲染时，它才能向 AI 请求笑话。

与 ChatGPT Desktop 或 ChatGPT Web 一起使用

在开发期间，ChatGPT 需要一个远程 MCP 服务器的 HTTPS URL。保持 npm start 运行，然后使用隧道工具（如 ngrok 或 Cloudflare Tunnel）暴露端口 8787。

使用 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. 粘贴以 /mcp 结尾的 HTTPS URL。

8. 将其命名为 Joke Button。

9. 开始一个新聊天，从“更多”菜单中选择该插件，并询问：Show the joke button.

10. 点击 Tell a joke。

对于这个 ChatGPT UI 测试，你不需要名为 MCP servers 的设置。该设置用于 Codex 的本地 MCP 宿主配置，而不是用于添加 ChatGPT 开发者插件连接。

如果开发者模式或加号按钮缺失，请检查桌面应用是否是最新版本，以及你的账户或工作区是否允许插件开发。

如果应用正常工作，ChatGPT 应该会收到按钮的消息，并用一个简短的笑话回应。

在 ChatGPT Desktop 应用中使用 Codex

Codex 可以从共享的 MCP 设置连接到 Streamable HTTP MCP 服务器。

MCP servers 设置仅出现在支持 Codex 的本地客户端上，可能不会出现在常规的 ChatGPT 聊天设置视图中。如果它可用：

1. 保持 npm start 运行。

2. 打开 ChatGPT 桌面应用。

3. 打开设置，然后选择 MCP servers。

4. 选择“添加服务器”。

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.

根据界面的不同，Codex 的 MCP 工具支持可能会显示文本回退，而不是渲染 iframe UI。要获得实际的单按钮 UI，请使用支持 MCP Apps UI 的 ChatGPT。

如果该设置不可见，请将 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

安全说明

服务器会验证 2026-07-28 Streamable HTTP 传输所需的 MCP 协议版本和镜像 MCP 头。

对于本地开发，接受没有 Origin 头的请求，接受回环浏览器来源，也接受常见的 OpenAI 宿主来源。对于其他宿主来源，请使用以下命令启动服务器：

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

在暴露一个可以访问私有数据或执行操作的真实 MCP 服务器之前，请使用身份验证。此示例两者都不涉及。

项目文件

• server.js：无依赖的 MCP 服务器

• public/joke-button.html：MCP App UI 小部件

• codex-config.example.toml：示例 Codex MCP 配置