Skip to main content
Glama
zhengziha

jzt-sepp-mcp-server

by zhengziha

jzt-sepp-mcp-server

能效平台(SEPP,sepp.op.yyjzt.com)缺陷管理的 MCP Server,基于 FastMCP 封装。

功能

  • 自动登录:支持三种方式,按顺序尝试:

    1. 磁盘缓存的登录态(data/cookies.json,有效期约 7 天);

    2. SEPP_AUTH_TOKEN(浏览器里复制的 sepp-auth JWT);

    3. 账号密码登录:调用平台 normal_auth 接口,密码 sha256 加密后提交,无需浏览器。

    • Playwright Keycloak SSO 明文表单 默认禁用(明文密码会被计入错误次数、连续 5 次锁定账号),仅当显式设置 SEPP_ALLOW_SSO_LOGIN=true 才作为最后兜底。

  • 获取用户项目信息:get_user_projects(健康诊所科技 / 开发工程师)。

  • 查询缺陷,支持多用户:query_defects / query_my_defects / get_users(姓名/账号 → userId 映射)。

    • query_defects(responsers=["郑益2", "房航"]) 一次查多个用户:自动把名称解析为 userId、逐个查询后合并去重;

    • 不指定负责人时默认查"我"(默认用户 郑自航/1001967)。

  • 定时提醒:

    • monitor_add 创建监控任务,支持一次监控多个用户(responsers 名称列表),内置 APScheduler 定时轮询;

    • 新增缺陷提醒:缺陷 ID 首次出现时提醒;

    • 负责人变更提醒:缺陷换了负责人时提醒,并 @ 新负责人(否则新负责人收不到通知,会以为该缺陷是别人的);

    • 超时提醒:缺陷超过 timeout_hours(默认 2 小时)仍未处理时提醒;

    • 提醒渠道:钉钉/企微/飞书 webhook、SMTP 邮件(至少配置一个,否则仅打印日志);

    • 监控状态持久化在 data/monitor_state.json,重启后自动恢复;

    • 负责人 @:配置 SEPP_DINGTALK_AT_MAP(姓名 → 钉钉手机号)后,命中映射的负责人用手机号 @(触发钉钉提醒);未命中或未配置则负责人名称加粗显示。

  • 脱离 agent 独立运行:CLI 提供 monitor-add / monitor-update / run-check / daemon;配合 scripts/sepp-monitor-service.sh 可把轮询装成 launchd 系统级常驻服务(登录自启、崩溃自动拉起,与 MCP / agent 是否开启无关,见下文"定时任务")。

Related MCP server: Bug Bounty MCP Server

目录结构

.
├── sepp_mcp/
│   ├── server.py     # FastMCP 服务(工具定义)
│   ├── auth.py       # 自动登录(normal_auth API / token / cookie 缓存,SSO 默认禁用)
│   ├── client.py     # HTTP 客户端(登录态复用 + 多用户解析/合并查询)
│   ├── monitor.py    # 缺陷监控(新增/负责人变更/超时提醒 + APScheduler + 多用户)
│   ├── alerts.py     # 告警通知(webhook / 邮件,支持钉钉 @ 手机号)
│   ├── cli.py        # 命令行入口(serve / monitor-add / run-check / daemon / log-cleanup)
│   ├── logs.py       # 日志轮转与过期清理(按天轮转 + 删除 N 天前)
│   └── config.py     # 配置加载(.env / config.yaml)
├── scripts/
│   ├── com.jzt.sepp-monitor.plist   # launchd 服务定义(登录自启 + KeepAlive)
│   └── sepp-monitor-service.sh      # 服务安装/启停/状态/日志管理
├── logs/                            # 常驻服务日志(自动写入)
├── .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 浏览器(仅在启用 SSO 兜底登录时需要)
uv run playwright install chromium   # 或 .venv/bin/playwright install chromium

配置

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

必填(两种方式任选其一):

# 方式 A:账号密码(自动走 normal_auth 接口,密码 sha256 加密提交)
SEPP_USERNAME=你的账号
SEPP_PASSWORD=你的密码

# 方式 B:直接提供 sepp-auth token(浏览器 F12 复制,有效期约 7 天)
SEPP_AUTH_TOKEN=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9...

可选:

SEPP_USER_ID=1001967          # 默认用户("我"),查询未指定负责人时使用
SEPP_USER_NAME=郑自航
SEPP_USER_ACCOUNT=ZHENGZIH

