bangumi-mcp

Плагин Roxy Plugin API v2, использующий официальный API Bangumi для постраничного запроса списка коллекций, точного прогресса по отдельным элементам, установки статусов «смотрю/просмотрено», обновления прогресса просмотра аниме по эпизодам через интерфейс глав, а также активного уведомления о новых сериях аниме, которые вы смотрите, на основе запланированного времени выхода по AniList.

Границы безопасности

• Подключается только к https://api.bgm.tv и https://graphql.anilist.co, используя User-Agent, соответствующий официальным требованиям.

• Bangumi Access Token и AniList Access Token считываются только из config.local.toml в plugin-data Roxy, не записываются в репозиторий, логи или результаты инструментов.

• Все удаленные записи сначала генерируют предварительный просмотр с названием произведения и целевым статусом/номером серии; подтверждение действует для одного использования и истекает через 10 минут.

• При полном запросе коллекции или накоплении 100 прочитанных записей сначала отображается область запроса только для чтения и предполагаемое количество запросов, а затем ожидается посимвольное подтверждение после текущего раунда.

• Прогресс аниме обновляется с помощью PATCH /v0/users/-/collections/{subject_id}/episodes и явных идентификаторов глав, без использования ep_status на уровне элемента для изменения количества серий аниме.

Related MCP server: Anitabi MCP Server

Установка

Roxy устанавливает только зафиксированные снимки Git. Выполните из репозитория Roxy:

.venv/bin/python main.py plugin-install \
  --source https://github.com/roxy-plugins/bangumi-mcp.git \
  --marketplace github

Вывод установки укажет каталог данных, по умолчанию:

<workspace>/plugin-data/bangumi-github/

После входа в Bangumi перейдите на страницу Bangumi Access Token для генерации личного токена. Этот токен является учетными данными API для доступа к аккаунту, а не паролем Bangumi.

В этом каталоге создайте config.local.toml с правами доступа 0600:

access_token = "<在此填写 Bangumi Access Token>"
user_agent = "roxy-plugins/bangumi-mcp/0.5.0 (https://github.com/roxy-plugins/bangumi-mcp)"

[anime_push]
enabled = true
notify_before_minutes = 0
display_timezone = "Asia/Shanghai"
anilist_token = "<在此填写 AniList Access Token>"

# 只有自动匹配失败时才需要配置；左侧是 Bangumi subject ID。
[anime_push.media_id_overrides]
"501963" = 123456

Пользователи, установившие старую версию и явно указавшие user_agent в локальной конфигурации, после обновления плагина также должны изменить его на указанный выше новый идентификатор. Не помещайте токен в аргументы командной строки или сообщения чата. После настройки проверьте:

.venv/bin/python main.py plugin-doctor bangumi@github

Запущенный Roxy отслеживает изменения конфигурации и публикует новое committed generation; новый сеанс загрузит навык bangumi и инструменты MCP.

Уведомления о выходе

• Уведомления основаны на nextAiringEpisode.airingAt из AniList, точность нормализована до минут; это указывает запланированное время выхода, а не доступность стриминга, субтитров или источника.

• notify_before_minutes=0 начинает ожидание доставки с момента запланированного выхода; можно установить целое число от 0 до 1440 для предварительного уведомления.

• По достижении времени уведомления Roxy считывает событие при следующем proactive tick. Gate, Judge, занятость сеанса или состояние канала могут задержать сообщение на несколько минут.

• Плагин обрабатывает только аниме, отмеченные в Bangumi как «смотрю», и перед генерацией уведомления через интерфейс глав подтверждает, что эта серия еще не отмечена как «просмотрено».

• У AniList и Bangumi нет общего стабильного идентификатора. Автоматическое сопоставление принимает только единственного строгого кандидата; при неудаче можно явно указать media ID AniList в media_id_overrides приватной конфигурации.

• Для включения anime_push необходимо настроить AniList Access Token; он может быть записан только в указанный выше приватный файл plugin-data, не помещайте его в командную строку, диалог или репозиторий.

• Кэш, ожидающие доставки события и ACK сохраняются в anime_updates.db в том же каталоге plugin-data. Отключение anime_push.enabled не удаляет эту базу данных.

Документация по дизайну

• Дизайн списка коллекций пользователя

• Намерение запроса коллекции и границы отображения

• Границы подтверждения полного и массового запроса коллекции

• Дизайн уведомлений о выходе новых серий

Разработка и проверка

python -m pip install -r mcp/requirements.txt -r requirements-dev.txt
pytest
PYTHONPATH=/path/to/plugin-contracts \
  python -m akashic_plugin_contracts check plugin.py

Модульные тесты используют поддельные HTTP-сессии, не обращаются к реальным аккаунтам Bangumi и не требуют Access Token.