MCP OpenFEC Server

Instructions

Implementation Reference

• src/server.ts:585-612 (handler)

  The primary handler function for the 'get_candidate_contributions' tool. It validates the input parameters using Zod schema, consumes a rate limit token, fetches the principal committee ID for the candidate, queries the OpenFEC API endpoint for Schedule A (itemized contributions), and returns the response data as formatted JSON text.

  private async handleGetCandidateContributions(args: any) {
    const schema = z.object({
      candidate_id: z.string(),
      election_year: z.number().optional(),
      sort: z.enum(['desc', 'asc']).optional()
    });
  
    const { candidate_id, election_year, sort } = schema.parse(args);
    this.rateLimiter.consumeToken();
  
    const response = await this.axiosInstance.get(`/schedules/schedule_a/`, {
      params: {
        committee_id: await this.getCommitteeId(candidate_id),
        two_year_transaction_period: election_year,
        sort: sort === 'desc' ? '-contribution_receipt_amount' : 'contribution_receipt_amount',
        per_page: 10
      }
    });
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(response.data, null, 2),
        },
      ],
    };
  }

• src/server.ts:586-590 (schema)

  Zod runtime validation schema for the tool's input parameters inside the handler.

  const schema = z.object({
    candidate_id: z.string(),
    election_year: z.number().optional(),
    sort: z.enum(['desc', 'asc']).optional()
  });

• src/server.ts:170-192 (registration)

  Registration of the 'get_candidate_contributions' tool in the ListTools handler, including the tool name, description, and JSON input schema definition.

  {
    name: 'get_candidate_contributions',
    description: 'Get individual contributions for a candidate',
    inputSchema: {
      type: 'object',
      properties: {
        candidate_id: {
          type: 'string',
          description: 'FEC candidate ID'
        },
        election_year: {
          type: 'number',
          description: 'Election year'
        },
        sort: {
          type: 'string',
          description: 'Optional: Sort by contribution_receipt_amount (desc for highest first)',
          enum: ['desc', 'asc']
        }
      },
      required: ['candidate_id']
    },
  },

• src/server.ts:614-628 (helper)

  Helper method used by the handler to fetch the principal campaign committee ID (designation 'P') for the given candidate ID, necessary because contributions are queried by committee.

  private async getCommitteeId(candidate_id: string): Promise<string> {
    const response = await this.axiosInstance.get(`/candidate/${candidate_id}/committees`, {
      params: {
        designation: 'P'
      }
    });
    
    if (response.data.results && response.data.results.length > 0) {
      return response.data.results[0].committee_id;
    }
    throw new McpError(
      ErrorCode.InvalidRequest,
      'No principal campaign committee found for candidate'
    );
  }

• src/server.ts:455-456 (registration)

  Dispatcher case in the CallToolRequest handler that routes calls to the specific handler method.

  case 'get_candidate_contributions':
    return await this.handleGetCandidateContributions(request.params.arguments);