lb_wallet_topup

Instructions

Implementation Reference

• src/tools/wallet.tools.ts:70-95 (handler)

  Handler for lb_wallet_topup tool. Sends a POST request to /api/v1/wallet/topup with the amount, returns a TopupResponse containing a Stripe checkout URL.

  server.tool(
    "lb_wallet_topup",
    "Generate a Stripe checkout URL to top up wallet balance. Returns a URL to complete payment.",
    {
      amount: z
        .number()
        .min(5)
        .max(5000)
        .describe("Top-up amount in USD (minimum $5, maximum $5,000)"),
    },
    { destructiveHint: true },
    async (params) => {
      try {
        const res = await client.request<TopupResponse>(
          "POST",
          "/api/v1/wallet/topup",
          { amount: params.amount },
          undefined,
          "lb_wallet_topup",
        );
        return formatResult(res.data);
      } catch (e) {
        return formatErrorResult(e);
      }
    },
  );

• src/client/types.ts:105-107 (schema)

  Response type returned by the topup endpoint — contains a Stripe checkout URL.

  export interface TopupResponse {
    checkout_url: string;
  }

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

  Registration of lb_wallet_topup via server.tool() inside the registerWalletTools function, 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);
        }
      },
    );
  
    server.tool(
      "lb_wallet_get_transactions",
      "Get Listing Bureau wallet transaction history (paginated). Last page may include legacy entries beyond per_page count.",
      {
        page: z.number().int().min(1).optional().describe("Page number (default 1)"),
        per_page: z
          .number()
          .int()
          .min(1)
          .max(100)
          .optional()
          .describe("Results per page (default 50, max 100)"),
      },
      { readOnlyHint: true  },
      async (params) => {
        try {
          const query: Record<string, string> = {};
          if (params.page !== undefined) query.page = String(params.page);
          if (params.per_page !== undefined)
            query.per_page = String(params.per_page);
          const res = await client.request<Transaction[]>(
            "GET",
            "/api/v1/wallet/transactions",
            undefined,
            query,
            "lb_wallet_get_transactions",
          );
          if (res.meta) {
            return formatPaginatedResult(res.data, res.meta);
          }
          return formatResult(res.data);
        } catch (e) {
          return formatErrorResult(e);
        }
      },
    );
  
    server.tool(
      "lb_wallet_topup",
      "Generate a Stripe checkout URL to top up wallet balance. Returns a URL to complete payment.",
      {
        amount: z
          .number()
          .min(5)
          .max(5000)
          .describe("Top-up amount in USD (minimum $5, maximum $5,000)"),
      },
      { destructiveHint: true },
      async (params) => {
        try {
          const res = await client.request<TopupResponse>(
            "POST",
            "/api/v1/wallet/topup",
            { amount: params.amount },
            undefined,
            "lb_wallet_topup",
          );
          return formatResult(res.data);
        } catch (e) {
          return formatErrorResult(e);
        }
      },
    );
  }

• src/index.ts:57-57 (registration)

  Entry point where registerWalletTools is invoked, making all wallet tools (including lb_wallet_topup) available on the MCP server.

  registerWalletTools(server, client);

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

  Helper used to format the successful API response into an MCP CallToolResult.

  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;