TV推荐MCP服务器 🚀

英語版

TV おすすめ MCP サーバー 🚀

TMDb API を基盤とする海外ドラマおすすめ MCP サーバーです。ジャンル別おすすめ、類似作品のおすすめ、作品詳細の機能を提供します。

プロジェクトの説明

本プロジェクトは、包括的な海外ドラマのおすすめと情報検索サービスを提供するための、MCP（Model Context Protocol）ベースのサーバーです。サーバーは標準入出力（stdio）を通じて MCP 対応クライアントと通信し、TMDb（The Movie Database）API を呼び出してデータを取得します。作品の検索や詳細情報の確認から、視聴方法、キャスト情報、ユーザーレビューまで幅広く対応し、作品を一か所で探せる体験をユーザーに提供します。

プロジェクトの背景とビジョン

大規模言語モデル（LLM）はテキストの理解と生成に優れていますが、リアルタイムでパーソナライズされた海外ドラマをおすすめすることには限界があります（知識の更新期限や、ユーザーの好みを理解できないことなど）。ユーザーは自然言語でやり取りし、より正確でタイムリーなおすすめを得たいと考えていますが、既存の LLM ではそのニーズを完全には満たせません。本プロジェクトは、Model Context Protocol（MCP）サーバーを通じて LLM の機能を拡張し、この課題を解決するとともに、よりスマートな映像作品の探索体験を提供する機会を捉えることを目指しています。

ビジョン： LLM と自然な会話をすることで、ユーザーがパーソナライズされた、リアルタイムで、説明可能な海外ドラマのおすすめをシームレスに見つけ、理解し、入手できるようにし、LLM を頼れる個人向けエンターテインメントアドバイザーにします。

対象ユーザー

主な対象ユーザーは、Claude Desktop などの MCP 対応 LLM クライアントを使い慣れ、利用している個人ユーザーです。海外ドラマの愛好家であり、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 サーバーの実装：Model Context Protocol SDK for TypeScript を基盤としており、ツールの登録とクライアントとの通信を支えます。
• TMDb クライアント：TMDb API とのすべてのやり取りを担当し、認証、API リクエストの構築、レスポンスの処理を行います。
• おすすめツール：テレビ番組の検索や情報取得に関するさまざまな機能を提供するツールを公開します。

機能とロードマップ (Features & Roadmap)

以下は、本プロジェクトの全機能と開発状況の一覧です（.ai ディレクトリ内のユーザーストーリーに基づきます）。

Epic 1: コアおすすめツール MVP (Core Recommendation Tools MVP)

• MCP サーバーの基本設定と API 統合 (MCP Server Setup & API Integration) (story-1-1-setup-integration.md)
• ジャンル別に作品をおすすめ (Recommend Shows by Genre) (story-1-2-recommend-genre.md) - ツール: get_recommendations_by_genre
• 類似作品を検索 (Find Similar Shows) (story-1-3-recommend-similar.md) - ツール: get_similar_shows
• 作品の詳細を取得 (Get Show Details) (story-1-4-show-details.md) - ツール: get_show_details

Epic 2: 機能強化と拡張 (Enhancements & Expansion)

• キーワード／テーマに基づく検索 (Keyword/Theme Based Discovery) (story-2-1-keyword-discovery.md)
• 俳優の初期作品を検索 (Early Actor Works Discovery) (story-2-2-early-works.md)
• 詳細なエピソード情報と操作 (Detailed Episode Information & Interaction) (story-2-3-episode-details.md)
• コンテンツの集約（配信サービス／ネットワーク／制作会社別） (Provider/Network/Company Content Aggregation) (story-2-4-provider-aggregation.md)
• 俳優情報と出演作品を検索 (Query Actor Information and Credits) (story-2-5-actor-info.md) - ツール: get_actor_details_and_credits, find_shows_by_actor, get_recommendations_by_actor
• 高度な作品検索 (Advanced Show Discovery) (story-2-6-advanced-discovery.md) - ツール: discover_shows
• 人気作品とトレンド作品を検索 (Query Popular & Trending Shows) (story-2-7-popular-trending.md) - ツール: get_popular_shows, get_trending_shows
• 作品のユーザーレビューを検索 (Query Show User Reviews) (story-2-8-reviews-ratings.md) - ツール: get_show_reviews
• 作品の予告編と動画を検索 (Query Show Trailers & Videos) (story-2-9-trailers.md) - ツール: get_show_videos
• 作品の視聴方法を検索 (Query Show Watch Providers) (story-2-10-watch-providers.md) - ツール: get_watch_providers

Epic 3: パーソナライズと統合 (Personalization & Integration)

• 視聴進捗のスマート管理 (Smart Watch Progress Management) (story-3-1-watch-progress.md)

Epic 4: ビジュアル化と探索 (Visualization & Exploration)

• シリーズ／ユニバースのビジュアル探索 (Visual Franchise/Universe Exploration) (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密钥
   • 将API密钥填入.env文件的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. 点击"Install"按钮安装此服务
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 Key管理：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 Request来帮助改进这个项目。

许可证

MIT © 2023-present