get_stats

Instructions

Implementation Reference

• src/tools/stats.ts:18-42 (handler)

  Registration and handler for the 'get_stats' MCP tool. Registers the tool on the server with an empty input schema, and the handler calls api.stats() to fetch account usage statistics. Returns the stats data on success, or appropriate error responses on failure (auth, API error, or unknown error).

    server.registerTool(
      "get_stats",
      {
        description: `View your account usage statistics. Shows total URLs submitted, breakdown by gate (Tranco lookups, cache lookups, pipeline checks), free rate percentage, score threshold counts, and credit balance.
  
  Use this to understand your usage patterns: how many of your checks resolved free (known or cached domains) vs paid pipeline checks, and how many URLs scored above key thresholds.
  
  This is useful for:
  - Checking if your scoring profile is flagging the right proportion of URLs
  - Understanding your cost efficiency (higher free rate = more value per credit)
  - Reporting usage metrics`,
        inputSchema: {},
      },
      async () => {
        if (!api.hasApiKey) return authError();
  
        try {
          const result = await api.stats();
          return successResult(result);
        } catch (err) {
          if (err instanceof ApiRequestError) return apiErrorToResult(err);
          return errorResult(err instanceof Error ? err.message : "Unknown error");
        }
      }
    );

• src/types.ts:204-221 (schema)

  TypeScript interface StatsResponse defining the shape of data returned by get_stats. Contains usage breakdown (total_urls_submitted, tranco_lookups, cache_lookups, pipeline_checks_run, free_rate_pct), scoring (checks_above_50, checks_above_75), and account info (credits_remaining, total_credits_purchased, last_active_at).

  export interface StatsResponse {
    usage: {
      total_urls_submitted: number;
      tranco_lookups: number;
      cache_lookups: number;
      pipeline_checks_run: number;
      free_rate_pct: number;
    };
    scoring: {
      checks_above_50: number;
      checks_above_75: number;
    };
    account: {
      credits_remaining: number;
      total_credits_purchased: number;
      last_active_at: string;
    };
  }

• src/api.ts:201-203 (helper)

  The UnphurlAPI.stats() method that sends a GET request to /v1/account/stats. This is the actual API call invoked by the get_stats handler.

  async stats(): Promise<StatsResponse> {
    return this.doRequest<StatsResponse>("GET", "/v1/account/stats");
  }

• src/index.ts:40-45 (registration)

  Registration call in the main index.ts file where registerStatsTool is invoked to add 'get_stats' to the MCP server.

  registerStatsTool(server, api);
  registerAllowlistTools(server, api); // list_allowlist, add_to_allowlist, remove_from_allowlist
  
  // Start the server on stdio
  const transport = new StdioServerTransport();
  await server.connect(transport);