Skip to main content
Glama
OmniQQ-MCP

OmniQQ-MCP

by haoan33

upload_private_file

Send a local file as a private chat attachment to a QQ friend by specifying their QQ ID, absolute file path, and display filename with extension. Use for documents, PDFs, or archives.

Instructions

将本机磁盘上的文件作为私聊附件发送给指定 QQ 好友 (NapCat OneBot 11: upload_private_file)。 适用场景:向个人 QQ 好友交付文档、表格、PDF 或压缩包等本地文件。不适用与替代:若需将文件上传至 QQ 群共享空间,请改用 upload_group_file;若仅需发送纯文本或图片消息段,请改用 send_private_msg。 参数约束与交互:file_path 必须为当前机器上已存在且可读的本地绝对路径(如 D:/Desktop/report.xlsx);file_name 应包含正确的文件扩展名以便接收方客户端识别打开。 行为与返回:非幂等外部文件传输操作(默认超时 120 秒以支持大文件上传);前置要求当前账号已在线且目标为好友,成功返回 status='ok',若本地文件不存在、超出大小限制或非好友则返回非 0 retcode。

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

Input Schema

NameRequiredDescriptionDefault
user_idYes接收方好友的 QQ 号(5~11 位正整数)
file_nameYes对方在私聊窗口中看到的显示文件名(须含扩展名,如 'report.xlsx')
file_pathYes待发送本地文件的完整绝对路径(文件必须真实存在且可读)

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 / file_name / description
      Previous value: -"对方看到的显示文件名 (如 'report.xlsx')"New value: +"对方在私聊窗口中看到的显示文件名(须含扩展名,如 'report.xlsx')"
    • changedInput schema / properties / file_path / description
      Previous value: -"本地文件的绝对路径(例如 `/path/to/report.xlsx`)"New value: +"待发送本地文件的完整绝对路径(文件必须真实存在且可读)"
    • changedInput schema / properties / user_id / description
      Previous value: -"接收方好友 QQ 号"New value: +"接收方好友的 QQ 号(5~11 位正整数)"
    • 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. Changed2 schema fields changedv1.1.0
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / file_path / description
      Previous value: -"本地文件的绝对路径 (如 'D:/Desktop/report.xlsx')"New value: +"本地文件的绝对路径(例如 `/path/to/report.xlsx`)"
  3. First observedv1.0.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnly=false, openWorld=true, idempotent=false, destructive=false, so the safety profile is covered. The description adds meaningful context beyond that: a 120s default timeout for large files, the requirement that the account be online and the target be an existing friend, and the success/failure return codes (status='ok' vs non-zero retcode on missing file, size limit, or non-friend). It stops short of describing actual size limits or transfer progress behavior.

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?

Well front-loaded and organized into labeled sections (适用场景 / 不适用与替代 / 参数约束 / 行为与返回). Slightly longer than strictly necessary since some parameter guidance overlaps the schema, but every section is scannable and useful.

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 3-param mutation tool with full schema coverage, full annotations, and an output schema, the description covers purpose, routing, preconditions, and failure modes. Nothing an agent needs to invoke it correctly is missing; return-format detail is appropriately left 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 the baseline is 3. The description still adds value: it specifies that file_path must be an existing, readable absolute local path with a concrete example (D:/Desktop/report.xlsx) and that file_name must carry the correct extension for client-side opening, which reinforces and exemplifies rather than merely restates the 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?

States a specific verb + resource (send a local disk file as a private-chat attachment to a specified QQ friend) and identifies the underlying API (NapCat OneBot 11: upload_private_file). It explicitly distinguishes itself from upload_group_file (group sharing) and send_private_msg (text/image segments).

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?

Provides explicit 适用场景 (delivering documents, sheets, PDFs, archives to an individual friend) and 不适用与替代 clauses naming the two sibling alternatives with the exact conditions that select them. Nothing is left to inference.

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