Servidor MCP de la FEC

Un servidor del Protocolo de Contexto de Modelo (MCP) para la investigación y transparencia de la financiación de campañas de la Comisión Federal de Elecciones (FEC). Este servidor proporciona herramientas para buscar candidatos, recuperar informes financieros y analizar contribuciones y desembolsos a partir de los datos oficiales de la FEC.

Características

• search_candidates: Busca candidatos federales por nombre, filtra por año electoral, cargo, estado o partido

• get_committee_finances: Recupera resúmenes financieros, incluidos ingresos, desembolsos, efectivo disponible y tasa de consumo

• get_receipts: Obtiene contribuciones detalladas (Anexo A) con detalles del donante

• get_disbursements: Obtiene gastos detallados (Anexo B) con detalles del destinatario y el propósito

• Análisis destacado con indicadores: Bloques destacados opcionales para recibos/desembolsos con lista de referencia + razones de indicadores heurísticos

• get_independent_expenditures: Rastrea el gasto de los Super PAC a favor o en contra de candidatos (Anexo E)

• get_committee_flags: Comprueba RFAI, enmiendas y señales de alerta de cumplimiento relacionadas

• search_donors: Busca donantes individuales por nombre, empleador u ocupación en todos los comités

• search_spending: Busca gastos de campaña por descripción o destinatario en todos los comités

Todos los datos provienen directamente de la API oficial de OpenFEC.

Instalación

Requisitos previos

• Node.js 20 o posterior

• Una clave de API de la FEC (gratuita en api.open.fec.gov)

Instalar desde npm

npm install -g fec-mcp-server

Instalar desde el código fuente

git clone <repository-url>
cd fecmcp
npm install
npm run build

Configuración

Establece tu clave de API de la FEC como una variable de entorno:

export FEC_API_KEY=your-api-key-here

O crea un archivo .env en la raíz de tu proyecto:

FEC_API_KEY=your-api-key-here

Uso con Claude Desktop

Añade el servidor a tu archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fec": {
      "command": "npx",
      "args": ["fec-mcp-server"],
      "env": {
        "FEC_API_KEY": "your-api-key-here"
      }
    }
  }
}

O si se instaló globalmente:

{
  "mcpServers": {
    "fec": {
      "command": "fec-mcp-server",
      "env": {
        "FEC_API_KEY": "your-api-key-here"
      }
    }
  }
}

Herramientas

search_candidates

Busca candidatos en los registros de la FEC por nombre.

Parámetros:

• q (obligatorio): Nombre del candidato a buscar

• election_year (opcional): Filtrar por año electoral (ej. 2024)

• office (opcional): Filtrar por cargo - H (Cámara), S (Senado), P (Presidente)

• state (opcional): Filtrar por estado (código de 2 letras)

• party (opcional): Filtrar por código de partido (ej. "DEM", "REP")

Ejemplo:

Search for candidates named "Smith" running for Senate in 2024

get_committee_finances

Recupera el resumen financiero de un comité de campaña.

Parámetros:

• committee_id (obligatorio): ID del comité de la FEC (ej. "C00401224")

• cycle (opcional): Ciclo electoral de dos años (ej. 2024)

Resultados:

• Total de ingresos y desembolsos

• Efectivo disponible

• Deudas pendientes

• Tasa de consumo (ratio gasto/ingresos)

• Desglose de contribuciones (individual, PAC, partido)

• Porcentaje de pequeños donantes

Ejemplo:

Get the financial summary for committee C00401224

get_receipts

Recupera contribuciones detalladas (Anexo A) recibidas por un comité.

Parámetros:

• committee_id (obligatorio): ID del comité de la FEC

• min_amount (opcional): Monto mínimo de contribución (predeterminado: $1,000)

• two_year_transaction_period (opcional): Ciclo electoral (ej. 2024)

• cycle (opcional): Alias para two_year_transaction_period; alinea automáticamente los recibos con el uso del ciclo financiero

• contributor_type (opcional): "individual" o "committee"

• include_notable (opcional): Incluir bloque destacado con indicadores (predeterminado: true)

• fuzzy_threshold (opcional): Umbral de coincidencia difusa para indicadores de lista de referencia (predeterminado: 90, rango: 80-99)

• limit (opcional): Número de resultados (predeterminado: 20, máx: 100)

• sort_by (opcional): "amount" o "date" (predeterminado: "amount")

Ejemplo:

Show the top 10 contributions over $5,000 to committee C00401224

get_disbursements

Recupera gastos detallados (Anexo B) realizados por un comité.

Parámetros:

• committee_id (obligatorio): ID del comité de la FEC

• min_amount (opcional): Monto mínimo de desembolso (predeterminado: $1,000)

• two_year_transaction_period (opcional): Ciclo electoral

• cycle (opcional): Alias para two_year_transaction_period; alinea automáticamente los desembolsos con el uso del ciclo financiero

• purpose (opcional): Filtrar por palabra clave de propósito (ej. "MEDIA", "CONSULTING")

• include_notable (opcional): Incluir bloque destacado con indicadores (predeterminado: true)