# 定时监控默认监控的用户名称列表(逗号分隔,一次监控多个用户)
# monitor_add 不指定负责人时自动使用;也可调用时显式传 responsers
SEPP_MONITOR_USERS=郑益2,房航

# 钉钉 @ 负责人映射(姓名 -> 钉钉手机号):命中则 @ 手机号触发提醒,未命中则名称加粗
SEPP_DINGTALK_AT_MAP=郑益2:13800000000,房航:13900000000

# 告警渠道(至少配一个才有推送)
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_LOG_DIR=logs            # 常驻服务日志目录(默认 ./logs)
SEPP_LOG_RETENTION_DAYS=7    # 日志保留天数,每天自动轮转 + 清理(默认 7 天)
SEPP_TIMEOUT_HOURS=2         # 超时提醒阈值(小时)
SEPP_ALLOW_SSO_LOGIN=false   # 是否允许 Playwright SSO 浏览器兜底登录(默认禁用,防账号锁定)

运行 MCP(接入 Claude Code / CodeBuddy / 其他客户端)

uv run python -m sepp_mcp serve   # 或 .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"]
    }
  }
}

提供的工具

工具

说明

login_status

登录状态、token 过期时间、默认用户、监控用户配置

get_user_projects

当前用户的项目信息

get_users(keyword)

用户列表(按姓名/账号过滤),用于查 userId

query_defects(...)

查询缺陷。支持 responsers(名称列表,一次查多人)、fuzzy_responser / dev_responser_id / test_responser_id / status / priority / summary 过滤;不指定负责人时默认查"我"。多用户返回附加字段 matched / missing

query_my_defects(...)

查询"我"的缺陷

monitor_add(...)

新增监控。responsers=["郑益2","房航"] 一次监控多人;不填时用 SEPP_MONITOR_USERS 配置,否则默认"我";支持轮询间隔 + 新增/负责人变更/超时提醒开关

monitor_run_once(name)

立即检查一次

monitor_list / monitor_remove / monitor_enable

监控管理

定时任务(提醒)

提醒能力内置在 MCP 服务内(服务运行时自动轮询并恢复监控)。也可以完全脱离 agent 独立运行:

0) 命令行建监控

# 一次监控多个用户(名称列表)
uv run python -m sepp_mcp monitor-add --name 开发组缺陷 --responsers 郑益2 房航 --interval-minutes 30

# 或指定单个负责人 / 不指定(用 SEPP_MONITOR_USERS 配置,否则默认"我")
uv run python -m sepp_mcp monitor-add --name my_defects

1) 系统级常驻服务(launchd,推荐做长期提醒)

把轮询装成 LaunchAgent:登录自动启动、进程挂掉自动拉起,不依赖 IDE / agent / 终端是否开着 (这也是推荐方式 —— MCP serve 只在 agent 开着时存在,agent 一关定时器就停了)。

./scripts/sepp-monitor-service.sh install   # 安装并启动(写入 ~/Library/LaunchAgents)

命令

作用

install / uninstall

安装并启动 / 停止并卸载

start / stop / restart

启动 / 停止 / 重启(改了 sepp_mcp/ 代码后需 restart)

status

查看运行状态与 daemon 进程

logs

实时查看日志

  • 日志:logs/sepp-monitor.err.log(Python logging 走 stderr,实际运行日志在此)、logs/sepp-monitor.log

  • 日志自动整理:常驻服务每次启动和每天 03:07各整理一次 —— 把当前日志另存为 sepp-monitor.err.<YYYY-MM-DD>.log 后清空当前文件,并删除超过 7 天(SEPP_LOG_RETENTION_DAYS 可调)的历史日志。手动触发:uv run python -m sepp_mcp log-cleanup [--days 7]

  • 服务 Label:com.jzt.sepp-monitor;原生查看:launchctl print gui/$UID/com.jzt.sepp-monitor

  • 配置热同步:常驻服务每 60 秒对齐一次 data/monitor_state.json。通过 MCP 工具或命令行新建 / 改轮询间隔 / 删除的监控会被自动接管,无需重启服务。

  • Linux 可改用 systemd 等价方案,或退化为 nohup uv run python -m sepp_mcp daemon > logs/daemon.log 2>&1 &

