Baomihua Formatter MCP Server

Aвтономный Node.js MCP-сервер для просмотра и работы с медиафайлами в OpenList и CloudDrive2, а также для запросов метаданных фильмов и сериалов из TMDB. Сервер общается через MCP stdio и хранит учётные данные для хранилища и TMDB в локальной конфигурации окружения, а не в описаниях инструментов или в документации, закоммиченной в репозиторий.

Требования

• Node.js 20 или новее (package.json объявляет engines.node >=20.0.0).

• Сетевой доступ к настроенному endpoint OpenList и/или CloudDrive2 при использовании этих бэкендов.

• Учётные данные TMDB при использовании инструментов TMDB.

Установка

Из каталога проекта сервера:

Set-Location C:\path\to\baomihua-formatter-mcp-server
Copy-Item .env.example .env
npm install

Отредактируйте локальный .env, указав нужные для вашего окружения endpoint’ы и учётные данные. .env игнорируется Git; не коммитьте его, не вставляйте секреты в этот README и не включайте реальные учётные данные в конфигурацию MCP-клиента, которая попадает в систему контроля версий.

Поддерживаемые ключи конфигурации описаны в .env.example, в том числе:

• OPENLIST_URL, OPENLIST_USERNAME, OPENLIST_PASSWORD и необязательный OPENLIST_OTP_CODE;

• CLOUDDRIVE2_URL, CLOUDDRIVE2_TOKEN и CLOUDDRIVE2_TLS;

• TMDB_API_KEY или TMDB_TOKEN, а также необязательные TMDB_LANGUAGE и TMDB_PROXY;

• STORAGE_CONCURRENCY, UPLOAD_CONCURRENCY и STORAGE_MAX_CONCURRENCY;

Запуск MCP-сервера

npm-скрипт запускает stdio-сервер:

npm run mcp

Процесс предназначен для запуска MCP-клиентом, поэтому обычный трафик протокола передаётся через stdin/stdout. При встраивании сервера не выводите диагностику в stdout.

Типовая запись для MCP-клиента

Используйте абсолютный путь к исполняемому файлу Node и абсолютный путь к серверу. Замените только примеры путей и настройте секреты через локальный .env сервера; эта запись намеренно не содержит учётных данных:

{
  "mcpServers": {
    "baomihua-formatter": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\path\\to\\baomihua-formatter-mcp-server\\server.js"
      ]
    }
  }
}

MCP-клиент должен запускать запись в контексте, где проект сервера имеет свой файл .env. Эквивалентная команда оболочки:

& 'C:\Program Files\nodejs\node.exe' 'C:\path\to\baomihua-formatter-mcp-server\server.js'

Группы инструментов и их семантика

Навигация по хранилищу

Оба бэкенда хранилища предоставляют прямое перечисление и рекурсивное сканирование:

• openlist_list / clouddrive2_list перечисляют только прямых потомков.

• openlist_scan / clouddrive2_scan рекурсивно собирают всех потомков и принимают ограниченные параметры concurrency и continue_on_error.

• openlist_stat / clouddrive2_stat проверяют один конкретный путь.

• openlist_search / clouddrive2_search ищут записи внутри пути.

Операции сканирования и загрузки каталогов используют ограниченную конкурентность. Держите конкурентность в пределах настроенного на сервере максимума и оставляйте continue_on_error false, если только вы намеренно не допускаете частичное выполнение.

Операции с файлами

OpenList и CloudDrive2 предоставляют инструменты для создания каталогов, переименования, удаления файлов/каталогов, перемещения, копирования и загрузки файлов/каталогов. CloudDrive2 также предоставляет clouddrive2_get_download_url.

Каждый изменяющий инструмент требует confirm: true. Агент или MCP-клиент должен сначала показать пользователю точные предлагаемые пути, имена, места назначения, политику обработки конфликтов и разрушающие последствия. Сервер отклоняет неподтверждённые изменения. continue_on_error — это не механизм подтверждения; он лишь управляет тем, продолжит ли ограниченная партия выполнение после сбоя конкретного элемента.

TMDB

Сервер предоставляет tmdb_search_movie, tmdb_search_tv, tmdb_get_movie_details, tmdb_get_tv_details и tmdb_get_season_details. Эти инструменты возвращают кандидатов или метаданные; они не переименовывают файлы.

Извлечение названия/года/сезона/эпизода/качества из имени файла намеренно является ответственностью Агента. В рабочих процессах форматирования медиа осматривайте полный путь в хранилище, извлекайте эти поля самостоятельно, запрашивайте кандидатов из TMDB, сверяйте выбранный результат с детальными данными и просите пользователя устранить неоднозначность одноимённых кандидатов перед тем, как предлагать изменение.

Рекомендованный рабочий процесс

1. Выполните вызов *_list соответствующего бэкенда для прямой навигации или *_scan для рекурсивного сбора.

2. Сохраняйте исходные пути и независимо извлекайте название, год, сезон, эпизод, качество и маркеры субтитров.

3. Найдите кандидатов в TMDB, сравните их с извлечёнными данными и запросите детали для выбранного ID.

4. Покажите пользователю полное предложение по переименованию/перемещению/копированию/удалению/загрузке и дождитесь явного подтверждения.

5. Выполните подтверждённое изменение с confirm: true.

6. Проверьте результат повторным вызовом list, stat или scan и сообщите об успешных операциях, пропусках и ошибках.

Разработка

Запустите тестовый набор из этого каталога:

npm test

Проект является приватным, используете ESM и не имеет зависимости во время выполнения от старого CLI форматтера. Не включайте в коммиты учётные данные и сгенерированные логи.