bangumi-mcp

Complemento de la API v2 de Roxy Plugin, que utiliza la API oficial de Bangumi para consultar listas de colecciones paginadas, consultar el progreso exacto de un solo elemento, establecer "viendo/ya visto", actualizar el progreso de visualización de anime por episodios a través de la interfaz de capítulos, y recordar activamente los nuevos episodios de anime que se están viendo según el horario de emisión planificado de AniList.

Límites de seguridad

• Solo se conecta a https://api.bgm.tv y https://graphql.anilist.co, utilizando un User-Agent que cumple con los requisitos oficiales.

• El token de acceso de Bangumi y el token de acceso de AniList solo se leen desde config.local.toml en los datos del plugin de Roxy, y no se escriben en el repositorio, registros ni resultados de herramientas.

• Todas las escrituras remotas primero generan una vista previa que contiene el nombre de la obra y el estado/objetivo de episodios; se confirma el uso único y caduca después de 10 minutos.

• Cuando la consulta completa de colecciones o la lectura acumulada alcanza las 100 entradas, primero se muestra el alcance de la consulta de solo lectura y el número estimado de solicitudes, y se espera la confirmación palabra por palabra después de esta ronda.

• El progreso del anime se actualiza usando PATCH /v0/users/-/collections/{subject_id}/episodes y los identificadores de episodios explícitos, no usando ep_status a nivel de elemento para modificar el número de episodios.

Related MCP server: Anitabi MCP Server

Instalación

Roxy solo instala instantáneas confirmadas en Git. Ejecute desde el repositorio de Roxy:

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

La salida de la instalación proporcionará el directorio de datos, que por defecto es:

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

Después de iniciar sesión en Bangumi, vaya a la Página de token de acceso de Bangumi para generar un token personal. Este token es la credencial de acceso a la API de la cuenta, no la contraseña de Bangumi.

Cree config.local.toml con permisos 0600 en ese directorio:

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

Los usuarios que ya han instalado una versión anterior y que han establecido explícitamente user_agent en la configuración local, después de actualizar el complemento, también deben cambiarlo al nuevo identificador anterior. No coloque el token en los argumentos de la línea de comandos o en los mensajes de chat. Después de la configuración, verifique:

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

Roxy en ejecución observa los cambios de configuración y publica una nueva generación comprometida; las nuevas sesiones cargarán la habilidad bangumi y las herramientas MCP.

Recordatorios de emisión

• La base del recordatorio es nextAiringEpisode.airingAt de AniList, con precisión normalizada al minuto; indica la emisión planificada, no significa que el streaming, los subtítulos o la fuente ya estén disponibles.

• notify_before_minutes=0 comienza a esperar la entrega desde el momento de emisión planificado; se puede establecer como un entero entre 0 y 1440 para recordar con anticipación.

• Cuando llega el momento del recordatorio, Roxy lee el evento en el siguiente tick proactivo. Gate, Judge, sesión ocupada o el estado del canal pueden retrasar el mensaje unos minutos.

• El complemento solo procesa anime marcado como "viendo" en Bangumi, y antes de generar el recordatorio, confirma a través de la interfaz de episodios que ese episodio aún no está marcado como "ya visto".

• AniList y Bangumi no tienen un ID estable común. La coincidencia automática solo acepta un candidato estrictamente único; en caso de fallo, se puede especificar explícitamente el ID de AniList media en media_id_overrides de la configuración privada.

• Para habilitar anime_push, se debe configurar un token de acceso de AniList; solo se puede escribir en el archivo privado de datos del complemento mencionado, no en la línea de comandos, conversaciones o repositorio.

• El caché, los eventos pendientes de entrega y los ACK se guardan en anime_updates.db en el mismo directorio de datos del complemento. Desactivar anime_push.enabled no elimina esa base de datos.

Documentos de diseño

• Diseño de la lista de colecciones de usuarios

• Intención de consulta de colecciones y límites de visualización

• Límites de confirmación de consultas completas y grandes de colecciones

• Diseño de recordatorios de emisión de seguimiento de anime

Verificación de desarrollo

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

Todas las pruebas unitarias utilizan sesiones HTTP falsas, no acceden a cuentas reales de Bangumi y no requieren un token de acceso.