Beautiful MCP

应用程序SDK示例画廊


此仓库展示了与Apps SDK一起使用的示例UI组件，以及作为工具集暴露一系列组件的示例MCP服务器。 它旨在作为起点和灵感来源，帮助你构建自己的ChatGPT应用程序。

MCP + 应用程序SDK概览

模型上下文协议（MCP）是一种开放规范，用于将大型语言模型客户端连接到外部工具、数据和用户界面。MCP服务器会暴露模型在对话过程中可以调用的工具，并根据工具合约返回结果。这些结果可以包含额外的元数据（如内联HTML），Apps SDK会利用这些元数据来渲染丰富的用户界面组件（小部件），并将其与助手消息一同显示。

在应用程序开发工具包（Apps SDK）中，MCP（可能指某种中间件或通信协议组件）负责保持服务器、模型和用户界面（UI）的同步。通过标准化数据传输格式、认证和元数据，它使ChatGPT能够以与处理内置工具相同的方式处理您的连接器。一个针对Apps SDK的最小化MCP集成实现了以下三项功能：

1. 列出工具 – 您的服务器会公布其支持的工具，包括这些工具的JSON Schema输入/输出协议以及可选的注解（例如， readOnlyHint）。
2. 呼叫工具 – 当模型选择一个工具时，它会发出一个 call_tool 请求中包含与用户意图相匹配的参数。您的服务器执行该操作，并返回模型可以解析的结构化内容。
3. 返回小部件 – 除了结构化内容外，请在响应元数据中返回嵌入的资源，以便Apps SDK能够在Apps SDK客户端（ChatGPT）中内联渲染界面。

因为该协议与传输方式无关，所以您可以使用服务器发送事件（Server-Sent Events）或流式HTTP来托管服务器——应用程序SDK支持这两种方式。

在这个演示中，MCP服务器展示了每种工具如何通过将结构化有效载荷与（某种方式）结合来点亮小部件 _meta.openai/outputTemplate 从MCP服务器返回的元数据。

仓库结构

• src/ – 每个小部件示例的来源。
• assets/ – 在运行构建步骤后生成HTML、JS和CSS包。
• pizzaz_server_node/ – 使用官方TypeScript SDK实现的MCP服务器。
• pizzaz_server_python/ – Python MCP 服务器，用于返回 Pizzaz 小部件。
• solar-system_server_python/ – 用于3D太阳系小部件的Python MCP服务器。
• build-all.mts – Vite 构建编排器，为每个小部件入口点生成哈希包。

先决条件

• Node.js 18及以上版本
• pnpm（推荐）或 npm/yarn
• Python 3.10+（用于Python MCP服务器）

安装依赖项

克隆仓库并安装工作区依赖项：

pnpm install

使用 npm 还是 yarn？使用你偏好的客户端安装根依赖项，并相应地调整下面的命令。

构建组件库

这些组件被打包成独立的资源，供MCP服务器作为可重用的用户界面资源来提供服务。

pnpm run build

这个命令运行 build-all.mts，生成带版本的 .html， .js，和 .css 内部文件 assets/每个小部件都封装了其所需的CSS，因此您可以直接托管这些包，或者通过您自己的服务器进行分发。

要在本地迭代你的组件，你也可以启动 Vite 开发服务器：

pnpm run dev

提供静态资源

如果您想在不使用MCP服务器的情况下预览生成的包，请在运行构建后启动静态文件服务器：

pnpm run serve

这些资产面临的风险在于 http://localhost:4444 启用CORS，以便本地工具（包括MCP检查器）能够获取它们。

运行MCP服务器

该仓库提供了几个演示MCP服务器，展示了不同的小部件包：

• Pizzaz（Node.js与Python） – 受披萨启发的工具和组件集合
• 太阳系（Python） – 3D太阳系查看器

每个工具响应都包含纯文本内容、结构化的JSON，以及 _meta.openai/outputTemplate 元数据，以便应用程序软件开发工具包（SDK）可以填充匹配的小部件。

Pizzaz节点服务器

cd pizzaz_server_node
pnpm start

Pizzaz Python 服务器

python -m venv .venv
source .venv/bin/activate
pip install -r pizzaz_server_python/requirements.txt
uvicorn pizzaz_server_python.main:app --port 8000

太阳能系统Python服务器

python -m venv .venv
source .venv/bin/activate
pip install -r solar-system_server_python/requirements.txt
uvicorn solar-system_server_python.main:app --port 8000

你可以为所有Python服务器重用同一个虚拟环境——只需安装一次依赖项，然后运行所需的任意入口点。

在ChatGPT中进行测试

要在ChatGPT中添加这些应用，请启用 开发者模式并在设置中>连接器处添加您的应用程序。

要在不部署本地服务器的情况下将其添加进来，您可以使用类似这样的工具： ngrok 将您的本地服务器暴露给互联网。

例如，一旦您的MCP服务器运行起来，您可以执行：

ngrok http 8000

您将获得一个公共URL，可以在设置 > 连接器中使用它来将您的本地服务器添加到ChatGPT。

例如： https://.ngrok-free.app/mcp

一旦你添加了连接器，就可以在ChatGPT对话中使用它。

您可以通过在“更多”选项中选择您的应用，将其添加到对话上下文中。

然后，你可以通过提出相关问题来调用工具。例如，对于Pizzaz应用，你可以问：“镇上最好的披萨是什么？”。

下一步

• 自定义小部件数据：编辑其中的处理程序 pizzaz_server_node/src， pizzaz_server_python/main.py或者让太阳系服务器从您的系统中获取数据。
• 创建你自己的组件并将其添加到画廊中：将新条目拖入 src/ 它们将被构建脚本自动拾取。

部署您的MCP服务器

您可以选择您偏好的云环境来部署您的MCP服务器。

将此包含在环境变量中：

BASE_URL=https://your-server.com

这将用于生成小部件的HTML代码，以便它们能够从这个托管URL提供静态资源。

贡献

欢迎提出问题或提交拉取请求来改进这款应用，但请注意，我们可能无法审查所有建议。

许可证

这个项目遵循MIT许可证授权。详见 许可证 详情请见。