congressgov-mcp-server

Datos del Congreso de EE. UU.

Documentación

@cyanheads/congressgov-mcp-server

Accede a datos del Congreso de EE. UU. — proyectos de ley, votaciones, miembros, comités — a través de MCP. STDIO y HTTP Streamable.

11 Herramientas • 5 Recursos • 2 Prompts

Servidor público alojado: https://congressgov.caseyjhand.com/mcp

Herramientas

Once herramientas de solo lectura para consultar datos legislativos de EE. UU.:

Herramienta	Descripción
`congressgov_bill_lookup`	Explora y recupera datos de proyectos de ley legislativos de EE. UU. — acciones, patrocinadores, resúmenes, texto, proyectos de ley relacionados
`congressgov_enacted_laws`	Explora leyes públicas y privadas promulgadas por congreso
`congressgov_member_lookup`	Descubre miembros del Congreso por estado/distrito/congreso, recupera carteras legislativas
`congressgov_committee_lookup`	Explora comités del Congreso y su legislación, informes y nominaciones
`congressgov_roll_votes`	Recupera votaciones nominales de la Cámara y el Senado y las posiciones de voto de miembros individuales
`congressgov_senate_nominations`	Explora nominaciones presidenciales para puestos federales y sigue el proceso de confirmación del Senado
`congressgov_bill_summaries`	Explora resúmenes recientes de proyectos de ley del CRS — el feed de "lo que está sucediendo"
`congressgov_crs_reports`	Explora y recupera informes de análisis de políticas no partidistas del CRS
`congressgov_committee_reports`	Explora y recupera informes de comités que acompañan la legislación
`congressgov_daily_record`	Explora el Registro del Congreso diario — discursos en el pleno, debates y procedimientos
`congressgov_search_bills`	Búsqueda por palabras clave en títulos de proyectos de ley y resúmenes del CRS mediante un espejo local de texto completo (opt-in, desactivado por defecto)

`congressgov_bill_lookup`

Explora y recupera datos de proyectos de ley legislativos de EE. UU. de Congress.gov.

Filtra por número de congreso, tipo de proyecto de ley y rango de fechas de actualización
Recupera sub-recursos detallados: acciones, enmiendas, comités, copatrocinadores, proyectos de ley relacionados, temas, resúmenes, versiones de texto y títulos
content lee el texto real del documento de una versión de texto, una ventana de caracteres acotada a la vez — elige la versión con textVersionIndex, la ventana con characterOffset/characterLimit, y sigue nextOffset para recorrer un proyecto de ley completo
list por defecto es order='recent' (fecha de actualización más reciente primero); pasa order='oldest' para orden ascendente
Soporte de paginación para explorar grandes conjuntos de resultados

`congressgov_member_lookup`

Descubre miembros del Congreso y su actividad legislativa.

Explora por estado, distrito, número de congreso y cámara
Recupera la legislación patrocinada y copatrocinada de un miembro
Busca miembros específicos por ID de bioguide

`congressgov_committee_lookup`

Explora comités del Congreso y su legislación, informes y nominaciones.

Filtra por cámara (Cámara, Senado, Conjunto)
Recupera proyectos de ley, informes y nominaciones de comités
Las consultas de detalle y sub-recursos solo necesitan committeeCode — chamber se detecta automáticamente desde el código
Los proyectos de ley de comités por defecto son order='recent' (más recientes primero); pasa order='oldest' para orden ascendente por fecha de actualización

`congressgov_roll_votes`

Recupera votaciones nominales de la Cámara y el Senado y las posiciones de voto de miembros individuales.

Establece chamber a house (por defecto, desde la API de Congress.gov) o senate (desde el feed oficial LIS del Senado — la API no expone votaciones del Senado)
list explora votaciones por congreso y sesión, más recientes primero; pasa order='oldest' para orden ascendente
get devuelve la pregunta, el resultado, los recuentos, el desglose por partido y el proyecto de ley/nominación/enmienda asociado
members devuelve la posición registrada de cada miembro

