get_committee_finances

Instructions

Implementation Reference

• src/tools/get-committee-finances.ts:28-91 (handler)

  The main handler function `executeGetCommitteeFinances` that fetches committee reports, loans (Schedule C), and debts (Schedule D) in parallel, transforms them, calculates totals/candidate loans, and returns a formatted financial summary.

  export async function executeGetCommitteeFinances(
    client: FECClient,
    params: {
      committee_id: string;
      cycle?: number;
    }
  ): Promise<GetCommitteeFinancesResult> {
    try {
      // Fetch reports, loans, and debts in parallel
      const [reportsResponse, loansResponse, debtsResponse] = await Promise.all([
        client.getCommitteeReports(params.committee_id, {
          cycle: params.cycle,
        }),
        client.getScheduleC({
          committee_id: params.committee_id,
          two_year_transaction_period: params.cycle,
          limit: 20,
        }),
        client.getScheduleD({
          committee_id: params.committee_id,
          two_year_transaction_period: params.cycle,
          limit: 20,
        }),
      ]);
  
      if (reportsResponse.results.length === 0) {
        throw new NotFoundError('Committee reports', params.committee_id);
      }
  
      // Get the most recent report
      const report = reportsResponse.results[0];
      const baseSummary = transformCommitteeReport(report);
  
      // Transform loans and debts
      const loans = transformLoans(loansResponse.results);
      const debts = transformDebts(debtsResponse.results);
  
      // Calculate loan totals
      const totalLoans = loans.reduce((sum, loan) => sum + loan.amount, 0);
      const candidateLoans = loans
        .filter(loan => loan.is_candidate_loan)
        .reduce((sum, loan) => sum + loan.amount, 0);
  
      // Build enhanced summary
      const enhancedSummary: EnhancedFinancialSummary = {
        ...baseSummary,
        total_loans: totalLoans,
        candidate_loans: candidateLoans,
        loans,
        debts,
      };
  
      const formattedText = formatEnhancedFinancialSummaryText(enhancedSummary);
  
      return {
        content: [{ type: 'text', text: formattedText }],
      };
    } catch (error) {
      return {
        content: [{ type: 'text', text: formatErrorForToolResponse(error) }],
        isError: true,
      };
    }
  }

• src/schemas/finances.schema.ts:1-31 (schema)

  Zod schema definitions for get_committee_finances input validation: committee_id (C followed by 8 digits) and optional cycle (1980-2030).

  /**
   * Zod Schema for get_committee_finances tool
   */
  
  import { z } from 'zod';
  
  // Committee ID format: C followed by 8 digits
  const committeeIdPattern = /^C\d{8}$/;
  
  export const getCommitteeFinancesInputSchema = {
    committee_id: z
      .string()
      .regex(committeeIdPattern, 'Committee ID must be in format C00000000 (C followed by 8 digits)')
      .describe('FEC committee ID (e.g., "C00401224")'),
  
    cycle: z
      .number()
      .int()
      .min(1980, 'Cycle must be 1980 or later')
      .max(2030, 'Cycle must be 2030 or earlier')
      .optional()
      .describe('Two-year election cycle (e.g., 2024). Defaults to most recent.'),
  };
  
  export const getCommitteeFinancesParamsSchema = z.object(
    getCommitteeFinancesInputSchema
  );
  
  export type GetCommitteeFinancesInput = z.infer<
    typeof getCommitteeFinancesParamsSchema
  >;

• src/tools/index.ts:120-128 (registration)

  Registration of the 'get_committee_finances' tool with the MCP server, mapping the tool definition, params schema, and execute function.

  {
    def: GET_COMMITTEE_FINANCES_TOOL,
    paramsSchema: getCommitteeFinancesParamsSchema,
    execute: async (params) =>
      executeGetCommitteeFinances(client, params as {
        committee_id: string;
        cycle?: number;
      }),
  },

• src/tools/get-committee-finances.ts:17-21 (handler)

  Tool definition constant GET_COMMITTEE_FINANCES_TOOL with name 'get_committee_finances', description, and input schema reference.

  export const GET_COMMITTEE_FINANCES_TOOL = {
    name: 'get_committee_finances',
    description: `Retrieve comprehensive financial summary for a campaign committee from official FEC filings. Returns total receipts, disbursements, cash on hand, debts, loans (including candidate loans), and calculates burn rate (spending/income ratio). Includes Schedule C loans and Schedule D debts for complete financial picture. Essential for understanding campaign financial health and transparency research.`,
    inputSchema: getCommitteeFinancesInputSchema,
  };

• scripts/fec-day-acceptance.ts:190-195 (helper)

  Acceptance test script calling executeGetCommitteeFinances with committee_id and cycle to verify the tool works end-to-end.

  const financeStart = performance.now();
  const finances = await executeGetCommitteeFinances(client, {
    committee_id: committeeId,
    cycle: target.cycle,
  });
  console.log(`[get_committee_finances] ${finances.isError ? 'ERROR' : 'ok'} (${elapsedMs(financeStart)}ms)`);