@xzxzzx/bilibili-mcp 1.4.2 → 1.4.3

package/README.md

@@ -1133,21 +1133,27 @@ nanobot 的 MCP 配置兼容 Claude Desktop / Cursor 风格；也支持远程 MC
 
 ## ⚙️ 凭证配置
 
-为了稳定获取字幕、转录和评论，建议配置 Bilibili Cookie。公开视频元数据可能无需 Cookie，但不要依赖无 Cookie 模式获取字幕或评论。
+如果你使用上方“用 agent 工具帮你安装”的提示词，agent 会引导你完成本节步骤；通常不需要手动阅读完整配置。这里用于说明 Cookie 保存位置、安全边界，以及 Docker、本地开发等手动场景。为了稳定获取字幕、转录和评论，建议配置 Bilibili Cookie；公开视频元数据可能无需 Cookie。
 
-### 推荐方式：CLI 向导
+### 推荐方式：让 agent 引导你配置
+
+```bash
+npx -y @xzxzzx/bilibili-mcp config
+npx -y @xzxzzx/bilibili-mcp check
+```
+
+如果你使用上方“用 agent 工具帮你安装”的提示词，agent 会在添加 MCP server 后引导你运行这两个命令。`config` 会把 Cookie 保存到本机凭证配置，MCP server 启动后会自动读取；不会写入 MCP 客户端配置或仓库。
+
+如果已经全局安装，也可以运行：
 
 ```bash
-npm install -g @xzxzzx/bilibili-mcp
 bilibili-mcp config
 bilibili-mcp check
 ```
 
-CLI 会把凭证保存在本地配置目录，不会写入仓库。
-
 ### 环境变量方式
 
-适合 Docker、本地开发或手动配置 MCP 客户端环境变量。
+适合 Docker、本地开发或你明确知道当前 MCP server 运行环境的情况。不要把真实 Cookie 写进可共享的 MCP 客户端配置文件。
 
 | 变量名 | 说明 |
 |---|---|
@@ -1186,11 +1192,43 @@ BILIBILI_DEDEUSERID=<your_dedeuserid>
 | 只想拿完整转录文本 | `get_video_transcript` | 纯字幕文本、语言、数据来源 |
 | 想查看标题、作者、播放量等结构化信息 | `get_video_metadata` | 标题、作者、时长、发布时间、标签、统计数据 |
 | 想看观众反馈和热门评论 | `get_video_comments` | 热门评论、时间戳评论、可选回复 |
+| 让 agent 引导用户配置 Cookie | `get_credential_setup_instructions` | 安全配置步骤、推荐命令、注意事项 |
+| 检查 Cookie 是否已配置/登录 | `check_bilibili_credentials` | configured、source、logged_in、next_steps |
 
 ## 💡 工具调用示例
 
 > AI 客户端会自动将你的自然语言意图转换为对应的 JSON 调用。
 
+### `get_credential_setup_instructions`
+
+**适合**：agent 安装 MCP server 后，引导用户完成 Cookie 配置。
+
+请求示例：
+
+```json
+{
+  "name": "get_credential_setup_instructions",
+  "arguments": {}
+}
+```
+
+返回内容：推荐配置命令、全局安装命令、所需 Cookie 字段和安全提醒；不会返回任何 Cookie 值。
+
+### `check_bilibili_credentials`
+
+**适合**：检查当前环境是否已配置 Cookie，以及是否处于登录状态。
+
+请求示例：
+
+```json
+{
+  "name": "check_bilibili_credentials",
+  "arguments": {}
+}
+```
+
+返回内容：`configured`、`source`（`env` / `global_config` / `none`）、`logged_in` 和 `next_steps`；不会返回任何 Cookie 值。
+
 ### `get_video_transcript`
 
 **适合**：需要把视频内容交给 AI 做摘要、笔记、问答或知识整理。
@@ -1276,10 +1314,12 @@ BILIBILI_DEDEUSERID=<your_dedeuserid>
 
 ## 🛡️ API 限流机制
 
-为保证工具长效可用并合规调用底层接口，已内置以下限流策略：
+为降低触发 Bilibili 风控和接口限流的概率，已内置以下请求控制策略：
 
