📘 README.md--CineScope推荐器（电影和电视资源管理器） 🎬 CineScope推荐器
TMDB+MCP+Google ADK驱动的影视探索代理
CineScope Recommender是一个使用Google代理开发工具包（ADK）和TMDB API的完整封装MCP（模型上下文协议）服务器构建的代理人工智能系统。 它支持：
🔍 搜索电影和节目
🎥 获取详细建议
🎭 按流派/年份/语言查找标题
📊 过滤和元数据感知推理
💬 自然、上下文相关的提示（例如，“如果我喜欢X，接下来呢？”）
该项目满足了代理人工智能聊天与MCP-Wrapped Public API实习项目的所有基线要求。
🏛️ 架构概述 +----------------------+ |用户查询| +---------+------------+ | v +-----------+-------------+ |LLM代理（ADK）| |-系统提示| |-开发人员提示| |-工具选择逻辑| +-----------+-------------+ | MCP （标准） | +-----------+-------------+ |MCP服务器| |-搜索标题| |-get_recommendations| |-发现| |-缓存层| |-重试/回退| +-----------+-------------+ | +-----------+-------------+ |TMDB API| +--------------------------+
⚙️ 特性 ✔ 通过MCP集成TMDB
返回给代理的所有数据仅通过MCP工具流动。
✔ 三个完全实施的MCP工具
搜索标题
get_recommendations
发现
✔ 稳健的体系结构
输入验证
错误处理
速率限制检测
重试/回退
标准化数据模式
✔ 内存缓存
TTL=5分钟→ 更好的性能+减少API调用。
✔ 可观测性
结构化日志记录
工具调用日志
缓存命中/未命中日志
健康终点
✔ ADK代理
确定性工具的使用
防止重复的相同工具调用
包括时间戳和来源归因
解释为什么每个建议都适合
✔ 完整测试套件
代理提示测试
MCP工具测试
集成准备就绪
黄金成绩单支持
📦 文件夹结构 电影推荐/ │ ├── CineScope_推荐器/ │ ├── agent.py │ ├── mcp_server.py │ ├── __初始化__南美国家巴拉圭的缩写（Paraguay） │ └── .env（未提交--仅本地） │ ├── 测试/ │ ├── test_agent_prompt.py │ ├── test_mcp_server.py │ └── __初始化__南美国家巴拉圭的缩写（Paraguay） │ ├── README.md └── 需求.txt
🔑 环境变量
在内部添加.env文件：
CineScope_推荐器/.env
内容：
TMDB_API_KEY=您的_TMDB_API_KEY_here
确保=周围没有空格，也没有引号。
ADK会自动加载.env文件。
🚀 设置和安装
- 克隆仓库并进入项目
克隆 cd电影推荐
- 创建虚拟环境
python3-m视频 source.ven/bin/activate
- 安装依赖项
pip安装-r要求.txt
▶️ 运行代理
代理通过stdio自动启动您的MCP服务器。
运行：
adk运行CineScope_Recommender。代理：root_agent
如果你想在不指定类的情况下运行：
adk运行CineScope_推荐器
您将看到：
正在运行代理cine_scope_recommender。..键入exit退出。
现在键入您的查询：
搜索电影《盗梦空间》
🧪 运行测试 pytest-q
预期产量：
0.35秒内通过2次
测试包括：
代理提示测试
MCP服务器基本测试
JSON验证
工具可用性
🔧 MCP工具概述 🔍 搜索标题
在TMDB中搜索电影或电视节目。
论据：
{ “query”：“Inception”， “类型”：“电影”， “年份”：2010年， “语言”：“en” }
退货：
ID
标题
类型
年
评分
概述
后部路径
🎥 get_recommendations
根据标题ID获取TMDB推荐。
输入：
{ “id”：27205， “类型”：“电影” }
输出：
推荐标题
年
原因（如有）
🎭 发现
高级过滤：
{ “类型”：“电影”， “流派”：\[《颤栗》\]， “语言”：“ko”， “年份”：2023年， “sort_by”：“投票平均值” }
⚡ 缓存
缓存使用：
\_缓存\[（tool_name，args \_json）\]=（时间戳，数据）
TTL=300秒
优点：
避免速率限制
更快的响应
更高的评分标准
🔁 重试并后退
自动重试时间：
HTTP 429
连接问题
TMDB停机时间
退避策略：
1s → 2s → 4s → 放弃
🩺 健康端点 @服务器.list_endpoints def health（）： return{“status”：“ok”}
退货：
{“状态”：“正常”}
ADK用于可观察性。
💬 示例提示 搜索电影《盗梦空间》
如果我喜欢《星际穿越》，接下来我该看什么？
2020-2024年评分高于7.5的韩国顶级惊悚片
谁在《沙丘》中与Zendaya合作？
📝 黄金成绩单示例 用户：搜索电影《盗梦空间》\ 代理人：\ 根据TMDB（2025-11-30 14:22 UTC）：\ 《盗梦空间》（2010）——评分8.8\ 一部由莱昂纳多·迪卡普里奥主演的令人费解的科幻抢劫电影。。。
🎥 LOOM演示大纲
你的5分钟织机视频应该包括：
项目介绍
体系结构概述
代理代码演练
MCP服务器演练
运行测试
带有2-3个提示的现场演示
闭幕总结
🛠 故障排除 ❌ 找不到API密钥
→ 检查CineScope_Recommender/中是否存在.env。
❌ MCP会话已关闭
→ 修复run_strio→ 替换为stdio_server。
❌ 测试失败
→ 确保项目根目录在PYTHONPATH上。