• fuzzy_threshold (opcional): Umbral de coincidencia difusa para indicadores de lista de referencia (predeterminado: 90, rango: 80-99)

• limit (opcional): Número de resultados (predeterminado: 20, máx: 100)

• sort_by (opcional): "amount" o "date" (predeterminado: "amount")

Ejemplo:

Show media-related spending over $10,000 by committee C00401224

get_independent_expenditures

Recupera gastos independientes (Anexo E): dinero gastado por PAC y Super PAC para apoyar u oponerse a candidatos.

Parámetros:

• candidate_id (opcional): ID del candidato de la FEC para ver los gastos dirigidos a él

• committee_id (opcional): ID del comité de la FEC para ver sus gastos independientes

• support_oppose (opcional): Filtrar por "support" o "oppose"

• min_amount (opcional): Monto mínimo de gasto

• cycle (opcional): Ciclo electoral de dos años

• limit (opcional): Número de resultados (predeterminado: 20)

Nota: Se requiere candidate_id o committee_id.

Ejemplo:

Show independent expenditures opposing candidate P00009423

get_committee_flags

Comprueba si un comité de campaña tiene señales de alerta de cumplimiento, incluidos RFAI y enmiendas.

Parámetros:

• committee_id (obligatorio): ID del comité de la FEC

• cycle (opcional): Ciclo electoral de dos años

Resultados:

• Recuento y detalles de RFAI (Solicitud de Información Adicional)

• Recuento y detalles de enmiendas

• Problemas de cumplimiento recientes

Ejemplo:

Check committee C00401224 for any compliance flags

search_donors

Busca donantes individuales en todas las declaraciones de la FEC por nombre, empleador u ocupación.

Parámetros:

• contributor_name (opcional): Nombre del donante a buscar

• contributor_employer (opcional): Nombre del empleador (ej. "Goldman Sachs")

• contributor_occupation (opcional): Ocupación (ej. "Lobbyist")

• contributor_state (opcional): Código de estado de dos letras

• min_amount (opcional): Monto mínimo de contribución (predeterminado: $200)

• cycle (opcional): Ciclo electoral de dos años

• limit (opcional): Número de resultados (predeterminado: 20)

Nota: Se requiere al menos uno de contributor_name, contributor_employer o contributor_occupation.

Ejemplo:

Find contributions from employees of "Meta" in California

search_spending

Busca gastos de campaña (Anexo B) en todos los comités por descripción o destinatario.

Parámetros:

• description (opcional): Palabra clave en la descripción del gasto (ej. "travel", "consulting")

• recipient_name (opcional): Nombre del destinatario/proveedor

• recipient_state (opcional): Código de estado de dos letras

• min_amount (opcional): Monto mínimo (predeterminado: $500)

• cycle (opcional): Ciclo electoral de dos años

• limit (opcional): Número de resultados (predeterminado: 20)

Nota: Se requiere al menos uno de description o recipient_name.

Ejemplo:

Find spending on "golf" or "resort" across all committees

Desarrollo

Configuración

npm install

Ejecutar pruebas

npm test          # Watch mode
npm run test:run  # Single run
npm run test:coverage  # With coverage

Compilar

npm run build

Comprobación de tipos

npm run typecheck

Comprobaciones de aceptación en vivo

npm run acceptance:fec-day
npm run acceptance:notable

Límites de tasa de la API

La API de la FEC permite 1,000 solicitudes por hora con una clave de API. Para límites más altos (hasta 7,200 solicitudes/hora), contacta a la FEC.

Tiempos de espera y latencia de la API

El tiempo de espera predeterminado de la solicitud es de 30 segundos. Las herramientas de búsqueda (search_candidates, search_donors, search_spending) utilizan un tiempo de espera de 60 segundos porque estos endpoints de la API de la FEC realizan escaneos amplios de bases de datos y son inherentemente más lentos.

Para anular el tiempo de espera predeterminado globalmente, establece la variable de entorno FEC_API_TIMEOUT_MS:

export FEC_API_TIMEOUT_MS=45000  # 45 seconds

Docker

Compila la imagen del contenedor localmente:

docker build -t fec-mcp-server .

Ejecútalo con tu clave de API proporcionada en tiempo de ejecución:

docker run --rm -i \
  -e FEC_API_KEY=your-api-key-here \
  fec-mcp-server

Lanzamientos

Las comprobaciones de Glama esperan un lanzamiento de GitHub. Después de fusionar los cambios de tu próximo repositorio, crea y publica una etiqueta como v1.0.0 desde GitHub o con:

git tag v1.0.0
git push origin v1.0.0

Licencia

MIT

Descargo de responsabilidad

Esta herramienta está diseñada para la investigación de transparencia en la financiación de campañas. Proporciona acceso a datos públicos de la FEC de manera neutral y no partidista. La herramienta y sus resultados no deben utilizarse para promover u oponerse a ningún candidato o partido político.

Recursos

• Documentación de la API de OpenFEC

• FEC.gov

• Protocolo de Contexto de Modelo

• Atribución de la lista de referencia: github/DGA-Research/FEC_Coder_Project_Streamlit (instantáneas incluidas en resources/reference-lists/)