query_quota

Instructions

Implementation Reference

• src/minimax_mcp/tools/quota.py:38-107 (handler)

  Core handler function that queries MiniMax Token Plan remaining quota via client.get_remains(), then categorizes models into 5-hour cycle, daily cycle, or no-quota buckets with usage statistics.

  def query_quota(client: MiniMaxClient) -> dict:
      """查询 Token Plan 剩余额度"""
      result = client.get_remains()
  
      if not result.get("success"):
          return {
              "success": False,
              "error": result.get("error", "Failed to query quota"),
              "detail": result.get("detail", ""),
          }
  
      model_remains = result.get("model_remains", [])
  
      five_hour: list[dict] = []
      daily: list[dict] = []
      no_quota: list[dict] = []
  
      for m in model_remains:
          total = m.get("current_interval_total_count", 0)
          used = m.get("current_interval_usage_count", 0)
          remains_time = _format_ms(m.get("remains_time", 0))
  
          entry = {
              "name": m.get("model_name", "unknown"),
              "quota": total,
              "used": used,
              "remains": total - used,
              "remains_time": remains_time,
              "usage_pct": round(used / total * 100, 1) if total else 0,
          }
  
          if _is_five_hour_cycle(m):
              entry["cycle"] = "5小时"
              five_hour.append(entry)
          elif _is_daily_cycle(m):
              weekly_total = m.get("current_weekly_total_count", 0)
              weekly_used = m.get("current_weekly_usage_count", 0)
              entry["cycle"] = "日"
              entry["weekly_quota"] = weekly_total
              entry["weekly_used"] = weekly_used
              entry["weekly_remains"] = weekly_total - weekly_used
              entry["weekly_usage_pct"] = round(weekly_used / weekly_total * 100, 1) if weekly_total else 0
              entry["weekly_remains_time"] = _format_ms(m.get("weekly_remains_time", 0))
              daily.append(entry)
          elif total == 0 and used == 0:
              entry["cycle"] = "无配额（未订阅）"
              no_quota.append(entry)
          else:
              entry["cycle"] = "未知"
              daily.append(entry)
  
      # 计算总量统计
      total_five_hour_used = sum(m["used"] for m in five_hour)
      total_five_hour_quota = sum(m["quota"] for m in five_hour)
      total_daily_used = sum(m["used"] for m in daily)
      total_daily_quota = sum(m["quota"] for m in daily)
  
      return {
          "success": True,
          "summary": {
              "five_hour_models": len(five_hour),
              "five_hour_used_pct": round(total_five_hour_used / total_five_hour_quota * 100, 1) if total_five_hour_quota else 0,
              "daily_models": len(daily),
              "daily_used_pct": round(total_daily_used / total_daily_quota * 100, 1) if total_daily_quota else 0,
              "no_quota_models": len(no_quota),
          },
          "five_hour_cycle": five_hour,
          "daily_cycle": daily,
          "no_quota": no_quota,
      }

• src/minimax_mcp/tools/quota.py:11-22 (helper)

  Helper to convert milliseconds to HH:MM:SS format for display.

  def _format_ms(ms_val) -> str:
      """将毫秒数转为 HH:MM:SS 格式"""
      if not ms_val or ms_val <= 0:
          return "N/A"
      total_seconds = int(ms_val / 1000)
      h, remainder = divmod(total_seconds, 3600)
      m, s = divmod(remainder, 60)
      if h:
          return f"{h}小时{m}分"
      elif m:
          return f"{m}分{s}秒"
      return f"{s}秒"

• src/minimax_mcp/tools/quota.py:25-30 (helper)

  Helper to determine if a model uses a 5-hour reset cycle.

  def _is_five_hour_cycle(model: dict) -> bool:
      """5小时周期模型: weekly_total=0 但有 interval 配额"""
      return (
          model.get("current_weekly_total_count", 0) == 0
          and model.get("current_interval_total_count", 0) > 0
      )

• src/minimax_mcp/tools/quota.py:33-35 (helper)

  Helper to determine if a model uses a daily reset cycle.

  def _is_daily_cycle(model: dict) -> bool:
      """日周期模型: weekly_total > 0"""
      return model.get("current_weekly_total_count", 0) > 0

• src/minimax_mcp/server.py:48-58 (registration)

  MCP tool registration via @mcp.tool() decorator, wrapping the actual handler from minimax_mcp.tools.quota.

  @mcp.tool()
  def query_quota() -> dict:
      """查询 MiniMax Token Plan 剩余额度
  
      返回文本模型（5小时周期）和其他模型（日周期）的配额使用情况，
      包括已用次数、剩余次数、使用百分比、重置时间等。
  
      无需参数，使用 config.env 中配置的 API Key。
      """
      from minimax_mcp.tools.quota import query_quota as _run
      return _run(get_client())