# 📺 bili-note-mcp

**把 B站课程视频自动转为结构化学习笔记的 MCP 服务器。**

让任何支持 MCP 的 Agent（DSH、Claude Desktop、Cursor…）都能一键完成：
**B站视频 → 字幕提取 → VitePress 学习笔记 → 保存到本地**。

> 这是你在简历上的 **MCP 协议开发** 经历：Agent 工具扩展是当前 AI 工程最热的方向。

## 为什么做这个

备考时最耗时的不是"看视频"，而是"整理笔记"。这个 MCP 服务器把整个流程封装成 Agent 可调用的工具：

```
Agent 说"把鹏哥C语言 P117 的字幕做成笔记"
   └─→ bili_get_transcript(BV17a7K64ELH)   ← 提取字幕（带时间戳）
   └─→ bili_generate_note(...)              ← 转结构化笔记（要点/Active Recall/分段）
   └─→ bili_save_note(...)                  ← 保存到 VitePress 笔记目录
```

## 快速开始

```bash
# 1. 安装依赖
pip install 'mcp[cli]'

# 2. 测试（离线，不连 B站）
python tests/test_bili_note.py

# 3. 手动验证字幕提取（用任意 BV 号）
python -m tools.bili_subtitle BV17a7K64ELH

# 4. 启动 MCP 服务器（stdio 模式）
python server.py
```

## 配置到 DSH

在 `cordis.patch.yml` 的 insert 列表加：

```yaml
- id: mcp-client-bili-note
  name: '@huiliyi37/dsh-mcp-client'
  config:
    transport: stdio
    serverName: bili-note
    command: 'python'
    args: ['C:\Users\Administrator\Desktop\deeepseek\bili-note-mcp\server.py']
    toolCallTimeoutMs: 120000
    failOnStartupError: false
```

重启 DSH 后，Agent 就能调用 `bili_*` 系列工具。

## MCP 工具清单

| 工具名 | 功能 |
|:---|:---|
| `bili_get_video_info` | 获取视频元信息（标题/UP主/时长） |
| `bili_get_transcript` | 提取字幕全文（带时间戳，优先 AI 字幕） |
| `bili_generate_note` | 字幕 → VitePress 笔记（要点 + Active Recall） |
| `bili_save_note` | 保存笔记到本地目录 |
| `bili_search_video` | 搜索 B站视频（注意 412 风控） |

## 目录结构

```
bili-note-mcp/
├── server.py              # MCP 服务器入口（FastMCP）
├── tools/
│   ├── bili_subtitle.py   # B站 API 字幕提取
│   ├── bili_search.py     # B站视频搜索
│   └── note_generator.py  # 字幕 → VitePress 笔记
├── tests/
│   └── test_bili_note.py  # 离线测试
├── examples/
├── AGENTS.md
└── README.md
```

## 技术要点

- **FastMCP 协议**：官方 MCP Python SDK 的高层封装，`@mcp.tool` 装饰器自动生成工具 schema
- **无 Cookie 优先**：AI 字幕走公共接口，人工字幕需登录 Cookie（可选）
- **字幕临时链接**：约 15 分钟有效，失败自动尝试下一轨
- **离线可测**：核心逻辑（BV 解析/时间戳/笔记结构）不依赖外部 API

## 已知限制（实测）

- **字幕轨需要登录态**：B站对字幕接口（`/x/player/wbi/v2`）有登录校验，未带 Cookie 时
  多数视频返回"无可用字幕"。解决方式：
  1. 从浏览器复制 Cookie（`SESSDATA` 等），传给 `bili_get_transcript(cookies=...)`
  2. 或先用浏览器拿到字幕临时 URL（约 15 分钟有效），直接调用 `fetch_subtitle_json`
  3. 视频**元信息**（标题/UP主/时长）无 Cookie 即可用，已验证 ✅

## 简历亮点

- 开发 MCP 协议服务器，展示 **Agent 工具扩展** 能力
- 实际服务备考场景：B站课程 → 自动笔记，自己天天用
- FastMCP + 标准库，无重型框架，代码可读

## 许可证

MIT © 2026 wpc725562-dotcom