fathom-fyi

Instructions

Implementation Reference

• src/index.ts:444-479 (handler)

  The 'set_webhook' MCP tool is registered and implemented in src/index.ts. It validates inputs via Zod, performs access control, and calls the 'registerWebhook' helper function.

  // ─── Tool: set_webhook ───
  server.tool(
    'set_webhook',
    'Register a webhook that fires when market conditions meet your criteria. Fathom evaluates conditions every 60 seconds and POSTs a JSON payload to your URL when all conditions are met. Example: alert me at my bot URL when fear_greed < 20 and regime == capitulation. Available fields: fear_greed, risk_score, opportunity_score, regime, posture, cycle_phase, tvl_change_7d, defi_health, macro_impact, net_flow_signal, leverage_signal, btc_put_call, btc_sp500_correlation, macro_risk_appetite.',
    {
      url: z.string().url().describe('HTTPS URL to POST webhook payload to'),
      conditions: z.array(z.object({
        field: z.string().describe('Condition field (fear_greed, risk_score, regime, posture, net_flow_signal, leverage_signal, etc.)'),
        operator: z.enum(['<', '>', '<=', '>=', '==', '!=']).describe('Comparison operator'),
        threshold: z.union([z.string(), z.number()]).describe('Threshold value'),
      })).min(1).describe('Conditions that must ALL be true to trigger'),
      label: z.string().optional().describe('Human-readable label for this webhook'),
      cooldown_minutes: z.number().optional().describe('Minimum minutes between triggers (default: 60)'),
    },
    async ({ url, conditions, label, cooldown_minutes }) => {
      const gateError = gateTool('set_webhook');
      if (gateError) return { content: [{ type: 'text' as const, text: gateError }] };
  
      const webhook = await registerWebhook({
        url,
        conditions: conditions as { field: string; operator: '<' | '>' | '<=' | '>=' | '==' | '!='; threshold: string | number }[],
        label,
        cooldown_minutes: cooldown_minutes ?? 60,
      });
  
      return { content: [{ type: 'text' as const, text: JSON.stringify({
        status: 'registered',
        webhook_id: webhook.id,
        url: webhook.url,
        conditions: webhook.conditions,
        label: webhook.label,
        cooldown_minutes: webhook.cooldown_minutes,
        agent_guidance: `Webhook registered. Fathom will POST to ${webhook.url} when all conditions are met. Conditions are evaluated every 60 seconds. Cooldown: ${webhook.cooldown_minutes} minutes between triggers. Use manage_webhooks to list or remove webhooks.`,
      }, null, 2) }] };
    },
  );