jzt-sepp-mcp-server

An MCP Server for defect management on the Energy Efficiency Platform (SEPP, sepp.op.yyjzt.com), built on FastMCP.

Features

• Automatic login: Uses Playwright to automatically go through Keycloak SSO login, obtains the sepp-auth cookie, then directly calls the API over HTTP (no need to open a browser each time); the login state is persisted locally, no login required for 7 days.

  • Also supports directly pasting the sepp-auth JWT from the browser (SEPP_AUTH_TOKEN) to skip automatic login.

• Get user project info: get_user_projects (健康诊所科技 / Development Engineer).

• Query defect list, supports filtering by assignee: query_defects / query_my_defects / get_users (name/account → userId mapping).

• Scheduled reminders:

  • monitor_add creates a monitoring task (supports filtering by assignee), with built-in APScheduler periodic polling;

  • New defect reminder: reminds when a defect ID appears for the first time;

  • Timeout reminder: reminds when a defect remains unhandled beyond timeout_hours (default 2 hours);

  • Reminder channels: 钉钉/企微/飞书 webhook, SMTP email (configure at least one, otherwise only logs are printed);

  • Monitoring state is persisted in data/monitor_state.json and automatically restored after service restart.

Related MCP server: Bug Bounty MCP Server

Directory Structure

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

Configuration

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

Required:

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

Optional (at least one alert channel must be configured to receive push notifications):

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         # 超时提醒阈值（小时）

Running MCP (connecting to Claude Code / CodeBuddy / other clients)

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

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

Client mcpServers configuration example:

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

Or use the venv python:

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

Provided Tools

Scheduled Tasks (Reminders)

Reminder capability is built into the MCP service (it automatically polls and restores monitoring while the service is running). Two additional standalone running modes are also provided:

1) Resident daemon (recommended for long-term reminders)

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

2) With cron / CodeBuddy automation

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

Can be placed in crontab (e.g., every 30 minutes on workdays):

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

Usage Flow (using monitoring yourself as an example)

1. On first startup of the MCP service, call monitor_add(name="my_defects") to set up monitoring (defaults to monitoring "me" = 郑自航/1001967, and automatically records the baseline);

2. Call monitor_run_once(name="my_defects") to run a baseline immediately;

3. After that, it automatically checks every 30 minutes: new defects appear or unhandled for more than 2 hours will trigger a reminder;

4. After the service restarts, monitoring is automatically restored (no need to re-add).

FAQ

• WAF / CAPTCHA blocking causes login failure: Set SEPP_HEADLESS=false, manually pass the verification on first login, and the login state will be persisted afterward.

• Login reports "account/password not configured": SEPP_USERNAME / SEPP_PASSWORD are empty, and there is no valid cookie.

• sepp-auth is valid for about 7 days: After expiration, it will automatically re-login via Playwright (requires the browser to be installed).

• Defect return fields are subject to the actual platform: This tool directly passes through the platform's raw JSON; monitoring alerts calculate timeout based on foundTime (or the first discovery time).

Security Notes

• Account passwords, cookies, and browser login state are all stored locally in data/ (already added to .gitignore); do not commit them to the repository.

• Webhook/email are used only for reminders, not for sending sensitive data externally.