jzt-sepp-mcp-server

에너지 효율 플랫폼(SEPP, sepp.op.yyjzt.com) 결함 관리를 위한 MCP Server로, FastMCP 기반으로 캡슐화되어 있습니다.

기능

• 자동 로그인: Playwright로 Keycloak SSO 로그인을 자동 수행하여 sepp-auth 쿠키를 획득한 후 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 서비스 내에 내장되어 있습니다(서비스 실행 중 자동으로 폴링하며 모니터링을 복구합니다). 추가로 두 가지 독립 실행 방식을 제공합니다:

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가 비어 있고 유효한 쿠키도 없는 경우입니다.

• sepp-auth 유효 기간 약 7일: 만료 후 자동으로 Playwright 로그인을 다시 수행합니다(브라우저 설치 필요).

• 결함 반환 필드는 플랫폼 실제 기준을 따름: 이 도구는 플랫폼 원본 JSON을 그대로 전달합니다. 모니터링 알림은 foundTime(또는 최초 발견 시간)을 기준으로 타임아웃을 계산합니다.

보안 안내

• 계정 비밀번호, 쿠키, 브라우저 로그인 상태는 모두 로컬 data/에 저장됩니다(.gitignore에 포함됨). 저장소에 커밋하지 마세요.

• webhook/이메일은 알림 용도로만 사용되며, 민감 데이터를 외부로 전송하지 않습니다.