lb_wallet_get_balance

Instructions

Implementation Reference

• src/tools/wallet.tools.ts:17-31 (handler)

  The handler function for lb_wallet_get_balance tool. Calls client.request('GET', '/api/v1/wallet') to fetch wallet balance, then formats the result via formatResult(). On error, returns an error result via formatErrorResult().

    async () => {
      try {
        const res = await client.request<WalletBalance>(
          "GET",
          "/api/v1/wallet",
          undefined,
          undefined,
          "lb_wallet_get_balance",
        );
        return formatResult(res.data);
      } catch (e) {
        return formatErrorResult(e);
      }
    },
  );

• src/tools/wallet.tools.ts:11-31 (registration)

  Registration of the 'lb_wallet_get_balance' tool via server.tool(). The tool has no input schema (empty object {}) and is marked readOnlyHint: true. It's registered inside registerWalletTools() which is called from src/index.ts line 57.

  export function registerWalletTools(server: McpServer, client: LBClient) {
    server.tool(
      "lb_wallet_get_balance",
      "Get Listing Bureau wallet balance (credits and USD). May include a warning if data is temporarily unavailable.",
      {},
      { readOnlyHint: true  },
      async () => {
        try {
          const res = await client.request<WalletBalance>(
            "GET",
            "/api/v1/wallet",
            undefined,
            undefined,
            "lb_wallet_get_balance",
          );
          return formatResult(res.data);
        } catch (e) {
          return formatErrorResult(e);
        }
      },
    );

• src/client/types.ts:90-93 (schema)

  The WalletBalance interface defines the response type for this tool: balance_usd (number) and held_usd (number).

  export interface WalletBalance {
    balance_usd: number;
    held_usd: number;
  }

• src/utils/response.ts:10-54 (helper)

  The formatResult() helper used to format the wallet balance data into an MCP CallToolResult, including extraction of warning/balance_warning fields.

  export function formatResult(data: unknown): CallToolResult {
    const warnings: string[] = [];
    let cleaned: Record<string, unknown> | unknown = data;
  
    if (data && typeof data === "object") {
      const obj = { ...(data as Record<string, unknown>) };
  
      // Top-level warning string
      if ("warning" in obj && typeof obj.warning === "string") {
        warnings.push(obj.warning);
        delete obj.warning;
      }
  
      // balance_warning object (independent of warning)
      if ("balance_warning" in obj && obj.balance_warning && typeof obj.balance_warning === "object") {
        const bw = obj.balance_warning as Record<string, unknown>;
        const parts: string[] = [];
        if (typeof bw.warning === "string" && bw.warning.trim()) parts.push(bw.warning);
        if (typeof bw.daily_cost_estimate === "number")
          parts.push(`Daily cost estimate: $${bw.daily_cost_estimate.toFixed(2)}`);
        if (typeof bw.balance === "number")
          parts.push(`Balance: $${bw.balance.toFixed(2)}`);
        if (typeof bw.days_remaining === "number")
          parts.push(`Days remaining: ${bw.days_remaining.toFixed(1)}`);
        if (parts.length > 0) warnings.push(parts.join(" | "));
        delete obj.balance_warning;
      }
  
      cleaned = obj;
    }
  
    let text = JSON.stringify(cleaned, null, 2);
    for (const w of warnings) {
      text += `\n\n⚠️ Warning: ${w}`;
    }
  
    const notice = getUpdateNotice();
    if (notice) {
      text += `\n\n${notice}`;
    }
  
    return {
      content: [{ type: "text", text }],
    };
  }

• src/client/lb-client.ts:188-222 (helper)

  The LBClient.request() method that performs the authenticated HTTP request. For this tool, it makes a GET request to /api/v1/wallet with the tool name 'lb_wallet_get_balance' in the X-LB-Tool header.

  async request<T>(
    method: string,
    path: string,
    body?: Record<string, unknown>,
    query?: Record<string, string>,
    toolName?: string,
  ): Promise<ApiSuccessResponse<T>> {
    await this.ensureAuth();
    const response = await this.doRequest<T>(method, path, body, query, toolName);
  
    // Single retry on 401
    if (response.status === "error" && response._statusCode === 401) {
      this.jwt = null;
      await this.ensureAuth();
      const retry = await this.doRequest<T>(method, path, body, query, toolName);
      if (retry.status === "error") {
        throw new LBApiError(
          retry._statusCode ?? 500,
          retry.error.code,
          retry.error.message,
        );
      }
      return retry as ApiSuccessResponse<T>;
    }
  
    if (response.status === "error") {
      throw new LBApiError(
        response._statusCode ?? 500,
        response.error.code,
        response.error.message,
      );
    }
  
    return response as ApiSuccessResponse<T>;
  }