wave_get_usage

Instructions

Implementation Reference

• src/tools/billing.ts:58-70 (handler)

  The handler function for wave_get_usage tool. It accepts optional 'period' (current|previous) and 'breakdown' (summary|daily|by_stream) parameters, builds URL query params, fetches /api/v1/billing/usage, and returns the response body as text content.

    async ({ period, breakdown }) => {
      const params = new URLSearchParams();
      if (period) params.set("period", period);
      if (breakdown) params.set("breakdown", breakdown);
  
      const query = params.toString();
      const path = `/api/v1/billing/usage${query ? `?${query}` : ""}`;
      const res = await waveFetch(path);
      if (!res.ok) return errorContent(res.status, res.body);
  
      return textContent(res.body);
    },
  );

• src/tools/billing.ts:48-57 (schema)

  Zod schema defining input parameters for wave_get_usage: 'period' (enum current/previous, optional) and 'breakdown' (enum summary/daily/by_stream, optional).

  {
    period: z
      .enum(["current", "previous"])
      .optional()
      .describe("Billing period to query (default: current)"),
    breakdown: z
      .enum(["summary", "daily", "by_stream"])
      .optional()
      .describe("Level of usage detail (default: summary)"),
  },

• src/tools/billing.ts:32-71 (registration)

  The registerBillingTools function registers both wave_get_subscription and wave_get_usage tools on the MCP server via server.tool(). Called from src/server.ts line 23.

  export function registerBillingTools(server: McpServer): void {
    server.tool(
      "wave_get_subscription",
      "Get current subscription details including plan, billing cycle, and feature entitlements",
      {},
      async () => {
        const res = await waveFetch("/api/v1/billing/subscription");
        if (!res.ok) return errorContent(res.status, res.body);
  
        return textContent(res.body);
      },
    );
  
    server.tool(
      "wave_get_usage",
      "Get current billing period usage including streaming minutes, storage, and bandwidth consumption",
      {
        period: z
          .enum(["current", "previous"])
          .optional()
          .describe("Billing period to query (default: current)"),
        breakdown: z
          .enum(["summary", "daily", "by_stream"])
          .optional()
          .describe("Level of usage detail (default: summary)"),
      },
      async ({ period, breakdown }) => {
        const params = new URLSearchParams();
        if (period) params.set("period", period);
        if (breakdown) params.set("breakdown", breakdown);
  
        const query = params.toString();
        const path = `/api/v1/billing/usage${query ? `?${query}` : ""}`;
        const res = await waveFetch(path);
        if (!res.ok) return errorContent(res.status, res.body);
  
        return textContent(res.body);
      },
    );
  }

• src/server.ts:23-24 (registration)

  The call site where registerBillingTools is invoked to register billing tools (including wave_get_usage) on the MCP server.

  registerBillingTools(server);
  registerProductionTools(server);

• src/tools/billing.ts:5-19 (helper)

  The waveFetch helper used by the handler to make authenticated API calls. Constructs URL using getBaseUrl() from auth.ts and includes auth headers.

  async function waveFetch(
    path: string,
    init?: RequestInit,
  ): Promise<{ ok: boolean; status: number; body: string }> {
    const url = `${getBaseUrl()}${path}`;
    const res = await fetch(url, {
      ...init,
      headers: {
        ...getAuthHeaders(),
        ...init?.headers,
      },
    });
    const body = await res.text();
    return { ok: res.ok, status: res.status, body };
  }