-- **请求间隔**：500ms（0.5秒）
-- **执行方式**：加入队列顺序处理，禁止大并发请求。
+- **请求启动间隔**：默认 500ms（0.5 秒），可通过 `BILIBILI_RATE_LIMIT_MS` 调整。
+- **执行方式**：对 API 请求启动做节流，避免瞬时大并发；适合本地单用户 MCP 使用。
+- **重试策略**：对 408、429、5xx、网络错误和超时进行最多 3 次指数退避重试。
+- **超时控制**：默认 10 秒，可通过 `BILIBILI_REQUEST_TIMEOUT_MS` 调整。
 
 ---
 
@@ -1293,11 +1333,31 @@ cd bilibili-mcp
 # 2. 安装依赖包
 npm install
 
-# 3. 启动监听与实时编译
+# 3. 运行测试
+npm test
+
+# 4. 编译 TypeScript
+npm run build
+
+# 5. 启动监听与实时编译
 npm run watch
 ```
 
-本工具输出报错信息统一使用 `console.error`，以避免干扰 Stdio 协议数据。
+常用命令：
+
+| 命令 | 用途 |
+|---|---|
+| `npm run build` | 编译 TypeScript 到 `dist/` |
+| `npm test` | 运行 Vitest 单元测试 |
+| `npm run watch` | 开发时持续编译 |
+| `npm start` | 运行已编译的 stdio MCP server |
+| `npm pack --dry-run` | 检查 npm 包会包含哪些文件 |
+
+本地调试说明：
+
+- MCP server 的入口是 `dist/index.js`，CLI 入口是 `dist/cli.js`；修改源码后先运行 `npm run build`。
+- 启动 stdio MCP server 后，`stdout` 必须保留给 MCP 协议数据；调试日志和错误信息应写到 `stderr`，因此本项目使用 `console.error` 输出运行日志。
+- 不要在测试、日志、示例或提交内容中写入真实 Cookie。需要验证凭证时，使用 `npx -y @xzxzzx/bilibili-mcp check` 或本地环境变量。
 
 ---
 
@@ -1305,14 +1365,15 @@ npm run watch
 
 > **⚠️ 重要：使用本工具即代表您同意以下条款**
 
-- **商标声明**：Bilibili (哔哩哔哩) 是哔哩哔哩公司的注册商标。本项目为基于公开协议的第三方开源辅助工具。
-- **协议精神**：本项目**仅供个人学习、辅助阅读使用**。坚决抵制任何用于商业剥削、大规模滥用抓取等违规操作。
-- **责任归属**：所有请求均为用户本地发起。开发者不对由于高频使用等原因导致的账号风控或其他后果负责。
-- **隐私保护**：本工具严格保护用户隐私，所有凭证信息仅在本地加密/非加密存储，除与 Bilibili 官方接口通信外，无任何后台上传行为。
+- **非官方项目**：Bilibili（哔哩哔哩）是哔哩哔哩公司的注册商标。本项目是第三方开源辅助工具，不隶属于 Bilibili，也不代表 Bilibili 官方。
+- **使用边界**：本项目仅供个人学习、辅助阅读和内容理解使用。请遵守 Bilibili 用户协议、robots/接口访问规则和当地法律法规；不要用于商业剥削、大规模抓取、绕过权限或其他滥用场景。
+- **账号风险**：所有请求均由用户本机发起。高频调用、异常访问模式、Cookie 泄露或账号自身状态可能触发风控、限流或账号异常；相关后果由使用者自行承担。
+- **Cookie 安全**：不要把真实 Cookie 写入 MCP 客户端配置、公开聊天、Issue、PR、README、日志或测试文件。建议使用本项目的本机凭证配置、运行环境变量或本地 `.env` 管理 Cookie；Cookie 泄露后应立即在 Bilibili 账号侧失效旧登录状态。
+- **隐私说明**：本项目不会把 Cookie 上传到除 Bilibili 官方接口以外的第三方服务。凭证仅在本机按用户选择的方式保存或读取；当前本地配置文件不承诺系统级加密，请自行保护设备、账号和配置文件访问权限。
 
 ### 许可证
 
-基于 **GNU General Public License v3.0** 开源。
+本项目基于 **GNU General Public License v3.0** 开源。使用、复制、修改和分发本项目时，请遵守 GPL-3.0 的许可要求。
 
 ---
 
@@ -1331,7 +1392,7 @@ npm run watch
 如果您在使用过程中遇到任何问题，或者有好的功能建议，欢迎通过以下方式联系：
 
 - **提交 Issue**：[GitHub Issues](https://github.com/365903728-oss/bilibili-mcp/issues) —— **推荐方式**，我会定期查看并回复。
-- **项目讨论**：在 [GitHub Discussions](https://github.com/365903728-oss/bilibili-mcp/discussions)（如果已开启）中交流。
+- **项目讨论**：在 [GitHub Discussions](https://github.com/365903728-oss/bilibili-mcp/discussions) 中交流。
 
 感谢您的支持！
 

package/README_EN.md

@@ -1133,21 +1133,27 @@ nanobot's MCP config is compatible with Claude Desktop / Cursor style config. It
 
 ## ⚙️ Credential Configuration
 
-For reliable access to subtitles, transcripts, and comments, configure Bilibili Cookies. Public video metadata may work without cookies, but do not rely on cookieless mode for subtitles or comments.
+If you use the "Install With Your Agent" prompt above, the agent should guide you through this section; you usually do not need to read the full setup manually. This section explains where Cookies are stored, the safety boundary, and manual scenarios such as Docker or local development. For reliable subtitles, transcripts, and comments, configure Bilibili Cookies; public video metadata may work without cookies.
 
-### Recommended: CLI Wizard
+### Recommended: Agent-Guided Credential Setup
+
+```bash
+npx -y @xzxzzx/bilibili-mcp config
+npx -y @xzxzzx/bilibili-mcp check
+```
+
+If you use the "Install With Your Agent" prompt above, the agent should guide you to run these commands after it adds the MCP server. `config` saves Cookies to the local credential config, which the MCP server reads automatically when it starts; it does not write Cookies into MCP client config or the repository.
+
+If the package is already installed globally, you can also run:
 
 ```bash
