Wizzy Mcp Tmdb

wizzy-mcp-tmdb

项目概述和用途

wizzy-mcp-tmdb 项目是一个使用 JavaScript 实现的 MCP（Model Context Protocol）服务，提供用于搜索和检索 The Movie Database（TMDB）信息的工具。它允许 AI 客户端通过标准化协议访问电影、电视节目和人物数据。

主要功能

• 搜索电影：使用 search_tmdb 工具跨电影、电视节目和人物进行多类型搜索。
• 获取详情：使用 get_tmdb_details 工具获取特定条目的详细信息。
• 热门内容：使用 trending_all 工具检索所有媒体类型中的热门内容。

安装

先决条件

• Node.js 18 或更高版本（需要支持全局 fetch）
• 管理员提供的 TMDB API 密钥（Bearer 令牌），用于访问 TNL TMDB 代理（production-api.tnl.one）

设置

1. 克隆仓库并进入项目目录。

2. 安装依赖：

   npm install
   

3. 将 TMDB API 密钥设置为环境变量：

   • 在 Windows PowerShell 中：

     $env:TMDB_AUTH_TOKEN="YOUR_TNL_PROXY_BEARER_TOKEN"
     

   • 在 macOS/Linux 中：

     export TMDB_AUTH_TOKEN="YOUR_TNL_PROXY_BEARER_TOKEN"
     

使用方法

启动 MCP 服务

启动服务：

npm start

服务通过 stdio 通信，应在兼容 MCP 的客户端（例如 IDE 或聊天客户端）中配置命令 node mcp-tmdb-server.js 和环境变量 TMDB_AUTH_TOKEN。

MCP 集成示例

以下代码片段展示了如何集成 MCP 工具：

搜索电影

// Example MCP tool call for searching
{
  "method": "tools/call",
  "params": {
    "name": "search_tmdb",
    "arguments": {
      "query": "dune",
      "page": 1,
      "language": "en-US",
      "include_adult": false
    }
  }
}

获取电影详情

// Example MCP tool call for getting details
{
  "method": "tools/call",
  "params": {
    "name": "get_tmdb_details",
    "arguments": {
      "type": "movie",
      "id": 438631,
      "append": "credits,images"
    }
  }
}

获取热门内容

// Example MCP tool call for trending content
{
  "method": "tools/call",
  "params": {
    "name": "trending_all",
    "arguments": {
      "time_window": "day",
      "page": 1,
      "language": "en-US"
    }
  }
}

MCP 客户端集成

要将此 MCP 服务集成到你的 MCP 客户端（例如 IDE 或兼容的聊天客户端）中，请按以下步骤操作：

1. 如有需要，安装 npm 包：

   npm install -g wizzy-mcp-tmdb
   

2. 在 MCP 客户端中创建或更新 mcp.json 文件，并使用以下配置：

   {
     "mcpServers": {
       "tmdb": {
         "command": "npx",
         "args": ["wizzy-mcp-tmdb"],
         "env": {
           "TMDB_AUTH_TOKEN": "YOUR_TNL_PROXY_BEARER_TOKEN"
         },
         "alwaysAllow": [
           "get_watch_providers",
           "discover_tv",
           "discover_by_provider"
         ]
       }
     }
   }
   

   注意：目前可以将 TMDB_AUTH_TOKEN 设置为任意值，因为 TMDB API 调用是免费的，且不要求必须进行身份验证。

测试策略

该项目使用 Jest 进行全面测试，包括：

• 单元测试：验证各个处理函数、输入验证和响应格式（参见 tests/unit/handlers.test.js）。
• 集成测试：使用模拟响应测试 API 交互、错误处理和网络故障（参见 tests/integration/api.test.js）。
• 协议测试：确保符合 MCP 协议，包括工具列表和调用（参见 tests/protocol/mcp.test.js）。

运行测试套件：

npm test

监视模式：

npm run test:watch

项目结构

wizzy-mcp-tmdb/
├── mcp-tmdb-server.js          # Main MCP server implementation
├── package.json                # Project configuration and dependencies
├── MCP_GUIDE.md                # Detailed MCP integration guide
├── babel.config.cjs            # Babel configuration for Jest
├── tests/
│   ├── unit/
│   │   └── handlers.test.js    # Unit tests for handlers
│   ├── integration/
│   │   └── api.test.js         # Integration tests for API calls
│   └── protocol/
│       └── mcp.test.js         # MCP protocol compliance tests
└── tests/fixtures/             # Mock data for tests
    ├── movieDetails.json
    ├── searchMultiResponse.json
    └── trendingAllResponse.json

贡献

欢迎贡献！请遵循以下指南：

1. Fork 此仓库。
2. 创建功能分支。
3. 进行更改并添加测试。
4. 确保所有测试通过。
5. 提交 pull request。

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

致谢

• 感谢 The Movie Database（TMDB）提供 API。
• 使用 Model Context Protocol SDK 构建。

联系方式

如有疑问或需要支持，请在 GitHub 上提交 issue。