电影上下文提供者

Name: 电影上下文提供者
Author: render-examples

作者：render-examples6 星标更新：2025-10-17

安装使用来源：spider==github.com

项目介绍

MCP: 电影内容提供者

这是一个使用**OpenAI 应用程序 SDK构建的演示应用程序，可以部署到Render**。

管理你的个人电影观看清单，获取由人工智能驱动的推荐，并在 ChatGPT 中直接与漂亮的插件进行交互。电影数据由**TMDB**提供。支持多提供商的大规模语言模型（LLM）和 PostgreSQL 数据持久化。

这是什么？

这个演示实现了一个带有观看清单、评分和人工智能推荐的电影发现应用——完全集成到 ChatGPT 中。

https://github.com/user-attachments/assets/82e33bd5-8a5e-4f03-b8df-44c352dc1ded

你会学到什么：

创建交互式插件
实现MCP 工具
零配置部署
集成多个 LLM 提供商（OpenAI、Anthropic、Google）

分叉此仓库以构建你自己的 MCP 功能的 OpenAI 应用。自定义它，从中学到知识，并将其部署到 Render。

功能

MCP 工具

搜索与发现

search_movies - 根据标题搜索一个或多个电影
discover_movies - 高级过滤（导演、演员、类型、年份、评分）
get_movie_details - 包含演员阵容、评分和海报插件的完整详情

观看清单管理

add_to_watchlist, remove_from_watchlist, get_watchlist

观看历史

mark_as_watched, mark_as_watched_batch, get_watched_movies

偏好设置

set_preferences, get_preferences, remove_preference_item

AI 功能（需要 LLM API 密钥）

get_recommendations - 基于观看历史和偏好的个性化电影建议

所有工具都在 backend/src/tools/ 中实现。

注意： 只有 get_recommendations 工具需要 LLM API 密钥。其他所有功能只需 TMDB API 密钥即可工作。

插件

在 ChatGPT 中渲染的交互式用户界面组件：

电影海报 - 包含演员阵容、背景图和快速操作（添加到观看清单、标记为已观看）的完整详情视图
电影列表 - 搜索结果和观看清单的可排序网格，具有内联操作
偏好设置 - 可视化编辑器，用于最喜欢的类型、演员和导演（帮助 AI 推荐）

多提供商 AI

推荐支持 OpenAI（GPT-5）、Anthropic（Claude Sonnet 4.5）或 Gemini（2.5 Flash）。基于可用 API 密钥自动检测。

性能与缓存

内置 Valkey 缓存以优化性能：

TMDB API 调用 - 人物搜索（7天）和电影详情（30天）
用户偏好设置 - 更新时自动失效，缓存5分钟
结果：缓存数据的响应时间小于毫秒，而 API 调用则为 200-300 毫秒

Valkey 在 Render 上自动配置，感谢我们的蓝图设置。无需额外配置。

开始

快速开始：部署到 Render

此应用设计为零配置部署到 Render。包含的 render.yaml 蓝图会自动配置所需的一切。

先决条件

准备好你的 API 密钥（部署期间添加）：

TMDB API 密钥（必需，免费）：
1. 在 themoviedb.org 注册账户
2. 前往设置 → API
3. 请求一个 API 密钥（选择“开发者”用于个人用途）
4. 复制你的“API 密钥（v3 认证）” - 这就是你要使用的密钥
LLM API 密钥（可选，仅用于推荐工具）：
- OpenAI API 密钥（付费） - 用于 GPT-5
- Anthropic API 密钥（付费） - 用于 Claude Sonnet 4.5
- Google Gemini API 密钥（提供免费层级） - 用于 Gemini 2.5 Flash
- 如果跳过此步骤，所有功能均可工作，除了 get_recommendations

三步部署

1. 分叉此仓库

点击页面右上角的“分叉”按钮以创建你自己的副本。

2. 在 Render 上创建一个新的蓝图

前往 Render 控制台
点击新建 → 蓝图
连接你的 GitHub 账户并选择你分叉的仓库
Render 将自动检测 render.yaml 文件

3. 将你的 API 密钥作为环境变量添加

当提示时，添加这些秘密环境变量：

变量	必需？	描述
`TMDB_API_KEY`	✅ 必需	你的 TMDB API 密钥（用于所有电影数据）
`OPENAI_API_KEY`	🤖 可选*	OpenAI API 密钥（GPT-5 用于推荐）
`ANTHROPIC_API_KEY`	🤖 可选*	Anthropic API 密钥（Claude Sonnet 4.5 用于推荐）
`GEMINI_API_KEY`	🤖 可选*	Google Gemini API 密钥（2.5 Flash 用于推荐）
`ADMIN_API_KEY`	✨ 推荐	你个人的 MCP 访问密钥（未设置时自动生成）
`ADMIN_EMAIL`	可选	管理员用户邮箱（默认为 `admin@localhost`）

