@xzxzzx/bilibili-mcp 1.3.8 → 1.4.1

package/README.md

@@ -4,70 +4,72 @@
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![npm downloads](https://img.shields.io/npm/dm/@xzxzzx/bilibili-mcp.svg)](https://www.npmjs.com/package/@xzxzzx/bilibili-mcp)
 
-## ✨ **为你的 AI 助手装上 B 站的眼睛**：一键提取视频字幕与热门评论，助力高效信息总结 🚀
-## ✨ **Equip your AI assistant with "Bilibili Eyes"**: One-click extraction of video subtitles and popular comments for efficient information summarization 🚀
-🌐 **[English Documentation](https://github.com/365903728-oss/bilibili-mcp/blob/master/README_EN.md)** (English read me version here)  
-📜 **[更新日志 (Changelog)](https://github.com/365903728-oss/bilibili-mcp/blob/master/CHANGELOG.md)**
-
-> [!TIP]
-> ⚠️ **提示**：使用前请务必配置您的 B 站 Cookie，否则将无法提取视频字幕与评论。详见 [**⚙️ 凭证配置**](#️-凭证配置)(凭证只会保存在本地，不会上传到任何地方)。
->
-> ⚠️ **Notice**: Please make sure to configure your Bilibili Cookies before use, otherwise video subtitles and comments cannot be extracted. See [**⚙️ Credential Configuration**](#️-credential-configuration) (Cookies are only stored locally and will not be uploaded anywhere).
+Bilibili MCP server — 让 Claude、Cursor、Codex 等 AI 客户端直接读取 Bilibili 视频字幕、转录、元数据和热门评论的 MCP server。
 
+🌐 [English Documentation](https://github.com/365903728-oss/bilibili-mcp/blob/master/README_EN.md) · 📜 [更新日志](https://github.com/365903728-oss/bilibili-mcp/blob/master/CHANGELOG.md) · 📦 [npm](https://www.npmjs.com/package/@xzxzzx/bilibili-mcp) · 🚀 [Release v1.4.0](https://github.com/365903728-oss/bilibili-mcp/releases/tag/v1.4.0)
 
+> [!TIP]
+> ⚠️ 使用前请配置 B 站 Cookie。Metadata 可能无需 Cookie，但字幕/转录/评论建议配置。详见 [**凭证配置**](#️-凭证配置)。
 
 ---
 
-## 📑 目录
-
-- [Bilibili MCP Tool](#bilibili-mcp-tool)
-  - [✨ **为你的 AI 助手装上 B 站的眼睛**：一键提取视频字幕与热门评论，助力高效信息总结 🚀](#-为你的-ai-助手装上-b-站的眼睛一键提取视频字幕与热门评论助力高效信息总结-)
-  - [✨ **Equip your AI assistant with "Bilibili Eyes"**: One-click extraction of video subtitles and popular comments for efficient information summarization 🚀](#-equip-your-ai-assistant-with-bilibili-eyes-one-click-extraction-of-video-subtitles-and-popular-comments-for-efficient-information-summarization-)
-  - [📑 目录](#-目录)
-  - [⚡ 快速预检](#-快速预检)
-  - [🌟 功能特性](#-功能特性)
-    - [1. 视频总结 (`get_video_info`)](#1-视频总结-get_video_info)
-    - [2. 评论总结 (`get_video_comments`)](#2-评论总结-get_video_comments)
-    - [3. 🛡️ 稳健性增强](#3-️-稳健性增强)
-  - [📋 环境要求](#-环境要求)
-  - [🚀 安装方式](#-安装方式)
-    - [🖱️ Cursor](#️-cursor)
-    - [Claude Code](#claude-code)
-      - [方法一：通过 CLI 命令快速安装（推荐）](#方法一通过-cli-命令快速安装推荐)
-      - [方法二：通过配置文件手动添加（高级）](#方法二通过配置文件手动添加高级)
-    - [Claude Desktop (桌面客户端)](#claude-desktop-桌面客户端)
-      - [方法一：通过配置文件手动添加](#方法一通过配置文件手动添加)
-      - [方法二：通过 npm 全局安装](#方法二通过-npm-全局安装)
-    - [🏗️ Trae (字节跳动官方 IDE)](#️-trae-字节跳动官方-ide)
-    - [🌊 Windsurf (Codeium 官方 IDE)](#-windsurf-codeium-官方-ide)
-    - [⚡ Zed](#-zed)
-    - [♊ Gemini CLI (Google 官方命令行工具)](#-gemini-cli-google-官方命令行工具)
-    - [⌨️ Codex CLI (OpenAI 官方命令行工具)](#️-codex-cli-openai-官方命令行工具)
-    - [🪐 Antigravity (Google 官方 IDE)](#-antigravity-google-官方-ide)
-    - [📦 OpenCode](#-opencode)
-  - [⚙️ 凭证配置](#️-凭证配置)
-    - [🔑 第一步：获取 Bilibili Cookie](#-第一步获取-bilibili-cookie)
-    - [📝 第二步：应用凭证](#-第二步应用凭证)
-      - [方式 A：使用 CLI 向导（推荐，适用于全局安装）](#方式-a使用-cli-向导推荐适用于全局安装)
-      - [方式 B：手动配置环境变量（适用于本地开发或 Docker）](#方式-b手动配置环境变量适用于本地开发或-docker)
-      - [🔒 安全须知](#-安全须知)
-  - [💡 工具使用示例](#-工具使用示例)
-  - [🛡️ API 限流机制](#️-api-限流机制)
-  - [🛠️ 开发指南](#️-开发指南)
-  - [⚖️ 安全性与免责声明](#️-安全性与免责声明)
-    - [许可证](#许可证)
-  - [🛠️ 开发过程](#️-开发过程)
-  - [💬 反馈与建议](#-反馈与建议)
+## ⚡ 快速开始
+
+选择你正在使用的 AI 客户端，点击后可直接跳转到详细配置方法：
+
+- [Codex app / Codex CLI](#codex-app--codex-cli)
+- [Claude Code](#claude-code)
+- [Claude Desktop](#claude-desktop)
+- [OpenCode](#opencode)
+- [OpenClaw](#openclaw)
+- [Hermes](#hermes)
+- [WorkBuddy](#workbuddy)
+- [CodeBuddy](#codebuddy)
+- [Trae CN](#trae-cn)
+- [Trae International](#trae-international)
+- [Trae SOLO CN](#trae-solo-cn)
+- [Trae SOLO International](#trae-solo-international)
+- [Antigravity / Antigravity CLI](#antigravity--antigravity-cli)
+- [Pi](#pi)
+- [Oh My Pi](#oh-my-pi)
+- [Crush](#crush)
+- [DeepSeek-TUI](#deepseek-tui)
+- [Deep Code](#deep-code)
+- [Reasonix](#reasonix)
+- [Langcli](#langcli)
+- [GitHub Copilot CLI](#github-copilot-cli)
+- [Cursor](#cursor)
+- [Cline](#cline)
+- [Kilo Code](#kilo-code)
+- [VS Code](#vs-code)
+- [GitHub Copilot (VS Code)](#github-copilot-vs-code)
+- [Windsurf](#windsurf)
+- [Zed](#zed)
+- [Cherry Studio](#cherry-studio)
+- [LobeHub / LobeChat](#lobehub--lobechat)
+- [AstrBot](#astrbot)
+- [nanobot](#nanobot)
 
 ---
 
-## ⚡ 快速预检
-
-> [!IMPORTANT]
-> **本工具需要 Bilibili 凭证 (Cookie) 才能发挥完整功能。**
-> 如果没有正确配置凭证，您可能无法获取视频字幕、评论
+## 📑 目录
 
-在开始安装前，请确保您已经了解[如何获取并配置 Cookie](#️-凭证配置)。
+- [⚡ 快速开始](#-快速开始)
+- [🌟 功能特性](#-功能特性)
+  - [1. 视频总结 (`get_video_info`)](#1-视频总结-get_video_info)
+  - [2. 评论总结 (`get_video_comments`)](#2-评论总结-get_video_comments)
+  - [3. 视频转录 (`get_video_transcript`)](#3-视频转录-get_video_transcript)
+  - [4. 视频元数据 (`get_video_metadata`)](#4-视频元数据-get_video_metadata)
+  - [5. 行为说明与错误处理](#5-行为说明与错误处理)
+- [📋 环境要求](#-环境要求)
+- [🚀 客户端接入方式](#-客户端接入方式)
+- [⚙️ 凭证配置](#️-凭证配置)
+- [🧭 该用哪个工具](#-该用哪个工具)
+- [💡 工具调用示例](#-工具调用示例)
+- [🛡️ API 限流机制](#️-api-限流机制)
+- [🛠️ 开发指南](#️-开发指南)
+- [⚖️ 安全性与免责声明](#️-安全性与免责声明)
+- [💬 反馈与建议](#-反馈与建议)
 
 ---
 
@@ -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` |
 
 ## 📋 环境要求
 
@@ -99,38 +140,68 @@
 
 ---
 
-## 🚀 安装方式
+## 🚀 客户端接入方式
+
+> [!NOTE]
+> 不要在客户端配置文件中写入真实 Cookie。建议先用 `bilibili-mcp config` 或环境变量配置凭证，详见 [⚙️ 凭证配置](#️-凭证配置)。
+
+### Codex app / Codex CLI
+
+Codex app、Codex CLI 和 Codex IDE extension 共用 MCP 配置。优先使用下面任一方式添加：
 
-### 🖱️ Cursor
+#### Codex app
 
-Cursor 同样原生支持 MCP，你可以通过图形界面快速添加：
+打开 Settings → Integrations & MCP，添加自定义 MCP server：
 
-1. 打开 Cursor 设置：`Cursor Settings` > `Features` > `MCP Servers`
-2. 点击 **+ Add New MCP Server**
-3. 填写以下信息：
-   - **Name**: `bilibili-mcp` (或任意你喜欢的名字)
-   - **Type**: 选择 `command`
-   - **Command**: `npx -y @xzxzzx/bilibili-mcp` （如果 Windows 遇到路径问题，可尝试 `cmd /k npx -y @xzxzzx/bilibili-mcp`）
-4. 点击 **Add** 保存。配置完成后，可能需要点击列表旁的刷新按钮来加载工具库。
+- Command: `npx`
+- Arguments: `["-y", "@xzxzzx/bilibili-mcp"]`
 
-> **提示**：高级用户也可直接在项目根目录创建 `.cursor/mcp.json` 配置文件。
+#### Codex CLI
+
+```bash
+codex mcp add bilibili-mcp -- npx -y @xzxzzx/bilibili-mcp
+```
+
+配置后，在 Codex CLI TUI 中运行 `/mcp` 查看 server 状态。
+
+#### 手动配置
+
+也可以直接编辑 Codex 配置文件：
+
+- 用户级：`~/.codex/config.toml`
+- 项目级：`.codex/config.toml`（仅在 Codex 信任该项目时加载）
+
+```toml
+[mcp_servers.bilibili-mcp]
+command = "npx"
+args = ["-y", "@xzxzzx/bilibili-mcp"]
+```
 
 ### Claude Code
 
-#### 方法一：通过 CLI 命令快速安装（推荐）
+```bash
+claude mcp add bilibili-mcp -- npx -y @xzxzzx/bilibili-mcp
+```
 
-直接在终端运行以下命令：
+默认会作为当前项目的本地 MCP server 保存。配置后可在 Claude Code 中运行 `/mcp`，或在终端运行 `claude mcp list` 检查连接状态。
+
+如果希望所有项目都可用，可使用用户级 scope：
 
 ```bash
-claude mcp add bilibili-mcp --command "npx" --args "-y" --args "@xzxzzx/bilibili-mcp"
+claude mcp add --scope user bilibili-mcp -- npx -y @xzxzzx/bilibili-mcp
 ```
 
-完成后重启 Claude Code 即可使用。
+也可以手动编辑 `~/.claude.json`，在对应项目或用户配置下添加与 Claude Desktop 相同的 JSON。
+
+### Claude Desktop
+
+打开 Claude Desktop 的 Settings → Developer → Edit Config，或直接编辑：
+
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
-#### 方法二：通过配置文件手动添加（高级）
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 
-1. 打开 Claude Code 配置文件（通常在 `~/.claude.json`）
-2. 在 `mcpServers` 节点下添加：
+添加：
 
 ```json
 {
@@ -142,19 +213,125 @@ claude mcp add bilibili-mcp --command "npx" --args "-y" --args "@xzxzzx/bilibili
   }
 }
 ```
-3. 保存后重启 Claude Code。
 
-### Claude Desktop (桌面客户端)
+保存后重启 Claude Desktop。该配置适合本地 stdio MCP server；不要在 `env`、`args` 或配置文件里写真实 Cookie。
 
-Claude Desktop 支持通过全局配置文件接入 MCP 服务器：
+### OpenCode
 
-#### 方法一：通过配置文件手动添加
+编辑 OpenCode 配置文件 `~/.config/opencode/opencode.json`，在 `mcp` 下添加本地 MCP server：
 
-1. 打开 Claude Desktop 配置文件：
-   - Windows 路径：`%APPDATA%\Claude\claude_desktop_config.json`
-   - macOS 路径：`~/Library/Application Support/Claude/claude_desktop_config.json`
-   - *提示：您也可以在 Claude Desktop 的 **Settings** -> **Developer** 中点击 **Edit Config** 直接打开该文件。*
-2. 在 `mcpServers` 节点下添加：
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "bilibili-mcp": {
+      "type": "local",
+      "command": ["npx", "-y", "@xzxzzx/bilibili-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+OpenCode 会把 MCP tools 加入可用工具上下文。使用时可在提示词中明确要求使用 `bilibili-mcp`。
+
+### OpenClaw
+
+使用 OpenClaw 的 MCP registry 注册本服务：
+
+```bash
+openclaw mcp set bilibili-mcp '{"command":"npx","args":["-y","@xzxzzx/bilibili-mcp"]}'
+```
+
+检查配置：
+
+```bash
+openclaw mcp list
+openclaw mcp show bilibili-mcp
+```
+
+也可以在 OpenClaw 配置中加入同等结构：
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "bilibili-mcp": {
+        "command": "npx",
+        "args": ["-y", "@xzxzzx/bilibili-mcp"]
+      }
+    }
+  }
+}
+```
+
+`openclaw mcp set` 只写入 OpenClaw 的 MCP server 定义；具体运行时是否启用，取决于你的 OpenClaw agent/runtime 配置。
+
+### Hermes
+
+编辑 `~/.hermes/config.yaml`，在 `mcp_servers` 下添加：
+
+```yaml
+mcp_servers:
+  bilibili-mcp:
+    command: "npx"
+    args: ["-y", "@xzxzzx/bilibili-mcp"]
+```
+
+如果你已经在运行 Hermes 会话，使用 `/reload-mcp` 重新加载 MCP 配置；也可以开启一个新的 Hermes 会话。
+
+### Cursor
+
+Cursor 编辑器和 Cursor CLI (`cursor-agent`) 共用同一套 `mcp.json` 配置。CLI 会自动读取编辑器已配置的 MCP server。
+
+#### 方式一：Cursor 编辑器
+
+在 Cursor 设置中打开 MCP / MCP Servers，添加自定义 stdio server；也可以直接编辑配置文件。
+
+项目级配置：
+
+```text
+.cursor/mcp.json
+```
+
+全局配置：
+
+```text
+~/.cursor/mcp.json
+```
+
+配置内容：
+
+```json
+{
+  "mcpServers": {
+    "bilibili-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@xzxzzx/bilibili-mcp"]
+    }
+  }
+}
+```
+
+#### 方式二：Cursor CLI
+
+Cursor CLI 使用同一份 `mcp.json`，无需单独再写一份配置。可用下面命令检查：
+
+```bash
+cursor-agent mcp list
+cursor-agent mcp list-tools bilibili-mcp
+```
+
+如果 MCP server 需要认证，Cursor CLI 使用：
+
+```bash
+cursor-agent mcp login bilibili-mcp
+```
+
+### Cline
+
+Cline 支持本地 STDIO 和远程 MCP。编辑 Cline MCP 配置文件，加入：
 
 ```json
 {
@@ -162,56 +339,177 @@ Claude Desktop 支持通过全局配置文件接入 MCP 服务器：
     "bilibili-mcp": {
       "command": "npx",
       "args": ["-y", "@xzxzzx/bilibili-mcp"],
-      "env": {
-        "BILIBILI_SESSDATA": "你的_SESSDATA",
-        "BILIBILI_BILI_JCT": "你的_bili_jct",
-        "BILIBILI_DEDEUSERID": "你的_DedeUserID"
-      }
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+Cline CLI 用户可用 JSON 方式查看或管理 MCP 设置：
+
+```bash
+cline config mcp --json
+```
+
+配置后在 Cline 的 MCP 面板确认 server 已启用。不要把真实 Cookie 写进 Cline 配置。
+
+### Kilo Code
+
+Kilo Code 的 MCP server 写在主配置文件的 `mcp` 对象下。
+
+配置位置：
+
+- 全局：`~/.config/kilo/kilo.jsonc`
+- 项目级：`kilo.jsonc`
+- 项目级：`.kilo/kilo.jsonc`
+
+添加：
+
+```jsonc
+{
+  "mcp": {
+    "bilibili-mcp": {
+      "type": "local",
+      "command": ["npx", "-y", "@xzxzzx/bilibili-mcp"],
+      "enabled": true,
+      "timeout": 10000
+    }
+  }
+}
+```
+
+也可以在 Kilo Code 设置 UI 中打开 Agent Behaviour → MCP Servers 添加。项目级配置优先于全局配置。
+
+### VS Code
+
+VS Code 原生支持 MCP 配置。工作区配置可通过命令面板打开：
+
+```text
+MCP: Open Workspace Folder MCP Configuration
+```
+
+这会创建或打开：
+
+```text
+.vscode/mcp.json
+```
+
+添加：
+
+```json
+{
+  "servers": {
+    "bilibili-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@xzxzzx/bilibili-mcp"]
     }
   }
 }
 ```
-3. 保存文件并从侧边栏重启或重新开启对话。
 
-#### 方法二：通过 npm 全局安装
+用户级配置可用命令面板打开：
+
+```text
+MCP: Open User Configuration
+```
+
+VS Code MCP 还支持 HTTP、SSE、Windows named pipe 和 Unix socket。配置后可在 VS Code 的 MCP server 列表中启动、停止或查看 server 状态。使用本项目时不要把真实 Cookie 写进 `.vscode/mcp.json`。
+
+### GitHub Copilot (VS Code)
+
+GitHub Copilot Chat 在 VS Code 中读取 VS Code MCP 配置。工作区配置可写入：
+
+```text
+.vscode/mcp.json
+```
 
-安装后可直接使用命令行工具管理配置：
+添加：
+
+```json
+{
+  "servers": {
+    "bilibili-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@xzxzzx/bilibili-mcp"]
+    }
+  }
+}
+```
+
+也可以用命令面板打开 `MCP: Open User Configuration` 配置全局 MCP。配置后在 Copilot Chat Agent Mode 中使用该 server 的工具。
+
+### WorkBuddy
+
+WorkBuddy 官方文档推荐通过界面配置 MCP。进入侧边栏 插件 → MCP 服务器 → 配置 MCP，然后添加：
+
+```json
+{
+  "mcpServers": {
+    "bilibili-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@xzxzzx/bilibili-mcp"]
+    }
+  }
+}
+```
+
+也可以按作用域编辑配置文件：
+
+- 用户级：`~/.workbuddy/mcp.json`
+- 项目级：`<项目目录>/.workbuddy/mcp.json`
+
+### CodeBuddy
+
+#### 方式一：CodeBuddy CLI
+
+CodeBuddy CLI 可以直接添加 stdio MCP server：
 
 ```bash
-npm install -g @xzxzzx/bilibili-mcp
+codebuddy mcp add --scope user bilibili-mcp -- npx -y @xzxzzx/bilibili-mcp
 ```
 
-安装验证与检查：
-1. `bilibili-mcp --help` （查看帮助）
-2. `bilibili-mcp config` （通过交互向导配置 Cookie）
-3. `bilibili-mcp check` （检查配置状态）
+检查配置：
 
-### 🏗️ Trae (字节跳动官方 IDE)
+```bash
+codebuddy mcp list
+codebuddy mcp get bilibili-mcp
+```
 
-Trae 提供了非常便捷的 MCP 接入界面，国内/国际版操作一致：
+#### 方式二：CodeBuddy IDE
 
-1. 打开 Trae 设置：点击左下角齿轮 -> **Settings** (或 `Cmd/Ctrl + ,`)。
-2. 找到 **AI** 选项卡 -> **MCP**。
-3. 点击 **Add Server** 按钮。
-4. 在弹出窗口中填写：
-   - **Name**: `bilibili-mcp`
-   - **Type**: 选择 `command` (stdio)
-   - **Command**: `npx`
-   - **Arguments**: `["-y", "@xzxzzx/bilibili-mcp"]`
-5. 点击 **Save**。
+在 CodeBuddy IDE 侧栏对话面板右上角打开 CodeBuddy Settings → MCP → Add MCP，填入：
 
-> **提示**：Trae 也会自动识别项目根目录下的 `.trae/mcp_config.json` 文件。
+```json
+{
+  "mcpServers": {
+    "bilibili-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@xzxzzx/bilibili-mcp"],
+      "description": "Bilibili MCP server"
+    }
+  }
+}
+```
 
-### 🌊 Windsurf (Codeium 官方 IDE)
+如果使用项目级 `.mcp.json`，请确认 CodeBuddy settings 允许启用该项目 MCP server。
 
-Windsurf 同样支持通过标准 JSON 配置文件接入：
+### Trae CN
+
+在 Trae CN 中打开 AI 对话窗口右上角设置入口，进入 MCP 配置；也可以直接编辑 MCP 配置文件。
+
+常见配置路径：
+
+- Windows: `%APPDATA%\Trae\User\settings\mcp.json`
+- macOS: `~/Library/Application Support/Trae/User/settings/mcp.json`
+- 项目级：`.trae/mcp.json`
+
+添加：
 
-1. 打开 Windsurf 设置：`Cmd/Ctrl + ,` -> 在左侧点击 **Advanced** -> **Cascade**。
-2. 点击 **Add custom server +** 或 **View raw config**（这将打开 `mcp_config.json`）。
-3. 如果是手动编辑，文件路径通常为：
-   - Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
-   - macOS/Linux: `~/.codeium/windsurf/mcp_config.json`
-4. 在 `mcpServers` 节点下添加：
 ```json
 {
   "mcpServers": {
@@ -222,18 +520,56 @@ Windsurf 同样支持通过标准 JSON 配置文件接入：
   }
 }
 ```
-5. 保存并重启 Windsurf 后，在 Cascade 面板即可看到新添加的工具。
 
-### ⚡ Zed
+如果你使用项目级 `.trae/mcp.json`，请在 Trae 的 MCP 管理面板中确认项目配置导入已启用。
 
-Zed 编辑器通过 `settings.json` 配置文件中的 `context_servers` 字段来支持 MCP：
+### Trae International
 
-1. 打开 Zed 的设置文件：`Cmd + ,` (macOS) 或 `Ctrl + ,` (Windows/Linux)。
-2. 在 JSON 配置文件中添加 (或修改) `context_servers` 节点：
+在 Trae 国际版中打开 AI 对话窗口右上角 Settings → MCP，选择 Add 或手动配置 MCP server。
+
+如果需要直接编辑项目级配置，可创建 `.trae/mcp.json`：
 
 ```json
 {
-  "context_servers": {
+  "mcpServers": {
+    "bilibili-mcp": {
+      "command": "npx",
+      "args": ["-y", "@xzxzzx/bilibili-mcp"]
+    }
+  }
+}
+```
+
+Trae 支持 stdio MCP server；本项目使用 `npx` 启动 stdio server。
+
+### Trae SOLO CN
+
+Trae SOLO CN 是 Trae 中国版的 SOLO 工作方式。官方公开文档没有给出独立于 Trae MCP 的专属配置文件；当前可按 Trae 项目级 MCP 配置接入，然后在 SOLO Coder 中使用。
+
+在项目根目录创建 `.trae/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "bilibili-mcp": {
+      "command": "npx",
+      "args": ["-y", "@xzxzzx/bilibili-mcp"]
+    }
+  }
+}
+```
+
+然后在 Trae 的 MCP 管理面板中确认项目配置导入已启用，并在 SOLO Coder 中使用该 MCP server。
+
+### Trae SOLO International
+
+Trae SOLO International 已存在，官方 FAQ 说明国际版 SOLO 面向 Pro 用户。没有找到单独的 SOLO 专属 MCP JSON 格式；可使用 Trae International 的 MCP 配置方式，然后在 SOLO Coder / Builder with MCP 中调用。
+
+项目级配置同样使用 `.trae/mcp.json`：
+
+```json
+{
+  "mcpServers": {
     "bilibili-mcp": {
       "command": "npx",
       "args": ["-y", "@xzxzzx/bilibili-mcp"]
@@ -241,17 +577,22 @@ Zed 编辑器通过 `settings.json` 配置文件中的 `context_servers` 字段
   }
 }
 ```
-3. 保存文件。Zed 桌面端会自动重启 Context Server。
-4. 在编辑器中通过 `/` 触发 AI 辅助时，可以看到来自该服务器的 Context 或工具。
 
-### ♊ Gemini CLI (Google 官方命令行工具)
+如果使用 Trae International 的 UI，打开 AI 对话窗口右上角 Settings → MCP，手动添加同等 `mcpServers` 配置。
+
+### Antigravity / Antigravity CLI
+
+Gemini CLI 已迁移到 Antigravity CLI。新的 MCP 配置不再写在 `~/.gemini/settings.json`，而是使用独立的 `mcp_config.json`。
 
-Gemini CLI 通过全局或项目级的 `settings.json` 文件管理 MCP 服务器：
+Antigravity IDE 可通过 MCP Store → Manage MCP Servers → View raw config 打开配置；Antigravity CLI 可通过 `/mcp` 管理 MCP servers。
 
-1. 找到全局配置文件：
-   - Windows: `%USERPROFILE%\.gemini\settings.json`
-   - macOS/Linux: `~/.gemini/settings.json`
-2. 在 `mcpServers` 节点下添加：
+常见配置路径：
+
+- Antigravity IDE：`~/.gemini/antigravity/mcp_config.json`
+- Antigravity CLI 全局：`~/.gemini/antigravity-cli/mcp_config.json`
+- Antigravity CLI 工作区：`.agents/mcp_config.json`
+
+添加：
 
 ```json
 {
@@ -263,150 +604,537 @@ Gemini CLI 通过全局或项目级的 `settings.json` 文件管理 MCP 服务
   }
 }
 ```
-3. 如果您是通过项目级配置，请在项目根目录创建 `.gemini/settings.json`。
-4. 保存后，运行 `gemini` 命令时即可调用相关工具。
 
-> **国内版提示**：如果您在国内环境下使用，请确保已正确配置 `HTTP_PROXY` 或 `HTTPS_PROXY` 环境变量，以便 `npx` 顺利下载包以及 CLI 能够访问 Google API。
+保存后重启 Antigravity / Antigravity CLI，或在 CLI 中使用 `/mcp` 检查 server 是否加载。
 
-### ⌨️ Codex CLI (OpenAI 官方命令行工具)
+### Pi
 
-Codex CLI 使用 TOML 格式的配置文件，并支持通过命令行快速添加：
+Pi 通过 `pi-mcp-adapter` 使用 MCP。先安装 adapter：
 
-**方式一：通过命令行添加（推荐）**
-直接在终端运行：
 ```bash
-codex mcp add bilibili-mcp -- npx -y @xzxzzx/bilibili-mcp
+pi install npm:pi-mcp-adapter
 ```
 
-**方式二：手动修改配置文件**
-1. 找到配置文件：
-   - 全局路径：`~/.codex/config.toml`
-   - 项目路径：`.codex/config.toml`
-2. 添加以下内容：
+重启 Pi 后，优先使用项目级共享配置：
 
-```toml
-[mcp_servers.bilibili-mcp]
-command = "npx"
-args = ["-y", "@xzxzzx/bilibili-mcp"]
+```text
+.mcp.json
 ```
-保存后重启 Codex CLI 即可识别工具。
 
-### 🪐 Antigravity (Google 官方 IDE)
+添加：
 
-Antigravity 原生支持 MCP 协议。你可以通过 UI 界面或直接修改配置文件来添加：
+```json
+{
+  "mcpServers": {
+    "bilibili-mcp": {
+      "command": "npx",
+      "args": ["-y", "@xzxzzx/bilibili-mcp"]
+    }
+  }
+}
+```
+
+也可以使用用户级共享配置：
+
+```text
+~/.config/mcp/mcp.json
+```
+
+Pi 还支持 Pi 专属覆盖文件：
+
+- 全局：`~/.pi/agent/mcp.json`
+- 项目级：`.pi/mcp.json`
+
+如果你已经在 Cursor、Claude Code、Codex、Windsurf 等客户端里配置过 MCP，可在 Pi 中运行 `/mcp setup` 导入或生成配置；终端也可运行：
+
+```bash
+pi-mcp-adapter init
+```
+
+Pi 默认 lazy 连接 MCP server，只有实际调用工具时才启动。进入 Pi 后使用 `/mcp` 查看 server 状态和工具列表。不要在 Pi 的 MCP 配置里写真实 Cookie；凭证请用 `bilibili-mcp config` 或环境变量配置。
+
+### Oh My Pi
+
+Oh My Pi (`omp`) 原生支持 MCP，优先使用 OMP 专属配置文件：
+
+- 项目级：`.omp/mcp.json`
+- 用户级：`~/.omp/agent/mcp.json`
+
+也可以使用可被其他 MCP client 复用的项目根配置：
 
-**方式一：通过界面添加（推荐）**
-1. 在编辑器侧边栏顶部点击 `...` 下拉菜单，打开 **MCP Store** 面板。
-2. 点击 **Manage MCP Servers -> View raw config**。
-3. 参考下方 JSON 格式填入配置。
+- `mcp.json`
+- `.mcp.json`
 
-**方式二：手动修改配置文件**
-- Windows 路径：`%USERPROFILE%\.gemini\antigravity\mcp_config.json`
-- macOS/Linux 路径：`~/.gemini/antigravity/mcp_config.json`
+添加：
 
-在 `mcpServers` 节点下添加：
 ```json
 {
+  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
   "mcpServers": {
     "bilibili-mcp": {
+      "type": "stdio",
       "command": "npx",
       "args": ["-y", "@xzxzzx/bilibili-mcp"]
     }
   }
 }
 ```
-保存后配置即刻生效。
 
-### 📦 OpenCode
+也可以在 OMP 会话中使用引导式配置：
 
-OpenCode 用户可以通过编辑配置文件接入：
+```text
+/mcp add
+```
+
+修改配置后使用：
+
+```text
+/mcp reload
+/mcp list
+/mcp test bilibili-mcp
+```
+
+OMP 支持 `stdio`、`http` 和 `sse` MCP。不要在 `env`、`args` 或配置文件中写真实 Cookie。
+
+### Crush
+
+Crush 支持项目级和用户级 JSON 配置，MCP server 写在 `mcp` 对象下。
+
+配置优先级：
 
-1. 编辑 `~/.config/opencode/opencode.json`
-2. 在 `mcp` 节点下添加以下内容：
+- 项目级：`.crush.json`
+- 项目级：`crush.json`
+- 用户级：`~/.config/crush/crush.json`
+
+添加：
 
 ```json
 {
-  "$schema": "https://opencode.ai/config.json",
+  "$schema": "https://charm.land/crush.json",
   "mcp": {
+    "bilibili-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@xzxzzx/bilibili-mcp"]
+    }
+  }
+}
+```
+
+Crush 也支持 HTTP 和 SSE MCP。不要在 `env` 或 `args` 中写真实 Cookie；凭证请使用本项目的 CLI 向导或环境变量。
+
+### DeepSeek-TUI
+
+DeepSeek-TUI 同时是 MCP client 和 MCP server。作为 MCP client 时，可用 `deepseek mcp add` 添加本项目：
+
+```bash
+deepseek mcp add bilibili-mcp -- npx -y @xzxzzx/bilibili-mcp
+```
+
+也可以编辑：
+
+```text
+~/.deepseek/mcp.json
+```
+
+添加：
+
+```json
+{
+  "mcpServers": {
+    "bilibili-mcp": {
+      "command": "npx",
+      "args": ["-y", "@xzxzzx/bilibili-mcp"]
+    }
+  }
+}
+```
+
+可用 `deepseek mcp list` 和 `deepseek mcp validate` 检查配置。DeepSeek-TUI 暴露的 MCP 工具通常以 `mcp_<server>_<tool>` 形式出现。
+
+### Deep Code
+
+Deep Code 使用 `~/.deepcode/settings.json` 配置 MCP server。把 `bilibili-mcp` 加到 `mcpServers`：
+
+```json
+{
+  "mcpServers": {
+    "bilibili-mcp": {
+      "command": "npx",
+      "args": ["@xzxzzx/bilibili-mcp"]
+    }
+  }
+}
+```
+
+Deep Code 文档说明 `command` 为 `npx` 时会自动补充 `-y`。配置后启动 `deepcode`，输入 `/mcp` 查看 MCP server 状态和可用工具。
+
+### Reasonix
+
+Reasonix 支持原生 MCP。最简单的方式是启动时传入 `--mcp`：
+
+```bash
+npx reasonix code --mcp "bilibili=npx -y @xzxzzx/bilibili-mcp"
+```
+
+也可以编辑全局配置：
+
+```text
+~/.reasonix/config.json
+```
+
+在 `mcp` 数组中添加：
+
+```json
+{
+  "mcp": [
+    "bilibili=npx -y @xzxzzx/bilibili-mcp"
+  ]
+}
+```
+
+Reasonix 的格式是 `name=command arg1 arg2`。如果需要项目级覆盖，可放在项目的 `.reasonix/` 下。
+
+### Langcli
+
+Langcli 当前官方文档只明确提供内置 Chrome MCP 用法，没有找到可添加任意 stdio MCP server 的 `mcpServers` 或 CLI 配置方式。因此这里暂不提供 `bilibili-mcp` 接入配置，避免误导用户。
+
+如果只需要使用 Langcli 的内置 Chrome MCP，可按官方文档启动：
+
+```bash
+langcli --chrome
+```
+
+然后在 Langcli 中输入：
+
+```text
+/mcp
+```
+
+在 MCP 面板里管理 `mcp-chrome`。等 Langcli 官方公开任意 MCP server 配置方式后，再补充本项目的 `npx -y @xzxzzx/bilibili-mcp` 接入示例。
+
+### GitHub Copilot CLI
+
+GitHub Copilot CLI 可在交互模式里使用 `/mcp add` 添加 MCP server。按表单选择 `STDIO` 或 `Local`，然后填入：
+
+- Server Name: `bilibili-mcp`
+- Command: `npx`
+- Args: `-y @xzxzzx/bilibili-mcp`
+
+也可以编辑用户级配置：
+
+```text
+~/.copilot/mcp-config.json
+```
+
+添加：
+
+```json
+{
+  "mcpServers": {
     "bilibili-mcp": {
       "type": "local",
-      "command": ["npx", "-y", "@xzxzzx/bilibili-mcp"],
-      "enabled": true
+      "command": "npx",
+      "args": ["-y", "@xzxzzx/bilibili-mcp"],
+      "env": {},
+      "tools": ["*"]
     }
   }
 }
 ```
 
----
+项目级配置可用 `.mcp.json` 或 `.github/mcp.json`，并且会优先于用户级同名 server。进入 Copilot CLI 后可用 `/mcp show` 查看状态。
 
----
+### Windsurf
 
-## ⚙️ 凭证配置
+Windsurf 的 MCP 由 Cascade 使用。官方入口是 Cascade 面板右上角的 `MCPs` 图标，或 Windsurf Settings → Cascade → MCP Servers。
 
-为了获取更完整的评论数据、绕过匿名访问限制并确保工具稳定运行，**必须**配置 B 站 Cookie。
+#### 方式一：Cascade / MCP Servers UI
 
-### 🔑 第一步：获取 Bilibili Cookie
+打开 MCP Marketplace 或 MCP Servers 设置后，添加自定义 stdio MCP server：
 
-1. 在电脑浏览器登录 [bilibili.com](https://www.bilibili.com)
-2. 按 `F12` 打开开发者工具（或在页面右键选择“检查”）。
-3. 切换到 **Application (应用)** 选项卡 -> 在左侧菜单找到 **Cookies** -> 点击 `https://www.bilibili.com`。
-4. 在右侧列表中找到以下三个关键变量，并记录它们的 **Value**：
-    - `SESSDATA`
-    - `bili_jct` (即 CSRF Token)
-    - `DedeUserID` (您的用户数字 ID)
+- Command: `npx`
+- Arguments: `["-y", "@xzxzzx/bilibili-mcp"]`
 
-> [!TIP]
-> 如果您在 `Application` 找不到，也可以查看 `Network` (网络) 选项卡中的任意一个请求，在 `Headers` -> `Cookie` 字段中也能找到这些值。
+Windsurf 也支持 MCP deeplink；如果你在文档或网页中提供安装入口，可以使用 `windsurf://windsurf-mcp-registry?serverName=<server-name>` 打开对应 MCP registry 页面。
+
+#### 方式二：Raw config
+
+直接编辑：
 
-### 📝 第二步：应用凭证
+```text
+~/.codeium/windsurf/mcp_config.json
+```
 
-您可以针对不同的使用习惯选择以下任一方式：
+添加：
+
+```json
+{
+  "mcpServers": {
+    "bilibili-mcp": {
+      "command": "npx",
+      "args": ["-y", "@xzxzzx/bilibili-mcp"]
+    }
+  }
+}
+```
+
+Windsurf/Cascade 支持 `stdio`、Streamable HTTP 和 SSE MCP。本项目使用本地 stdio server，因此不要把真实 Bilibili Cookie 写进该配置文件；凭证请用 `bilibili-mcp config` 或环境变量配置。
+
+### Zed
+
+Zed 使用 `context_servers` 配置 MCP，不使用 `mcpServers`。可以通过 Agent Panel 的 settings view 添加自定义 server，也可以直接编辑 `settings.json`。
+
+#### 方式一：Agent Panel UI
+
+打开 Agent Panel 的 Settings view，点击 Add Custom Server，填入本项目的 stdio server 配置。
+
+配置后，在 Agent Panel 的 settings view 中查看 server 名称旁边的状态圆点；绿色表示 server active。
+
+#### 方式二：settings.json
+
+用户级设置可通过 Zed 的 `zed: open settings` 打开。项目级设置可写入：
+
+```text
+.zed/settings.json
+```
+
+添加：
+
+```json
+{
+  "context_servers": {
+    "bilibili-mcp": {
+      "command": "npx",
+      "args": ["-y", "@xzxzzx/bilibili-mcp"]
+    }
+  }
+}
+```
+
+#### 方式三：Zed extension
+
+Zed 也支持以 extension 的方式安装 MCP server。通用自定义 server 用上面的 `context_servers` 更直接；如果未来本项目发布 Zed MCP extension，再改用 extension 安装。
+
+Zed 支持 MCP Tools 和 Prompts，也支持远程 MCP；远程 server 使用 `url` 和可选 `headers`。本项目是本地 stdio server，不要在 Zed 配置里写真实 Bilibili Cookie。
+
+### Cherry Studio
+
+Cherry Studio 在 Settings → MCP Server 中添加 MCP server。添加本项目时选择 `STDIO`：
+
+- Name: `bilibili-mcp`
+- Type: `STDIO`
+- Command: `npx`
+- Parameters: `-y @xzxzzx/bilibili-mcp`
+
+保存后，Cherry Studio 会启动该 MCP server；在聊天窗口中启用对应 MCP server 后即可调用工具。
+
+### LobeHub / LobeChat
+
+LobeChat Desktop 支持导入 MCP server JSON。打开：
+
+```text
+Settings → Default Agent → Plugin Settings → Custom Plugins → Quick JSON Configuration Import
+```
+
+粘贴：
+
+```json
+{
+  "mcpServers": {
+    "bilibili-mcp": {
+      "command": "npx",
+      "args": ["-y", "@xzxzzx/bilibili-mcp"]
+    }
+  }
+}
+```
+
+安装后，在对应 Agent 的插件设置中启用该 MCP server。不要把真实 Cookie 写进 LobeChat 配置；凭证请通过本项目 CLI 或环境变量配置。
+
+### AstrBot
+
+AstrBot 通过 WebUI 管理 MCP。先确保 AstrBot 运行环境可使用 `npm` 和 `node`，然后在 WebUI 的 MCP 服务器管理入口添加本地 MCP server：
+
+```json
+{
+  "mcpServers": {
+    "bilibili-mcp": {
+      "command": "npx",
+      "args": ["-y", "@xzxzzx/bilibili-mcp"]
+    }
+  }
+}
+```
+
+如果 AstrBot 运行在 Docker 中，需要确保容器内已安装 Node.js / npm，且容器能访问运行 MCP server 所需的网络。
+
+### nanobot
+
+nanobot 的配置文件是：
+
+```text
+~/.nanobot/config.json
+```
+
+在 `tools.mcpServers` 下添加：
+
+```json
+{
+  "tools": {
+    "mcpServers": {
+      "bilibili-mcp": {
+        "command": "npx",
+        "args": ["-y", "@xzxzzx/bilibili-mcp"]
+      }
+    }
+  }
+}
+```
+
+nanobot 的 MCP 配置兼容 Claude Desktop / Cursor 风格；也支持远程 MCP 的 `url` 和 `headers`。凭证仍应由本项目 CLI 或环境变量管理，不要写入 nanobot 配置。
+
+## ⚙️ 凭证配置
+
+为了稳定获取字幕、转录和评论，建议配置 Bilibili Cookie。公开视频元数据可能无需 Cookie，但不要依赖无 Cookie 模式获取字幕或评论。
+
+### 推荐方式：CLI 向导
 
-#### 方式 A：使用 CLI 向导（推荐，适用于全局安装）
-如果您全局安装了 npm 包（`npm i -g @xzxzzx/bilibili-mcp`），直接运行：
 ```bash
+npm install -g @xzxzzx/bilibili-mcp
 bilibili-mcp config
+bilibili-mcp check
 ```
-交互向导将引导您输入凭证并安全保存在**本地**配置目录（`~/.bilibili-mcp/config.json`）中。
 
-#### 方式 B：手动配置环境变量（适用于本地开发或 Docker）
-在项目根目录创建 `.env` 文件，手动填入以下变量：
+CLI 会把凭证保存在本地配置目录，不会写入仓库。
+
+### 环境变量方式
+
+适合 Docker、本地开发或手动配置 MCP 客户端环境变量。
 
 | 变量名 | 说明 |
-| :--- | :--- |
-| **BILIBILI_SESSDATA** | `SESSDATA` 的值 |
-| **BILIBILI_BILI_JCT** | `bili_jct` 的值 |
-| **BILIBILI_DEDEUSERID** | `DedeUserID` 的值 |
+|---|---|
+| `BILIBILI_SESSDATA` | Bilibili 登录 Cookie 中的 SESSDATA |
+| `BILIBILI_BILI_JCT` | Bilibili 登录 Cookie 中的 bili_jct |
+| `BILIBILI_DEDEUSERID` | Bilibili 用户 ID |
+
+`.env` 示例：
+
+```env
+BILIBILI_SESSDATA=<your_sessdata>
+BILIBILI_BILI_JCT=<your_bili_jct>
+BILIBILI_DEDEUSERID=<your_dedeuserid>
+```
+
+### Cookie 获取提醒
 
-> [!WARNING]
-> `.env` 文件仅供本地加载，**切勿提交到 Git 或公开仓库**。
+请只从你自己的 Bilibili 登录会话中获取 Cookie。不同浏览器的开发者工具界面会变化，具体步骤请以浏览器实际界面为准。
 
-#### 🔒 安全须知
+不要把 Cookie 发给他人，不要粘贴到公开聊天、Issue、PR、README、日志或测试文件。
 
-- **隐私保护**：您的凭证信息仅存储在您的本地设备上。本工具**绝不会**将其上传至除 Bilibili 官方 API 以外的任何第三方服务器。
-- **配置隔离**：`.env` 文件已被 `.gitignore` 排除。
-- **时效性**：Cookie 具有时效性。若遇到 `412` 或权限错误，请尝试更新 Cookie。
+### 安全须知
+
+- Cookie 只应保存在本地配置、环境变量或 `.env` 中。
+- `.env` 已被 `.gitignore` 排除，但仍要避免提交。
+- Cookie 泄露后应立即在 Bilibili 账号侧失效旧登录状态。
+- 本项目不会把 Cookie 上传到除 Bilibili 官方 API 以外的第三方服务。
 
 ---
 
-## 💡 工具使用示例
+## 🧭 该用哪个工具？
+
+| 目标 | 推荐工具 | 返回重点 |
+|---|---|---|
+| 想让 AI 总结一个视频 | `get_video_info` | 字幕优先；无字幕时返回标题、简介、标签 |
+| 只想拿完整转录文本 | `get_video_transcript` | 纯字幕文本、语言、数据来源 |
+| 想查看标题、作者、播放量等结构化信息 | `get_video_metadata` | 标题、作者、时长、发布时间、标签、统计数据 |
+| 想看观众反馈和热门评论 | `get_video_comments` | 热门评论、时间戳评论、可选回复 |
+
+## 💡 工具调用示例
+
+> AI 客户端会自动将你的自然语言意图转换为对应的 JSON 调用。
+
+### `get_video_transcript`
+
+**适合**：需要把视频内容交给 AI 做摘要、笔记、问答或知识整理。
+
+请求示例：
 
-在支持 MCP 的对话流中，你可以直接输入自然语言，底层会自动调用对应的 JSON 格式配置：
+```json
+{
+  "name": "get_video_transcript",
+  "arguments": {
+    "bvid_or_url": "https://www.bilibili.com/video/BV1xx411c7mD",
+    "preferred_lang": "zh-Hans",
+    "fallback_to_description": false
+  }
+}
+```
+
+返回内容：`bvid`、`title`、`language`、`transcript`（按行合并）、`data_source`（`subtitle` 或 `description`）。
+
+> 默认无字幕时返回 `SUBTITLE_UNAVAILABLE`。如需降级，设置 `fallback_to_description: true`。
+
+### `get_video_metadata`
+
+**适合**：想快速了解视频基本信息，不需要字幕或评论内容。
+
+请求示例：
+
+```json
+{
+  "name": "get_video_metadata",
+  "arguments": {
+    "bvid_or_url": "BV1xx411c7mD"
+  }
+}
+```
+
+返回内容：`bvid`、`title`、`author`、`duration`、`pubdate` / `pubdate_timestamp`、`description`、`tags` 和 `stats`（播放、点赞、投币、收藏、分享、评论、弹幕）。
+
+### `get_video_info`
+
+**适合**：让 AI 总结视频核心内容——会优先尝试字幕，无字幕时回退到简介和标签。
+
+请求示例：
 
 ```json
-// 获取默认语言视频信息
 {
   "name": "get_video_info",
-  "arguments": { "bvid_or_url": "BV1xx4x1x7xx" }
+  "arguments": {
+    "bvid_or_url": "https://www.bilibili.com/video/BV1xx411c7mD",
+    "preferred_lang": "zh-Hans"
+  }
 }
+```
+
+返回内容：`data_source`（`subtitle` 或 `description`）、`video_info`（标题、描述、标签、字幕文本、发布时间）。
+
+> 无字幕视频会自动降级返回描述和标签（即 `data_source: "description"`）。
 
-// 获取 10 条简短评估
+### `get_video_comments`
+
+**适合**：想了解观众对视频的真实评价、找精彩时间点。
+
+请求示例：
+
+```json
 {
   "name": "get_video_comments",
-  "arguments": { "bvid_or_url": "BV1xx4x1x7xx", "detail_level": "brief" }
+  "arguments": {
+    "bvid_or_url": "BV1xx411c7mD",
+    "detail_level": "detailed",
+    "limit": 10,
+    "sort": "hot",
+    "include_replies": true
+  }
 }
 ```
 
+返回内容：`comments[]`（含 `author`、`content`、`likes`、`timestamp`、`has_timestamp`）、`summary`（总数和时间戳评论数）。
+
+> Cookie 过期或未登录可能导致评论为空。`sort: "time"` 可获取最新评论，`include_replies: false` 不返回子回复。
+
 ---
 
 ## 🛡️ API 限流机制