Skip to main content
Glama
OmniQQ-MCP

OmniQQ-MCP

by haoan33

upload_group_file

Uploads a local file from disk to a specified QQ group's shared file space so you can distribute resources, summary sheets, or notice attachments.

Instructions

将本机磁盘上的文件上传至指定 QQ 群的群文件共享空间 (NapCat OneBot 11: upload_group_file)。 适用场景:向 QQ 群发布共享资料、汇总表或通知附件。不适用与替代:若需将文件单独私发给某个好友,请改用 upload_private_file;若仅需在群内发送文字通知,请改用 send_group_msg。 参数约束与交互:file_path 必须为本机已存在的绝对路径;省略 folder 时默认上传至群文件根目录,若指定 folder 则须传入通过 call_napcat_api(action='get_group_root_files') 查询到的有效群文件夹 ID。 行为与返回:非幂等群文件创建操作(默认超时 120 秒,同名文件通常会在群文件列表中产生新条目);前置要求当前账号已加入目标群且群文件空间未满、具备上传权限,成功返回 status='ok'。

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": {
      "group_id": "<group_id>",
      "file_path": "<file_path>",
      "file_name": "<file_name>"
    },
    "name": "upload_group_file"
  }
}

Input Schema

NameRequiredDescriptionDefault
folderNo目标群文件夹 ID(可选;留空则上传至群文件根目录)
group_idYes目标 QQ 群号(正整数,须为已加入的群聊)
file_nameYes在群文件列表中展示的文件名称(须含扩展名)
file_pathYes待上传本地文件的完整绝对路径(文件必须真实存在且可读)

Output Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv1.2.2
    • changedInput schema / properties / file_name / description
      Previous value: -"群文件中显示的文件名"New value: +"在群文件列表中展示的文件名称(须含扩展名)"
    • changedInput schema / properties / file_path / description
      Previous value: -"本地文件的绝对路径"New value: +"待上传本地文件的完整绝对路径(文件必须真实存在且可读)"
    • changedInput schema / properties / folder / description
      Previous value: -"目标群文件夹 ID (可选,不填则上传至群文件根目录)"New value: +"目标群文件夹 ID(可选;留空则上传至群文件根目录)"
    • changedInput schema / properties / group_id / description
      Previous value: -"目标 QQ 群号"New value: +"目标 QQ 群号(正整数,须为已加入的群聊)"
    • 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?

The description adds significant behavior beyond the annotations: it discloses non-idempotency, a default 120-second timeout, duplicate-name behavior, permission and capacity prerequisites, and success status. These details go well beyond the provided annotations and are exactly what an agent needs before mutating group file state.

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 front-loaded with the core action, then cleanly grouped into use cases, alternatives, parameter constraints, and behavior. Despite its length, every section carries actionable information for a non-idempotent upload operation.

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 this is a non-idempotent write operation with an output schema and four parameters, the description covers purpose, alternatives, prerequisites, parameter constraints, timeout behavior, and return status sufficiently. An agent has everything needed to call it correctly without relying on undocumented assumptions.

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 100%, so the baseline is 3, but the description adds operational meaning for `folder`: if omitted it defaults to the root, and if specified it must be a valid folder ID obtained via `call_napcat_api(action='get_group_root_files')`. It also reinforces that `file_path` must be an existing absolute local path, though it adds little new detail for `group_id` and `file_name`.

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 and resource: uploading a local file to a QQ group's shared file space. It explicitly distinguishes this from sending files privately and from sending text messages in the group, so an agent can select it confidently 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 Guidelines5/5

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

It gives concrete use cases such as publishing shared materials or notification attachments, and explicitly routes private-file sending to `upload_private_file` and text-only group notices to `send_group_msg`. It also states prerequisites: the account must have joined the group, have upload permission, and the group file space must not be full.

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