2) 配合 cron(无需常驻进程)

uv run python -m sepp_mcp run-check --name 开发组缺陷

放到 crontab(如工作日每 30 分钟一次):

*/30 * * * 1-5 cd /Users/zhengzihang/Documents/my-mcp/jzt-sepp-mcp-server && uv run python -m sepp_mcp run-check --name 开发组缺陷 >> data/cron.log 2>&1

使用流程(以监控多人小组为例)

  1. 配置 .env:SEPP_MONITOR_USERS=郑益2,房航(和可选 SEPP_DINGTALK_AT_MAP 手机号映射);

  2. 通过 MCP monitor_add(name="组内缺陷") 或命令行 monitor-add 建立监控(首次执行为基线检查,只记录不提醒);

  3. 之后每 interval_minutes 自动检查:出现新缺陷、缺陷换了负责人 或 超过 2 小时未处理 都会推送,消息中负责人按映射 @手机号(触发钉钉提醒)或加粗显示;

  4. 服务重启后监控自动恢复(无需重新添加);常驻服务运行中改动监控,会在 60 秒内自动生效。

常见问题

  • 登录报 "用户名或密码错误" 并被计数:SSO 明文表单默认已禁用;请确认走的是 normal_auth(账号密码自动 sha256)或 SEPP_AUTH_TOKEN。

  • normal_auth 失败 / 想手动过验证码:SEPP_HEADLESS=false 首次登录手动过验证;或直接配置 SEPP_AUTH_TOKEN。

  • 登录报 "未配置账号密码":SEPP_USERNAME / SEPP_PASSWORD 为空,且没有有效 cookie / token。

  • sepp-auth 有效期约 7 天:过期后会自动重新登录(normal_auth API,无需浏览器)。

  • 多用户查询某名称解析不到:返回的 missing 字段会列出;请核对名称与 get_users 中的 userName 是否一致。

  • 有缺陷但没收到提醒:按顺序排查:

    1. 轮询进程是否活着 —— ./scripts/sepp-monitor-service.sh status;或看 data/monitor_state.json 的修改时间是否远超轮询间隔。MCP serve 只在 agent 开着时存在,agent 一关定时器就停,装了 launchd 常驻服务才不受影响;

    2. 缺陷负责人是否在监控范围内、status 是否落在监控的 1,2,3,4,5,6 内;

    3. 已记录过的缺陷不会重复报"新增",只在状态变化或超过 timeout_hours(默认 2 小时)未处理时再提醒。

  • MCP 配到多个 agent / 多个客户端会不会重复定时任务:不会重复。服务用跨进程文件锁保证:

    • data/monitor_state.sched.lock(调度权):多个 MCP 实例 / daemon 同时运行只有一个真正定时轮询,其余仅提供服务;

    • data/monitor_state.check.lock(检查互斥):run_check 串行执行、基于最新 state 去重,即使手动并发触发也不会重复提醒或写坏状态。

    • 锁文件位于 data/(已 gitignore);Windows 无 fcntl 时退化为单进程行为,建议只跑一个实例。

  • 缺陷返回字段以平台实际为准:本工具直接透传平台原始 JSON;监控告警按 foundTime(或首次发现时间)计算超时。

安全说明

  • 账号密码、cookie、浏览器登录态均保存在本地 data/(已加入 .gitignore),请勿提交到仓库。

  • 密码通过 sha256 摘要提交给平台 normal_auth 接口,本地不落盘明文。

  • webhook/邮件仅做提醒,不做敏感数据外发。

Available Tools