`congressgov_bill_summaries`

Explora resúmenes recientes de proyectos de ley del CRS.

Filtra por congreso y tipo de proyecto de ley
Explora cronológicamente para ver qué se está moviendo en el Congreso

`congressgov_crs_reports`

Explora y recupera informes del CRS — análisis de políticas no partidistas escritos por expertos en la materia de la Biblioteca del Congreso.

Explora el catálogo completo de informes
Recupera informes individuales por número de producto

`congressgov_daily_record`

Explora el Registro del Congreso diario — discursos en el pleno, debates y texto legislativo publicado cada día que el Congreso está en sesión.

Explora volúmenes por número de congreso
Recupera artículos de números específicos
content lee el texto real de un artículo, seleccionado por articleIndex y acotado por characterOffset/characterLimit

`congressgov_search_bills`

Búsqueda por palabras clave en títulos de proyectos de ley y resúmenes del CRS contra un espejo local de texto completo — la ruta de descubrimiento que la propia API de Congress.gov no tiene.

Opt-in: desactivado por defecto, y no se ofrece a los clientes hasta CONGRESS_MIRROR_ENABLED=true. Con la bandera establecida pero el índice aún no construido (bun run mirror:init), la herramienta es invocable y responde con un resultado vacío y un aviso para construir el índice
Acota con filtros congress, billType y originChamber
Devuelve coincidencias clasificadas por BM25 con el id derivado de cada proyecto de ley, listo para una llamada de seguimiento a congressgov_bill_lookup

Recursos

Patrón de URI	Descripción
`congress://current`	Número de congreso actual, fechas de sesión, información de cámara
`congress://bill-types`	Tabla de referencia de códigos válidos de tipo de proyecto de ley
`congress://member/{bioguideId}`	Perfil de miembro por ID de bioguide
`congress://bill/{congress}/{billType}/{billNumber}`	Detalle de proyecto de ley por congreso, tipo y número
`congress://committee/{committeeCode}`	Detalle de comité por código de comité

Prompts

Prompt	Descripción
`congressgov_bill_analysis`	Marco estructurado para analizar un proyecto de ley
`congressgov_legislative_research`	Marco de investigación para un área de políticas en todo el Congreso

Características

Construido sobre @cyanheads/mcp-ts-core:

Definiciones declarativas de herramientas — un archivo por herramienta, el marco maneja el registro y la validación
Manejo unificado de errores en todas las herramientas
Autenticación conectable (none, jwt, oauth)
Backends de almacenamiento intercambiables: in-memory, filesystem, Supabase
Registro estructurado con trazado opcional de OpenTelemetry
Se ejecuta localmente (stdio/HTTP) o en Docker desde el mismo código base

Específico de Congress.gov:

Cliente con seguridad de tipos para la API REST v3 de Congress.gov
Clave API opcional de api.data.gov — por defecto DEMO_KEY (30 req/h); clave propia obtiene 5,000 req/h
Paginación automática y normalización de respuestas
Conciencia de límites de tasa
Todas las herramientas son de solo lectura e idempotentes

Primeros pasos

Instancia pública alojada

Una instancia pública está disponible en https://congressgov.caseyjhand.com/mcp — no requiere instalación. Apunta cualquier cliente MCP a ella mediante HTTP Streamable:

{
  "mcpServers": {
    "congressgov-mcp-server": {
      "type": "streamable-http",
      "url": "https://congressgov.caseyjhand.com/mcp"
    }
  }
}

Autoalojado / Local

Agrega lo siguiente a tu archivo de configuración del cliente MCP.

{
  "mcpServers": {
    "congressgov-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/congressgov-mcp-server@latest"],
      "env": {
        "CONGRESS_API_KEY": "your-api-key"
      }
    }
  }
}

O con npx (no requiere Bun):

