get_candidate_contributions
Retrieve individual campaign contributions for a specific candidate using their FEC ID and election year. Sort results by contribution amount to analyze donor support patterns.
Instructions
Get individual contributions for a candidate
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| candidate_id | Yes | FEC candidate ID | |
| election_year | No | Election year | |
| sort | No | Optional: Sort by contribution_receipt_amount (desc for highest first) |
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);