10 tools
get_user_projectsA

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

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

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry behavioral disclosure. It notes that the returned information is 'basically fixed' (该信息基本固定), conveying data stability. However, it does not mention side effects, authentication requirements, or any other behavioral traits. This is minimal but not misleading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is brief and front-loaded: a single sentence stating the purpose, followed by a concrete example. No redundant words or fluff; every element earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no inputs and an output schema (though not shown here), the description provides an example of the output and notes that the data is stable. This is sufficient for an agent to call the tool correctly. The example compensates for any missing output schema details, and the 'basically fixed' note adds context about data volatility.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters (schema defines none), and schema coverage is 100% since there is nothing to document. The baseline for zero parameters is 4, and the description does not need to add parameter details. It correctly focuses on the return value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (get) and resource (current logged-in user's project information on the energy efficiency platform) and provides a concrete example of the return structure. This distinguishes it from siblings like get_users, query_my_defects, and monitor_list, which target different resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives. While the purpose makes it obvious that it is for querying user projects, there is no mention of conditions, exclusions, or alternative tools. The context of siblings implies distinct resources, but no direct guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_usersA

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

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

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full disclosure burden. It adds value by stating the tool returns userId/userName/userAccount and supports fuzzy filtering — behavior not visible from the schema alone. However, it discloses no operational details such as pagination, whether an empty keyword returns all users, or authentication requirements. Given the read-only nature is implied rather than explicit, a 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences with zero filler. The first is front-loaded with the core purpose and returned fields; the second adds the downstream use case. Every clause earns its place, and the most important information appears first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation. The tool is a simple list query with one optional parameter, and the description covers purpose, filtering semantics, and the primary usage scenario. The only minor gap is not stating what an empty keyword returns, but the default '' implies it lists all users — a small omission against an otherwise complete definition.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It does: '可按姓名或账号模糊过滤' explains that the keyword parameter matches fuzzily against both name and account fields — meaning the schema's bare 'keyword' string could not provide. This adds real semantic value beyond the input schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource: '查询能效平台用户列表' (query the energy platform user list), and names the returned fields (userId/userName/userAccount) plus the fuzzy filtering behavior. This is concrete and unambiguous, and the chained reference to query_defects further situates its role among siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The second sentence gives explicit usage context: use this tool to map an owner name/account to a userId, then pass that to query_defects for filtering. This tells the agent when the tool is the right choice. It doesn't name exclusions or when to prefer siblings like get_user_projects, but the stated use case is clear enough for a 4.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

login_statusA

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

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the tool returns login status, account, sepp-auth expiry, and default user info, which gives the agent a concrete expectation of the output. It does not mention side effects (none expected for a read-only status check) and does not contradict any annotations (since none exist). The only minor gap is lack of explicit side-effect or permission notes, but the described behavior is unambiguous.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the primary action 'view current login status' and then enumerates the specific pieces of information returned. Every word adds value, with no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool takes no parameters, has a provided output schema (so return format is covered), and the description explicitly lists the returned information, the description is complete for an agent to invoke it correctly. There are no missing operational details or ambiguities.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, so the baseline is 4. The description adds no parameter information because none are needed; it correctly implies that no input is required. The schema already defines an empty object, so the description need not elaborate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb (查看/view) and resource (current login status), and includes specific details such as account, sepp-auth expiration time, and default user info. This distinguishes it clearly from sibling tools like get_users or query_my_defects, which target different resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: use this when you need to check login status or retrieve default user information. However, it does not explicitly state when to use it versus alternatives, nor does it mention any exclusions or prerequisites. The intent is clear but not explicitly framed as a decision guide.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 建立基线。

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes
statusNo1,2,3,4,5,6
timeout_alertNo
timeout_hoursNo
fuzzy_responserNo
dev_responser_idNo
interval_minutesNo
new_defect_alertNo
test_responser_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It discloses key behaviors: first execution is baseline (record-only), reminders start afterwards; notifications via webhook/email, logging otherwise. It also explains default assignee behavior. Missing details like persistence or immediate activation, but these are less critical for a creation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with bullet points, front-loading the main purpose. It is reasonably concise but includes some redundant phrasing; still, every element adds value for a 9-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (9 params, no annotations) and that an output schema exists (though not shown), the description covers essential aspects: parameters, behavior, prerequisites, and suggestions. It doesn't explicitly address error cases or permissions, but these are not critical for initial use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides zero description coverage, so the description compensates fully. It explains fuzzy_responser, dev/test_responser_id, timeout_alert/hours, new_defect_alert, and interval_minutes, adding meaning beyond the schema's bare types and defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: creating a defect monitoring task with periodic polling and reminders. The verb 'add' is explicit, and it's distinguished from sibling tools like monitor_run_once, monitor_list, etc. by naming what it does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a concrete usage suggestion: '建议先 monitor_run_once 建立基线' (recommends running monitor_run_once first to establish baseline). It also explains how to specify a responser using get_users. However, it doesn't explicitly state when not to use this tool or compare directly with all siblings, so it falls short of full guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

monitor_enableC

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

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes
enabledYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action without revealing side effects, permission requirements, or the impact on monitoring tasks (e.g., does enabling start immediate monitoring? Are changes reversible?). This is a significant gap for a state-changing operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence, which is efficient, but it lacks content. While it doesn't waste words, it also doesn't earn its place by providing needed information. It is more under-specified than concise, so a moderate score is appropriate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With only two simple parameters and no annotations, the tool is not complex, but the description still fails to cover essential aspects: parameter meaning, usage context, and behavioral implications. The output schema exists but description does not clarify what the tool returns or any side effects. Sibling tools exist, but no guidance is given to distinguish them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate by explaining parameters. The description does not mention 'name' or 'enabled' at all. An agent cannot infer that 'enabled' controls the enable/disable state or that 'name' identifies the task. This is a complete failure to add semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('启用/停用' = enable/disable) and the resource ('缺陷监控任务' = defect monitoring task). This differentiates it from sibling tools like monitor_add, monitor_remove, and monitor_run_once, which have distinct verbs and purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus alternatives. It does not say 'use this to toggle the enabled state of an existing monitor' nor does it mention any prerequisites or exclusions. Agents are left to infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

monitor_listB

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

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It says 'view', which implies a read-only operation, but does not explicitly state that it has no side effects, nor does it mention authentication requirements, pagination, or any other behavioral characteristics. The implicit read-only nature is left to inference.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no unnecessary words. It is front-loaded with the primary action ('view') and resource, and the parenthetical detail about defect counts is efficiently included. There is zero fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and an output schema exists, the description is adequate for an agent to understand the tool's function. It clearly states what is being listed and what accompanies the status. It does not explain any optional behavior or edge cases, but given the simplicity of a parameter-less list operation, this is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so schema coverage is effectively 100%. The description adds no parameter-level details because there are none to add. The baseline score of 3 applies since the schema already fully covers the (absent) parameters, and the description does not compensate with any clarification needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'view' and the resource 'all defect monitoring tasks and status', including the specific detail of recorded defect counts. This is specific and distinguishes it from sibling tools like monitor_add or monitor_run_once which imply different operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention when to use monitor_list vs query_defects or other monitoring tools, nor any conditions that would make this tool inappropriate. No exclusions or alternatives are named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

monitor_removeB

删除一个缺陷监控任务

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'delete', implying destructiveness, but does not describe permanence, reversibility, required permissions, or side effects (e.g., deleting associated runs or logs). This is a significant gap for a destructive operation without any annotation support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no fluff. It front-loads the verb and resource, making the core intent immediately clear. While extremely brief, it is appropriately sized for a simple delete operation and contains no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (one parameter, no enums, output schema present), but the description lacks crucial contextual details such as what the output represents, any error conditions, or how the 'name' parameter maps to the monitoring task. It provides the bare minimum and does not fully equip an agent to call it correctly, especially given the lack of parameter guidance and behavioral transparency.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has a single parameter 'name' with 0% description coverage, and the tool description does not explicitly clarify that 'name' refers to the monitoring task's name or how it is used for deletion. The description adds no semantic value beyond what the schema already shows (a string named 'name'), failing to compensate for the missing parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Delete a defect monitoring task' states a specific verb (delete) and a clear resource (defect monitoring task), distinguishing it from sibling tools like monitor_add, monitor_list, and monitor_enable. The action and target are unmistakable, leaving no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives. It does not mention preconditions, such as whether the task must exist, or any exclusions (e.g., do not use for disabling rather than deleting). The description provides no contextual direction for an agent choosing among the monitor tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

monitor_run_onceB

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

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the tool executes a check and returns results (new/timeout counts), but it gives no information about side effects, permissions, idempotency, or whether the check mutates any state. For an action that triggers an immediate execution, this lack of detail is a notable gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that leads with the action and purpose. It contains no filler or redundancy. While it lacks structured formatting, it is efficient and front-loaded. It could be slightly more informative, but brevity is appropriate for a simple action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present (though not shown), the return value is somewhat covered. The description explains the outcome (returns results) and the trigger. However, it does not mention possible error conditions (e.g., non-existent monitor), prerequisites, or side effects. Given the single-parameter simplicity and the presence of an output schema, the description is adequate but not thorough for a tool that executes an action.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It does add meaning by indicating that the parameter 'name' refers to the specific monitor to be checked ('指定监控'), which maps the parameter to the resource. However, it does not explicitly state that 'name' is the monitor identifier, nor does it give any format or validation hints. The minimal parameter makes this a moderate pass.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('execute'), the resource ('monitor check'), and the immediate nature ('without waiting for the scheduled cycle'). It also indicates the output ('return results of this run'). This distinguishes it from sibling tools like monitor_add, monitor_list, monitor_remove, and monitor_enable, which manage monitors rather than execute a check.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase '不等定时周期' (does not await the scheduled cycle) implies the tool is for ad-hoc immediate checks, contrasting with the routine behavior of the monitor. However, it does not explicitly state when to prefer this over alternatives, nor does it mention any conditions or prerequisites. There is no explicit 'use when' or 'do not use when' guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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)。

