Skip to main content
Glama
haoan33

OmniQQ-MCP

by haoan33
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

login_new_qq_by_qrcode

Start a QR-code login for a new QQ account or expired session: generate a scannable image, wait for phone confirmation, then save OneBot 11 settings and keep the account running in the background.

Instructions

启动全新 QQ 账号的二维码扫码登录流程，生成高清二维码图片 (qrcode.png) 等待手机 QQ 扫码，成功后自动写入 OneBot 11 端口配置并转为后台常驻运行。 适用场景：首次绑定新 QQ 号，或已有账号登录态过期需要重新手机扫码授权时调用。不适用与替代：若目标 QQ 号已在本地缓存列表且凭证有效，请勿重新扫码，应改用 switch_qq_account 免扫码秒级切换。 参数约束与交互：open_image=True 会在本机 Windows 桌面自动弹出二维码查看器；wait_scan_seconds 控制阻塞等待用户手机确认的最大秒数（超时未扫返回 status='scan_timed_out'）。 行为与副作用：会主动停止当前正在运行的本地 NapCat 进程并重置自动登录配置；前置要求本地 NapCat 已部署（未部署请先调用 deploy_or_update_napcat），成功时返回 status='logged_in_and_configured'、new_uin 及 online_account。

Input Schema

NameRequiredDescriptionDefault
open_imageNo生成二维码后是否立即调用系统默认图片查看器在桌面弹出显示，默认 True
wait_scan_secondsNo阻塞等待用户使用手机 QQ 扫描并确认登录的最大超时秒数（建议 30~120），默认 45

Output Schema

NameRequiredDescriptionDefault
dataNo接口返回的业务负载数据（对象或数组，具体字段依工具而定）
statusNo执行状态标识，成功为 'ok'（或特定生命周期状态），失败为 'failed' 或 'error'
messageNo状态说明或错误诊断详情
retcodeNoOneBot 11 响应状态码，0 表示成功，非 0 表示协议端或网络错误

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.2.2
    • changedInput schema / properties / open_image / description
      Previous value: -"是否自动在电脑屏幕上用图片查看器弹出二维码图片，默认 True"New value: +"生成二维码后是否立即调用系统默认图片查看器在桌面弹出显示，默认 True"
    • changedInput schema / properties / wait_scan_seconds / description
      Previous value: -"等待用户手机扫码的最大秒数，默认 45 秒"New value: +"阻塞等待用户使用手机 QQ 扫描并确认登录的最大超时秒数（建议 30~120），默认 45"
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "data": {
+      "description": "接口返回的业务负载数据（对象或数组，具体字段依工具而定）"
+    },
+    "message": {
+      "description": "状态说明或错误诊断详情",
+      "type": "string"
+    },
+    "retcode": {
+      "description": "OneBot 11 响应状态码，0 表示成功，非 0 表示协议端或网络错误",
+      "type": "integer"
+    },
+    "status": {
+      "description": "执行状态标识，成功为 'ok'（或特定生命周期状态），失败为 'failed' 或 'error'",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}
  2. Changed1 schema field changedv1.1.0
    • addedInput schema / additionalProperties
      Added value: +false
  3. First observedv1.0.0

TDQS

A4.9/5.0
Behavior5/5

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

Despite annotations only flagging readOnlyHint=false, openWorldHint=true and destructiveHint=false, the description goes well beyond them: it discloses that the running local NapCat process is stopped and auto-login config reset, gives the timeout outcome status='scan_timed_out', the success payload (status='logged_in_and_configured', new_uin, online_account), and the Windows desktop pop-up side effect. This is exactly the extra context annotations cannot carry.

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?

Front-loaded with the core action, then organized into labeled sections (适用场景/不适用与替代/参数约束/行为与副作用). Every sentence carries routing, constraint or outcome information with no filler.

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?

For a non-idempotent, open-world login tool, the description covers prerequisites, side effects, timeout semantics and status return values, so an agent can call it correctly even without opening the output schema.

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 coverage is 100%, so the baseline is 3; the description nevertheless adds behavioral meaning beyond the schema by tying wait_scan_seconds to a blocking wait with the specific timeout return value, and by localizing open_image to a Windows desktop viewer.

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?

States a specific verb and resource: starting a QR-code login flow for a brand-new QQ account, writing the OneBot 11 port config on success and moving the process to background. It is clearly distinguishable from switch_qq_account, which it names explicitly.

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

Usage Guidelines5/5

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

Explicit when-to-use (first-time binding, expired credentials), when-not-to-use (account already cached and valid), and the alternative to use instead (switch_qq_account). It also names the prerequisite tool deploy_or_update_napcat.

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

Deploy Server

Other Tools