jzt-sepp-mcp-server

MCP Server для управления дефектами платформы энергоэффективности (SEPP, sepp.op.yyjzt.com), реализованный на основе FastMCP.

Возможности

• Автоматический вход: через Playwright автоматически выполняется вход через Keycloak SSO, после получения cookie sepp-auth вызовы API выполняются напрямую по HTTP (без необходимости каждый раз открывать браузер); состояние входа сохраняется локально, повторный вход не требуется в течение 7 дней.

  • Также поддерживается вставка JWT sepp-auth из браузера (SEPP_AUTH_TOKEN) для пропуска автоматического входа.

• Получение информации о проектах пользователя: get_user_projects (健康诊所科技 / инженер-разработчик).

• Запрос списка дефектов с фильтрацией по ответственному: query_defects / query_my_defects / get_users (маппинг имя/учётная запись → userId).

• Периодические напоминания:

  • monitor_add создаёт задачу мониторинга (с фильтрацией по ответственному), встроенный планировщик APScheduler выполняет периодический опрос;

  • Уведомление о новых дефектах: уведомление при первом появлении ID дефекта;

  • Уведомление о превышении срока: уведомление, если дефект не обработан дольше timeout_hours (по умолчанию 2 часа);

  • Каналы уведомлений: webhook DingTalk/WeCom/Feishu, SMTP-почта (необходимо настроить хотя бы один, иначе только запись в лог);

  • Состояние мониторинга сохраняется в 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=你的密码

Необязательные (для отправки уведомлений необходимо настроить хотя бы один канал оповещения):

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"]
    }
  }
}

Или с использованием python из venv:

{
  "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") для немедленного однократного выполнения базовой проверки;

3. Далее автоматическая проверка каждые 30 минут: при появлении нового дефекта или превышении 2 часов без обработки будет отправлено уведомление;

4. После перезапуска сервиса мониторинг восстанавливается автоматически (повторное добавление не требуется).

Частые вопросы

• Сбой входа из-за WAF / перехвата капчи: установите SEPP_HEADLESS=false, при первом входе пройдите капчу вручную, после этого состояние входа будет сохранено.

• Ошибка входа "не настроены учётные данные": SEPP_USERNAME / SEPP_PASSWORD пусты и нет действующего cookie.

• Срок действия sepp-auth около 7 дней: после истечения автоматически выполняется повторный вход через Playwright (требуется установленный браузер).

• Возвращаемые поля дефектов зависят от фактических данных платформы: данный инструмент напрямую передаёт исходный JSON платформы; при расчёте превышения срока в уведомлениях мониторинга используется foundTime (или время первого обнаружения).

Примечания по безопасности

• Учётные данные, cookie и состояние входа в браузере сохраняются локально в data/ (добавлено в .gitignore), не отправляйте их в репозиторий.

• Webhook/почта используются только для уведомлений, отправка чувствительных данных не выполняется.