ParametersJSON Schema
NameRequiredDescriptionDefault
statusNo
summaryNo
page_numNo
priorityNo
page_sizeNo
fuzzy_responserNo
dev_responser_idNo
test_responser_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the crucial default behavior (all owner params empty → queries 'me'), the accepted input formats (userId/name/account for fuzzy_responser), and the raw JSON return (total/list). While it doesn't mention read-only nature or potential side effects, it's a query tool and the behavior is transparent enough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a parameter list, a default behavior paragraph, and return format note. It's a bit lengthy but each sentence adds value. The main purpose is front-loaded, and the parameter list is clearly formatted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter tool with all optional parameters, the description provides sufficient context: default behaviors, parameter formats, and return structure. It could mention precedence when multiple owner filters are provided, but the tool can be called correctly based on the given information. The presence of an output schema (not shown) further reduces the need to detail returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It explains every parameter in detail: fuzzy_responser with examples, dev/test responser as userIds, status with default value, priority, summary, and pagination. It goes beyond the schema by providing the type of values (userId vs name) and default behaviors.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool '查询缺陷列表' (queries a defect list) with owner-based filtering, which is a specific verb+resource. It also distinguishes itself from the sibling query_my_defects by explaining the default behavior falls back to the same query, making the tool's scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly explains when to use this tool versus query_my_defects: the default (no owner params) is equivalent to query_my_defects, and to query others you must pass fuzzy_responser. This gives clear conditional guidance, though it doesn't explicitly say 'use query_my_defects for your own defects' as a shortcut.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_my_defectsA

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

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

