Model Context Protocol (MCP)

В TorrPlay встроен сервер Model Context Protocol (MCP). С его помощью ИИ-ассистенты (Claude Desktop, Cursor и другие агенты) могут напрямую управлять запущенным TorrPlay.

Через MCP ассистенты умеют просматривать раздачи, проверять статус стриминга и кэша, добавлять или удалять торренты, а также генерировать ссылки на видео в диалоге.

Архитектура

Сервер MCP запускается отдельной командой CLI:

torrplay mcp [flags]

• Изоляция процессов: MCP-сервер работает с TorrPlay через HTTP/REST API и не обращается напрямую к файлам базы данных, что исключает блокировки и конфликты.
• Транспорты:
  • stdio (по умолчанию): обмен данными через стандартные потоки ввода/вывода (stdin/stdout), подходит для локальных клиентов вроде Claude Desktop.
  • sse: передача событий Server-Sent Events по протоколу HTTP с привязкой к локальному адресу loopback.

Параметры командной строки и переменные окружения

Доступные возможности

Инструменты (Tools)

• list_torrents: вывод списка активных и сохранённых торрентов со статусом, прогрессом и перечнем файлов.
• get_torrent: получение подробных метаданных, состояния кэша частей и структуры файлов выбранного торрента.
• add_torrent: добавление торрента по magnet-ссылке или хешу.
• delete_torrent: удаление торрента и освобождение занятой им оперативной памяти.
• update_torrent: изменение метаданных (название, категория, обложка).
• get_stream_url: создание прямых HTTP-ссылок на видео с действующими токенами воспроизведения.
• preload_torrent: запуск или замена предзагрузки файла, в том числе возле сохранённой позиции просмотра.
• get_preload_status: получение статуса предзагрузки, прогресса, числа пиров и скорости.
• cancel_preload: отмена предзагрузки с освобождением памяти и приоритетов частей.
• get_memory_stats: использование и лимиты кэша в оперативной памяти, статистика буферов частей торрента.
• get_torrent_stats: скорость загрузки, пиры, потоки чтения и состояние частей выбранного торрента.
• get_system_info: версия, сборка, время работы и тип развёртывания TorrPlay.
• get_system_logs: поиск по сохранённым логам и фильтрация по уровню.
• get_system_metrics: текущая активность торрентов и скорость передачи данных.

Ресурсы (Resources)

• torrplay://torrents: актуальный список всех торрентов библиотеки.
• torrplay://torrents/{hash}: подробное состояние конкретного торрента.
• torrplay://system/memory: статистика использования памяти под кэш частей и вытеснения LRU.
• torrplay://system/info: версия, сборка, время работы и тип развёртывания TorrPlay.
• torrplay://system/logs: последние записи из кольцевого буфера логов.
• torrplay://system/metrics: текущая активность торрентов и скорость передачи данных.

Шаблоны запросов (Prompts)

• find_playable_file: поиск основного видеофайла в раздаче и подготовка ссылки для воспроизведения.
• stream_diagnostics: анализ пиров, частей, потоков чтения и памяти для диагностики остановок воспроизведения.

Аутентификация

MCP-клиент передаёт TORRPLAY_TOKEN во всех запросах как Bearer-токен. Если аутентификация включена, выберите в TorrPlay тип Bearer и укажите административный JWT, полученный через /oauth/token. Токены воспроизведения и Stremio действуют только для медиаконтента и не подходят для инструментов управления. Встроенный MCP-клиент не умеет отправлять данные Basic Authentication.

Настройка в Claude Desktop

Чтобы подключить TorrPlay MCP к Claude Desktop, добавьте следующую конфигурацию в файл claude_desktop_config.json:

{
  "mcpServers": {
    "torrplay": {
      "command": "/usr/local/bin/torrplay",
      "args": ["mcp"],
      "env": {
        "TORRPLAY_URL": "http://127.0.0.1:8090",
        "TORRPLAY_TOKEN": "your-jwt-token-if-enabled"
      }
    }
  }
}

Укажите вместо /usr/local/bin/torrplay путь к исполняемому файлу TorrPlay в вашей системе. После сохранения перезапустите Claude Desktop — инструменты TorrPlay появятся в списке доступных действий.

Запуск транспорта SSE

Для клиентов и агентов, работающих по протоколу SSE:

torrplay mcp -transport sse -addr 127.0.0.1:8091 -url http://127.0.0.1:8090