fathom-fyi

Instructions

Implementation Reference

• src/auth/tier-check.ts:157-215 (handler)

  The function getAccountStatus calculates the user's account tier, usage limits, available tools, and upgrade information.

  export function getAccountStatus(): {
    tier: string;
    requests_used: number;
    requests_limit: number;
    requests_remaining: number;
    tools_available: number;
    tools_total: number;
    tools_locked: string[];
    cache_freshness: string;
    upgrade_url: string;
    upgrade_benefits: string[];
  } {
    const tier = getCurrentTier();
    const config = TIER_CONFIGS[tier];
  
    // Get current usage
    const entry = requestCounts.get('default');
    const now = Date.now();
    const isExpired = !entry || now - entry.windowStart > 3600_000;
    const used = isExpired ? 0 : entry.count;
    const limit = config.rateLimit === -1 ? Infinity : config.rateLimit;
    const remaining = limit === Infinity ? Infinity : Math.max(0, limit - used);
  
    // Locked tools
    const allTools = UNLIMITED_TOOLS;
    const locked = allTools.filter(t => !config.tools.includes(t));
  
    // Upgrade benefits
    const benefits: string[] = [];
    if (tier === 'free') {
      benefits.push('Starter ($29/mo): 22 tools including derivatives, stablecoins, correlation, alternative signals, alerts, strategies, key rotation');
      benefits.push('Pro ($99/mo): 27 tools + custom strategies, crowd intelligence, portfolio analysis');
      benefits.push('Unlimited ($299/mo): All 31 tools + webhooks, unlimited requests, 4x fresher data');
    } else if (tier === 'starter') {
      benefits.push('Pro ($99/mo): +5 tools — portfolio analysis, custom strategies, crowd intelligence, signal history, historical context');
      benefits.push('Unlimited ($299/mo): +webhooks, unlimited requests, 4x fresher data');
    } else if (tier === 'pro') {
      benefits.push('Unlimited ($299/mo): +webhooks, unlimited requests, 4x fresher data');
    }
  
    const freshnessLabels: Record<number, string> = {
      1: 'Standard',
      0.5: '2x fresher',
      0.25: '4x fresher',
    };
  
    return {
      tier,
      requests_used: used,
      requests_limit: limit === Infinity ? -1 : limit,
      requests_remaining: remaining === Infinity ? -1 : remaining,
      tools_available: config.tools.length,
      tools_total: allTools.length,
      tools_locked: locked,
      cache_freshness: freshnessLabels[config.cacheTtlMultiplier] ?? 'Standard',
      upgrade_url: 'https://fathom.fyi/#pricing',
      upgrade_benefits: benefits,
    };
  }

• src/index.ts:434-442 (registration)

  The 'get_account_status' tool is registered on the MCP server, calling the getAccountStatus handler.

  server.tool(
    'get_account_status',
    'Check your Fathom account: current tier, requests used this hour, available and locked tools, cache freshness, and upgrade options. Available on all tiers including free.',
    {},
    async () => {
      const status = getAccountStatus();
      return { content: [{ type: 'text' as const, text: JSON.stringify(status, null, 2) }] };
    },
  );