bangumi-mcp

Roxy Plugin API v2 プラグイン。Bangumi 公式 API を使用して、コレクションリストのページネーションクエリ、単一エントリの正確な進捗取得、「視聴中/視聴済み」の設定、エピソードインターフェースによるアニメ視聴進捗のエピソードごとの更新、および AniList の予定放送時間に基づく視聴中アニメの新エピソードの能動的通知を行います。

セキュリティ境界

• https://api.bgm.tv および https://graphql.anilist.co のみに接続し、公式要件に準拠した User-Agent を使用します。

• Bangumi Access Token と AniList Access Token は Roxy plugin-data の config.local.toml からのみ読み取り、リポジトリ、ログ、ツール結果には書き込みません。

• すべてのリモート書き込みは、作品名と対象ステータス/エピソード番号を含むプレビューを生成します。確認記録は単回使用で、10 分後に期限切れとなります。

• 完全なコレクションクエリまたは累積読み取りが 100 件に達した場合、まず読み取り専用のクエリ範囲と予想リクエスト数を表示し、このラウンド後の逐次確認を待ちます。

• アニメ進捗は PATCH /v0/users/-/collections/{subject_id}/episodes と明確なエピソード ID を使用し、エントリレベルの 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 のパスワードではありません。

そのディレクトリにパーミッション 0600 の config.local.toml を作成：

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 Skill と MCP ツールが読み込まれます。

放送通知

• 通知の基準は AniList の nextAiringEpisode.airingAt で、精度は分単位に正規化されます。これは予定放送時刻を示し、ストリーミング、字幕、またはソースが既に利用可能であることを意味するものではありません。

• notify_before_minutes=0 は予定放送時刻から配信を待機します。0 から 1440 の整数で設定し、事前通知を行えます。

• 通知時刻に達すると、Roxy は次の proactive tick でイベントを読み取ります。Gate、Judge、セッションのビジー状態、またはチャンネルの状態により、メッセージが数分遅れる可能性があります。

• プラグインは Bangumi で「視聴中」とマークされたアニメのみを処理し、通知生成前にエピソードインターフェースでそのエピソードがまだ「視聴済み」とマークされていないことを確認します。

• AniList と Bangumi には共通の安定した ID はありません。自動マッチングは一意の厳密な候補のみを受け入れます。失敗した場合は、プライベート設定の media_id_overrides で AniList media ID を明示的に指定できます。

• anime_push を有効にするには、AniList Access Token を設定する必要があります。これは上記の plugin-data プライベートファイルにのみ書き込まれ、コマンドライン、会話、リポジトリには配置しないでください。

• キャッシュ、配信待ちイベント、ACK は同じ plugin-data ディレクトリ内の anime_updates.db に保存されます。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 も必要としません。