STARWARCLOUD STARWAR.AI
返回市场
电视推荐MCP服务器

电视推荐MCP服务器

作者：terryso5 星标更新：2025-05-05
安装使用来源：spider==github.com

项目介绍

English Version

TV 推荐 MCP 服务器 🚀

codecov npm version NPM Downloads Node.js Version PRs Welcome smithery badge License: MIT DeepWiki

基于 TMDb API 的美国电视剧推荐 MCP 服务器，提供按类型、相似电视剧和电视剧详情的推荐功能。

项目描述

该项目是一个基于 MCP（模型上下文协议）的服务器，专门设计用于提供全面的美国电视剧推荐和信息查询服务。该服务器通过标准输入输出（STDio）与支持 MCP 的客户端通信，并通过调用 TMDb（The Movie Database）API 获取数据。服务涵盖各种功能，如电视剧发现、详情查询、观看渠道、演员信息、用户评论等，为用户提供一站式的电视剧探索体验。

项目背景与愿景

大规模语言模型（LLMs）在理解和生成文本方面表现出色，但在提供实时、个性化的美国电视剧推荐方面存在局限性，例如知识截止和缺乏对用户偏好的理解。用户希望通过自然语言交互获得更准确和及时的推荐，但现有的 LLMs 无法完全满足这一需求。本项目旨在通过 Model Context Protocol（MCP）Server 扩展 LLM 的能力，解决这一痛点，并抓住机会提供更加智能化的影视发现体验。

愿景： 使用户能够通过与 LLM 的自然对话无缝地发现、了解并获取个性化、实时且可解释的美国电视剧推荐，将 LLM 转变为强大的个人娱乐顾问。

目标受众

主要目标用户是熟悉并使用支持 MCP 的 LLM 客户端（如 Claude Desktop）的个人用户。他们是美国电视剧的粉丝，愿意使用 AI 来获取信息，并希望以一种更自然和互动的方式发现符合自己口味的新剧集。

系统架构

此 MCP 服务器采用模块化设计，重点分离明确。服务器初始化 MCP 框架，注册各种推荐工具，并使用 TMDb 客户端与 TMDb API 进行交互。配置设置（特别是 TMDb API 密钥）通过环境变量进行管理。

高级架构图

flowchart TD
    A["MCP客户端<br>(LLM工具)"] -- "MCP请求<br>(stdio)" --> B
    
    subgraph "服务器架构"
    B["MCP核心<br>(stdio)"] --> C["工具路由器"]
    C --> D["工具实现层"]
    D --> E["TMDb服务客户端"]
    D --> F["工具辅助功能<br>(如类型映射)"]
    E -- "HTTP请求" --> G["TMDb API"]
    D --> H["日志系统"]
    E --> H
    end
    
    G -- "HTTP响应" --> E
    B -- "发送响应" --> A

核心组件

  • MCP 服务器实现：服务器基于 TypeScript 的 Model Context Protocol SDK 构建，提供了工具注册和客户端通信的基础。
  • TMDb 客户端：负责与 TMDb API 的所有交互，处理身份验证、构建 API 请求和处理响应。
  • 推荐工具：服务器暴露了各种工具，并提供了与电视节目发现和信息检索相关的特定功能。

功能与路线图

以下是该项目的完整功能列表和开发状态（基于目录中的 .ai 用户故事）：

Epic 1: 核心推荐工具 MVP (Core Recommendation Tools MVP)

  • [x] MCP 服务器设置&API 集成 (story-1-1-setup-integration.md)
  • [x] 按类型推荐剧集 (story-1-2-recommend-genre.md) - 工具：get_recommendations_by_genre
  • [x] 查找相似剧集 (story-1-3-recommend-similar.md) - 工具：get_similar_shows
  • [x] 获取剧集详情 (story-1-4-show-details.md) - 工具：get_show_details

Epic 2: 增强与扩展

  • [ ] 关键词/主题发现 (story-2-1-keyword-discovery.md)
  • [ ] 早期作品发现 (story-2-2-early-works.md)
  • [ ] 详细的剧集信息与互动 (story-2-3-episode-details.md)
  • [ ] 按平台/网络/公司聚合内容 (story-2-4-provider-aggregation.md)
  • [x] 查询演员信息和贡献 (story-2-5-actor-info.md) - 工具：get_actor_details_and_credits, find_shows_by_actor, get_recommendations_by_actor
  • [x] 高级剧集发现 (story-2-6-advanced-discovery.md) - 工具：discover_shows
  • [x] 查询热门与趋势剧集 (story-2-7-popular-trending.md) - 工具：get_popular_shows, get_trending_shows
  • [x] 查询剧集用户评论 (story-2-8-reviews-ratings.md) - 工具：get_show_reviews
  • [x] 查询剧集预告片和视频 (story-2-9-trailers.md) - 工具：get_show_videos
  • [x] 查询剧集观看渠道 (story-2-10-watch-providers.md) - 工具：get_watch_providers

