Fluduro | 一个 ChatGPT 应用项目

Fluduro 是一个简单的性格与花朵测验应用。该项目旨在通过直接在 ChatGPT 中创建交互式小部件，探索 OpenAI Apps SDK 和 模型上下文协议 (MCP)。

🛠️ 项目概览

这个项目的目标是学习如何：

1. 构建一个暴露工具和 UI 资源的 MCP 服务器。

2. 使用 OpenAI Apps SDK 在 ChatGPT 中渲染自定义 HTML/CSS 小部件。

3. 使用 ngrok 将本地服务器连接到 ChatGPT。

4. 使用 LLM（Groq）动态生成测验问题。

工具与资源：

• 工具：say_hello, start, submit_answers, show_results, get_quiz_state。

• UI 小部件：欢迎、测验和结果界面。

Related MCP server: Hello Widget Example

📸 视觉展示

![Welcome Screen (Light Mode)](./screenshots/welcome-light.png)
<!-- slide -->
![Welcome Screen (Dark Mode)](screenshots/welcome-dark.png)
<!-- slide -->
![Quiz Screen](screenshots/quiz.png)
<!-- slide -->
![Results Screen](screenshots/result.png)

⚡ 本地设置

1. 安装

克隆仓库并安装依赖：

git clone <repository-url>
cd plantora
npm install

2. 配置

为你的 API 密钥创建一个 .env 文件：

cp .env.example .env

将你的 Groq API 密钥添加到 API_KEY 字段。你可以在 console.groq.com 免费获取一个。

3. 运行与隧道

以 HTTP 模式启动服务器，并使用 ngrok 创建一个公共 HTTPS 隧道（ChatGPT 要求）：

# Terminal 1: Start the server
npm run start:http

# Terminal 2: Start ngrok on the same port
ngrok http 3553

记下 ngrok 提供的公共 URL（例如 https://xyz.ngrok-free.dev）。

🔗 如何连接到 ChatGPT

要在 ChatGPT 中测试此应用，请按照以下步骤操作：

1. 在 ChatGPT 中启用开发者模式（设置 → 应用与连接器 → 高级设置）。

2. 在设置 → 连接器中，点击创建。

3. 选择 Streamable HTTP，并粘贴带有 /mcp 路径的 ngrok URL： https://your-id.ngrok-free.dev/mcp

4. 将其命名为“Fluduro”，然后点击创建。

5. 将连接器添加到新聊天，然后输入 “开始测验。”

🤖 技术栈

• 后端：Node.js 与 @modelcontextprotocol/sdk。

• LLM：Groq (Llama 3.3 70B) 用于生成问题和分析性格特征。

• 前端：原生 HTML/CSS，搭配 Tailwind CSS (CDN) 和 Google Fonts。

• 隧道：ngrok。

📖 从 SDK 中学到的关键经验

• window.openai 桥接：学习了如何在小部件 iframe 与宿主之间进行通信。

• 主题同步：使用 openai:set_globals 让 UI 适配 ChatGPT 的深色/浅色模式。

• 工具驱动 UI：学习了如何利用 structuredContent 从模型的工具输出触发 UI 更改。

结论

这个项目是构建 ChatGPT 生态系统中具有原生体验的应用的一次动手实践入门。它重点介绍了 OpenAI Apps 框架中工具注册、资源处理和状态管理的基础知识。

📸 视觉展示 - 参考截图

欢迎界面 - 浅色模式

欢迎界面 - 深色模式

测验界面

结果界面