mr-model MCP Standalone Service

The MCP (Model Context Protocol) standalone service for the mr-model platform, split out from the main repository mr-model.

• Main service (8866): mrmodel.cesario.top — Web/API/Membership/Payment/Push

• MCP service (this repo, 8868): mcp.cesario.top — 5 Model Context Protocol tools

Why the split

Repository structure

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 反代配置

Shared code with the main repository

backend/mrmodel_common.py is a copy from the main repo backend/addons/_mcp_shared/mrmodel_common.py.

Pragmatic DRY strategy: the main repo is the source, the MCP repo is the copy, manually synced via cp (see [[../mr-model/docs/mr-model-扩展包架构方案-2026-08-19]] §C).

Each time the source changes in the main repo:

1. Main repo commit + push

2. cp backend/addons/_mcp_shared/mrmodel_common.py ../mr-model-mcp/backend/mrmodel_common.py

3. MCP repo commit + push

4. Deployment order: main repo deploy first (schema may change) → then MCP repo deploy-mcp.sh

Development (local)

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

Deployment (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 steps: backup service → pull code → venv → syntax check → restart → health check → rollback on failure.

Troubleshooting

The 5 MCP tools

See the docstring of each tool in backend/mcp_server.py.

Maintenance

• Version: follows the main repo cadence, no independent version number

• Rollback: git revert HEAD + bash deploy-mcp.sh

• Monitoring: main repo mcp_addon /api/_addon/mcp/healthz probes 8868

Created on 2026-08-19 (mr-model B-tier MCP split)