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

开发（本地）

# 准备 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）

# 首次部署
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 拆分）