get_balance

Instructions

Implementation Reference

• src/tools/account.ts:16-20 (handler)

  The core handler for get_balance. Calls GET /v1/account/balance via callApiGet and returns formatted balance data.

    withErrorHandling(async () => {
      const result = await callApiGet("/v1/account/balance", getAuth());
      return { content: [{ type: "text" as const, text: formatResult(result.data, result) }] };
    })
  );

• src/tools/account.ts:10-21 (registration)

  The registerAccountTools function that registers the 'get_balance' tool on the MCP server with its description, empty schema, and readOnly hint.

  export function registerAccountTools(server: McpServer, getAuth: () => string) {
    server.tool(
      "get_balance",
      "Check the user's current credit balance. Returns credits remaining, daily spending cap, and plan info. Always call this FIRST before starting any multi-step analysis to understand the budget available. Costs 0 credits (free).",
      {},
      READ_ONLY,
      withErrorHandling(async () => {
        const result = await callApiGet("/v1/account/balance", getAuth());
        return { content: [{ type: "text" as const, text: formatResult(result.data, result) }] };
      })
    );
  }

• src/api-client.ts:94-130 (helper)

  The callApiGet helper used by get_balance to make the GET request to the balance API endpoint.

  export async function callApiGet(
    path: string,
    authHeader: string
  ): Promise<{ data: unknown; credits_used: number; credits_remaining: number; cached: boolean }> {
    const url = `${env.API_BASE_URL}${path}`;
  
    console.log(`[api] GET ${url} (auth: ${authHeader ? `${authHeader.slice(0, 15)}...` : "MISSING"})`);
  
    const response = await fetch(url, {
      method: "GET",
      headers: {
        Authorization: authHeader,
      },
      signal: AbortSignal.timeout(60_000),
    });
  
    if (!response.ok) {
      const text = await response.text();
      console.error(`[api] ${response.status} ${response.statusText} from ${path}: ${text.slice(0, 200)}`);
      throw new Error(`API returned ${response.status}: ${text.slice(0, 200)}`);
    }
  
    const result = (await response.json()) as ApiResponse;
  
    if (result.status === "error") {
      throw new Error(result.error.message);
    }
  
    console.log(`[api] ${path} OK (${result.credits_used} credits used, ${result.credits_remaining} remaining)`);
  
    return {
      data: result.data,
      credits_used: result.credits_used,
      credits_remaining: result.credits_remaining,
      cached: result.cached,
    };
  }

• src/api-client.ts:132-138 (helper)

  The formatResult helper used to format the API response (credits meta + JSON data) for get_balance.

  export function formatResult(
    data: unknown,
    meta: { credits_used: number; credits_remaining: number; cached: boolean }
  ): string {
    const metaLine = `[${meta.credits_used} credit${meta.credits_used !== 1 ? "s" : ""} used | ${meta.credits_remaining} remaining${meta.cached ? " | cached" : ""}]`;
    return `${metaLine}\n\n${JSON.stringify(data, null, 2)}`;
  }

• src/api-client.ts:143-158 (helper)

  The withErrorHandling wrapper that catches errors from the get_balance handler and returns them as structured MCP error content.

  export function withErrorHandling<T>(
    fn: (args: T) => Promise<ToolResult>
  ): (args: T) => Promise<ToolResult> {
    return async (args) => {
      try {
        return await fn(args);
      } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        console.error(`[mcp] Tool error: ${message}`);
        return {
          content: [{ type: "text" as const, text: `Error: ${message}` }],
          isError: true,
        };
      }
    };
  }