{
  "mcpServers": {
    "congressgov-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/congressgov-mcp-server@latest"],
      "env": {
        "CONGRESS_API_KEY": "your-api-key"
      }
    }
  }
}

Obtén una clave API gratuita en api.data.gov/signup para 5,000 req/h. Sin clave, el servidor recurre a DEMO_KEY (30 req/h).

Requisitos previos

Bun v1.3.2 o superior.

Instalación

Clona el repositorio:

git clone https://github.com/cyanheads/congressgov-mcp-server.git

Navega al directorio:

cd congressgov-mcp-server

Instala las dependencias:

bun install

Configuración

Toda la configuración se valida al inicio mediante esquemas Zod en src/config/server-config.ts. Variables de entorno clave:

Variable	Descripción	Por defecto
`CONGRESS_API_KEY`	Opcional. Clave API de api.data.gov. Omítela para usar `DEMO_KEY` (30 req/h); clave propia: 5,000 req/h.	`DEMO_KEY`
`CONGRESS_API_BASE_URL`	URL base de la API de Congress.gov	`https://api.congress.gov/v3`
`MCP_TRANSPORT_TYPE`	Transporte: `stdio` o `http`	`stdio`
`MCP_HTTP_PORT`	Puerto del servidor HTTP	`3010`
`MCP_AUTH_MODE`	Autenticación: `none`, `jwt` o `oauth`	`none`
`MCP_SESSION_MODE`	Modo de sesión HTTP: `auto`, `stateful` o `stateless`. Este servidor no mantiene estado por sesión; la imagen Docker ejecuta `stateless`.	`auto` (resuelve a `stateful`)
`MCP_LOG_LEVEL`	Nivel de registro (`debug`, `info`, `warning`, `error`, etc.)	`info`
`LOGS_DIR`	Directorio para archivos de registro (solo Node.js).	`<project-root>/logs`
`STORAGE_PROVIDER_TYPE`	Backend de almacenamiento	`in-memory`
`OTEL_ENABLED`	Habilita instrumentación OpenTelemetry (spans, métricas, registros de finalización)	`false`

Ejecutar el servidor

Desarrollo local

Compila y ejecuta la versión de producción:

bun run rebuild
bun run start:http   # or start:stdio

Ejecuta comprobaciones y pruebas:

bun run devcheck     # Lints, formats, type-checks
bun run test         # Runs test suite

Docker

docker build -t congressgov-mcp-server .
docker run -e CONGRESS_API_KEY=your-api-key -p 3010:3010 congressgov-mcp-server

Estructura del proyecto

Directorio	Propósito
`src/mcp-server/tools/definitions/`	Definiciones de herramientas (`*.tool.ts`). Once herramientas de Congress.gov.
`src/mcp-server/resources/definitions/`	Definiciones de recursos. Recursos de congreso, proyecto de ley, miembro y comité.
`src/mcp-server/prompts/definitions/`	Definiciones de prompts. Prompts de análisis de proyectos de ley e investigación legislativa.
`src/services/congress-api/`	Cliente API de Congress.gov — autenticación, paginación, límites de tasa.
`src/config/`	Análisis y validación de variables de entorno específicas del servidor con Zod.
`tests/`	Pruebas unitarias y de integración, reflejando la estructura de `src/`.

Guía de desarrollo

Consulta CLAUDE.md para pautas de desarrollo y reglas arquitectónicas. La versión corta:

Los manejadores lanzan excepciones, el marco las captura — sin try/catch en la lógica de herramientas
Usa ctx.log para registro, ctx.state para almacenamiento
Todas las herramientas son de solo lectura con readOnlyHint: true y idempotentHint: true

Contribuciones

Las incidencias y solicitudes de extracción son bienvenidas. Ejecuta comprobaciones y pruebas antes de enviar:

bun run devcheck
bun run test

Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0. Consulta el archivo LICENSE para más detalles.