-npm install -g @xzxzzx/bilibili-mcp
 bilibili-mcp config
 bilibili-mcp check
 ```
 
-The CLI saves credentials to a local config directory, outside the repository.
-
 ### Environment Variables
 
-For Docker, local development, or manual MCP client configuration.
+For Docker, local development, or cases where you explicitly control the MCP server runtime environment. Do not put real Cookies in shareable MCP client config files.
 
 | Variable | Description |
 |---|---|
@@ -1186,11 +1192,43 @@ Do not share cookies with others. Do not paste them into public chats, issues, P
 | Get clean transcript text | `get_video_transcript` | Plain subtitle text, language, data source |
 | See structured metadata | `get_video_metadata` | Title, author, duration, publish date, tags, stats |
 | View audience reactions | `get_video_comments` | Popular comments, timestamped highlights, optional replies |
+| Guide users through Cookie setup | `get_credential_setup_instructions` | Safe setup steps, recommended commands, security notes |
+| Check whether Cookies are configured/logged in | `check_bilibili_credentials` | configured, source, logged_in, next_steps |
 
 ## 💡 Tool Call Examples
 
 > Your AI client will automatically turn your natural-language intent into the corresponding JSON call.
 
+### `get_credential_setup_instructions`
+
+**Best for**: letting an agent guide Cookie setup after installing the MCP server.
+
+Request:
+
+```json
+{
+  "name": "get_credential_setup_instructions",
+  "arguments": {}
+}
+```
+
+Returns: recommended setup commands, global-install commands, required Cookie fields, and security notes; never returns Cookie values.
+
+### `check_bilibili_credentials`
+
+**Best for**: checking whether the current environment has Cookies configured and whether they are logged in.
+
+Request:
+
+```json
+{
+  "name": "check_bilibili_credentials",
+  "arguments": {}
+}
+```
+
+Returns: `configured`, `source` (`env` / `global_config` / `none`), `logged_in`, and `next_steps`; never returns Cookie values.
+
 ### `get_video_transcript`
 
 **Best for**: feeding video content into AI for summarization, note-taking, Q&A, or knowledge management.
@@ -1276,31 +1314,63 @@ Returns: `comments[]` (author, content, likes, timestamp, has_timestamp), `summa
 
 ## 🛡️ API Rate Limiting
 
