[{"_1":2,"_312":-5,"_313":-5},"loaderData",{"_3":4,"_22":23,"_24":25,"_242":243},"root",{"_5":6,"_7":8},"toasts",[],"visitor",{"_9":10,"_11":12},"viewportWidth",1280,"visitorSession",{"_13":14,"_16":17,"_18":-5,"_19":20,"_21":-5},"attributes",[15],"BOT","id",7058884,"membership","referenceId","01971406-43e3-74e8-b880-2f000258007a","userAccount","routes/_public/_layout",{},"routes/_public/mcp/servers/~namespace/~slug/_pages/_layout",{"_26":27,"_28":-5,"_29":30,"_31":41,"_160":161,"_241":141},"availableLocales",[],"githubUser","locale",{"_31":32,"_35":38,"_39":40},"mcpServer",{"_33":34,"_35":34,"_36":37},"description","tv-recommender-mcp-server","name","readme","[English Version](README.en.md)\n\n# TV推荐MCP服务器 🚀\n\n[![codecov](https://codecov.io/github/terryso/tv-recommender-mcp-server/graph/badge.svg?token=ZMF2J8D636)](https://codecov.io/github/terryso/tv-recommender-mcp-server)\n[![npm version](https://badge.fury.io/js/tv-recommender-mcp-server.svg)](https://badge.fury.io/js/tv-recommender-mcp-server)\n![NPM Downloads](https://img.shields.io/npm/dw/tv-recommender-mcp-server)\n[![Node.js Version](https://img.shields.io/node/v/tv-recommender-mcp-server)](https://nodejs.org)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/terryso/tv-recommender-mcp-server/pulls)\n[![smithery badge](https://smithery.ai/badge/@terryso/tv-recommender-mcp-server)](https://smithery.ai/server/@terryso/tv-recommender-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![DeepWiki](https://img.shields.io/badge/DeepWiki-项目文档-blue)](https://deepwiki.com/terryso/tv-recommender-mcp-server)\n\n> 基于TMDb API的美剧推荐MCP服务器，提供按类型推荐、相似剧集推荐和剧集详情功能。\n\n## 项目描述\n\n本项目是一个基于MCP(Model Context Protocol)的服务器，专门用于提供全面的美剧推荐和信息查询服务。服务器通过标准输入/输出(stdio)与支持MCP的客户端通信，并通过调用TMDb(The Movie Database) API获取数据。服务覆盖从剧集发现、详情查询到观看渠道、演员信息、用户评论等多方面功能，为用户提供一站式剧集探索体验。\n\n### 项目背景与愿景\n\n大型语言模型（LLM）在理解和生成文本方面表现出色，但在提供实时、个性化的美剧推荐方面存在局限性（如知识截止、缺乏用户偏好理解）。用户期望通过自然语言交互获得更精准、更及时的推荐，而现有LLM难以完全满足此需求。本项目旨在通过Model Context Protocol (MCP) Server扩展LLM的能力，解决这一痛点，抓住提供更智能影视发现体验的机会。\n\n**愿景：** 让用户能够通过与LLM的自然对话，无缝地发现、了解并获取个性化、实时、可解释的美剧推荐，将LLM变为强大的个人娱乐顾问。\n\n### 目标用户\n\n主要目标用户是熟悉并使用支持MCP的LLM客户端（如Claude Desktop）的个人用户。他们是美剧爱好者，对通过AI获取信息持开放态度，并希望以更自然、交互的方式发现符合口味的新剧集。\n\n## 系统架构\n\n此MCP服务器采用模块化设计，具有明确的关注点分离。服务器初始化MCP框架，注册各种推荐工具，并使用TMDb客户端与TMDb API交互。配置设置（特别是TMDb API密钥）通过环境变量管理。\n\n### 高级架构图\n\n```mermaid\nflowchart TD\n A[\"MCP客户端
(LLM工具)\"] -- \"MCP请求
(stdio)\" --> B\n \n subgraph \"服务器架构\"\n B[\"MCP核心
(stdio)\"] --> C[\"工具路由器\"]\n C --> D[\"工具实现层\"]\n D --> E[\"TMDb服务客户端\"]\n D --> F[\"工具辅助功能
(如类型映射)\"]\n E -- \"HTTP请求\" --> G[\"TMDb API\"]\n D --> H[\"日志系统\"]\n E --> H\n end\n \n G -- \"HTTP响应\" --> E\n B -- \"发送响应\" --> A\n```\n\n### 核心组件\n\n- **MCP服务器实现**：服务器基于Model Context Protocol SDK for TypeScript构��，提供工具注册和客户端通信的基础。\n- **TMDb客户端**：负责与TMDb API的所有交互，处理认证、构建API请求并处理响应。\n- **推荐工具**：服务器公开各种工具，提供与电视节目发现和信息检索相关的特定功能。\n\n## 功能与路线图 (Features & Roadmap)\n\n以下是本项目的完整功能列表及开发状态 (基于 `.ai` 目录下的用户故事):\n\n**Epic 1: 核心推荐工具 MVP (Core Recommendation Tools MVP)**\n- [x] **MCP 服务器基础设置与 API 集成 (MCP Server Setup & API Integration)** (`story-1-1-setup-integration.md`)\n- [x] **按类型推荐剧集 (Recommend Shows by Genre)** (`story-1-2-recommend-genre.md`) - 工具: `get_recommendations_by_genre`\n- [x] **查找相似剧集 (Find Similar Shows)** (`story-1-3-recommend-similar.md`) - 工具: `get_similar_shows`\n- [x] **获取剧集详情 (Get Show Details)** (`story-1-4-show-details.md`) - 工具: `get_show_details`\n\n**Epic 2: 增强与扩展 (Enhancements & Expansion)**\n- [ ] **基于关键词/主题发现 (Keyword/Theme Based Discovery)** (`story-2-1-keyword-discovery.md`)\n- [ ] **发现演员早期作品 (Early Actor Works Discovery)** (`story-2-2-early-works.md`)\n- [ ] **详细的单集信息与互动 (Detailed Episode Information & Interaction)** (`story-2-3-episode-details.md`)\n- [ ] **内容聚合(按平台/网络/公司) (Provider/Network/Company Content Aggregation)** (`story-2-4-provider-aggregation.md`)\n- [x] **查询演员信息及其作品 (Query Actor Information and Credits)** (`story-2-5-actor-info.md`) - 工具: `get_actor_details_and_credits`, `find_shows_by_actor`, `get_recommendations_by_actor`\n- [x] **高级剧集发现 (Advanced Show Discovery)** (`story-2-6-advanced-discovery.md`) - 工具: `discover_shows`\n- [x] **查询热门与趋势剧集 (Query Popular & Trending Shows)** (`story-2-7-popular-trending.md`) - 工具: `get_popular_shows`, `get_trending_shows`\n- [x] **查询剧集用户评论 (Query Show User Reviews)** (`story-2-8-reviews-ratings.md`) - 工具: `get_show_reviews`\n- [x] **查询剧集预告片与视频 (Query Show Trailers & Videos)** (`story-2-9-trailers.md`) - 工具: `get_show_videos`\n- [x] **查询剧集观看渠道 (Query Show Watch Providers)** (`story-2-10-watch-providers.md`) - 工具: `get_watch_providers`\n\n**Epic 3: 个性化与集成 (Personalization & Integration)**\n- [ ] **智能追剧进度管理 (Smart Watch Progress Management)** (`story-3-1-watch-progress.md`)\n\n**Epic 4: 可视化与探索 (Visualization & Exploration)**\n- [ ] **可视化系列/宇宙探索 (Visual Franchise/Universe Exploration)** (`story-4-1-franchise-visualization.md`)\n\n## 技术栈\n\n- **语言:** TypeScript\n- **运行时环境:** Node.js\n- **MCP SDK:** @modelcontextprotocol/sdk\n- **类型验证:** zod\n- **HTTP客户端:** axios\n- **外部API:** TMDb (The Movie Database)\n- **环境变量管理:** dotenv\n\n## 快速开始\n\n使用npx可以快速运行服务器，无需安装：\n\n```bash\n# 设置TMDb API密钥（必须）\nexport TMDB_API_KEY=your_api_key_here\n\n# 运行服务器\nnpx tv-recommender-mcp-server\n```\n\n## 安装步骤\n\n1. 从NPM安装\n ```bash\n npm install -g tv-recommender-mcp-server\n ```\n\n2. 配置环境变量\n ```bash\n export TMDB_API_KEY=your_api_key_here\n ```\n\n3. 运行服务器\n ```bash\n tv-recommender-mcp-server\n ```\n\n或者，您可以克隆仓库：\n\n1. 克隆仓库\n ```bash\n git clone <仓库地址>\n cd tv-recommender-mcp-server\n ```\n\n2. 安装依赖\n ```bash\n npm install\n ```\n\n3. 配置环境变量\n - 复制`.env-example`为`.env`\n - 在[TMDb](https://www.themoviedb.org/)申请API密钥\n - 将API密钥填入`.env`文件的`TMDB_API_KEY`字段\n\n4. 构建并运行项目\n ```bash\n npm run build\n npm start\n ```\n\n## 在Smithery平台中使用\n\n要在Smithery平台中使用此MCP服务器，请按照以下步骤操作：\n\n1. 访问 [Smithery平台](https://smithery.ai) 并登录您的账户\n2. 搜索\"@terryso/tv-recommender-mcp-server\"或直接访问 [tv-recommender-mcp-server](https://smithery.ai/server/@terryso/tv-recommender-mcp-server)\n3. 点击\"Install\"按钮安装此服务\n4. **重要**: 在配置过程中，您需要提供一个TMDb API密钥\n - 您可以在 [TMDb](https://www.themoviedb.org/) 网站注册并申请免费API密钥\n - 在输入框中填入您的API密钥\n5. 完成安装后，您可以在任何支持Smithery工具的AI聊天中使用此服务\n\n## 在Cursor中配置MCP服务器\n\n要在Cursor中使用此MCP服务器，请按照以下步骤操作：\n\n1. 在项目根目录创建（或编辑）`.cursor/mcp.json`文件\n\n2. 在文件中配置服务器信息，格式如下（使用npx方式）：\n ```json\n {\n \"mcpServers\": {\n \"TVRecommender\": {\n \"command\": \"npx\",\n \"args\": [\n \"tv-recommender-mcp-server\"\n ]\n }\n }\n }\n ```\n\n3. 使用环境变量传递TMDb API密钥：\n ```json\n {\n \"mcpServers\": {\n \"TVRecommender\": {\n \"command\": \"env\",\n \"args\": [\n \"TMDB_API_KEY=your_api_key_here\",\n \"npx\",\n \"tv-recommender-mcp-server\"\n ]\n }\n }\n }\n ```\n\n4. 保存文件后，Cursor会自动检测并加载此MCP服务器\n\n5. 现在，您可以在Cursor中通过以下方式使用此工具：\n - 在对话中输入 `/` 并选择 `TVRecommender` 工具\n - 输入相关查询，如 \"推荐科幻类电视剧\" 或 \"查找与《权力的游戏》相似的剧集\"\n\n6. 如需调试或查看日志：\n - 在Cursor的开发者工具中（按 `Cmd+Option+I` 打开）查看控制台输出\n - 通过环境变量启用调试模式：`\"DEBUG=mcp:*,npx tv-recommender-mcp-server\"`\n\n## 使用场景示例\n\n以下是几个实际使用场景示例，展示如何结合多个工具获得更好的体验：\n\n1. **发现新剧集**：\n - 使用 `get_popular_shows` 或 `get_trending_shows` 获取当前热门剧集\n - 找到感兴趣的剧集后，用 `get_show_details` 查看详情\n - 通过 `get_show_videos` 观看预告片\n - 使用 `get_watch_providers` 查找哪里可以观看\n\n2. **基于喜爱的演员探索**：\n - 通过 `get_actor_details_and_credits` 查看喜欢的演员的所有作品\n - 使用 `get_recommendations_by_actor` 获取与该演员相关的推荐\n - 对感兴趣的剧集，用 `get_show_reviews` 查看其他观众的评价\n\n3. **精确筛选剧集**：\n - 使用 `discover_shows` 结合多种条件（类型、年代、评分、关键词等）精确查找符合个人口味的剧集\n - 例如：查找2020年后的高分科幻剧集，或者查找特定电视网络（如HBO、Netflix）的原创剧集\n\n4. **相似内容探索**：\n - 看完一部喜欢的剧集后，使用 `get_similar_shows` 寻找风格相似的其他剧集\n - 结合 `get_recommendations_by_genre` 探索更多同类型优质内容\n\n以上功能可以在AI聊天中自然地组合使用，例如可以对AI说\"推荐一些类似《怪奇物语》的科幻剧，并告诉我在哪里可以观看\"，MCP工具会自动配合AI提供所需信息。\n\n## 工具说明\n\n本MCP服务器提供以下工具:\n\n1. **get_recommendations_by_genre** - 按类型获取剧集推荐\n2. **get_similar_shows** - 获取与指定剧集相似的推荐\n3. **get_show_details** - 获取指定剧集的详细信息\n4. **get_watch_providers** - 查询特定剧集在指定国家/地区的观看渠道（流媒体、租赁、购买）\n5. **discover_shows** - 高级剧集发现，支持多种条件组合（如类型、评分、年份、关键词、播放平台等）\n6. **find_shows_by_actor** - 查找演员参演的剧集\n7. **get_recommendations_by_actor** - 获取演员推荐的剧集\n8. **get_actor_details_and_credits** - 获取演员详细信息（如简介、照片）及其参演的剧集列表\n9. **get_popular_shows** - 获取当前最热门的剧集\n10. **get_trending_shows** - 获取近期趋势剧集（支持日趋势和周趋势）\n11. **get_show_videos** - 获取指定剧集的预告片和相关视频\n12. **get_show_reviews** - 查看其他用户对特定剧集的评论\n\n### 工具详细文档\n\n更多关于工具使用和系统架构的详细文档，请访问我们的[DeepWiki文档](https://deepwiki.com/terryso/tv-recommender-mcp-server)，其中包含：\n- 工具实现架构\n- 请求流程图\n- 部署和配置指南\n- 各工具的详细参数说明\n- 开发和测试指南\n- 项目路线图等\n\n## 功能示例\n\n以下是各工具的使用示例:\n\n### 获取观看渠道\n```\n/TVRecommender get_watch_providers --show_title=\"怪奇物语\" --country_code=\"US\"\n```\n\n### 高级剧集发现\n```\n/TVRecommender discover_shows --with_genres=[\"科幻\", \"惊悚\"] --vote_average_gte=8.0 --first_air_date_year=2022\n```\n\n### 查询演员信息及作品\n```\n/TVRecommender get_actor_details_and_credits --actor_name=\"布莱恩·科兰斯顿\"\n```\n\n### 获取热门与趋势剧集\n```\n/TVRecommender get_popular_shows\n/TVRecommender get_trending_shows --time_window=\"day\"\n```\n\n### 获取剧集预告片与视频\n```\n/TVRecommender get_show_videos --show_title=\"权力的游戏\"\n```\n\n### 查询剧集用户评论\n```\n/TVRecommender get_show_reviews --show_title=\"绝命毒师\" --page=1\n```\n\n## 安全考量\n\n- **API Key管理**：TMDb API密钥是敏感的，不应硬编码在源代码中或提交到版本控制系统。它将仅通过环境变量使用dotenv包加载。.env文件必须包含在.gitignore中。\n- **输入验证**：尽管MCP通信通常在客户端/服务器之间受信任，但建议在工具实现中进行基本的输入参数验证。\n- **速率限制**：请注意TMDb API的速率限制。如有必要，请在未来的迭代中实现基本的重试逻辑或缓存。\n- **依赖项**：保持依赖项更新，以修补已知的漏洞。\n\n## 开发模式\n\n如果您希望参与开发，可以使用以下命令启动开发模式：\n\n```bash\nnpm run dev\n```\n\n## 发布到NPM\n\n本项目配置了GitHub Actions工作流，可以自动发布到NPM：\n\n1. 确保更新了`package.json`中的版本号\n2. 在GitHub仓库设置中添加以下密钥：\n - `NPM_TOKEN`: 您的NPM访问令牌\n3. 在GitHub上创建一个新的Release或推送标签（v*格式）\n4. GitHub Actions会自动构建并发布到NPM\n\n您也可以手动触发工作流进行发布。\n\n## 贡献指南\n\n欢迎提交Issue和Pull Request来帮助改进这个项目。\n\n## 许可证\n\n[MIT](LICENSE) © 2023-present ","English","tag","en-US",{"_42":43,"_44":45,"_13":56,"_66":34,"_67":34,"_68":69,"_72":73,"_94":-5,"_16":95,"_96":97,"_98":99,"_35":34,"_110":85,"_111":112,"_115":-5,"_116":117,"_118":-5,"_119":120,"_125":-5,"_106":34,"_126":-5,"_127":128,"_86":157,"_158":159},"addedAt","2025-05-04T14:09:51.742742896Z","argumentsJsonSchema",{"_46":47,"_53":54,"_51":55},"properties",{"_48":49},"TMDB_API_KEY",{"_33":50,"_51":52},"Your API key for The Movie Database (TMDb)","type","string","required",[48],"object",[57,58,59,60,61,62,63,64,65],"category:entertainment-and-media","category:search","environment:network","hosting:remote-capable","language:typescript","security_grade:a","quality_grade:a","license_grade:a","author:claimed","descriptionMarkdown","descriptionPlainText","githubProject",{"_36":37,"_70":71},"url","https://github.com/terryso/tv-recommender-mcp-server","githubRepository",{"_74":75,"_76":77,"_78":79,"_80":81,"_35":34,"_82":83,"_88":89,"_90":91,"_93":89},"defaultBranch","master","fullName","terryso/tv-recommender-mcp-server","githubTreeId",114608,"language","TypeScript","owner",{"_84":85,"_86":87},"login","terryso","uid","31nh393eom","recentStargazers",2,"spdxLicense",{"_35":92},"MIT License","stargazers","glamaJson",6284,"inspectable",true,"integrations",[100],{"_101":102,"_33":108,"_86":109},"brand",{"_103":104,"_35":105,"_106":107},"logoSvgPath","M6.62 12a2.291 2.291 0 0 1 2.292-2.295h-.013A2.291 2.291 0 0 1 11.189 12a2.291 2.291 0 0 1-2.29 2.291h.013A2.291 2.291 0 0 1 6.62 12zm10.72-4.062h4.266a2.291 2.291 0 0 0 2.29-2.291 2.291 2.291 0 0 0-2.29-2.296H17.34a2.291 2.291 0 0 0-2.291 2.296 2.291 2.291 0 0 0 2.29 2.29zM2.688 20.645h8.285a2.291 2.291 0 0 0 2.291-2.292 2.291 2.291 0 0 0-2.29-2.295H2.687a2.291 2.291 0 0 0-2.291 2.295 2.291 2.291 0 0 0 2.29 2.292zm10.881-6.354h.81l1.894-4.586H15.19l-1.154 3.008h-.013l-1.135-3.008h-1.154zm4.208 0h1.011V9.705h-1.011zm2.878 0h3.235v-.93h-2.223v-.933h1.99v-.934h-1.99v-.855h2.107v-.934h-3.112zM1.31 7.941h1.01V4.247h1.31v-.895H0v.895h1.31zm3.747 0h1.011V5.959h1.958v1.984h1.011v-4.59h-1.01v1.711H6.061V3.351H5.057zm5.348 0h3.242v-.933H11.41v-.934h1.99v-.933h-1.99v-.856h2.107v-.934h-3.112zM.162 14.296h1.005v-3.52h.013l1.167 3.52h.765l1.206-3.52h.013v3.52h1.011v-4.59H3.82L2.755 12.7h-.013L1.686 9.705H.156zm14.534 6.353h1.641a3.188 3.188 0 0 0 .98-.149 2.531 2.531 0 0 0 .824-.437 2.123 2.123 0 0 0 .567-.713 2.193 2.193 0 0 0 .223-.983 2.399 2.399 0 0 0-.218-1.07 1.958 1.958 0 0 0-.586-.716 2.405 2.405 0 0 0-.873-.392 4.349 4.349 0 0 0-1.046-.13h-1.519zm1.013-3.656h.596a2.26 2.26 0 0 1 .606.08 1.514 1.514 0 0 1 .503.244 1.167 1.167 0 0 1 .34.412 1.28 1.28 0 0 1 .13.587 1.546 1.546 0 0 1-.13.658 1.127 1.127 0 0 1-.347.433 1.41 1.41 0 0 1-.518.238 2.797 2.797 0 0 1-.649.07h-.538zm4.686 3.656h1.88a2.997 2.997 0 0 0 .613-.064 1.735 1.735 0 0 0 .554-.214 1.221 1.221 0 0 0 .402-.39 1.105 1.105 0 0 0 .155-.606 1.188 1.188 0 0 0-.071-.415 1.01 1.01 0 0 0-.204-.34 1.087 1.087 0 0 0-.317-.24 1.297 1.297 0 0 0-.413-.13v-.012a1.203 1.203 0 0 0 .575-.366.962.962 0 0 0 .216-.648 1.081 1.081 0 0 0-.149-.603 1.022 1.022 0 0 0-.389-.354 1.673 1.673 0 0 0-.54-.169 4.463 4.463 0 0 0-.6-.041h-1.712zm1.011-3.734h.687a1.4 1.4 0 0 1 .24.022.748.748 0 0 1 .22.075.432.432 0 0 1 .16.147.418.418 0 0 1 .061.236.47.47 0 0 1-.055.233.433.433 0 0 1-.146.156.62.62 0 0 1-.204.084 1.058 1.058 0 0 1-.23.026h-.745zm0 1.835h.765a1.96 1.96 0 0 1 .266.02 1.015 1.015 0 0 1 .26.07.519.519 0 0 1 .204.152.406.406 0 0 1 .08.26.481.481 0 0 1-.06.253.519.519 0 0 1-.16.168.62.62 0 0 1-.217.09 1.155 1.155 0 0 1-.237.027H21.4z","The Movie Database","slug","the-movie-database","Utilizes TMDb API to provide TV show recommendations, including discovering shows by genre, finding similar shows, and retrieving detailed information about specific TV series.","9oaup4ivgx","namespace","npmPackage",{"_35":34,"_113":114},"weeklyDownloads",235,"prompts","redditPostForeignId","1kel570","resources","scores",{"_121":122,"_123":122,"_124":122},"license",100,"quality","security","simpleIcon","supportedPlatforms","tools",[129,142,150],{"_35":130,"_131":132},"get_recommendations_by_genre","inputSchema",{"_51":55,"_133":134,"_53":135,"_46":137,"_140":141},"$schema","http://json-schema.org/draft-07/schema#",[136],"genre",{"_136":138},{"_51":52,"_33":139},"电视剧类型，如\"喜剧\"、\"科幻\"、\"悬疑\"等，支持中英文","additionalProperties",false,{"_35":143,"_131":144},"get_similar_shows",{"_51":55,"_133":134,"_53":145,"_46":147,"_140":141},[146],"show_title",{"_146":148},{"_51":52,"_33":149},"剧集名称，如\"怪奇物语\"、\"绝命毒师\"等",{"_35":151,"_131":152},"get_show_details",{"_51":55,"_133":134,"_53":153,"_46":154,"_140":141},[146],{"_146":155},{"_51":52,"_33":156},"剧集名称，用于获取详细信息","eed7pwh69r","updatedAt","2025-05-05T07:00:23.420420846Z","meta",[162,165,167,174,177,179,182,185,188,191,194,196,199,202,204,206,208,210,212],{"_163":164},"title","tv-recommender-mcp-server | Glama",{"_166":34,"_35":33},"content",{"_168":169,"_170":171,"_172":173},"href","https://glama.ai/mcp/servers/@terryso/tv-recommender-mcp-server","rel","canonical","tagName","link",{"_166":34,"_175":176},"property","og:title",{"_166":34,"_175":178},"og:description",{"_166":180,"_175":181},"https://glama.ai/logo.png","og:logo",{"_166":183,"_175":184},"https://glama.ai/mcp/servers/@terryso/tv-recommender-mcp-server/og-image","og:image",{"_166":186,"_175":187},"630","og:image:height",{"_166":189,"_175":190},"1200","og:image:width",{"_166":192,"_175":193},"website","og:type",{"_166":169,"_175":195},"og:url",{"_166":197,"_175":198},"Glama – MCP Hosting Platform","og:site_name",{"_166":200,"_35":201},"summary_large_image","twitter:card",{"_166":197,"_35":203},"twitter:title",{"_166":34,"_35":205},"twitter:description",{"_166":183,"_35":207},"twitter:image",{"_166":186,"_35":209},"twitter:image:height",{"_166":189,"_35":211},"twitter:image:width",{"_213":214},"script:ld+json",{"_215":216,"_217":218},"@context","http://schema.org","@graph",[219],{"_215":220,"_221":222,"_223":224},"https://schema.org","@type","BreadcrumbList","itemListElement",[225,232,235,239],{"_221":226,"_227":228,"_35":229,"_230":231},"ListItem","item","https://glama.ai/","Glama","position",1,{"_221":226,"_227":233,"_35":234,"_230":89},"https://glama.ai/mcp","MCP",{"_221":226,"_227":236,"_35":237,"_230":238},"https://glama.ai/mcp/servers","Servers",3,{"_221":226,"_227":169,"_35":34,"_230":240},4,"visitorIsMaintainer","routes/_public/mcp/servers/~namespace/~slug/_pages/reviews/_route",{"_28":-5,"_31":244,"_160":276,"_311":-5},{"_42":43,"_44":245,"_13":249,"_66":34,"_67":34,"_68":250,"_72":252,"_94":-5,"_16":95,"_96":97,"_98":255,"_35":34,"_110":85,"_111":258,"_115":-5,"_116":117,"_118":-5,"_119":259,"_125":-5,"_106":34,"_126":-5,"_127":260,"_86":157,"_158":159},{"_46":246,"_53":248,"_51":55},{"_48":247},{"_33":50,"_51":52},[48],[57,58,59,60,61,62,63,64,65],{"_36":251,"_70":71},"[English Version](README.en.md)\n\n# TV推荐MCP服务器 🚀\n\n[![codecov](https://codecov.io/github/terryso/tv-recommender-mcp-server/graph/badge.svg?token=ZMF2J8D636)](https://codecov.io/github/terryso/tv-recommender-mcp-server)\n[![npm version](https://badge.fury.io/js/tv-recommender-mcp-server.svg)](https://badge.fury.io/js/tv-recommender-mcp-server)\n![NPM Downloads](https://img.shields.io/npm/dw/tv-recommender-mcp-server)\n[![Node.js Version](https://img.shields.io/node/v/tv-recommender-mcp-server)](https://nodejs.org)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/terryso/tv-recommender-mcp-server/pulls)\n[![smithery badge](https://smithery.ai/badge/@terryso/tv-recommender-mcp-server)](https://smithery.ai/server/@terryso/tv-recommender-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![DeepWiki](https://img.shields.io/badge/DeepWiki-项目文档-blue)](https://deepwiki.com/terryso/tv-recommender-mcp-server)\n\n> 基于TMDb API的美剧推荐MCP服务器，提供按类型推荐、相似剧集推荐和剧集详情功能。\n\n## 项目描述\n\n本项目是一个基于MCP(Model Context Protocol)的服务器，专门用于提供全面的美剧推荐和信息查询服务。服务器通过标准输入/输出(stdio)与支持MCP的客户端通信，并通过调用TMDb(The Movie Database) API获取数据。服务覆盖从剧集发现、详情查询到观看渠道、演员信息、用户评论等多方面功能，为用户提供一站式剧集探索体验。\n\n### 项目背景与愿景\n\n大型语言模型（LLM）在理解和生成文本方面表现出色，但在提供实时、个性化的美剧推荐方面存在局限性（如知识截止、缺乏用户偏好理解）。用户期望通过自然语言交互获得更精准、更及时的推荐，而现有LLM难以完全满足此需求。本项目旨在通过Model Context Protocol (MCP) Server扩展LLM的能力，解决这一痛点，抓住提供更智能影视发现体验的机会。\n\n**愿景：** 让用户能够通过与LLM的自然对话，无缝地发现、了解并获取个性化、实时、可解释的美剧推荐，将LLM变为强大的个人娱乐顾问。\n\n### 目标用户\n\n主要目标用户是熟悉并使用支持MCP的LLM客户端（如Claude Desktop）的个人用户。他们是美剧爱好者，对通过AI获取信息持开放态度，并希望以更自然、交互的方式发现符合口味的新剧集。\n\n## 系统架构\n\n此MCP服务器采用模块化设计，具有明确的关注点分离。服务器初始化MCP框架，注册各种推荐工具，并使用TMDb客户端与TMDb API交互。配置设置（特别是TMDb API密钥）通过环境变量管理。\n\n### 高级架构图\n\n```mermaid\nflowchart TD\n A[\"MCP客户端
(LLM工具)\"] -- \"MCP请求
(stdio)\" --> B\n \n subgraph \"服务器架构\"\n B[\"MCP核心
(stdio)\"] --> C[\"工具路由器\"]\n C --> D[\"工具实现层\"]\n D --> E[\"TMDb服务客户端\"]\n D --> F[\"工具辅助功能
(如类型映射)\"]\n E -- \"HTTP请求\" --> G[\"TMDb API\"]\n D --> H[\"日志系统\"]\n E --> H\n end\n \n G -- \"HTTP响应\" --> E\n B -- \"发送响应\" --> A\n```\n\n### 核心组件\n\n- **MCP服务器实现**：服务器基于Model Context Protocol SDK for TypeScript构建，提供工具注册和客户端通信的基础。\n- **TMDb客户端**：负责与TMDb API的所有交互，处理认证、构建API请求并处理响应。\n- **推荐工具**：服务器公开各种工具，提供与电视节目发现和信息检索相关的特定功能。\n\n## 功能与路线图 (Features & Roadmap)\n\n以下是本项目的完整功能列表及开发状态 (基于 `.ai` 目录下的用户故事):\n\n**Epic 1: 核心推荐工具 MVP (Core Recommendation Tools MVP)**\n- [x] **MCP 服务器基础设置与 API 集成 (MCP Server Setup & API Integration)** (`story-1-1-setup-integration.md`)\n- [x] **按类型推荐剧集 (Recommend Shows by Genre)** (`story-1-2-recommend-genre.md`) - 工具: `get_recommendations_by_genre`\n- [x] **查找相似剧集 (Find Similar Shows)** (`story-1-3-recommend-similar.md`) - 工具: `get_similar_shows`\n- [x] **获取剧集详情 (Get Show Details)** (`story-1-4-show-details.md`) - 工具: `get_show_details`\n\n**Epic 2: 增强与扩展 (Enhancements & Expansion)**\n- [ ] **基于关键词/主题发现 (Keyword/Theme Based Discovery)** (`story-2-1-keyword-discovery.md`)\n- [ ] **发现演员早期作品 (Early Actor Works Discovery)** (`story-2-2-early-works.md`)\n- [ ] **详细的单集信息与互动 (Detailed Episode Information & Interaction)** (`story-2-3-episode-details.md`)\n- [ ] **内容聚合(按平台/网络/公司) (Provider/Network/Company Content Aggregation)** (`story-2-4-provider-aggregation.md`)\n- [x] **查询演员信息及其作品 (Query Actor Information and Credits)** (`story-2-5-actor-info.md`) - 工具: `get_actor_details_and_credits`, `find_shows_by_actor`, `get_recommendations_by_actor`\n- [x] **高级剧集发现 (Advanced Show Discovery)** (`story-2-6-advanced-discovery.md`) - 工具: `discover_shows`\n- [x] **查询热门与趋势剧集 (Query Popular & Trending Shows)** (`story-2-7-popular-trending.md`) - 工具: `get_popular_shows`, `get_trending_shows`\n- [x] **查询剧集用户评论 (Query Show User Reviews)** (`story-2-8-reviews-ratings.md`) - 工具: `get_show_reviews`\n- [x] **查询剧集预告片与视频 (Query Show Trailers & Videos)** (`story-2-9-trailers.md`) - 工具: `get_show_videos`\n- [x] **查询剧集观看渠道 (Query Show Watch Providers)** (`story-2-10-watch-providers.md`) - 工具: `get_watch_providers`\n\n**Epic 3: 个性化与集成 (Personalization & Integration)**\n- [ ] **智能追剧进度管理 (Smart Watch Progress Management)** (`story-3-1-watch-progress.md`)\n\n**Epic 4: 可视化与探索 (Visualization & Exploration)**\n- [ ] **可视化系列/宇宙探索 (Visual Franchise/Universe Exploration)** (`story-4-1-franchise-visualization.md`)\n\n## 技术栈\n\n- **语言:** TypeScript\n- **运行时环境:** Node.js\n- **MCP SDK:** @modelcontextprotocol/sdk\n- **类型验证:** zod\n- **HTTP客户端:** axios\n- **外部API:** TMDb (The Movie Database)\n- **环境变量管理:** dotenv\n\n## 快速开始\n\n使用npx可以快速运行服务器，无需安装：\n\n```bash\n# 设置TMDb API密钥（必须）\nexport TMDB_API_KEY=your_api_key_here\n\n# 运行服务器\nnpx tv-recommender-mcp-server\n```\n\n## 安装步骤\n\n1. 从NPM安装\n ```bash\n npm install -g tv-recommender-mcp-server\n ```\n\n2. 配置环境变量\n ```bash\n export TMDB_API_KEY=your_api_key_here\n ```\n\n3. 运行服务器\n ```bash\n tv-recommender-mcp-server\n ```\n\n或者，您可以克隆仓库：\n\n1. 克隆仓库\n ```bash\n git clone <仓库地址>\n cd tv-recommender-mcp-server\n ```\n\n2. 安装依赖\n ```bash\n npm install\n ```\n\n3. 配置环境变量\n - 复制`.env-example`为`.env`\n - 在[TMDb](https://www.themoviedb.org/)申请API密钥\n - 将API密钥填入`.env`文件的`TMDB_API_KEY`字段\n\n4. 构建并运行项目\n ```bash\n npm run build\n npm start\n ```\n\n## 在Smithery平台中使用\n\n要在Smithery平台中使用此MCP服务器，请按照以下步骤操作：\n\n1. 访问 [Smithery平台](https://smithery.ai) 并登录您的账户\n2. 搜索\"@terryso/tv-recommender-mcp-server\"或直接访问 [tv-recommender-mcp-server](https://smithery.ai/server/@terryso/tv-recommender-mcp-server)\n3. 点击\"Install\"按钮安装此服务\n4. **重要**: 在配置过程中，您需要提供一个TMDb API密钥\n - 您可以在 [TMDb](https://www.themoviedb.org/) 网站注册并申请免费API密钥\n - 在输入框中填入您的API密钥\n5. 完成安装后，您可以在任何支持Smithery工具的AI聊天中使用此服务\n\n## 在Cursor中配置MCP服务器\n\n要在Cursor中使用此MCP服务器，请按照以下步骤操作：\n\n1. 在项目根目录创建（或编辑）`.cursor/mcp.json`文件\n\n2. 在文件中配置服务器信息，格式如下（使用npx方式）：\n ```json\n {\n \"mcpServers\": {\n \"TVRecommender\": {\n \"command\": \"npx\",\n \"args\": [\n \"tv-recommender-mcp-server\"\n ]\n }\n }\n }\n ```\n\n3. 使用环境变量传递TMDb API密钥：\n ```json\n {\n \"mcpServers\": {\n \"TVRecommender\": {\n \"command\": \"env\",\n \"args\": [\n \"TMDB_API_KEY=your_api_key_here\",\n \"npx\",\n \"tv-recommender-mcp-server\"\n ]\n }\n }\n }\n ```\n\n4. 保存文件后，Cursor会自动检测并加载此MCP服务器\n\n5. 现在，您可以在Cursor中通过以下方式使用此工具：\n - 在对话中输入 `/` 并选择 `TVRecommender` 工具\n - 输入相关查询，如 \"推荐科幻类电视剧\" 或 \"查找与《权力的游戏》相似的剧集\"\n\n6. 如需调试或查看日志：\n - 在Cursor的开发者工具中（按 `Cmd+Option+I` 打开）查看控制台输出\n - 通过环境变量启用调试模式：`\"DEBUG=mcp:*,npx tv-recommender-mcp-server\"`\n\n## 使用场景示例\n\n以下是几个实际使用场景示例，展示如何结合多个工具获得更好的体验：\n\n1. **发现新剧集**：\n - 使用 `get_popular_shows` 或 `get_trending_shows` 获取当前热门剧集\n - 找到感兴趣的剧集后，用 `get_show_details` 查看详情\n - 通过 `get_show_videos` 观看预告片\n - 使用 `get_watch_providers` 查找哪里可以观看\n\n2. **基于喜爱的演员探索**：\n - 通过 `get_actor_details_and_credits` 查看喜欢的演员的所有作品\n - 使用 `get_recommendations_by_actor` 获取与该演员相关的推荐\n - 对感兴趣的剧集，用 `get_show_reviews` 查看其他观众的评价\n\n3. **精确筛选剧集**：\n - 使用 `discover_shows` 结合多种条件（类型、年代、评分、关键词等）精确查找符合个人口味的剧集\n - 例如：查找2020年后的高分科幻剧集，或者查找特定电视网络（如HBO、Netflix）的原创剧集\n\n4. **相似内容探索**：\n - 看完一部喜欢的剧集后，使用 `get_similar_shows` 寻找风格相似的其他剧集\n - 结合 `get_recommendations_by_genre` 探索更多同类型优质内容\n\n以上功能可以在AI聊天中自然地组合使用，例如可以对AI说\"推荐一些类似《怪奇物语》的科幻剧，并告诉我在哪里可以观看\"，MCP工具会自动配合AI提供所需信息。\n\n## 工具说明\n\n本MCP服务器提供以下工具:\n\n1. **get_recommendations_by_genre** - 按类型获取剧集推荐\n2. **get_similar_shows** - 获取与指定剧集相似的推荐\n3. **get_show_details** - 获取指定剧集的详细信息\n4. **get_watch_providers** - 查询特定剧集在指定国家/地区的观看渠道（流媒体、租赁、购买）\n5. **discover_shows** - 高级剧集发现，支持多种条件组合（如类型、评分、年份、关键词、播放平台等）\n6. **find_shows_by_actor** - 查找演员参演的剧集\n7. **get_recommendations_by_actor** - 获取演员推荐的剧集\n8. **get_actor_details_and_credits** - 获取演员详细信息（如简介、照片）及其参演的剧集列表\n9. **get_popular_shows** - 获取当前最热门的剧集\n10. **get_trending_shows** - 获取近期趋势剧集（支持日趋势和周趋势）\n11. **get_show_videos** - 获取指定剧集的预告片和相关视频\n12. **get_show_reviews** - 查看其他用户对特定剧集的评论\n\n### 工具详细文档\n\n更多关于工具使用和系统架构的详细文档，请访问我们的[DeepWiki文档](https://deepwiki.com/terryso/tv-recommender-mcp-server)，其中包含：\n- 工具实现架构\n- 请求流程图\n- 部署和配置指南\n- 各工具的详细参数说明\n- 开发和测试指南\n- 项目路线图等\n\n## 功能示例\n\n以下是各工具的使用示例:\n\n### 获取观看渠道\n```\n/TVRecommender get_watch_providers --show_title=\"怪奇物语\" --country_code=\"US\"\n```\n\n### 高级剧集发现\n```\n/TVRecommender discover_shows --with_genres=[\"科幻\", \"惊悚\"] --vote_average_gte=8.0 --first_air_date_year=2022\n```\n\n### 查询演员信息及作品\n```\n/TVRecommender get_actor_details_and_credits --actor_name=\"布莱恩·科兰斯顿\"\n```\n\n### 获取热门与趋势剧集\n```\n/TVRecommender get_popular_shows\n/TVRecommender get_trending_shows --time_window=\"day\"\n```\n\n### 获取剧集预告片与视频\n```\n/TVRecommender get_show_videos --show_title=\"权力的游戏\"\n```\n\n### 查询剧集用户评论\n```\n/TVRecommender get_show_reviews --show_title=\"绝命毒师\" --page=1\n```\n\n## 安全考量\n\n- **API Key管理**：TMDb API密钥是敏感的，不应硬编码在源代码中或提交到版本控制系统。它将仅通过环境变量使用dotenv包加载。.env文件必须包含在.gitignore中。\n- **输入验证**：尽管MCP通信通常在客户端/服务器之间受信任，但建议在工具实现中进行基本的输入参数验证。\n- **速率限制**：请注意TMDb API的速率限制。如有必要，请在未来的迭代中实现基本的重试逻辑或缓存。\n- **依赖项**：保持依赖项更新，以修补已知的漏洞。\n\n## 开发模式\n\n如果您希望参与开发，可以使用以下命令启动开发模式：\n\n```bash\nnpm run dev\n```\n\n## 发布到NPM\n\n本项目配置了GitHub Actions工作流，可以自动发布到NPM：\n\n1. 确保更新了`package.json`中的版本号\n2. 在GitHub仓库设置中添加以下密钥：\n - `NPM_TOKEN`: 您的NPM访问令牌\n3. 在GitHub上创建一个新的Release或推送标签（v*格式）\n4. GitHub Actions会自动构建并发布到NPM\n\n您也可以手动触发工作流进行发布。\n\n## 贡献指南\n\n欢迎提交Issue和Pull Request来帮助改进这个项目。\n\n## 许可证\n\n[MIT](LICENSE) © 2023-present ",{"_74":75,"_76":77,"_78":79,"_80":81,"_35":34,"_82":253,"_88":89,"_90":254,"_93":89},{"_84":85,"_86":87},{"_35":92},[256],{"_101":257,"_33":108,"_86":109},{"_103":104,"_35":105,"_106":107},{"_35":34,"_113":114},{"_121":122,"_123":122,"_124":122},[261,266,271],{"_35":130,"_131":262},{"_51":55,"_133":134,"_53":263,"_46":264,"_140":141},[136],{"_136":265},{"_51":52,"_33":139},{"_35":143,"_131":267},{"_51":55,"_133":134,"_53":268,"_46":269,"_140":141},[146],{"_146":270},{"_51":52,"_33":149},{"_35":151,"_131":272},{"_51":55,"_133":134,"_53":273,"_46":274,"_140":141},[146],{"_146":275},{"_51":52,"_33":156},[277,279,281,283,285,286,287,288,289,290,291,292,293,294,295,296,297,298,299],{"_163":278},"Reviews | tv-recommender-mcp-server | Glama",{"_166":280,"_35":33},"Read community reviews and feedback for tv-recommender-mcp-server. Discover user experiences, ratings, strengths, and potential limitations of this MCP implementation from actual users.",{"_168":282,"_170":171,"_172":173},"https://glama.ai/mcp/servers/@terryso/tv-recommender-mcp-server/reviews",{"_166":284,"_175":176},"Reviews | tv-recommender-mcp-server",{"_166":280,"_175":178},{"_166":180,"_175":181},{"_166":183,"_175":184},{"_166":186,"_175":187},{"_166":189,"_175":190},{"_166":192,"_175":193},{"_166":282,"_175":195},{"_166":197,"_175":198},{"_166":200,"_35":201},{"_166":197,"_35":203},{"_166":280,"_35":205},{"_166":183,"_35":207},{"_166":186,"_35":209},{"_166":189,"_35":211},{"_213":300},{"_215":216,"_217":301},[302],{"_215":220,"_221":222,"_223":303},[304,305,306,307,308],{"_221":226,"_227":228,"_35":229,"_230":231},{"_221":226,"_227":233,"_35":234,"_230":89},{"_221":226,"_227":236,"_35":237,"_230":238},{"_221":226,"_227":169,"_35":34,"_230":240},{"_221":226,"_227":282,"_35":309,"_230":310},"Reviews",5,"review","actionData","errors"]

Rate & Review

MCP directory API