Skip to main content
Glama
jzt-sepp-mcp-server

jzt-sepp-mcp-server

by zhengziha

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: DevSecOps 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

Tool

Description

login_status

Login status, token expiration time

get_user_projects

Current user's project information

get_users(keyword)

User list (filtered by name/account), used to look up userId

query_defects(...)

Query defects, supports fuzzy_responser / dev_responser_id / test_responser_id / status / priority / summary filtering; when no assignee is specified, defaults to "me" (default user 郑自航/1001967)

query_my_defects(...)

Query "my" defects

monitor_add(...)

Add monitoring (if assignee is not filled, defaults to monitoring "me"; polling interval + new/timeout reminder switches)

monitor_run_once(name)

Run a check immediately

monitor_list / monitor_remove / monitor_enable

Monitoring management

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:

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.

Available Tools

10 tools
get_user_projectsA

获取当前登录用户在能效平台的项目信息。

示例返回:[{"productCode": "JKZS", "productId": 17, "roleName": "开发工程师", "productName": "健康诊所科技"}](该信息基本固定)

Inputs: no named parameters. Returns: result

get_usersA

查询能效平台用户列表(含 userId/userName/userAccount),可按姓名或账号模糊过滤。

用于把负责人姓名/账号映射为 userId,再传给 query_defects 过滤。

Inputs: keyword. Returns: result

login_statusA

查看当前登录状态(是否已登录、账号、sepp-auth 过期时间)及默认用户信息

Inputs: no named parameters. Returns: object

monitor_addA

新增一个缺陷监控任务(自动定时轮询 + 提醒)。

  • 负责人不填时默认监控"我"(默认用户 郑自航/1001967);也可指定: fuzzy_responser(userId/姓名/账号,查别人),或 dev_responser_id / test_responser_id(用 get_users 查 userId)

  • new_defect_alert: 是否提醒新增缺陷

  • timeout_alert / timeout_hours: 是否提醒处理超时,超过 N 小时未处理(默认 2 小时)

  • 首次执行为基线检查(只记录不提醒),之后开始提醒。

  • 提醒通过 webhook(钉钉/企微/飞书)或邮件发送,未配置时仅打印日志。 建议先 monitor_run_once 建立基线。

Inputs: name (required), status, timeout_alert, timeout_hours, +5 more. Returns: object

monitor_enableC

启用/停用一个缺陷监控任务

Inputs: name (required), enabled (required). Returns: object

monitor_listB

查看所有缺陷监控任务及状态(含已记录缺陷数)

Inputs: no named parameters. Returns: object

monitor_removeB

删除一个缺陷监控任务

Inputs: name (required). Returns: object

monitor_run_onceB

立即执行一次指定监控的检查(不等定时周期),返回本次结果(新增/超时数等)

Inputs: name (required). Returns: object

query_defectsA

查询缺陷列表(支持按负责人过滤)。

参数:

  • fuzzy_responser: 负责人模糊匹配,可填 userId/姓名/账号,例如 "1001967" 或 "郑自航"

  • dev_responser_id: 开发负责人 userId(用 get_users 查询)

  • test_responser_id: 测试负责人 userId

  • status: 缺陷状态,逗号分隔多个,默认 "1,2,3,4,5,6"(全部)

  • priority: 优先级过滤

  • summary: 标题关键字过滤

  • page_num / page_size: 分页

默认行为:三个负责人参数都不填时,默认查"我"(默认用户 郑自航/1001967)的缺陷, 与 query_my_defects 等价;要查别人请显式传 fuzzy_responser(姓名/账号/userId)。

返回平台的原始 JSON(含 total / list)。

Inputs: status, summary, page_num, priority, +4 more. Returns: object

query_my_defectsA

查询"我"(默认用户 郑自航/1001967)负责的缺陷列表。

等价于 query_defects(fuzzy_responser=默认用户 userId)。

Inputs: status, page_num, page_size. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools are distinct, but query_my_defects duplicates query_defects with default parameters, causing potential confusion about which to use. The monitor_* tools are clearly separated from query tools, but the redundant convenience wrapper slightly reduces clarity.

    Naming Consistency4/5

    The majority follow a verb_noun pattern (get_user_projects, query_defects, monitor_add, etc.), but login_status deviates by using a noun phrase instead of a verb action. This is a minor inconsistency, easily readable but not perfectly uniform.

    Tool Count5/5

    10 tools is well-scoped for the domain of user lookup, defect querying, and monitoring lifecycle. Each tool serves a clear purpose, and the count is neither too sparse nor excessive for the apparent functionality.

    Completeness4/5

    The tool surface covers user info retrieval, defect querying with filtering, and full monitoring lifecycle (add, list, remove, enable, run_once). A minor gap is the lack of an update/edit operation for monitoring tasks, but this can be worked around by delete/add, so it's not critical.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Allows developers to query security findings (SAST issues, secrets, patches) using natural language within AI-assisted tools like Claude Desktop, Cursor, and other MCP-compatible environments.
      17
      11
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Integrates SAST, DAST, IAST, and SCA security testing tools for AI-powered DevSecOps automation, enabling comprehensive security scanning and reporting through natural language interfaces.
      17
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI coding assistants to leverage Application Security Posture Management (ASPM) capabilities, allowing developers to write secure code, query security risks, trigger diff scans, and manage security findings directly from their AI assistant.
      5
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables natural-language chat-driven API testing, letting users upload API specs, run deterministic pytest checks against live targets, inspect results, create defects, and view failure trends.
      MIT