Example MCP Server Python

OpenAI Apps SDK的MCP服务器

使用官方MCP SDK构建的模型上下文协议（MCP）服务器，旨在部署在Koyeb上并与OpenAI Apps SDK集成。

概述

此MCP服务器演示了如何通过Apps SDK创建可供OpenAI GPT模型使用的AI可访问工具和小部件。服务器作为HTTP服务运行，并通过流式HTTP传输公开MCP功能。

特性

资源

• UI小部件：在ChatGPT中显示待办事项列表的HTML界面(ui://widget/todo.html)

工具

• 全部添加：创建具有给定标题的新待办事项
• complete_todo：根据待办事项的ID将其标记为已完成

先决条件

• Node.js 20+
• Docker（用于容器化部署）
• A. 科耶布 账户
• OpenAI Apps SDK访问

地方发展

1. 克隆存储库

   git clone 
   cd example-mcp-server

1. 安装依赖项

   npm install

1. 运行服务器

   node server.js

服务器将于启动 http://0.0.0.0:8787 默认情况下（或生产中的端口8080）。

部署在Koyeb

选项1：从GitHub部署

1. 将代码推送到GitHub存储库
2. 首选 Koyeb仪表板
3. 点击“创建服务”
4. 选择“GitHub”作为部署方式
5. 选择您的存储库
6. Koyeb将自动检测Dockerfile并部署

选项2：使用Docker进行部署

# Build the Docker image
docker build -t mcp-server .

# Run locally to test
docker run -p 8080:8080 -e PORT=8080 mcp-server

环境变量

• PORT：服务器监听的端口（默认值：本地8787，生产环境8080）

与OpenAI Apps SDK集成

一旦部署到Koyeb上，您将收到一个公共URL。要将此MCP服务器与OpenAI Apps SDK一起使用：

1. 获取您的Koyeb部署URL （例如。， https://your-app.koyeb.app)

1. 重要：MCP终点位于 /mcp，因此您的完整URL将是：

   https://your-app.koyeb.app/mcp

1. 在OpenAI Apps SDK中配置:

- 将服务器URL添加到您的ChatGPT设置中 - 服务器将在MCP服务器列表中显示为“todo app”

1. OpenAI模型现在将能够：

- 将待办事项添加到列表中 - 将待办事项标记为已完成 - 显示一个显示所有待办事项的交互式小部件

项目结构

.
├── server.js            # MCP server implementation with Node.js
├── public/
│   └── todo-widget.html # Web component for ChatGPT UI
├── Dockerfile           # Container configuration for Node.js
├── package.json         # Node.js dependencies
└── README.md           # This file

运作原理

1. MCP-SDK 使用工具和UI资源创建MCP服务器
2. UI小部件 （HTML文件）被用作资源，并在ChatGPT的iframe中呈现
3. 流式HTTP服务器传输 在HTTP上公开MCP协议 /mcp 端点
4. Node.js HTTP服务器 为应用程序提供服务
5. OpenAI应用软件开发工具包 连接到服务器，显示UI，并使GPT模型可以使用工具
6. 当调用工具时，结果通过以下方式传递给小部件 window.openai.toolOutput

添加新工具

要添加新工具，请使用 server.registerTool():

server.registerTool(
  "tool_name",
  {
    title: "Tool Title",
    description: "Description of what your tool does",
    inputSchema: {
      param: z.string().min(1),
    },
    _meta: {
      "openai/outputTemplate": "ui://widget/your-widget.html",
      "openai/toolInvocation/invoking": "Running tool",
      "openai/toolInvocation/invoked": "Tool completed",
    },
  },
  async (args) => {
    // Your implementation here
    return {
      content: [{ type: "text", text: "Result message" }],
      structuredContent: { /* data for widget */ },
    };
  }
);

更新UI小部件

编辑 public/todo-widget.html 自定义工具结果在ChatGPT中的显示方式。小部件通过以下方式接收工具输出 window.openai.toolOutput 并且可以使用收听更新 openai:set_globals 活动。

故障排除

健康检查失败

• 确保服务器绑定到 0.0.0.0 （不是 127.0.0.1)
• 验证 PORT 环境变量设置正确

404错误

• 确保您正在连接到 /mcp 端点，而不仅仅是根URL
• 例子： https://your-app.koyeb.app/mcp （不是 https://your-app.koyeb.app/)

连接被拒绝

• 检查Koyeb部署是否正常
• 验证服务是否在正确的端口上侦听

小部件未更新

• 检查浏览器控制台是否有错误
• 核实一下 structuredContent 正在从工具处理程序返回
• 确保小部件正在读取 window.openai.toolOutput

资源

• 模型上下文协议SDK
• 模型上下文协议
• Koyeb文件
• OpenAI应用软件开发工具包

许可证

麻省理工学院