AI导哈

电影数据协议服务器

一个集成TMDB API和OpenAI Apps SDK的MCP服务器，用于AI驱动的电影查询、推荐和可视化展示。

  • by SergioDeIscarValera
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 SergioDeIscarValera/tmdb-mcp-server

使用说明

TMDB MCP服务器

A. 模型上下文协议（MCP） 无缝集成 电影数据库（TMDB）API 随着 OpenAI应用软件开发工具包该项目使AI代理（如ChatGPT或Claude中的代理）能够调用与电影相关的查询工具，渲染交互式视觉组件（如旋转木马、细节卡和预告片缩略图），同时遵守OpenAI的设计准则，以获得原生对话体验。

该服务器专为尝试MCP的开发人员而设计，为人工智能驱动的电影发现、推荐和媒体浏览提供支持。它被设计为模块化、可扩展和生产就绪，重点是干净的架构和可重用性。

备注：此项目需要 TMDB API密钥 （免费版可用）。设置它 .env 作为 TMDB_API_KEY=your_key_here.

目的

该项目的核心目标是将TMDB的丰富电影数据与MCP连接起来，使AI模型能够：

  • 查询和发现：搜索电影、演员、流派和趋势。
  • 可视化结果：渲染UI组件，如搜索结果的旋转木马、详细视图和可点击的预告片缩略图。
  • 连锁行动：工具返回结构化数据（如JSON ID），供AI链接调用（如搜索）→ 获取详细信息→ 放映预告片）。
  • 增强人工智能工作流程非视觉工具为推理提供原始数据，而视觉工具则在人工智能聊天中创造引人入胜的在线体验。

此设置演示了MCP如何使用外部API扩展AI代理，遵循OpenAI的 设计指南 实现无缝集成——对话式、简单易用。

经过测试 MCPJam检查员 （用于MCP服务器的类似Postman的工具）用于本地调试、工具执行和LLM游乐场模拟。MCPJam支持STDIO/SSE/HTTP传输和多模型测试（例如Claude、GPT）。

特性

  • 核心工具:

    • getMovieIdByTitle：从标题中获取电影ID（用于链接的文本输出）。
    • getMovieGenres：列出可用于过滤的类型（JSON）。
    • searchActorsIds：搜索参与者并返回ID/名称（JSON）。
    • getReviews：获取指定语言（JSON）的电影评论。

  • 可视化工具（带UI组件）:

    • getMovieCarousel：搜索电影并渲染响应式旋转木马。
    • getMovieDetails：显示详细的电影信息（海报、演员、流派）。
    • getRecommendations：类似电影的轮播。
    • getMoviesByGenre：基于类型的电影发现转盘（使用 getMovieGenres 第一）。
    • getMoviesByActor：演员摄影转盘（使用 searchActorsIds 第一）。
    • getTrending：热门电影轮播（每日/每周）。
    • getUpcoming：即将发布的旋转木马。
    • getTrailer：可点击的预告片缩略图（在新选项卡中打开YouTube）。

  • 设计合规性：所有UI都使用自定义的OpenAI风格的CSS系统，具有亮/暗模式、间距比例和可访问性（WCAG 2.1）。

  • 测试与调试：与MCPJam Inspector兼容，用于可视化工具测试和LLM模拟。

技术栈

类别 技术
框架 xMCP （MCP服务器脚手架、工具/资源的自动注册）
API集成 TMDB API （v3，带Zod验证）
UI渲染 MCP用户界面 (@mcp-ui/server 对于rawHtml资源）
设计系统 自定义OpenAI Apps SDK CSS（颜色、间距、排版、阴影变量）
验证 萨德 （输入/输出模式）
环境 TypeScript、Node.js 20+、HTTP传输（可配置为STDIO）
测试 MCPJam检查员 （本地MCP调试，LLM操场）
部署 兼容Vercel/Next.js（通过xMCP适配器）

项目结构

.
├── package.json          # Dependencies and scripts
├── package-lock.json     # Lockfile
├── README.md            # You are here
├── src/
│   ├── prompts/         # MCP prompts (e.g., review-code.ts)
│   ├── resources/       # UI widgets (rawHtml components)
│   │   └── (movies)/
│   │       ├── [query]/     # Dynamic: carousel.ts (reusable for searches)
│   │       └── [movieId]/  # Dynamic: details.ts, trailer.ts
│   ├── services/        # API logic (tmdbService.ts with Zod schemas)
│   ├── styles/          # Design system (openaiDesing.ts)
│   └── tools/           # MCP tools (endpoints, e.g., getMovieCarousel.ts)
├── tsconfig.json        # TypeScript config
├── xmcp.config.ts       # xMCP configuration (HTTP transport, paths)
└── xmcp-env.d.ts        # Type declarations

快速开始

先决条件

  • Node.js 20+。
  • TMDB API密钥（设置在 .env).

安装

  1. 克隆仓库：

    git clone https://github.com/SergioDeIscarValera/tmdb-mcp-server.git
cd tmdb-mcp-server

  2. 安装依赖项：

    npm install

  3. 设置 .env:

    TMDB_API_KEY=your_tmdb_api_key_here

  4. 在开发中运行：

    npm run dev
    • 服务器启动时间 http://localhost:3001/mcp.

使用MCPJam检查员进行测试

  1. 安装MCPJam检查器：

    npx @mcpjam/inspector@beta
    • 在浏览器中打开进行视觉测试。

  2. 连接您的服务器：

    • 添加HTTP服务器： http://localhost:3001/mcp.
    • 测试工具（例如。， getMovieCarousel)、资源和提示。
    • 使用LLM游乐场模拟AI通话。

用法示例

通过以下方式连接到Cursor/Claude桌面 mcp.json:

{
  "mcpServers": {
    "tmdb-mcp-server": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

提示：“播放《盗梦空间》电影的旋转木马。”

  • AI呼叫 getMovieCarousel → 渲染视觉旋转木马。

API端点和工具

所有工具均通过xMCP自动注册。关键示例：

工具 描述 输入 输出
getMovieCarousel 搜索电影→ 旋转木马UI query: string 视觉转盘
getMovieDetails 电影详情→ 卡片用户界面 movieId: number 视觉细节
getRecommendations 类似电影→ 旋转木马 movieId: number 视觉转盘
getMovieIdByTitle 标题→ ID title: string 文本ID（例如“27205”）
getReviews 评论→ JSON movieId: number, language: string 文本JSON
getTrailer 拖车缩略图→ 可点击UI movieId: number 视觉缩略图（打开YouTube）

完整列表在 src/tools/.

部署

  • 维塞尔：使用xMCP的Next.js适配器(npx init-xmcp@latest 使用Next.js）。
  • 构建: npm run build → 部署 dist/http.js.
  • 环境变量：设置 TMDB_API_KEY 在生产中。

许可证

这个项目是开源的，可以自由使用、修改和分发，没有任何限制。欢迎您出于任何目的复制、改编或构建它。对原作者的提及或赞扬， 塞尔吉奥·德·伊斯卡尔·瓦莱拉非常感谢，但不是必需的。

致谢

欢迎通过GitHub贡献、报告问题或提出改进建议！ 🚀

相关 MCP