@xzxzzx/bilibili-mcp 1.3.8 → 1.4.0

package/README.md

@@ -28,7 +28,9 @@
   - [🌟 功能特性](#-功能特性)
     - [1. 视频总结 (`get_video_info`)](#1-视频总结-get_video_info)
     - [2. 评论总结 (`get_video_comments`)](#2-评论总结-get_video_comments)
-    - [3. 🛡️ 稳健性增强](#3-️-稳健性增强)
+    - [3. 视频转录 (`get_video_transcript`)](#3-视频转录-get_video_transcript)
+    - [4. 视频元数据 (`get_video_metadata`)](#4-视频元数据-get_video_metadata)
+    - [5. 行为说明与错误处理](#5-行为说明与错误处理)
   - [📋 环境要求](#-环境要求)
   - [🚀 安装方式](#-安装方式)
     - [🖱️ Cursor](#️-cursor)
@@ -85,12 +87,51 @@
 - 优先保留包含时间戳的评论（如 `05:20`），方便定位高能片段
 - 支持两种详细程度：
   - `brief`: 10 条热门评论速览
-  - `detailed`: 50 条热门评论 + 高赞连带回复
+  - `detailed`: 20 条热门评论 + 高赞连带回复
+- 可选参数：
+  - `limit`: 显式评论数量 `1-50`，覆盖 `detail_level` 的默认数量
+  - `sort`: 排序方式 `"hot"`（按热度，默认）或 `"time"`（按时间）
+  - `include_replies`: 是否包含高赞回复（默认 `true`）
+
+### 3. 视频转录 (`get_video_transcript`)
+- 返回纯字幕文本，按行合并
+- 支持指定偏好语言（默认按 `zh-Hans` > `ai-zh` > `zh-CN` > `zh-Hant` > `en` 优先级选择）
+- 可选参数：
+  - `preferred_lang`: 偏好字幕语言代码
+  - `fallback_to_description`: 字幕不可用时是否降级为视频描述（默认 `false`）
+- 默认不降级：无字幕时返回 `SUBTITLE_UNAVAILABLE` 错误
+- Cookie 失效时始终返回 `COOKIE_EXPIRED`，不静默降级
+
+### 4. 视频元数据 (`get_video_metadata`)
+- 返回视频标题、作者、时长、发布时间、描述、标签、播放/点赞/投币等统计信息
+- 不获取字幕或评论
+- 仅需 `bvid_or_url` 参数
+
+### 5. 行为说明与错误处理
 
-### 3. 🛡️ 稳健性增强
 - **Cookie 过期智能检测**：当字幕获取为空时自动验证登录状态，区分“无字幕视频”与“凭证失效”，并抛出明确的 `COOKIE_EXPIRED` 错误，避免静默降级。
 
----
+#### 无 Cookie 行为
+
+- 部分公开视频元数据（`get_video_metadata`）可能在未登录状态下工作。
+- 字幕（`get_video_info`、`get_video_transcript`）在未登录时可能无法获取、不完整或返回空结果。
+- 评论（`get_video_comments`）在未登录时可能不完整、被限流或返回空列表。
+- 不建议依赖无 Cookie 模式获取字幕或评论。
+
+#### Cookie 凭据来源
+
+- Cookie 凭据应通过 `.env` 文件、环境变量或凭据管理工具提供。
+- 支持的环境变量：`BILIBILI_SESSDATA`、`BILIBILI_BILI_JCT`、`BILIBILI_DEDEUSERID`。
+- **切勿**在源码、脚本、文档、测试、日志或示例中硬编码 Cookie 值。
+- 如果 Cookie 值曾出现在仓库历史中，应尽快到 Bilibili 账号设置中轮换/失效旧 Cookie。
+
+#### 预期错误码
+
+| 错误码 | 含义 | 调用方建议 |
+|--------|------|-----------|
+| `VALIDATION_ERROR` | 输入参数不合法 | 检查并修正 `bvid_or_url` 或其他参数 |
+| `COOKIE_EXPIRED` | Cookie 已失效或未登录 | 用户应更新/轮换 Bilibili 凭据 |
+| `SUBTITLE_UNAVAILABLE` | 视频无可用的字幕 | 对 `get_video_transcript` 可重试并设置 `fallback_to_description: true` |
 
 ## 📋 环境要求
 
@@ -405,6 +446,24 @@ bilibili-mcp config
   "name": "get_video_comments",
   "arguments": { "bvid_or_url": "BV1xx4x1x7xx", "detail_level": "brief" }
 }
+
+// 获取纯字幕文本（无字幕时返回错误）
+{
+  "name": "get_video_transcript",
+  "arguments": { "bvid_or_url": "BV1xx4x1x7xx" }
+}
+
+// 获取视频元数据
+{
+  "name": "get_video_metadata",
+  "arguments": { "bvid_or_url": "BV1xx4x1x7xx" }
+}
+
+// 获取评论（自定义数量+排序）
+{
+  "name": "get_video_comments",
+  "arguments": { "bvid_or_url": "BV1xx4x1x7xx", "limit": 5, "sort": "time", "include_replies": false }
+}
 ```
 
 ---

package/README_EN.md

@@ -23,7 +23,9 @@ View this document in [简体中文](./README.md)
   - [🌟 Features](#-features)
     - [1. Video Summarization (`get_video_info`)](#1-video-summarization-get_video_info)
     - [2. Comment Summarization (`get_video_comments`)](#2-comment-summarization-get_video_comments)
-    - [3. 🛡️ Robustness Enhancement](#3-️-robustness-enhancement)
+    - [3. Video Transcript (`get_video_transcript`)](#3-video-transcript-get_video_transcript)
+    - [4. Video Metadata (`get_video_metadata`)](#4-video-metadata-get_video_metadata)
+    - [5. Behavior and Error Handling](#5-behavior-and-error-handling)
   - [📋 Requirements](#-requirements)
   - [🚀 Installation](#-installation)
     - [🖱️ Cursor](#️-cursor)
@@ -80,12 +82,51 @@ Before proceeding with installation, please ensure you are familiar with [How to
 - Prioritizes comments with timestamps (e.g., `05:20`) for quick highlight location.
 - Supports two levels of detail:
   - `brief`: 10 popular comments summary.
-  - `detailed`: 50 popular comments + high-quality replies.
+  - `detailed`: 20 popular comments + high-quality replies.
+- Optional parameters:
+  - `limit`: Explicit comment count `1-50`, overrides `detail_level` default.
+  - `sort`: Sort order `"hot"` (default) or `"time"`.
+  - `include_replies`: Whether to include top replies (default `true`).
+
+### 3. Video Transcript (`get_video_transcript`)
+- Returns clean subtitle text, joined by newlines.
+- Supports preferred language selection (defaults to `zh-Hans` > `ai-zh` > `zh-CN` > `zh-Hant` > `en` priority).
+- Optional parameters:
+  - `preferred_lang`: Preferred subtitle language code.
+  - `fallback_to_description`: Fall back to video description if subtitles unavailable (default `false`).
+- By default, returns `SUBTITLE_UNAVAILABLE` error when no subtitles exist.
+- Cookie expiration always returns `COOKIE_EXPIRED`, never silently falls back.
+
+### 4. Video Metadata (`get_video_metadata`)
+- Returns video title, author, duration, publish date, description, tags, and stats (views, likes, coins, etc.).
+- Does not fetch subtitles or comments.
+- Only requires the `bvid_or_url` parameter.
+
+### 5. Behavior and Error Handling
 
-### 3. 🛡️ Robustness Enhancement
 - **Intelligent Cookie Expiration Detection**: Automatically verifies login status when subtitles are empty, distinguishing between "videos without subtitles" and "invalid credentials," and throwing a clear `COOKIE_EXPIRED` error to prevent silent degradation.
 
----
+#### Without Cookie
+
+- Some public video metadata (`get_video_metadata`) may work without authentication.
+- Subtitles (`get_video_info`, `get_video_transcript`) may be unavailable, incomplete, or fail without authentication.
+- Comments (`get_video_comments`) may be incomplete, empty, or rate-limited without authentication.
+- Do not rely on cookie-less mode for reliable subtitle or comment access.
+
+#### Credential Sources
+
+- Credentials should be supplied via `.env` file, environment variables, or the credential helper.
+- Supported environment variables: `BILIBILI_SESSDATA`, `BILIBILI_BILI_JCT`, `BILIBILI_DEDEUSERID`.
+- **Never** hard-code Cookie values in source code, scripts, docs, tests, logs, or examples.
+- If Cookie values were previously exposed in repository history, rotate them immediately via Bilibili account settings.
+
+#### Expected Error Codes
+
+| Code | Meaning | Caller Action |
+|------|---------|---------------|
+| `VALIDATION_ERROR` | Invalid input parameter | Fix the `bvid_or_url` or other parameter |
+| `COOKIE_EXPIRED` | Cookie expired or not logged in | User should refresh/rotate Bilibili credentials |
+| `SUBTITLE_UNAVAILABLE` | No subtitles available for this video | For `get_video_transcript`, retry with `fallback_to_description: true` |
 
 ## 📋 Requirements
 
@@ -389,6 +430,24 @@ AI assistants will call these tools using JSON:
   "name": "get_video_comments",
   "arguments": { "bvid_or_url": "BV1xx4x1x7xx", "detail_level": "brief" }
 }
+
+// Transcript-only text (returns error if no subtitles)
+{
+  "name": "get_video_transcript",
+  "arguments": { "bvid_or_url": "BV1xx4x1x7xx" }
+}
+
+// Video metadata
+{
+  "name": "get_video_metadata",
+  "arguments": { "bvid_or_url": "BV1xx4x1x7xx" }
+}
+
+// Comments with custom limit + sort
+{
+  "name": "get_video_comments",
+  "arguments": { "bvid_or_url": "BV1xx4x1x7xx", "limit": 5, "sort": "time", "include_replies": false }
+}
 ```
 
 ---

package/dist/bilibili/client.d.ts

@@ -1,78 +1,4 @@
-/**
- * 检查当前 Cookie 是否处于登录状态。
- * 通过调用 /x/web-interface/nav 接口，解析 isLogin 字段来判断。
- * 该函数不会在日志或错误信息中输出任何 Cookie 内容。
- */
-export declare function checkLoginStatus(): Promise<{
-    isLogin: boolean;
-}>;
-/**
- * 带有 WBI 签名的 GET 请求
- */
-export declare function fetchWithWBI(path: string, params: Record<string, string | number>, additionalHeaders?: Record<string, string>): Promise<unknown>;
-/**
- * 普通的 GET 请求（不需要 WBI 签名）
- */
-export declare function fetchWithoutWBI(path: string, params?: Record<string, string | number>, additionalHeaders?: Record<string, string>): Promise<unknown>;
-/**
- * 获取视频基本信息
- */
-export declare function getVideoInfo(bvid: string): Promise<{
-    title: string;
-    desc: string;
-    pic?: string;
-    owner: {
-        name: string;
-        face: string;
-    };
-    stat: {
-        view: number;
-        danmaku: number;
-        reply: number;
-        favorite: number;
-        coin: number;
-        share: number;
-        like: number;
-    };
-    cid: number;
-    aid: number;
-    duration: number;
-    pubdate: number;
-    tag?: {
-        tag_name: string;
-    }[];
-}>;
-/**
- * 获取视频字幕信息
- *
- * 策略：优先使用带 WBI 签名的 /x/player/wbi/v2 接口。
- * 若该接口返回空字幕（部分视频的 AI 字幕 subtitle_url 只在非 WBI 版接口中暴露），
- * 自动降级到 /x/player/v2 重试一次。
- */
-export declare function getVideoSubtitle(bvid: string, cid: number): Promise<{
-    subtitle: {
-        subtitles: Array<{
-            id: number;
-            lan: string;
-            lan_doc: string;
-            subtitle_url: string;
-        }>;
-    };
-}>;
-/**
- * 获取字幕内容
- */
-export declare function getSubtitleContent(url: string): Promise<{
-    body: Array<{
-        from: number;
-        to: number;
-        location: number;
-        content: string;
-    }>;
-}>;
-/**
- * 获取视频评论
- */
-export declare function getVideoComments(videoUrlOrBvid: string, page?: number, pageSize?: number, sort?: number, // 0按时间，1按热度
-includeReplies?: boolean): Promise<any>;
+export { checkLoginStatus, fetchWithWBI, fetchWithoutWBI } from "./http.js";
+export { getSubtitleContent, getVideoInfo, getVideoSubtitle, } from "./video-api.js";
+export { getVideoComments } from "./comments-api.js";
 //# sourceMappingURL=client.d.ts.map

package/dist/bilibili/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/bilibili/client.ts"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAqBtE;AA2PD;;GAEG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EACvC,iBAAiB,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAC7C,OAAO,CAAC,OAAO,CAAC,CAoHlB;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EACxC,iBAAiB,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAC7C,OAAO,CAAC,OAAO,CAAC,CAsDlB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM;WAEpC,MAAM;UACP,MAAM;UACN,MAAM;WACL;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;UAC/B;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;SAC9G,MAAM;SACN,MAAM;cACD,MAAM;aACP,MAAM;UACT;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE;GAE/B;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;cAelD;QACR,SAAS,EAAE,KAAK,CAAC;YACf,EAAE,EAAE,MAAM,CAAC;YACX,GAAG,EAAE,MAAM,CAAC;YACZ,OAAO,EAAE,MAAM,CAAC;YAChB,YAAY,EAAE,MAAM,CAAC;SACtB,CAAC,CAAC;KACJ;GAsBJ;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7D,IAAI,EAAE,KAAK,CAAC;QACV,IAAI,EAAE,MAAM,CAAC;QACb,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ,CAAC,CA4BD;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,cAAc,EAAE,MAAM,EACtB,IAAI,GAAE,MAAU,EAChB,QAAQ,GAAE,MAAW,EACrB,IAAI,GAAE,MAAU,EAAE,YAAY;AAC9B,cAAc,GAAE,OAAc,gBAgI/B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/bilibili/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}