bangumi-mcp

Ein Plugin für die Roxy Plugin API v2, das mit der offiziellen Bangumi-API die Sammlungsliste seitenweise abfragt, den genauen Fortschritt eines einzelnen Eintrags ermittelt, den Status „wird geschaut/gesehen“ setzt, über die Episoden-Schnittstelle den Anime-Ansehfortschritt Episode für Episode aktualisiert und gemäß der geplanten Ausstrahlungszeit von AniList proaktiv an neue Episoden der gerade geschauten Anime erinnert.

Sicherheitsgrenzen

• Es verbindet sich nur mit https://api.bgm.tv und https://graphql.anilist.co und verwendet einen User-Agent, der den offiziellen Anforderungen entspricht.

• Bangumi Access Token und AniList Access Token werden nur aus config.local.toml in den Roxy plugin-data gelesen und nicht in Repositorys, Protokolle oder Tool-Ergebnisse geschrieben.

• Alle Remote-Schreibvorgänge erzeugen zuerst eine Vorschau mit dem Werktitel und dem Zielstatus bzw. der Ziel-Episodenanzahl. Die Bestätigung gilt für eine einmalige Verwendung und verfällt nach 10 Minuten.

• Bei einer vollständigen Sammlungsabfrage oder wenn die kumulierte Anzahl gelesener Einträge 100 erreicht, werden zuerst der schreibgeschützte Abfragebereich und die voraussichtliche Anzahl der Anfragen angezeigt; anschließend wird nach dieser Runde auf eine ausdrückliche Bestätigung gewartet.

• Der Anime-Fortschritt verwendet PATCH /v0/users/-/collections/{subject_id}/episodes und explizite Episoden-IDs; der ep_status auf Eintragsebene wird nicht verwendet, um die Anime-Episodenanzahl zu ändern.

Related MCP server: Anitabi MCP Server

Installation

Roxy installiert nur Git-committete Snapshots. Führen Sie im Roxy-Repository aus:

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

Die Installationsausgabe gibt das Datenverzeichnis an. Standardmäßig ist das:

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

Nachdem Sie sich bei Bangumi angemeldet haben, rufen Sie die Bangumi Access Token-Seite auf, um ein persönliches Token zu erzeugen. Dieses Token ist die API-Zugangsberechtigung für das Konto, nicht das Bangumi-Passwort.

Erstellen Sie in diesem Verzeichnis eine config.local.toml mit den Berechtigungen 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

Benutzer einer bereits installierten älteren Version, die in ihrer lokalen Konfiguration user_agent explizit gesetzt haben, müssen diesen nach dem Plugin-Update auf die oben genannte neue Kennung ändern. Legen Sie das Token nicht in Befehlszeilenargumente oder Chat-Nachrichten. Prüfen Sie nach der Konfiguration:

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

Ein laufendes Roxy beobachtet Konfigurationsänderungen und veröffentlicht eine neue committed generation. Neue Sitzungen laden den bangumi Skill und die MCP-Tools.

Ausstrahlungserinnerungen

• Die Erinnerung basiert auf dem nextAiringEpisode.airingAt-Feld von AniList, wobei die Genauigkeit auf Minuten normalisiert wird. Es gibt den geplanten Ausstrahlungszeitpunkt an, nicht dass Streaming, Untertitel oder Quellen bereits verfügbar sind.

• notify_before_minutes=0 wartet ab dem geplanten Ausstrahlungszeitpunkt auf die Zustellung; es kann auf eine ganze Zahl zwischen 0 und 1440 gesetzt werden, um früher zu erinnern.

• Sobald der Erinnerungszeitpunkt erreicht ist, liest Roxy beim nächsten proaktiven Tick die Ereignisse. Gate, Judge, eine beschäftigte Sitzung oder der Kanalstatus können die Nachricht um einige Minuten verzögern.

• Das Plugin verarbeitet nur Anime, die bei Bangumi als „wird geschaut“ markiert sind, und bestätigt vor dem Generieren der Erinnerung über die Episoden-Schnittstelle, dass diese Episode noch nicht als „gesehen“ markiert ist.

• AniList und Bangumi haben keine gemeinsame stabile ID. Die automatische Zuordnung akzeptiert nur einen eindeutigen strikten Kandidaten. Bei einem Fehlschlag kann in media_id_overrides in der privaten Konfiguration eine explizite AniList-Media-ID angegeben werden.

• Zum Aktivieren von anime_push muss ein AniList Access Token konfiguriert sein. Es darf nur in die oben genannte private Datei in den Roxy plugin-data geschrieben werden, nicht in Befehlszeile, Konversation oder Repository.

• Cache, noch zuzustellende Ereignisse und ACKs werden in anime_updates.db im selben plugin-data-Verzeichnis gespeichert. Das Deaktivieren von anime_push.enabled löscht diese Datenbank nicht.

Design-Dokumente

• Design der Benutzersammlungsliste

• Abfrageintention und Anzeigegrenzen für Sammlungen

• Bestätigungsgrenzen für vollständige und große Sammlungsabfragen

• Design der Ausstrahlungserinnerungen für verfolgte Anime

Entwicklungsvalidierung

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

Die Komponententests verwenden ausschließlich gefälschte HTTP-Sitzungen, greifen nicht auf echte Bangumi-Konten zu und benötigen keine Access Tokens.