search_spending

Instructions

Implementation Reference

• src/tools/search-spending.ts:22-114 (handler)

  The main handler function for the search_spending tool. Calls the FEC API client's searchSpending method, groups results by committee, formats disbursements into a readable text output including recipient, amount, date, purpose, category, and location.

  export async function executeSearchSpending(
    client: FECClient,
    params: {
      description?: string;
      recipient_name?: string;
      recipient_state?: string;
      min_amount?: number;
      cycle?: number;
      limit?: number;
    }
  ): Promise<SearchSpendingResult> {
    try {
      const response = await client.searchSpending({
        description: params.description,
        recipient_name: params.recipient_name,
        recipient_state: params.recipient_state,
        min_amount: params.min_amount ?? 500, // Default to $500 to filter noise
        two_year_transaction_period: params.cycle,
        limit: params.limit ?? 20,
      }, 60_000);
  
      // Build header
      const lines: string[] = ['## Spending Search Results'];
  
      // Show search criteria
      const criteria: string[] = [];
      if (params.description) criteria.push(`description: "${params.description}"`);
      if (params.recipient_name) criteria.push(`recipient: "${params.recipient_name}"`);
      if (params.recipient_state) criteria.push(`state: ${params.recipient_state}`);
      if (params.min_amount) criteria.push(`minimum: ${formatCurrency(params.min_amount)}`);
      if (params.cycle) criteria.push(`cycle: ${params.cycle}`);
  
      lines.push(`*Search: ${criteria.join(', ')}*`);
      lines.push(`*Found ${response.pagination.count} disbursements, showing ${response.results.length}*`);
      lines.push('');
  
      if (response.results.length === 0) {
        lines.push('No disbursements found matching the criteria.');
        return {
          content: [{ type: 'text', text: lines.join('\n') }],
        };
      }
  
      // Calculate totals
      const totalAmount = response.results.reduce((sum, r) => sum + r.disbursement_amount, 0);
      lines.push(`**Total (shown):** ${formatCurrency(totalAmount)}`);
      lines.push('');
  
      // Group by spending committee
      const byCommittee = new Map<string, typeof response.results>();
      for (const result of response.results) {
        const key = result.committee_name || result.committee_id;
        if (!byCommittee.has(key)) {
          byCommittee.set(key, []);
        }
        byCommittee.get(key)!.push(result);
      }
  
      // Format results
      let index = 1;
      for (const [committeeName, disbursements] of byCommittee) {
        const committeeTotal = disbursements.reduce((sum, d) => sum + d.disbursement_amount, 0);
        lines.push(`### ${committeeName} (${formatCurrency(committeeTotal)})`);
  
        for (const disb of disbursements) {
          const location = [disb.recipient_city, disb.recipient_state].filter(Boolean).join(', ');
  
          lines.push(`${index}. **${disb.recipient_name}** - ${formatCurrency(disb.disbursement_amount)}`);
          lines.push(`   - Date: ${formatDate(disb.disbursement_date)}`);
          if (disb.disbursement_description) {
            lines.push(`   - Purpose: ${disb.disbursement_description}`);
          }
          if (disb.disbursement_purpose_category) {
            lines.push(`   - Category: ${disb.disbursement_purpose_category}`);
          }
          if (location) {
            lines.push(`   - Location: ${location}`);
          }
          lines.push('');
          index++;
        }
      }
  
      return {
        content: [{ type: 'text', text: lines.join('\n') }],
      };
    } catch (error) {
      return {
        content: [{ type: 'text', text: formatErrorForToolResponse(error) }],
        isError: true,
      };
    }
  }

• src/schemas/search-spending.schema.ts:1-54 (schema)

  Zod-based input schema defining parameters: description (string), recipient_name (string), recipient_state (2-letter string), min_amount (number >= 0), cycle (int 2000-2030), limit (int 1-100). Includes a superRefine ensuring at least one of description or recipient_name is provided.

  /**
   * search_spending Input Schema
   */
  
  import { z } from 'zod';
  
  export const searchSpendingInputSchema = {
    description: z
      .string()
      .optional()
      .describe('Search disbursement descriptions for keywords (e.g., "dinner", "travel", "event tickets", "Disney")'),
    recipient_name: z
      .string()
      .optional()
      .describe('Search for payments to a specific recipient/vendor'),
    recipient_state: z
      .string()
      .length(2)
      .optional()
      .describe('Two-letter state code to filter by (e.g., "FL", "NV")'),
    min_amount: z
      .number()
      .min(0)
      .optional()
      .describe('Minimum disbursement amount to include'),
    cycle: z
      .number()
      .int()
      .min(2000)
      .max(2030)
      .optional()
      .describe('Two-year election cycle (e.g., 2024)'),
    limit: z
      .number()
      .int()
      .min(1)
      .max(100)
      .optional()
      .describe('Maximum number of results to return (default: 20)'),
  };
  
  export const searchSpendingParamsSchema = z
    .object(searchSpendingInputSchema)
    .superRefine((value, ctx) => {
      if (!value.description && !value.recipient_name) {
        ctx.addIssue({
          code: z.ZodIssueCode.custom,
          message:
            'Please provide at least one search criterion: description or recipient_name.',
        });
      }
    });
  
  export type SearchSpendingInput = z.infer<typeof searchSpendingParamsSchema>;

• src/tools/index.ts:197-209 (registration)

  Registers the search_spending tool in the MCP server's tool registry by mapping SEARCH_SPENDING_TOOL, searchSpendingParamsSchema, and executeSearchSpending to the server.tool() call.

  {
    def: SEARCH_SPENDING_TOOL,
    paramsSchema: searchSpendingParamsSchema,
    execute: async (params) =>
      executeSearchSpending(client, params as {
        description?: string;
        recipient_name?: string;
        recipient_state?: string;
        min_amount?: number;
        cycle?: number;
        limit?: number;
      }),
  },

• src/tools/search-spending.ts:11-15 (helper)

  Tool definition object with name 'search_spending', description, and inputSchema. Used for registration.

  export const SEARCH_SPENDING_TOOL = {
    name: 'search_spending',
    description: `Search campaign spending (Schedule B) across all committees by description or recipient. Use to find questionable expenditures like "steak dinner", "event tickets", "travel", "Disney", "golf", or payments to specific vendors. Essential for identifying spending patterns and potential misuse of campaign funds.`,
    inputSchema: searchSpendingInputSchema,
  };