*至少需要一个 LLM API 密钥，如果你想使用 get_recommendations 工具。其他所有功能（搜索、观看清单、偏好设置等）无需任何 LLM 即可工作。

免费层级注意事项： 提供的 Render 蓝图预配置为每个服务运行在免费计划下（托管的 Postgres 实例在前 30 天是免费的）。免费服务在闲置时会停止，因此长时间暂停后的第一个请求可能会很慢或偶尔超时。一旦实例激活，一切都会正常运行。如果你想要生产级别的响应速度，请将服务提升到 Starter 或 Standard 计划。

点击应用，Render 将：

✅ 配置 PostgreSQL 数据库
✅ 配置 Valkey 缓存（用于性能）
✅ 部署后端 Node.js 服务
✅ 部署前端插件静态站点
✅ 自动运行数据库迁移
✅ 将所有内容连接在一起
✅ 分配 HTTPS 域名

就这样！ 大约 5 分钟后，你的应用将在以下地址上线：

后端 MCP 服务器：https://your-app-name.onrender.com
插件 UI：https://your-app-name-widgets.onrender.com

创建一个 OpenAI 应用

https://github.com/user-attachments/assets/bacc934b-670b-48ac-89bd-4acaf2d6889d

创建一个 OpenAI 应用来在 ChatGPT 中使用你的 MCP 服务器：

第一步：找到你的 API 密钥

你需要 API 密钥来连接。通过以下方式找到它：

查看你的 Render 部署日志（首次部署后显示） - 查找类似以下的行：

连接 URL: https://your-app-name.onrender.com/mcp/messages
API 密钥（Bearer 令牌）: moviemcp_xxxxx...
OpenAI 应用 MCP URL: https://your-app-name.onrender.com/mcp/messages?api_key=moviemcp_xxxxx...

复制 OpenAI 应用 MCP URL，你将在第 3 步中使用它

第二步：启用开发者模式（仅第一次）

打开 ChatGPT 并前往设置（左下角的齿轮图标）
导航至 应用和连接器
向下滚动并点击 高级设置
启用 开发者模式

第三步：创建你的 OpenAI 应用

回到 应用和连接器
点击创建（或 新连接器）
填写连接器详细信息：
- 名称：电影内容提供者（或你喜欢的任何名称）
- 描述（可选）：简要描述其功能
- MCP 服务器 URL：粘贴你在第一步中从服务器日志复制的 OpenAI 应用 MCP URL 值。它应该看起来像这样 https://your-app-name.onrender.com/mcp/messages?api_key=your_API_key_here
- 身份验证：选择无认证
- 勾选 “我信任此应用程序”（自定义连接器所需）
点击创建

ChatGPT 将测试连接并添加 MCP 服务器。

第四步：在聊天中启用应用

重要：直到你在 ChatGPT 对话中启用该应用，它才有效。

在 chatgpt.com 打开 ChatGPT
点击左下角消息输入旁边的 + 按钮
从列表中选择你的 电影内容提供者 应用
开始聊天："搜索 Inception" 或 "显示我的观看清单"

替代方案：其他 MCP 客户端（无插件）

你也可以使用其他兼容 MCP 的客户端，如 Claude Desktop 或 Cursor。添加以下配置：

其他 MCP 客户端 添加到你的 MCP 配置：

{
  "mcpServers": {
    "movies": {
      "url": "https://your-app-name.onrender.com/mcp/messages",
      "headers": {
        "Authorization": "Bearer YOUR_ADMIN_API_KEY"
      },
      "transport": "streamableHttp"
    }
  }
}

注意：只有 ChatGPT 支持 OpenAI 插件，其他 MCP 客户端响应的是基于文本的回复而不是交互式 UI 组件。

插件如何工作

插件在 ChatGPT 内部提供交互式 UI 组件：

后端返回结构化数据 + 插件元数据在 _meta 字段中
ChatGPT 渲染插件（例如，ui://widget/movie-poster）
插件通过 window.openai.callTool() 调用工具进行交互
状态更新自动进行，无需刷新页面

可用插件：

movie-poster - 包含操作的详细电影视图
movie-list - 可排序/筛选的电影网格
preferences - 管理最喜欢的类型、演员和导演

查看 frontend/src/widgets/ 获取实现细节。

多提供商 LLM（可选）

AI 推荐支持三个提供商（优先级：OpenAI → Anthropic → Gemini）：

