构建你的第一个 ChatGPT 应用 | 使用 Apps SDK 的逐步教程

引言

当 AI 成为日常工作流程的核心，ChatGPT 已成为数十亿用户的自然工具。然而直到现在，ChatGPT 的重点主要是"对话"，而不是"交互"。

如果你能在 ChatGPT 内直接与应用互动------比如预订酒店、设计演示文稿------全部在同一个界面中完成，会怎样？

这正是 ChatGPT Apps 带来的能力。

借助全新的 Apps SDK，开发者现在可以构建运行在 ChatGPT 内部的交互式、具备上下文能力的应用。

在本指南中，你将学习如何构建属于你的 ChatGPT 应用。我将带你走过每一步代码，并解释其工作原理。

完成后，你将拥有一个可在 ChatGPT 环境中动态展示组件（widgets）的可运行应用。

---

第 0 步：ChatGPT 应用如何工作？

一个 ChatGPT 应用，本质上就是一个提供 widget 的 MCP 服务器。

ChatGPT 应用的工作流程

如上图所示，流程从 ChatGPT 根据用户消息触发应用开始。用户的消息会被发送到应用。

应用随后会选择最匹配用户意图的 MCP 工具。例如，当用户提出"我想买衣服"，应用可能会选择名为 ShowClothes 的工具。

工具会返回 widget 与数据：

• widget：显示在 ChatGPT 内的组件
• data：ChatGPT 可使用的结构化响应

---

第 1 步：安装 FastApps

了解 ChatGPT 应用如何工作后，我们将开始实践。

我们会使用 FastApps ------ 一个开源框架，用于构建 ChatGPT 应用。

首先使用 uv 安装 FastApps：

uv tool install fastapps
uv tool install --upgrade fastapps   # 更新到最新版本

---

第 2 步：初始化新应用

安装后，运行以下命令快速开始：

fastapps init my-app
cd my-app
fastapps dev

你会看到一个通过 Cloudflare Tunnel 自动生成的公共 URL。

你的 MCP 服务器将暴露在 /mcp 路径下。

示例：

https://your-public-url.trycloudflare.com/mcp

---

第 3 步：测试你的应用

方案 A：使用 MCPJam Inspector 测试

连接并测试你的服务器：

npx @mcpjam/inspector@latest

然后输入你的公共 URL + /mcp。

---

方案 B：在 ChatGPT 内测试

1. 打开 ChatGPT → 设置 → Connectors
2. 添加公共 URL + /mcp
3. 选择「No authentication」

---

第 4 步：创建更多 Widgets

你可以随时新增组件：

fastapps create additional-widget

---

第 5 步：编辑你的 Widget

你只需要修改两个目录：

1️⃣ server/tools/ --- MCP 工具

定义应用的逻辑与交互结构。

示例：

# server/tools/my_widget_tool.py
from fastapps import BaseWidget, Field, ConfigDict
from pydantic import BaseModel
from typing import Dict, Any

class MyWidgetInput(BaseModel):
    model_config = ConfigDict(populate_by_name=True)
    name: str = Field(default="World")

class MyWidgetTool(BaseWidget):
    identifier = "my-widget"
    title = "My Widget"
    input_schema = MyWidgetInput
    invoking = "Processing..."
    invoked = "Done!"

    widget_csp = {
        "connect_domains": [],
        "resource_domains": []
    }

    async def execute(self, input_data: MyWidgetInput) -> Dict[str, Any]:
        return {
            "name": input_data.name,
            "message": f"Hello, {input_data.name}!"
        }

每个 MCP 工具都包含定义其特性的属性。可通过下方表格了解其含义。

如需更多细节，请参考 FastApps 文档。

必需类属性

属性	类型	描述	示例
identifier	str	唯一 widget 标识，必须与 widgets/ 目录下文件夹同名	"greeting"
title	str	在 ChatGPT 界面展示的人类可读名称	"Show Greeting Widget"
input_schema	Type[BaseModel]	输入参数定义，ChatGPT 通过 JSON schema 判断如何调用工具	GreetingInput
invoking	str	调用执行时显示的提示	"Preparing your greeting..."
invoked	str	执行结束时显示的提示	"Greeting ready!"

可选属性

属性	类型	描述	示例
description	str	说明工具用途，便于模型判断何时调用	"Display a personalized greeting widget"
widget_accessible	bool	组件是否可从前端触发工具	True

---

2️⃣ widgets/ --- 前端 UI（React）

该目录包含在 ChatGPT 显示的 UI 组件。

示例：

// widgets/my-widget/index.jsx
import React from 'react';
import { useWidgetProps } from 'fastapps';

export default function MyWidget() {
  const props = useWidgetProps();

  return (
    <div style={{
      padding: '40px',
      textAlign: 'center',
      background: '#4A90E2',
      color: 'white',
      borderRadius: '12px'
    }}>
      <h1>{props.message}</h1>
      <p>Welcome, {props.name}!</p>
    </div>
  );
}

Widgets 是 React 组件，并可通过特殊 hooks 与 ChatGPT 交互。

如需更多细节，请参考 FastApps 文档。

---

第 6 步：部署你的 ChatGPT 应用

你可以直接通过 CLI 部署：

fastapps cloud deploy

按照 CLI 指引逐步操作即可。

---

结语

在本教程中，你学习了如何使用 FastApps 框架创建 ChatGPT 应用。

你已搭建了应用核心------MCP 服务器，创建了 widgets 和工具，并通过 CLI 将其部署公开。

若想进一步了解部署方法，可参考这篇指南。

这一结构非常简单却功能强大。

只需少量代码，你就能构建一个可供所有人使用的完整 ChatGPT 应用。