jzt-sepp-mcp-server

MCP-Server für das Fehlermanagement der Energieeffizienzplattform (SEPP, sepp.op.yyjzt.com), basierend auf FastMCP.

Funktionen

• Automatische Anmeldung: Automatischer Keycloak-SSO-Login über Playwright, danach direkter HTTP-Aufruf der Schnittstellen mit dem sepp-auth-Cookie (kein Browserstart bei jedem Mal erforderlich); der Anmeldestatus wird lokal gespeichert, 7 Tage ohne erneute Anmeldung.

  • Es wird auch unterstützt, das sepp-auth-JWT direkt aus dem Browser einzufügen (SEPP_AUTH_TOKEN), um die automatische Anmeldung zu überspringen.

• Benutzerprojektinformationen abrufen: get_user_projects (Health Clinic Technology / Development Engineer).

• Fehlerliste abfragen, Filterung nach Verantwortlichem unterstützt: query_defects / query_my_defects / get_users (Name/Konto → userId-Zuordnung).

• Zeitgesteuerte Erinnerungen:

  • monitor_add erstellt Überwachungsaufgaben (Filterung nach Verantwortlichem unterstützt), mit integrierter APScheduler-Zeitplanabfrage;

  • Erinnerung bei neuen Fehlern: Erinnerung beim ersten Auftreten einer Fehler-ID;

  • Timeout-Erinnerung: Erinnerung, wenn ein Fehler länger als timeout_hours (Standard 2 Stunden) nicht bearbeitet wurde;

  • Erinnerungskanäle: DingTalk/WeCom/Feishu-Webhook, SMTP-E-Mail (mindestens eines konfigurieren, sonst nur Log-Ausgabe);

  • Der Überwachungsstatus wird in data/monitor_state.json gespeichert und nach einem Dienstneustart automatisch wiederhergestellt.

Related MCP server: Bug Bounty MCP Server

Verzeichnisstruktur

.
├── sepp_mcp/
│   ├── server.py     # FastMCP 服务（工具定义）
│   ├── auth.py       # 自动登录（Playwright SSO / token / cookie 缓存）
│   ├── client.py     # HTTP 客户端（登录态复用 + 401 自动重登）
│   ├── monitor.py    # 缺陷监控（新增/超时提醒 + APScheduler）
│   ├── alerts.py     # 告警通知（webhook / 邮件）
│   ├── cli.py        # 命令行入口（serve / run-check / daemon）
│   └── config.py     # 配置加载（.env / config.yaml）
├── .env.example
└── pyproject.toml

Installation

cd jzt-sepp-mcp-server

# 方式一：uv（推荐）
uv sync

# 方式二：pip
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 安装 Playwright Chromium 浏览器（自动登录必需）
uv run playwright install chromium   # 或 .venv/bin/playwright install chromium

Konfiguration

cp .env.example .env   # 然后编辑

Pflichtfelder:

SEPP_USERNAME=你的账号
SEPP_PASSWORD=你的密码

Optional (für Benachrichtigungen muss mindestens ein Alarmkanal konfiguriert sein):

SEPP_WEBHOOK_URL=https://oapi.dingtalk.com/robot/send?access_token=xxx
SEPP_WEBHOOK_TYPE=dingtalk   # dingtalk | wecom | feishu | generic
SEPP_EMAIL_TO=you@example.com
SEPP_SMTP_HOST=...
SEPP_TIMEOUT_HOURS=2         # 超时提醒阈值（小时）

MCP ausführen (Anbindung an Claude Code / CodeBuddy / andere Clients)

# 方式一：uv
uv run python -m sepp_mcp serve

# 方式二：venv
.venv/bin/python -m sepp_mcp serve

Beispiel für die mcpServers-Konfiguration des Clients:

{
  "mcpServers": {
    "sepp": {
      "command": "uv",
      "args": ["--directory", "/Users/zhengzihang/Documents/my-mcp/jzt-sepp-mcp-server", "run", "python", "-m", "sepp_mcp"]
    }
  }
}

Oder mit dem Python der venv:

{
  "mcpServers": {
    "sepp": {
      "command": "/Users/zhengzihang/Documents/my-mcp/jzt-sepp-mcp-server/.venv/bin/python",
      "args": ["-m", "sepp_mcp"]
    }
  }
}

Bereitgestellte Tools

Geplante Aufgaben (Erinnerungen)

Die Erinnerungsfunktion ist in den MCP-Dienst integriert (der Dienst fragt beim Laufen automatisch ab und stellt die Überwachung wieder her). Zusätzlich werden zwei eigenständige Ausführungsarten angeboten:

1) Dauerhafter Daemon (empfohlen für langfristige Erinnerungen)

nohup .venv/bin/python -m sepp_mcp daemon > data/daemon.log 2>&1 &

2) In Kombination mit cron / CodeBuddy-Automatisierung

.venv/bin/python -m sepp_mcp run-check --name my_defects

Kann in die crontab eingetragen werden (z. B. an Werktagen alle 30 Minuten):

*/30 * * * 1-5 cd /Users/zhengzihang/Documents/my-mcp/jzt-sepp-mcp-server && .venv/bin/python -m sepp_mcp run-check --name my_defects >> data/cron.log 2>&1

Verwendungsablauf (am Beispiel der Überwachung der eigenen Fehler)

1. MCP-Dienst zum ersten Mal starten, monitor_add(name="my_defects") aufrufen, um eine Überwachung einzurichten (standardmäßig wird "ich" = Zheng Zihang/1001967 überwacht, die Basislinie wird automatisch erfasst);

2. monitor_run_once(name="my_defects") aufrufen, um die Basislinie einmal sofort auszuführen;

3. Danach wird alle 30 Minuten automatisch geprüft: neue Fehler oder länger als 2 Stunden nicht bearbeitete Fehler lösen eine Erinnerung aus;

4. Nach einem Dienstneustart wird die Überwachung automatisch wiederhergestellt (kein erneutes Hinzufügen erforderlich).

Häufige Fragen

• WAF / Captcha-Blockierung führt zu Anmeldefehler: SEPP_HEADLESS=false setzen, beim ersten Login das Captcha manuell lösen, danach wird der Anmeldestatus gespeichert.

• Anmeldung meldet "Keine Kontodaten konfiguriert": SEPP_USERNAME / SEPP_PASSWORD sind leer und es gibt kein gültiges Cookie.

• sepp-auth ist ca. 7 Tage gültig: Nach Ablauf wird automatisch ein neuer Playwright-Login durchgeführt (Browser muss installiert sein).

• Die zurückgegebenen Fehlerfelder richten sich nach der tatsächlichen Plattform: Dieses Tool gibt die ursprünglichen JSON-Daten der Plattform direkt durch; die Überwachungswarnung berechnet den Timeout anhand von foundTime (oder dem Zeitpunkt der ersten Erkennung).

Sicherheitshinweise

• Kontodaten, Cookies und der Browser-Anmeldestatus werden lokal in data/ gespeichert (in .gitignore aufgenommen), bitte nicht ins Repository committen.

• Webhook/E-Mail dienen nur der Benachrichtigung, es werden keine sensiblen Daten nach außen gesendet.