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는 구성 변경을 감시하고 새로운 커밋된 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도 필요하지 않습니다.