jzt-sepp-mcp-server

Servidor MCP para la gestión de defectos de la plataforma de eficiencia energética (SEPP, sepp.op.yyjzt.com), encapsulado sobre FastMCP.

Funcionalidades

• Inicio de sesión automático: utiliza Playwright para completar automáticamente el inicio de sesión SSO de Keycloak, obtiene la cookie sepp-auth y luego realiza llamadas HTTP directas a la API (sin necesidad de abrir el navegador cada vez); el estado de inicio de sesión se persiste localmente, sin necesidad de volver a iniciar sesión durante 7 días.

  • También admite pegar directamente el JWT sepp-auth del navegador (SEPP_AUTH_TOKEN) para omitir el inicio de sesión automático.

• Obtener información de proyectos del usuario: get_user_projects (Health Clinic Technology / Ingeniero de desarrollo).

• Consultar lista de defectos, con filtro por responsable: query_defects / query_my_defects / get_users (mapeo nombre/cuenta → userId).

• Recordatorios programados:

  • monitor_add crea tareas de monitoreo (admite filtro por responsable), con sondeo periódico integrado mediante APScheduler;

  • Aviso de nuevos defectos: avisa cuando un ID de defecto aparece por primera vez;

  • Aviso de tiempo de espera agotado: avisa cuando un defecto supera timeout_hours (por defecto 2 horas) sin ser atendido;

  • Canales de aviso: webhook de DingTalk/WeCom/Feishu, correo SMTP (al menos configurar uno, de lo contrario solo se registra en el log);

  • El estado del monitoreo se persiste en data/monitor_state.json y se restaura automáticamente al reiniciar el servicio.

Related MCP server: Bug Bounty MCP Server

Estructura de directorios

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

Instalación

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

Configuración

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

Obligatorio:

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

Opcional (los canales de alerta deben configurarse al menos uno para recibir notificaciones):

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

Ejecutar MCP (integrar con Claude Code / CodeBuddy / otros clientes)

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

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

Ejemplo de configuración de mcpServers en el cliente:

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

O usar el python del venv:

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

Herramientas proporcionadas

Tareas programadas (avisos)

La capacidad de aviso está integrada en el servicio MCP (el servicio sondea y restaura el monitoreo automáticamente durante su ejecución). Además, se proporcionan dos formas de ejecución independientes:

1) Daemon residente (recomendado para avisos a largo plazo)

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

2) Con cron / automatización de CodeBuddy

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

Se puede colocar en crontab (por ejemplo, cada 30 minutos en días laborables):

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

Flujo de uso (por ejemplo, monitorear los propios defectos)

1. Inicie el servicio MCP por primera vez y llame a monitor_add(name="my_defects") para establecer el monitoreo (por defecto monitorea "mis" defectos = Zheng Zihang/1001967, y registrará automáticamente la línea base);

2. Llame a monitor_run_once(name="my_defects") para ejecutar la línea base inmediatamente;

3. A partir de entonces, se comprueba automáticamente cada 30 minutos: si aparece un nuevo defecto o si supera las 2 horas sin ser atendido, se enviará un aviso;

4. Tras reiniciar el servicio, el monitoreo se restaura automáticamente (sin necesidad de volver a añadirlo).

Preguntas frecuentes

• Fallo de inicio de sesión por bloqueo de WAF / captcha: establezca SEPP_HEADLESS=false, pase el captcha manualmente en el primer inicio de sesión; a partir de entonces el estado de inicio de sesión se persistirá.

• Error de inicio de sesión "no se han configurado cuenta y contraseña": SEPP_USERNAME / SEPP_PASSWORD están vacíos y no hay cookie válida.

• La validez de sepp-auth es de aproximadamente 7 días: al caducar, se volverá a iniciar sesión automáticamente con Playwright (requiere que el navegador esté instalado).

• Los campos devueltos por los defectos dependen de la plataforma real: esta herramienta transmite directamente el JSON original de la plataforma; los avisos de monitoreo calculan el tiempo de espera según foundTime (o el momento del primer descubrimiento).

Nota de seguridad

• La cuenta y contraseña, la cookie y el estado de inicio de sesión del navegador se guardan localmente en data/ (ya incluido en .gitignore); no los envíe al repositorio.

• Los webhooks/correos se utilizan solo para avisos, no se envían datos sensibles al exterior.