jzt-sepp-mcp-server

エネルギー効率プラットフォーム（SEPP、sepp.op.yyjzt.com）の欠陥管理を行う MCP Server。FastMCP ベースでラップされています。

機能

• 自動ログイン：Playwright で Keycloak SSO ログインを自動実行し、sepp-auth cookie を取得後、直接 HTTP で API を呼び出します（毎回ブラウザを起動する必要なし）。ログイン状態はローカルに永続化され、7 日間は再ログイン不要です。

  • ブラウザからコピーした sepp-auth JWT（SEPP_AUTH_TOKEN）を直接貼り付けて自動ログインをスキップすることも可能です。

• ユーザー・プロジェクト情報の取得：get_user_projects（健康診療科技 / 開発エンジニア）。

• 欠陥リストの照会、担当者によるフィルタリング対応：query_defects / query_my_defects / get_users（氏名/アカウント → userId マッピング）。

• 定期リマインダー：

  • monitor_add で監視タスクを作成（担当者によるフィルタリング対応）、APScheduler による定期ポーリングを内蔵。

  • 新規欠陥リマインダー：欠陥 ID が初めて出現したときに通知。

  • タイムアウト・リマインダー：欠陥が timeout_hours（デフォルト 2 時間）を超えて未処理の場合に通知。

  • 通知チャネル：钉钉（DingTalk）/企微（WeCom）/飞书（Feishu）webhook、SMTP メール（最低 1 つ設定必須。未設定の場合はログ出力のみ）。

  • 監視状態は data/monitor_state.json に永続化され、サービス再起動後に自動復元されます。

Related MCP server: Bug Bounty MCP Server

ディレクトリ構成

.
├── 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

インストール

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

設定

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

必須：

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

任意（アラートチャネルは最低 1 つ設定しないとプッシュされません）：

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 の実行（Claude Code / CodeBuddy / その他クライアントへの接続）

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

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

クライアントの mcpServers 設定例：

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

または venv の python を使用：

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

提供ツール

定期タスク（リマインダー）

リマインダー機能は MCP サービス内に組み込まれています（サービス実行中に自動ポーリングと監視の復元を行います）。その他に、独立した 2 つの実行方法があります：

1) 常駐 daemon（長期的なリマインダーに推奨）

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

2) cron / CodeBuddy 自動化と組み合わせる

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

crontab に設定可能です（例：平日 30 分ごと）：

*/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

利用フロー（自分を監視する場合の例）

1. 初回に MCP サービスを起動し、monitor_add(name="my_defects") を呼び出して監視を確立（デフォルトで「自分」=郑自航/1001967 を監視し、ベースラインが自動記録されます）。

2. monitor_run_once(name="my_defects") を呼び出してベースラインを 1 回実行。

3. 以降 30 分ごとに自動チェック：新規欠陥の出現 または 2 時間を超えて未処理 の場合にリマインダーがプッシュされます。

4. サービス再起動後も監視は自動復元されます（再追加の必要なし）。

よくある質問

• WAF / 認証コードによるブロックでログイン失敗：SEPP_HEADLESS=false を設定し、初回ログイン時に手動で認証を通過。以降はログイン状態が永続化されます。

• ログイン時に「アカウント・パスワード未設定」エラー：SEPP_USERNAME / SEPP_PASSWORD が空、かつ有効な cookie がない場合。

• sepp-auth の有効期限は約 7 日：期限切れ後は自動的に Playwright で再ログインします（ブラウザのインストールが必要）。

• 欠陥の返却フィールドはプラットフォームの実物が基準：本ツールはプラットフォームの生 JSON をそのまま透過します。監視アラートは foundTime（または初回検出時刻）に基づいてタイムアウトを計算します。

セキュリティについて

• アカウント・パスワード、cookie、ブラウザのログイン状態はすべてローカルの data/ に保存されます（.gitignore に追加済み）。リポジトリにコミットしないでください。

• webhook/メールはリマインダーのみに使用し、機密データの外部送信は行いません。