提供商	模型	备注
OpenAI	GPT-5	最新的推理模型
Anthropic	Claude Sonnet 4.5	最佳的速度/智能平衡
Gemini	Gemini 2.5 Flash	最佳的价格/性能，提供免费层级

设置任意一个 API 密钥即可启用 get_recommendations 工具。模型固定且根据可用密钥自动检测。

认证与用户管理

演示认证说明
本项目使用简单的 API 密钥认证作为演示目的的捷径。每个 API 密钥既作为认证又作为用户标识，使得支持多个用户变得简单，无需复杂的 OAuth 流程。

对于生产应用，考虑实现 OAuth 2.0，这提供了：

安全的用户同意流程

令牌过期和刷新

不更改密码即可撤销访问

行业标准的安全实践

这里的 API 密钥方法故意简化，专注于展示MCP 和 OpenAI 应用 SDK 概念，而非最佳认证实践。

自动管理员用户设置

好消息！ 如果你在部署时设置了 ADMIN_API_KEY，管理员用户会在数据库迁移过程中自动创建。你可以立即使用你的管理员密钥连接：

# 你的 ADMIN_API_KEY 有两个作用：
# 1. 保护 /admin 端点
# 2. 你的个人 MCP API 密钥

# 部署后立即连接
https://movie-mcp-server.onrender.com/mcp/messages?api_key=YOUR_ADMIN_API_KEY

创建附加用户

使用管理员端点为其他人创建用户：

curl -X POST https://movie-mcp-server.onrender.com/admin/create-user \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

响应：

{
  "success": true,
  "user": {
    "id": 2,
    "email": "user@example.com",
    "apiKey": "moviemcp_abc123_def456..."
  },
  "message": "用户创建成功。安全保存此 API 密钥！"
}

💡 每个用户都有一个唯一的 API 密钥，用于隔离观看清单和偏好设置

使用你的 API 密钥

使用你的 API 密钥连接到 MCP 服务器：

# 通过查询参数
https://movie-mcp-server.onrender.com/mcp/messages?api_key=YOUR_API_KEY

# 通过授权头
curl https://movie-mcp-server.onrender.com/mcp/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

管理员端点

受 ADMIN_API_KEY 环境变量保护：

POST /admin/create-user - 创建具有自动生成 API 密钥的新用户
GET /admin/users - 列出所有用户（不显示 API 密钥）
GET /admin/health - 检查管理员端点状态

替代方案：手动 SQL

你也可以直接通过 SQL 创建用户：

INSERT INTO users (email, api_key)
VALUES ('user@example.com', 'moviemcp_' || floor(random() * 1000000000)::text || '_' || md5(random()::text));

生产建议：

迁移到 OAuth 2.0

应用使用示例

在 ChatGPT 中

用户：搜索 2010 年的科幻电影
→ 显示包含 Inception、Tron Legacy 等电影的电影列表插件

用户：告诉我关于 Inception
→ 显示包含完整详情的电影海报插件

用户：把它添加到我的观看清单
→ 确认添加，更新插件状态

用户：标记 Inception 为已观看，5 星
→ 保存评分，从观看清单中移除

用户：显示我的观看清单
→ 在列表插件中显示观看清单（可排序、可筛选）

用户：给我推荐一些适合安静夜晚的电影
→ AI 分析你的品味，显示个性化的推荐

高级查询

"查找高评分的克里斯托弗·诺兰电影"
"显示 90 年代受欢迎的动作电影"
"给我列出我没有观看过的汤姆·汉克斯电影"
"推荐类似于《降临》的发人深省的科幻电影"
"我的观看清单里有什么？"
"显示我评分最高的电影"

本地开发（可选）

想在部署前进行开发或测试吗？以下是方法：

先决条件

Node.js 20+
PostgreSQL 15+（本地实例或 Docker）
以上提到的 API 密钥

设置步骤

1. 克隆你分叉的仓库

git clone https://github.com/YOUR_USERNAME/movie-context-provider
cd movie-context-provider

2. 安装依赖项

# 后端

电影上下文提供者

项目介绍

MCP: 电影内容提供者

这是什么？

目录

功能

MCP 工具

插件

多提供商 AI

性能与缓存

开始

快速开始：部署到 Render

先决条件

三步部署

创建一个 OpenAI 应用

第一步：找到你的 API 密钥

第二步：启用开发者模式（仅第一次）

第三步：创建你的 OpenAI 应用

第四步：在聊天中启用应用

替代方案：其他 MCP 客户端（无插件）

插件如何工作

多提供商 LLM（可选）

认证与用户管理

自动管理员用户设置

创建附加用户

使用你的 API 密钥

管理员端点

替代方案：手动 SQL

应用使用示例

在 ChatGPT 中

高级查询

本地开发（可选）

先决条件

设置步骤