会员 MCP 工具清单、调用示例与重试

适用版本：会员插件 1.3.3 · 核对日期：2026-10-10

用途

使用会员 MCP 的 15 个查询和 8 个写入工具，并正确处理并发更新、账户调整和等级受理结果。

前置条件

完成MCP 连接与授权。账户调整对象已存在，会员未冻结，余额操作需开启账户能力。

操作入口

MCP 客户端发现的 PluginMember 工具。当前协议名称形如 PluginMember__get_member，以站点目录实际返回为准。

操作步骤

查询会员/等级，保存用于更新的当前版本。
更新会员状态、等级配置或等级状态时提供 expectedVersion；冲突后重新读取并核对，不强行覆盖。
调整积分/余额时提供稳定请求 ID、用户名、正负差额和操作原因。
超时后先用 get_account_adjustment 查询原请求，不更换 ID。
发放等级保存返回记录 ID，随后查询会员和等级记录确认最终生效。

预期结果与核对

账户调整返回审计记录与处理状态；发放等级返回 ACCEPTED，由原协调器继续更新会员和角色。

限制与注意事项

积分调整为整数且每次绝对值最多 10 亿；余额每次绝对值最多 100 万、最多两位小数，均不允许 0。普通列表每页默认 20、最多 100。流水非精确 ID 查询最多 7 天；概览显式范围最多 90 天。未知字段和显式 null 不被接受。

常见问题

调整状态 PENDING？ 账户可能已变化，查原流水和处理标记；同 ID 重试只在能确认处理标记时恢复，不盲目重放。
历史标记不存在？ 账户标记只保留最近 128 笔，不能推断未执行，需管理员核对。
发放后没获得角色？ ACCEPTED 不证明角色生效，检查等级记录和 Halo 角色。

工具清单

类别	查询工具	写入工具
会员	list_members、get_member	create_member、set_member_status
等级	list_levels、get_level、list_level_records、get_level_record	create_level、update_level、set_level_status、grant_member_level
账户与流水	list_transactions、get_transaction、get_account_adjustment、get_member_capabilities	adjust_points、adjust_balance
签到	list_sign_ins、get_sign_in_calendar	无
邀请	list_referrals、get_referral	无
概览	get_member_overview	无

create_member 只为已有 Halo 用户创建零资产、无等级会员账户，不创建 Halo 用户；冻结不禁用 Halo 登录。create_level 创建停用、角色为空的等级；角色在 Console 配置。等级发放拒绝绑定 super-role 的目标等级。

积分调整示例

{
  "requestId": "member-operation-20261010-001",
  "userId": "alice",
  "delta": 20,
  "reason": "活动人工补发积分"
}

目标工具为 PluginMember__adjust_points。核对时调用 PluginMember__get_account_adjustment，传 {"requestId":"member-operation-20261010-001"}。同一请求 ID 在积分与余额工具间共用空间；用户名、类型、数值或原因变化会冲突。

等级发放示例

{
  "requestId": "member-level-20261010-001",
  "userId": "alice",
  "levelId": "level-example",
  "validityDays": 30,
  "reason": "活动赠送30天会员"
}

调用 grant_member_level；目标等级必须已存在且启用。省略 validityDays 使用等级有效期，0 使用长期有效语义。重复请求不应新增记录或刷新有效期。

错误代码包括 INVALID_ARGUMENT、NOT_FOUND、FORBIDDEN、INVALID_STATE、CONFLICT、TOOL_TIMEOUT、INTERNAL。首期不含删除业务历史、批量导入导出、卡密明文、支付成功标记、提现和积分划转。