fec-mcp-server

Instructions

Implementation Reference

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

  The core handler function that executes the financial summary logic for a committee.

  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/tools/get-committee-finances.ts:17-21 (registration)

  Tool metadata definition and registration object.

  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,
  };

• src/schemas/finances.schema.ts:10-27 (schema)

  Input schema and type definition for the get_committee_finances tool.

  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 type GetCommitteeFinancesInput = {
    committee_id: string;
    cycle?: number;