get_filings

Instructions

Implementation Reference

• src/server.ts:630-661 (handler)

  The handler function that implements the get_filings tool logic: validates input with Zod schema, applies rate limiting, queries the OpenFEC API /filings endpoint with filters, and returns the response as MCP content.

  private async handleGetFilings(args: any) {
    const schema = z.object({
      committee_id: z.string().optional(),
      candidate_id: z.string().optional(),
      form_type: z.array(z.string()).optional(),
      min_receipt_date: z.string().optional(),
      max_receipt_date: z.string().optional(),
      state: z.string().optional(),
      sort: z.enum(['asc', 'desc']).optional()
    });
  
    const params = schema.parse(args);
    this.rateLimiter.consumeToken();
  
    const response = await this.axiosInstance.get('/filings', {
      params: {
        ...params,
        sort_hide_null: true,
        sort: params.sort === 'desc' ? '-receipt_date' : 'receipt_date',
        per_page: 20
      }
    });
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(response.data, null, 2),
        },
      ],
    };
  }

• src/server.ts:196-230 (schema)

  Input schema definition for the get_filings tool, advertised in the ListTools response.

  inputSchema: {
    type: 'object',
    properties: {
      committee_id: {
        type: 'string',
        description: 'Optional: FEC committee ID'
      },
      candidate_id: {
        type: 'string',
        description: 'Optional: FEC candidate ID'
      },
      form_type: {
        type: 'array',
        items: { type: 'string' },
        description: 'Optional: Form types to filter by (e.g., ["F3", "F3P"])'
      },
      min_receipt_date: {
        type: 'string',
        description: 'Optional: Minimum receipt date (YYYY-MM-DD)'
      },
      max_receipt_date: {
        type: 'string',
        description: 'Optional: Maximum receipt date (YYYY-MM-DD)'
      },
      state: {
        type: 'string',
        description: 'Optional: Two-letter state code'
      },
      sort: {
        type: 'string',
        enum: ['asc', 'desc'],
        description: 'Optional: Sort by receipt date'
      }
    }
  }

• src/server.ts:193-231 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining name, description, and inputSchema for get_filings.

  {
    name: 'get_filings',
    description: 'Retrieve official FEC filings with filters',
    inputSchema: {
      type: 'object',
      properties: {
        committee_id: {
          type: 'string',
          description: 'Optional: FEC committee ID'
        },
        candidate_id: {
          type: 'string',
          description: 'Optional: FEC candidate ID'
        },
        form_type: {
          type: 'array',
          items: { type: 'string' },
          description: 'Optional: Form types to filter by (e.g., ["F3", "F3P"])'
        },
        min_receipt_date: {
          type: 'string',
          description: 'Optional: Minimum receipt date (YYYY-MM-DD)'
        },
        max_receipt_date: {
          type: 'string',
          description: 'Optional: Maximum receipt date (YYYY-MM-DD)'
        },
        state: {
          type: 'string',
          description: 'Optional: Two-letter state code'
        },
        sort: {
          type: 'string',
          enum: ['asc', 'desc'],
          description: 'Optional: Sort by receipt date'
        }
      }
    }
  },

• src/server.ts:457-458 (registration)

  Dispatch case in the CallToolRequestSchema handler that routes get_filings calls to the handleGetFilings method.

  case 'get_filings':
    return await this.handleGetFilings(request.params.arguments);