-Built-in strategies to ensure long-term availability:
-- **Interval**: 500ms (0.5s).
-- **Execution**: Sequential queue, no concurrency.
+Built-in request controls reduce the chance of triggering Bilibili risk checks or API rate limits:
+
+- **Request start interval**: defaults to 500ms (0.5s), configurable with `BILIBILI_RATE_LIMIT_MS`.
+- **Execution model**: throttles API request starts to avoid burst concurrency; intended for local single-user MCP usage.
+- **Retry strategy**: retries 408, 429, 5xx, network errors, and timeouts up to 3 times with exponential backoff.
+- **Timeout**: defaults to 10 seconds, configurable with `BILIBILI_REQUEST_TIMEOUT_MS`.
 
 ---
 
 ## 🛠️ Development Guide
 
 ```bash
+# 1. Clone the repository
 git clone https://github.com/365903728-oss/bilibili-mcp.git
 cd bilibili-mcp
+
+# 2. Install dependencies
 npm install
+
+# 3. Run tests
+npm test
+
+# 4. Build TypeScript
+npm run build
+
+# 5. Watch and rebuild during development
 npm run watch
 ```
 
+Common commands:
+
+| Command | Purpose |
+|---|---|
+| `npm run build` | Compile TypeScript into `dist/` |
+| `npm test` | Run the Vitest unit tests |
+| `npm run watch` | Continuously compile during development |
+| `npm start` | Run the compiled stdio MCP server |
+| `npm pack --dry-run` | Inspect which files would be included in the npm package |
+
+Local debugging notes:
+
+- The MCP server entry point is `dist/index.js`, and the CLI entry point is `dist/cli.js`; run `npm run build` after changing source files.
+- For stdio MCP servers, `stdout` must be reserved for MCP protocol data. Runtime logs and errors should go to `stderr`, so this project uses `console.error` for operational logs.
+- Do not put real Cookies in tests, logs, examples, or commits. To verify credentials, use `npx -y @xzxzzx/bilibili-mcp check` or local environment variables.
+
 ---
 
 ## ⚖️ Safety and Disclaimer
 
-- **Trademark**: Bilibili is a registered trademark of Bilibili Inc. This is a third-party open-source tool.
-- **Liability**: Requests originate locally. Developers are not responsible for account restrictions.
-- **Privacy**: No back-end uploading; credentials stored locally.
+- **Unofficial project**: Bilibili is a registered trademark of Bilibili Inc. This is a third-party open-source helper tool. It is not affiliated with, endorsed by, or representative of Bilibili.
+- **Usage boundary**: This project is intended for personal learning, assisted reading, and content understanding. Follow Bilibili's terms, robots/interface access rules, and applicable laws. Do not use it for commercial exploitation, large-scale scraping, permission bypassing, or other abusive scenarios.
+- **Account risk**: Requests are initiated from the user's local machine. High-frequency access, abnormal request patterns, Cookie leaks, or account-specific state may trigger risk controls, rate limits, or account issues. Users are responsible for their own usage and consequences.
+- **Cookie safety**: Do not put real Cookies in MCP client config, public chats, issues, PRs, READMEs, logs, or test files. Prefer this project's local credential config, runtime environment variables, or a local `.env` file. If Cookies leak, invalidate the old Bilibili login session immediately.
+- **Privacy**: This project does not upload Cookies to any third-party service other than Bilibili's official API. Credentials are stored or read locally according to the user's chosen setup. The current local config file does not promise system-level encryption; protect your device, account, and config file permissions.
 
 ### License
-Open-sourced under **GNU General Public License v3.0**.
+Open-sourced under **GNU General Public License v3.0**. When using, copying, modifying, or distributing this project, follow the GPL-3.0 license requirements.
 
 ---
 
@@ -1319,6 +1389,6 @@ This project is a crystal of AI-collaborative development, spanning from prototy
 If you encounter any issues or have feature suggestions, feel free to reach out:
 
 - **Submit an Issue**: [GitHub Issues](https://github.com/365903728-oss/bilibili-mcp/issues) — **Recommended**, I check and respond regularly.
-- **Discussions**: Join our [GitHub Discussions](https://github.com/365903728-oss/bilibili-mcp/discussions) (if enabled) for general chat.
+- **Discussions**: Join our [GitHub Discussions](https://github.com/365903728-oss/bilibili-mcp/discussions) for general chat.
 
 Thank you for your support!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xzxzzx/bilibili-mcp",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "description": "Bilibili MCP tool for video metadata, transcripts, subtitles, and comment summarization",
   "type": "module",
   "main": "dist/index.js",