Epic 3: 个性化与集成

  • [ ] 智能追剧进度管理 (story-3-1-watch-progress.md)

Epic 4: 可视化与探索

  • [ ] 视觉化系列/宇宙探索 (story-4-1-franchise-visualization.md)

技术栈

  • 语言： TypeScript
  • 运行时环境： Node.js
  • MCP SDK： @modelcontextprotocol/sdk
  • 类型验证： zod
  • HTTP 客户端： axios
  • 外部 API： TMDb (The Movie Database)
  • 环境变量管理： dotenv

快速开始

使用 NPX 可以快速运行服务器而无需安装：

# 设置 TMDb API 密钥（必须）
export TMDB_API_KEY=your_api_key_here

# 运行服务器
npx tv-recommender-mcp-server

安装步骤

  1. 从 NPM 安装

    npm install -g tv-recommender-mcp-server

  2. 配置环境变量

    export TMDB_API_KEY=your_api_key_here

  3. 运行服务器

    tv-recommender-mcp-server

或者，您可以克隆仓库：

  1. 克隆仓库

    git clone <仓库地址>
cd tv-recommender-mcp-server

  2. 安装依赖

    npm install

  3. 配置环境变量

    • 复制 .env-example 为 .env
    • 在 TMDb 注册并申请 API 密钥
    • 在 .env 文件中填写 API 密钥字段 TMDB_API_KEY

  4. 构建并运行项目

    npm run build
npm start

在 Smithery 平台上使用

要在 Smithery 平台上使用此 MCP 服务器，请按照以下步骤操作：

  1. 访问 Smithery 平台 并登录您的账户
  2. 搜索 "@terryso/tv-recommender-mcp-server" 或直接访问 tv-recommender-mcp-server
  3. 点击“安装”按钮以安装此服务
  4. 重要 在配置过程中，您需要提供一个 TMDb API 密钥
    • 您可以在 TMDb 网站上注册并申请一个免费的 API 密钥
    • 在输入框中填写您的 API 密钥
  5. 安装后，您可以在支持 Smithery 工具的任何 AI 对话中使用此服务

在 Cursor 中配置 MCP 服务器

要在 Cursor 中使用此 MCP 服务器，请按照以下步骤操作：

  1. 在项目的根目录下创建（或编辑）.cursor/mcp.json 文件

  2. 在文件中配置服务器信息，如下所示（使用 npx）：

    {
  "mcpServers": {
    "TVRecommender": {
      "command": "npx",
      "args": [
        "tv-recommender-mcp-server"
      ]
    }
  }
}

  3. 使用环境变量传递 TMDb API 密钥：

    {
  "mcpServers": {
    "TVRecommender": {
      "command": "env",
      "args": [
        "TMDB_API_KEY=your_api_key_here",
        "npx",
        "tv-recommender-mcp-server"
      ]
    }
  }
}

  4. 保存文件后，Cursor 将自动检测并加载此 MCP 服务器

  5. 现在，您可以通过以下方式在 Cursor 中使用此工具：

    • 在对话中输入 / 并选择 TVRecommender 工具
    • 输入相关查询，例如“推荐科幻电视剧”或“搜索类似《权力的游戏》的电视剧”

  6. 要调试或查看日志：

    • 在 Cursor 的开发者工具中（按 Cmd+Option+I 查看控制台输出
    • 通过环境变量启用调试模式："DEBUG=mcp:*,npx tv-recommender-mcp-server"

使用场景示例

