Skip to main content
Glama
zhengziha

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: Bug Bounty 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": "健康诊所科技"}](该信息基本固定)

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