# tieba-mcp

MCP server for reading public Baidu Tieba content — 在真实浏览器会话内读取百度贴吧公开内容的 MCP 服务。

> ⚠️ **免责声明**
> - 本项目**仅用于学习与研究目的**，请遵守《百度贴吧用户协议》及相关法律法规。
> - 禁止商业用途，禁止大规模抓取、禁止将抓取数据对外售卖或用于实质性替代平台功能。
> - 本项目读取的是登录用户本人可见的公开内容，请控制请求频率（默认已内置 1s 节流）。
> - 使用本项目产生的任何后果由使用者自行承担。

## 功能

| 工具 | 说明 |
|---|---|
| `tieba_search` | 吧内搜索，返回帖子列表（标题/摘要/回复数/作者/发布时间） |
| `tieba_detail` | 按 tid 获取帖子详情（楼主楼层、作者、吧名、回复数） |
| `tieba_creator` | 获取指定用户的公开发帖列表（可选，需 MediaCrawler） |
| `tieba_health` | 环境与登录态自检 |

全部为只读操作。请求经常驻的真实 Edge/Chromium 浏览器会话发出（携带你注入的登录态），
因此不会被贴吧的非浏览器客户端风控拦截；搜索/详情接口走贴吧 PC 版 JSON API，响应毫秒级。

## 架构

```
MCP 层 (index.js, Node stdio)
  └── 常驻 worker (worker.py, Playwright + Edge)
        ├── 浏览器持久化上下文（登录态复用）
        ├── 贴吧 PC JSON API（搜索/详情，带签名）
        └── [可选] MediaCrawler CLI（tieba_creator）
```

PC 签名密钥**不硬编码**：由 `extract_sign_secret.py` 从贴吧公开前端 JS（tb3.bdstatic.com
公共 CDN 的 base 包，每个浏览器加载贴吧首页都会收到）中运行时提取，写入 `sign_secret.txt`
（已 gitignore）。

## 快速开始

依赖：

- Node.js ≥ 20
- Python 3.10+ 与 [Playwright](https://playwright.dev/python/)：`pip install playwright`
- Microsoft Edge（`channel="msedge"`，无需额外下载浏览器）
- （可选，仅 `tieba_creator` 需要）[MediaCrawler](https://github.com/NanmiCoder/MediaCrawler) 检出目录

安装与配置：

```bash
npm install
python extract_sign_secret.py        # 提取 PC 签名密钥 -> sign_secret.txt
# 如遇"百度安全验证"拦截：加 --proxy http://127.0.0.1:7892（你的代理地址）或重试一次
```

获取登录态（可选，用于更高稳定性）：

1. 浏览器登录 [tieba.baidu.com](https://tieba.baidu.com/)
2. F12 → Application → Cookies → `https://tieba.baidu.com` → 找到 **BDUSS**（httpOnly，需在
   Cookie 面板而非 console 中复制，`document.cookie` 拿不到）
3. 将 cookie 通过环境变量 `TIEBA_COOKIE` 注入，如 `BDUSS=xxx; STOKEN=yyy`

注册到 Claude Code：

```bash
claude mcp add tieba -- node index.js
# 或带环境变量：
claude mcp add tieba --env TIEBA_COOKIE="BDUSS=xxx" -- node index.js
```

## 环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `TIEBA_COOKIE` | 空 | 登录 cookie（`BDUSS=...; STOKEN=...`），不设也能以游客身份搜索 |
| `TIEBA_SIGN_SECRET` | 空 | 签名密钥，手动指定时优先于 `sign_secret.txt` |
| `TIEBA_MIN_INTERVAL` | `1.0` | 两次 API 请求的最小间隔（秒） |
| `TIEBA_USER_DATA_DIR` | `<repo>/browser_data` | 浏览器持久化目录（登录态） |
| `TIEBA_MC_DIR` | 空 | MediaCrawler 检出目录（仅 `tieba_creator` 需要） |
| `TIEBA_PYTHON` | `python` | worker 使用的 Python 解释器 |
| `TIEBA_RESULTS_DIR` | `<repo>/results` | 抓取结果落盘目录（仅 creator 工具使用） |

提示：贴吧对无代理的国内 IP 可能有安全验证，连接不稳定时可开启全局代理（系统代理会被
浏览器自动使用）。

## 工作原理

- **浏览器内请求**：请求通过 `page.evaluate` 在浏览器上下文中发出（`credentials: include`），
  携带真实浏览器指纹与你的登录态，绕开非浏览器客户端的 TLS 指纹风控。
- **PC 签名**：贴吧 PC JSON API 要求参数签名（sorted params + secret → md5）。密钥与算法
  均来自贴吧公开前端 JS（`tb3.bdstatic.com/tb/pc/pc-common/static/js/base.*.js` 中
  `t === Dt.PC ? '<key>' : ...` 结构），`extract_sign_secret.py` 按该结构提取；若贴吧调整
  打包结构，可手动设置 `TIEBA_SIGN_SECRET`。
- **限速**：worker 内置请求节流（`TIEBA_MIN_INTERVAL`），默认 1 秒。

## 许可与致谢

- 本项目整体采用 **NON-COMMERCIAL LEARNING LICENSE 1.1**（见 [LICENSE](LICENSE) 与 [NOTICE](NOTICE)）
- 签名实现与浏览器请求模式源自 [MediaCrawler](https://github.com/NanmiCoder/MediaCrawler)
  的贴吧模块（`media_platform/tieba/client.py`），致谢 [NanmiCoder](https://github.com/NanmiCoder)