get_balance

Instructions

Implementation Reference

• src/tools/billing.ts:19-41 (registration)

  Registration of the 'get_balance' tool via server.registerTool(). Defines the tool name, description, input schema (empty), and the async handler that checks auth and calls api.balance().

    // --- get_balance ---
    server.registerTool(
      "get_balance",
      {
        description: `Check your pipeline check credit balance. Shows credits remaining, total purchased, total used, and lifetime free lookups count.
  
  Credits are consumed only when unknown domains run through the full analysis pipeline. Known domains (Tranco Top 100K) and cached domains (previously analysed by any Unphurl customer) are always free.
  
  If credits_remaining is 0, you can still check known and cached domains for free. To check unknown domains, purchase more credits using the "purchase" tool.`,
        inputSchema: {},
      },
      async () => {
        if (!api.hasApiKey) return authError();
  
        try {
          const result = await api.balance();
          return successResult(result);
        } catch (err) {
          if (err instanceof ApiRequestError) return apiErrorToResult(err);
          return errorResult(err instanceof Error ? err.message : "Unknown error");
        }
      }
    );

• src/tools/billing.ts:30-41 (handler)

  The handler function for get_balance. Checks if API key is present (else returns authError), calls api.balance(), and returns the result wrapped in successResult. Catches ApiRequestError and generic errors.

    async () => {
      if (!api.hasApiKey) return authError();
  
      try {
        const result = await api.balance();
        return successResult(result);
      } catch (err) {
        if (err instanceof ApiRequestError) return apiErrorToResult(err);
        return errorResult(err instanceof Error ? err.message : "Unknown error");
      }
    }
  );

• src/tools/helpers.ts:8-12 (helper)

  successResult helper — wraps data into the standard MCP CallToolResult format (JSON-stringified text content).

  export function successResult(data: unknown): CallToolResult {
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
    };
  }

• src/tools/helpers.ts:23-37 (helper)

  authError helper — returns a standardized MCP error result when no API key is configured.

  export function authError(): CallToolResult {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            error: "auth_required",
            message:
              "API key is missing. Set UNPHURL_API_KEY in your MCP server configuration, or use the signup tool to create an account first.",
          }),
        },
      ],
      isError: true,
    };
  }

• src/types.ts:78-83 (schema)

  BalanceResponse type definition — the shape of the data returned by the balance API endpoint: credits_remaining, total_purchased, total_used, free_lookups.

  export interface BalanceResponse {
    credits_remaining: number;
    total_purchased: number;
    total_used: number;
    free_lookups: number;
  }