这里有几个实际的使用场景示例，展示如何结合多个工具以获得更好的体验：

  1. 发现新电视剧：

    • 使用 get_popular_shows 或 get_trending_shows 获取当前热门电视剧
    • 找到感兴趣的电视剧后，使用 get_show_details 查看详情
    • 使用 get_show_videos 观看预告片
    • 使用 get_watch_providers 查找观看渠道

  2. 基于喜爱的演员探索：

    • 使用 get_actor_details_and_credits 查看喜爱演员的所有作品
    • 使用 get_recommendations_by_actor 获取与演员相关的推荐
    • 对感兴趣的电视剧，使用 get_show_reviews 查看其他观众的评论

  3. 精确筛选电视剧：

    • 使用 discover_shows 结合多种条件（如类型、年代、评分、关键词等）精准搜索符合个人喜好的电视剧
    • 例如，搜索 2020 年以后高分的科幻剧，或搜索特定电视台（如 HBO 和 Netflix）的原创剧集

  4. 相似内容探索：

    • 在观看喜爱的电视剧后，使用 get_similar_shows 查找具有相似风格的其他电视剧
    • 结合 get_recommendations_by_genre 探索更多同类型的高质量内容

以上功能可以自然地结合在 AI 对话中，例如，您可以对 AI 说：“推荐一些类似于《怪奇物语》的科幻剧，并告诉我在哪里观看”，MCP 工具将自动配合 AI 提供所需的信息。

工具描述

此 MCP 服务器提供了以下工具：

  1. get_recommendations_by_genre - 按类型推荐电视剧
  2. get_similar_shows - 获取与指定电视剧相似的推荐
  3. get_show_details - 获取指定电视剧的详细信息
  4. get_watch_providers - 查询特定电视剧在指定国家/地区的观看渠道（流媒体、租赁、购买）
  5. discover_shows - 高级电视剧发现，支持多种条件组合（如类型、评分、年份、关键词、播放平台等）
  6. find_shows_by_actor - 搜索演员参与的电视剧
  7. get_recommendations_by_actor - 获取由演员推荐的电视剧
  8. get_actor_details_and_credits - 获取演员的详细信息（如简介、照片）及他们参与过的剧集列表
  9. get_popular_shows - 获取当前最热门的电视剧
  10. get_trending_shows - 获取最近的趋势剧集（支持每日和每周趋势）
  11. get_show_videos - 获取指定电视剧的预告片及相关视频
  12. get_show_reviews - 查看特定电视剧的用户评论

工具详细文档

有关工具使用的详细文档和系统架构，请访问我们的 DeepWiki 文档。这包括：

  • 工具实现架构
  • 请求流程图
  • 部署和配置指南
  • 各工具的详细参数规范
  • 开发和测试指南
  • 项目路线图等

功能示例

这里是每个工具的使用示例：

获取观看渠道

/TVRecommender get_watch_providers --show_title="怪奇物语" --country_code="US"

高级电视剧发现

/TVRecommender discover_shows --with_genres=["科幻", "惊悚"] --vote_average_gte=8.0 --first_air_date_year=2022

搜索演员信息和作品

/TVRecommender get_actor_details_and_credits --actor_name="布莱恩·科兰斯顿"

获取热门和趋势电视剧

/TVRecommender get_popular_shows
/TVRecommender get_trending_shows --time_window="day"

获取电视剧预告片和视频

/TVRecommender get_show_videos --show_title="权力的游戏"

搜索电视剧用户评论

/TVRecommender get_show_reviews --show_title="绝命毒师" --page=1

安全注意事项

  • API 密钥管理：TMDb API 密钥敏感，不应硬编码在源代码中或提交到版本控制系统。仅通过环境变量使用 dotenv 包加载。.env 文件必须包含在 .gitignore 中。
  • 输入验证：尽管 MCP 通信通常在客户端/服务器之间是可信的，建议在工具实现中执行基本的输入参数验证。
  • 速率限制：请注意 TMDb API 的速率限制。如有必要，在未来的迭代中实现基本的重试逻辑或缓存。
  • 依赖项：保持依赖项更新以修补已知漏洞。

开发模式

如果您希望参与开发，可以使用以下命令启动开发模式：

npm run dev

发布到 NPM

此项目配置了 GitHub Actions 工作流，可以自动发布到 NPM：

  1. 确保已更新 package.json 中的版本号
  2. 在 GitHub 仓库设置中添加以下密钥：
    • NPM_TOKEN 您的 NPM 访问令牌
  3. 在 GitHub 上创建新的 Release 或推送标签（格式为 v*）
  4. GitHub Actions 将自动构建并发布到 NPM

您也可以手动触发发布工作流。

贡献指南

欢迎提交 Issue 和 Pull Requests 以帮助改进此项目。

许可证

MIT © 2023-present