cpanel_bandwidth_usage

Instructions

Implementation Reference

• src/tools.py:400-411 (registration)

  Tool registration for 'cpanel_bandwidth_usage' with its name, description, and inputSchema. Requires 'account' (alias from accounts.json) and 'cpanel_user' (cPanel username).

  Tool(
      name="cpanel_bandwidth_usage",
      description="Get bandwidth usage stats for a specific cPanel account",
      inputSchema={
          "type": "object",
          "properties": {
              **ACCOUNT_PARAM,
              "cpanel_user": {"type": "string"}
          },
          "required": ["account", "cpanel_user"]
      }
  ),

• src/tools.py:562-563 (handler)

  Handler that executes the tool. Calls the cPanel UAPI StatsBar/get_stats module with 'display=bandwidthusage' to get bandwidth usage for the specified cPanel user.

  case "cpanel_bandwidth_usage":
      return await _get(client, url("StatsBar", "get_stats"), headers, {"display": "bandwidthusage"})

• src/tools.py:17-22 (helper)

  URL builder (_cpanel_url) that constructs the WHM-proxied cPanel UAPI endpoint used to call the StatsBar/get_stats API.

  def _cpanel_url(account: dict, module: str, function: str, cpanel_user: str = None) -> str:
      host = account["host"]
      port = account.get("port", 2087)
      # WHM-proxied UAPI call on behalf of a cPanel user
      user = cpanel_user or account.get("cpanel_user", "")
      return f"https://{host}:{port}/json-api/cpanel?api.version=1&cpanel_jsonapi_user={user}&cpanel_jsonapi_module={module}&cpanel_jsonapi_func={function}&cpanel_jsonapi_apiversion=3"

• src/tools.py:34-40 (helper)

  Generic async HTTP GET helper used to make the actual API request and parse JSON response.

  async def _get(client: httpx.AsyncClient, url: str, headers: dict, params: dict = None) -> dict:
      try:
          r = await client.get(url, headers=headers, params=params or {})
          r.raise_for_status()
          return r.json()
      except Exception as e:
          return {"error": str(e)}

• src/server.py:47-75 (registration)

  Top-level routing in call_tool that dispatches cpanel_* tools to handle_cpanel_tool, which includes the bandwidth usage tool.

  @app.call_tool()
  async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
      log.info(f"Tool called: {name} | Args: {json.dumps(arguments)}")
  
      if name == "list_accounts":
          accounts = load_accounts()
          result = [
              {"alias": a, "host": cfg["host"], "type": cfg.get("type","whm")}
              for a, cfg in accounts.items()
          ]
          return [TextContent(type="text", text=json.dumps(result, indent=2))]
  
      account_alias = arguments.get("account")
      if not account_alias:
          return [TextContent(type="text", text="ERROR: 'account' parameter is required. Use list_accounts to see available accounts.")]
  
      account = get_account(account_alias)
      if not account:
          return [TextContent(type="text", text=f"ERROR: Account '{account_alias}' not found. Use list_accounts to see configured accounts.")]
  
      async with httpx.AsyncClient(verify=False, timeout=30) as client:
          if name.startswith("whm_"):
              result = await handle_whm_tool(client, account, name, arguments)
          elif name.startswith("cpanel_"):
              result = await handle_cpanel_tool(client, account, name, arguments)
          else:
              result = {"error": f"Unknown tool: {name}"}
  
      return [TextContent(type="text", text=json.dumps(result, indent=2))]