使用说明（Markdown 格式）

项目简介
- 本仓库实现了一个基于 MCP（Model Context Protocol）的服务器端，专门把 Overseerr 的媒体检索、请求、管理等能力暴露给 LLM 客户端。通过定义和暴露工具（Tools），LLM 可执行诸如搜索、请求、获取详情等操作，并且服务器内部具备缓存、重试、数据整合等机制，提升性能与稳定性。
主要功能点
- 实现 MCP 服务器核心功能：提供工具集（search_media、request_media、manage_media_requests、get_media_details）以供客户端通过 JSON-RPC 调用。
- Overseerr 集成：通过 Overseerr 的 API 实现媒体搜索、请求创建、请求管理、媒体详情查询等能力。
- 数据处理与丰富：支持结果的精简格式（compact/standard/full），并能在需要时附加额外的详细字段（包括剧集分季信息）。
- 缓存与重试：内置缓存机制以及对外部 API 的重试逻辑，提升响应速度与稳定性。
- 多传输协议支持：可通过 STDIO（标准输入输出）或 SSE/HTTP 传输与 MCP 客户端通信，方便在不同场景使用。
- 安全性与校验：对 Overseerr 的 URL、API key 进行格式校验，提供错误信息，增强使用时的自助排错能力。
安装步骤（简化版）
- 确认环境：Node.js 18 及以上。
- 获取代码：将仓库克隆到本地或服务器。
- 安装依赖并构建：
  - 安装依赖并构建：安装依赖后执行构建，生成可执行入口。
  - 构建完成后，会生成可以直接运行的入口文件（如 build/index.js）。
- 配置 Overseerr 连接信息：
  - 需要 Overseerr 的实例地址和 API Key，用于访问 Overseerr API。
- 启动方式（两种模式任选其一）：
  - STDIO 模式（默认）：
    - 运行入口：node build/index.js
    - 通过标准输入输出与 MCP 客户端通信，默认端口未暴露，适合在本地开发或与进程间通信搭配使用。
  - HTTP/SSE 模式（对外暴露 MCP 端点）：
    - 设置环境变量 HTTP_MODE=true，并可通过 PORT 指定端口（默认 8085）。
    - 启动后，通过 HTTP/MCP 通道可随时建立连接，常用于远程客户端接入。
- 配置 MCP 客户端（以下信息用于客户端配置，不需要服务端改动）：
  - MCP 客户端需要知道服务器的启动命令和参数，以便与 MCP 服务器建立连接。
  - 客户端配置示例（以 JSON 表示，供客户端使用；请在实际使用时按下述字段逐项填写）： { "serverName": "overseerr", "command": "node", "args": ["build/index.js"], "env": { "OVERSEERR_URL": "https://overseerr.example.com", "OVERSEERR_API_KEY": "your-api-key-here" } // 如使用 Docker 部署，请相应调整为 Docker 启动命令及环境变量 }
基本使用方法
- 启动服务后，LLM 通过 MCP 客户端与 MCP 服务器建立连接，调用以下工具进行交互：
  - search_media：用于在 Overseerr 中执行单次、批量或去重搜索，支持返回摘要、详细信息等字段。
  - request_media：根据需要发起媒体请求，可单项或批量请求，支持 4K、季数、服务器与根目录等选项，以及干运行模式。
  - manage_media_requests：对请求进行查看、列出、批准、拒绝或删除等管理操作。
  - get_media_details：获取媒体的详细信息，支持多条目批量查询与按 level(基本/标准/完整)及字段筛选输出。
- 常用流程示例（简述）
  - 1. 通过 search_media 的 dedupeMode，传入一组标题，服务器会批量判断在 Overseerr 的可用性与状态，返回可操作结果及附加字段。
  - 1. 通过 request_media 提交所需的媒体请求，可以选择自动确认的场景，并根据需要传入季数或 all。
  - 1. 通过 get_media_details 获取媒体的详细信息，以便在对话中给出更丰富的上下文。
- 通过 SSE/HTTP 传输，LLM 客户端可以持续接收来自 MCP 的响应、通知及更新。
重要配置与运行提示
- Overseerr URL 与 API Key 需通过环境变量传入，且必须有效，否则会无法访问 Overseerr API。
- 本实现包含缓存、重试和错误处理逻辑，遇到网络错误或 5xx 时会自动重试，提升鲁棒性。
- 通过设置 HTTP_MODE 与 PORT，可以将 MCP 服务器暴露为可远程访问的 HTTP/ SSE 服务。

关键词

信息