Skip to main content
Glama
OmniQQ-MCP

OmniQQ-MCP

by haoan33

get_recent_messages

Read-onlyIdempotent

Retrieve recent private and group QQ messages from the local in-memory cache to poll live traffic or filter by chat type, target ID, or keyword.

Instructions

读取 MCP 服务后台通过 WebSocket 实时监听并保存在本地环形内存缓存池(上限 200 条,按登录账号隔离)中的近期 QQ 消息列表。 适用场景:快速轮询或按条件检索服务运行期间实时收到的最新私聊与群聊消息。不适用与替代:若需查询 MCP 启动之前的历史聊天记录或向更早页码翻页,请通过 call_napcat_api 调用 get_friend_msg_history 或 get_group_msg_history;若需查看加群/加好友审批请求或群撤回通知,请调用 get_recent_notices_and_requests。 参数约束与交互:当指定 target_id 时,若 chat_type='group' 则按群号过滤,若 chat_type='private' 则按发送者 QQ 号过滤,若 chat_type='all' 则同时匹配群号或 QQ 号;keyword 对净化后的消息文本 clean_text 与发送者昵称做大小写不敏感子串匹配。 行为与返回:纯内存只读操作(零外部网络延迟,不修改缓存状态);返回 ws_connected、count 及 messages 数组(每项含 message_id, chat_type, user_id, group_id, sender_name, clean_text, time)。

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_recent_messages"
  }
}

Input Schema

NameRequiredDescriptionDefault
countNo返回的最大最新消息条数(范围 1~200,默认 20)
keywordNo按消息正文或发送者昵称/群名片包含的子串关键词过滤;留空不过滤
chat_typeNo会话范围过滤枚举: 'all'(全部消息)、'private'(仅私聊)、'group'(仅群聊),默认 'all'all
target_idNo限定特定群号(group_id)或特定好友 QQ 号(user_id)的正整数 ID;留空不过滤
include_self_sentNo为 True 时包含当前登录账号自己发出的消息,为 False 时仅返回他人发来的消息,默认 False

Output Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv1.2.2
    • changedInput schema / properties / chat_type / description
      Previous value: -"消息类型过滤: 'all' (全部), 'private' (仅私聊), 'group' (仅群聊)"New value: +"会话范围过滤枚举: 'all'(全部消息)、'private'(仅私聊)、'group'(仅群聊),默认 'all'"
    • changedInput schema / properties / count / description
      Previous value: -"返回的最大消息条数,默认 20"New value: +"返回的最大最新消息条数(范围 1~200,默认 20)"
    • changedInput schema / properties / include_self_sent / description
      Previous value: -"是否包含自己发出的消息,默认 False"New value: +"为 True 时包含当前登录账号自己发出的消息,为 False 时仅返回他人发来的消息,默认 False"
    • changedInput schema / properties / keyword / description
      Previous value: -"按消息文本或发送者昵称关键词过滤 (可选)"New value: +"按消息正文或发送者昵称/群名片包含的子串关键词过滤;留空不过滤"
    • changedInput schema / properties / target_id / description
      Previous value: -"按特定群号 (group_id) 或特定用户 QQ 号 (user_id) 过滤 (可选)"New value: +"限定特定群号(group_id)或特定好友 QQ 号(user_id)的正整数 ID;留空不过滤"
    • 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 already declare readOnly/idempotent/non-destructive/closed-world, but the description adds traits the annotations cannot express: the 200-message cap, per-account isolation, pure in-memory operation with zero external network latency, and that it does not mutate cache state. It also names the returned envelope (`ws_connected`, `count`, `messages`) and per-item fields, so the agent knows the freshness/liveness signal exists.

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 the core identity, then cleanly partitioned under '适用场景', '不适用与替代', '参数约束与交互', and '行为与返回' — every section carries content. It is on the long side, and the field-by-field return enumeration is partly redundant with the existing output schema, but nothing is 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 read-only, 5-optional-parameter, snapshot-style retrieval tool, the agent has everything needed: what the buffer holds and its limits, when to prefer history APIs, how filters combine, and what the response looks like. Output schema exists, so nothing further is required on return values, and no behavioral gap remains for correct invocation.

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 schema alone sets a baseline of 3; the description earns above that by documenting cross-parameter behavior — `target_id` is interpreted as group_id under `chat_type='group'`, user_id under `private`, and either under `all` — and by specifying that `keyword` matches against `clean_text` and sender nickname case-insensitively. This interaction rule is not derivable from the schema. It stops short of 5 only because buffer-boundary behavior (what happens when fewer than `count` messages are cached) is unstated.

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 names a specific verb and resource — reading recent QQ messages held in a local ring buffer (cap 200, isolated per login account) fed by a live WebSocket listener. It also states scope ('近期', '服务运行期间实时收到的'), which immediately separates it from history-fetching siblings. An agent can tell what it gets and what it does not without opening the schema.

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 '适用场景' (fast polling / conditional search of live-received messages) and an explicit '不适用与替代' section that routes to `call_napcat_api` → `get_friend_msg_history`/`get_group_msg_history` for pre-start or older-page history, and to `get_recent_notices_and_requests` for approvals/recalls. Both the when and the when-not are named with the correct sibling alternatives.

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