# mr-model MCP 独立服务

mr-model 平台的 **MCP (Model Context Protocol) 独立服务**，从主仓 `mr-model` 拆分出来。

- **主服务（8866）**：`mrmodel.cesario.top` —— Web/API/会员/支付/推送
- **MCP 服务（本仓，8868）**：`mcp.cesario.top` —— 5 个 Model Context Protocol 工具

## 为什么拆

| 动机 | 详情 |
|------|------|
| **稳定独立升级** | MCP 想走自己的迭代节奏，不被主站 PR 阻塞 |
| **未来国内腾讯云迁移** | 必须先拆仓，否则主站 + MCP 一起迁成本翻倍 |
| **业务已 90% 独立** | systemd / 端口 / 域名 / Caddy / Restart 早独立，只差代码仓 + venv |

## 仓库结构

```
mr-model-mcp/
├── .env.example          # 环境变量模板（真实 .env 不入库）
├── README.md             # 本文件
├── requirements.txt      # 5 个精简依赖
├── deploy-mcp.sh         # 拉码/venv/语法/restart/verify/失败回滚
├── backend/
│   ├── mcp_server.py     # 1081 行，5 tools
│   ├── mcp_auth.py       # Bearer token 鉴权
│   ├── database.py       # 最小版（只 get_connection）
│   ├── user_service.py   # 最小版（只 _now_cst）
│   ├── membership_service.py  # 最小版（只 get_active_membership）
│   ├── agent_service.py  # 最小版（只 _labelize_text）
│   ├── config.py         # 最小版（MCP 需要的常量）
│   └── mrmodel_common.py # = 复制自主仓 addons/_mcp_shared/mrmodel_common.py
└── deploy/
    ├── mr-model-mcp.service  # systemd unit
    └── mcp.cesario.top.conf  # Caddy 反代配置
```

## 与主仓的共享代码

`backend/mrmodel_common.py` 是**复制自主仓** `backend/addons/_mcp_shared/mrmodel_common.py` 的副本。

DRY 务实策略：主仓是源头，MCP 仓是副本，**手动 cp 同步**（见 [[../mr-model/docs/mr-model-扩展包架构方案-2026-08-19]] §C 章节）。

每次主仓改源头：
1. 主仓 commit + push
2. `cp backend/addons/_mcp_shared/mrmodel_common.py ../mr-model-mcp/backend/mrmodel_common.py`
3. MCP 仓 commit + push
4. 部署顺序：先主仓 deploy（schema 可能变）→ 再 MCP 仓 deploy-mcp.sh

## 开发（本地）

```bash
# 准备 venv（首次）
python3 -m venv venv
venv/bin/pip install --upgrade pip
venv/bin/pip install -r requirements.txt

# 启动（默认 127.0.0.1:8868）
cp .env.example .env   # 按需改 DATABASE_PATH 指向主仓 DB
venv/bin/python3 backend/mcp_server.py

# 健康检查
curl http://127.0.0.1:8868/healthz
```

## 部署（A1）

```bash
# 首次部署
sudo cp deploy/mr-model-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable mr-model-mcp
bash deploy-mcp.sh   # 第一次跑会建 venv（60-120s）

# 后续升级
bash deploy-mcp.sh
```

`deploy-mcp.sh` 7 步：备份 service → 拉码 → venv → 语法检查 → 重启 → 健康检查 → 失败回滚。

## 故障排查

| 症状 | 排查 |
|------|------|
| 8868 起不来 | `journalctl -u mr-model-mcp -n 50` 看 systemd 日志 |
| healthz 5s 内非 200 | deploy-mcp.sh 自动 git revert + restart |
| 5 tools 全 401 | 主仓 sessions 表无有效 token（先登录主站拿 token 再试） |
| SQLite lock | 走主仓 `mrmodel.db`，并发已被 `busy_timeout=15s` 兜底 |
| Caddy 502 | `systemctl status caddy` + `caddy reload` |

## 5 个 MCP 工具

| 工具 | 用途 |
|------|------|
| `query_video_list` | 按博主/标签/时间窗查视频列表 |
| `query_comments` | 查视频评论（带点赞/时间/AI 标签） |
| `search_video_transcripts` | 全文检索视频 OCR 文本 |
| `search_videos` | 综合搜索（标题/简介/标签） |
| `query_blogger_opinions` | 查博主历史观点（用于辩证法） |

详见 `backend/mcp_server.py` 每 tool 的 docstring。

## 维护

- **版本**：跟随主仓节奏，无独立版本号
- **回滚**：`git revert HEAD` + `bash deploy-mcp.sh`
- **监控**：主仓 mcp_addon `/api/_addon/mcp/healthz` 探活 8868

---

*创建于 2026-08-19（mr-model B 档 MCP 拆分）*