Skip to main content
Glama
OmniQQ-MCP

OmniQQ-MCP

by haoan33

call_napcat_api

Destructive

Calls any NapCatQQ OneBot 11 action as a fallback when dedicated tools do not cover an operation, enabling access to additional QQ APIs.

Instructions

调用 NapCatQQ 任意 OneBot 11 标准或扩展底层 Action(覆盖全部 144+ 项功能)的通用兜底透传工具。 适用场景:仅当核心专用工具未覆盖所需功能时使用(例如查询历史记录 get_friend_msg_history/get_group_msg_history、群管禁言踢人 set_group_ban/set_group_kick、文件下载与 OCR download_file/ocr_image、好友与资料管理 get_friend_list/set_qq_profile、群相册或打卡等)。不适用与替代:严禁使用本工具替代已暴露的核心专用工具(发送私聊/群聊请用 send_private_msg/send_group_msg,撤回请用 delete_msg,上传文件请用 upload_private_file/upload_group_file);不确定 action 精确名称时,请先调用 list_supported_napcat_actions 检索。 参数约束与交互:action 必须为合法的 OneBot 11 / NapCat 端点名(不含前导斜杠 /);params 为传给该端点的 JSON 键值字典,上传或下载大文件时建议将 timeout 调大至 120.0。 行为、权限与副作用:操作性质完全取决于所调用的 action——get_*/fetch_* 为只读查询,而 delete_*/set_group_kick/set_group_leave 属于不可逆破坏性操作且要求当前账号已在线并具备相应群主/管理员权限;返回标准 OneBot 响应字典 {"status": "ok"|"failed", "retcode": int, "data": ...},未知 action 或参数错误时返回非 0 retcode 并提示调用 list_supported_napcat_actions。

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "call_napcat_api"
  }
}

Input Schema

NameRequiredDescriptionDefault
actionYes目标 OneBot 11 或 NapCat 扩展接口精确名称(可通过 `list_supported_napcat_actions` 查阅,如 'get_group_msg_history', 'set_group_ban', 'ocr_image')
paramsNo传递给该接口的请求参数字典(字段依具体 action 而定,无参数接口传空字典 {} 或省略)
timeoutNoHTTP 请求最大等待超时秒数(常规接口默认 30.0,文件传输类接口建议 120.0)

Output Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv1.2.2
    • changedInput schema / properties / action / description
      Previous value: -"NapCat 接口名称 (例如 'send_group_sign', 'fetch_ptt_text', 'get_cookies' 等)"New value: +"目标 OneBot 11 或 NapCat 扩展接口精确名称(可通过 `list_supported_napcat_actions` 查阅,如 'get_group_msg_history', 'set_group_ban', 'ocr_image')"
    • changedInput schema / properties / params / description
      Previous value: -"传递给该接口的 JSON 参数字典 (例如 {\"group_id\": 123456})"New value: +"传递给该接口的请求参数字典(字段依具体 action 而定,无参数接口传空字典 {} 或省略)"
    • changedInput schema / properties / timeout / description
      Previous value: -"请求超时秒数,默认 30.0"New value: +"HTTP 请求最大等待超时秒数(常规接口默认 30.0,文件传输类接口建议 120.0)"
    • 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.8/5.0
Behavior5/5

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

Annotations declare destructive=true/reversible flags generically, but the description goes well beyond them by explaining that the effect is action-dependent: get_*/fetch_* are read-only while delete_*/set_group_kick/set_group_leave are irreversible and require the account to be online with group owner/admin privileges. It also discloses the response envelope and that unknown actions return a non-zero retcode with a routing hint — exactly the context a generic dispatcher needs.

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?

Front-loaded with purpose, then usage, then constraints, then side effects — a clean layered structure. It is dense and slightly redundant (timeout=120 advice and the list_supported_napcat_actions pointer each appear twice, once in prose and once in the schema), which keeps it out of the top band.

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 generic open-world dispatcher with nested params and an output schema, the description covers the routing decision, the parameter contract, permission prerequisites, irreversibility classes and error semantics. Nothing an agent needs to invoke it safely is missing, and return-value details are correctly deferred to 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 a baseline of 3 applies, but the description adds real constraints the schema does not: action must exclude a leading slash, params is the raw JSON key-value body for that endpoint, and timeout should be raised for large file transfers. Most of the timeout guidance is already duplicated in the schema, which caps it below 5.

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 first sentence states a specific verb, resource and scope: a generic passthrough for any OneBot 11 / NapCat Action covering 144+ endpoints. It immediately distinguishes itself from the family of dedicated tools, so an agent knows this is the fallback escape hatch, not a normal path.

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 (only when dedicated tools don't cover the need) with concrete examples of uncovered cases (get_friend_msg_history, set_group_ban, ocr_image, set_qq_profile). Explicit when-not-to-use with named sibling alternatives (send_private_msg/send_group_msg, delete_msg, upload_private_file/upload_group_file) and a routing instruction to list_supported_napcat_actions when the action name is uncertain.

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