mr-model MCP eigenständiger Dienst

Der eigenständige MCP-Dienst (Model Context Protocol) der mr-model-Plattform, aus dem Haupt-Repository mr-model ausgegliedert.

• Hauptdienst (8866): mrmodel.cesario.top — Web/API/Mitglieder/Zahlung/Push

• MCP-Dienst (dieses Repository, 8868): mcp.cesario.top — 5 Model Context Protocol Tools

Warum die Ausgliederung

Repository-Struktur

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

Gemeinsamer Code mit dem Haupt-Repository

backend/mrmodel_common.py ist eine Kopie aus dem Haupt-Repository backend/addons/_mcp_shared/mrmodel_common.py.

Pragmatische DRY-Strategie: Das Haupt-Repository ist die Quelle, das MCP-Repository ist die Kopie, manuelle cp-Synchronisierung (siehe [[../mr-model/docs/mr-model-扩展包架构方案-2026-08-19]] Abschnitt C).

Jedes Mal, wenn das Haupt-Repository die Quelle ändert:

1. Haupt-Repository commit + push

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

3. MCP-Repository commit + push

4. Bereitstellungsreihenfolge: zuerst Haupt-Repository deployen (Schema kann sich ändern) → dann MCP-Repository deploy-mcp.sh

Entwicklung (lokal)

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

Bereitstellung (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 in 7 Schritten: Service sichern → Code ziehen → venv → Syntaxprüfung → Neustart → Health-Check → Rollback bei Fehler.

Fehlerbehebung

Die 5 MCP-Tools

Details siehe docstring jedes Tools in backend/mcp_server.py.

Wartung

• Version: Folgt dem Rhythmus des Haupt-Repositorys, keine eigene Versionsnummer

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

• Überwachung: mcp_addon des Haupt-Repositorys /api/_addon/mcp/healthz prüft die Erreichbarkeit von 8868

Erstellt am 2026-08-19 (mr-model B-Stufe MCP-Ausgliederung)