ParametersJSON Schema
NameRequiredDescriptionDefault
statusNo
page_numNo
page_sizeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It indicates a query operation (read-only implied) but does not explicitly state read-only, side effects, permissions, or pagination behavior. The equivalence to query_defects gives some behavioral context, but without knowing query_defects' full behavior, transparency is partial. Since it's a query, it's likely safe, but the disclosure is not explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the purpose and including a useful equivalence note. There is no fluff or redundant content; every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple query with an output schema, the description adequately covers the core purpose and default user. However, it omits parameter semantics and explicit behavioral transparency, which are needed given there are no annotations. The equivalence reference partially compensates but is not fully self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not mention any of the three parameters (status, page_num, page_size). While the parameter names are self-explanatory, the description adds no meaning about how they affect the query or any constraints. It fails to compensate for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool queries a list of defects assigned to a specific default user (郑自航/1001967). It also explicitly notes the equivalence to query_defects with a specific parameter, distinguishing it from the generic sibling tool. This is a specific verb+resource+scope that leaves no ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a clear use case: querying the current user's defects. The equivalence statement to query_defects helps an agent understand this is a convenience wrapper. However, it does not explicitly state when to use this versus the generic query_defects, nor does it mention any exclusions or alternatives beyond the equivalence.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 10 tool updatesv0.1.0
    • First observedget_user_projects
    • First observedget_users
    • First observedlogin_status
    • First observedmonitor_add
    • First observedmonitor_enable
    • First observedmonitor_list
    • First observedmonitor_remove
    • First observedmonitor_run_once
    • First observedquery_defects
    • First observedquery_my_defects

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

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    D
    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
    9
    MIT
  • A
    license
    C
    quality
    D
    maintenance
    Enables AI agents to generate and manage specialized bug bounty hunting workflows including reconnaissance, vulnerability testing, OSINT gathering, and file upload testing. Provides REST API endpoints for comprehensive security assessments with intelligence-driven vulnerability prioritization.
    40
    2
    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.
    4
    Apache 2.0