congressgov-mcp-server

Dados do congresso dos EUA

GitHub

Experimente este MCPPatrocinado

Documentação

@cyanheads/congressgov-mcp-server

Acesse dados legislativos dos EUA - projetos de lei, votações, membros, comitês - via MCP. STDIO & Streamable HTTP.

11 Ferramentas • 5 Recursos • 2 Prompts

Servidor Público Hospedado: https://congressgov.caseyjhand.com/mcp

Ferramentas

Onze ferramentas somente leitura para consultar dados legislativos dos EUA:

Ferramenta	Descrição
`congressgov_bill_lookup`	Navegue e recupere dados de projetos de lei dos EUA — ações, patrocinadores, resumos, textos, projetos relacionados
`congressgov_enacted_laws`	Navegue por leis públicas e privadas promulgadas por congresso
`congressgov_member_lookup`	Descubra membros do congresso por estado/distrito/congresso, recupere portfólios legislativos
`congressgov_committee_lookup`	Navegue por comitês do congresso e sua legislação, relatórios e nomeações
`congressgov_roll_votes`	Recupere votações nominais da Câmara e do Senado e posições de votação de membros individuais
`congressgov_senate_nominations`	Navegue por nomeações presidenciais para cargos federais e acompanhe o processo de confirmação no Senado
`congressgov_bill_summaries`	Navegue por resumos recentes de projetos de lei do CRS — o feed do "o que está acontecendo"
`congressgov_crs_reports`	Navegue e recupere relatórios de análise de políticas não partidários do CRS
`congressgov_committee_reports`	Navegue e recupere relatórios de comitês que acompanham a legislação
`congressgov_daily_record`	Navegue pelo Congressional Record diário — discursos, debates e procedimentos
`congressgov_search_bills`	Pesquise por palavras-chave em títulos de projetos e resumos do CRS via espelho local de texto completo (opt-in, desativado por padrão)

`congressgov_bill_lookup`

Navegue e recupere dados de projetos de lei dos EUA do Congress.gov.

Filtre por número do congresso, tipo de projeto e intervalo de data de atualização
Recupere sub-recursos detalhados: ações, emendas, comitês, co-patrocinadores, projetos relacionados, assuntos, resumos, versões de texto e títulos
content lê o texto real de uma versão de texto, uma janela limitada de caracteres por vez — escolha a versão com textVersionIndex, a janela com characterOffset/characterLimit, e siga nextOffset para percorrer um projeto completo
list usa como padrão order='recent' (data de atualização mais recente primeiro); passe order='oldest' para ordem crescente
Suporte a paginação para navegar em grandes conjuntos de resultados

`congressgov_member_lookup`

Descubra membros do congresso e sua atividade legislativa.

Navegue por estado, distrito, número do congresso e câmara
Recupere a legislação patrocinada e co-patrocinada de um membro
Consulte membros específicos pelo ID bioguide

`congressgov_committee_lookup`

Navegue por comitês do congresso e sua legislação, relatórios e nomeações.

Filtre por câmara (Câmara, Senado, Conjunto)
Recupere projetos, relatórios e nomeações de comitês
Consultas de detalhes e sub-recursos precisam apenas de committeeCode — chamber é detectado automaticamente a partir do código
Projetos de comitês usam como padrão order='recent' (mais recentes primeiro); passe order='oldest' para ordem crescente de data de atualização

`congressgov_roll_votes`

Recupere votações nominais da Câmara e do Senado e posições de votação de membros individuais.

Defina chamber como house (padrão, da API do Congress.gov) ou senate (do feed oficial LIS do Senado — a API não expõe votações do Senado)
list navega por votações por congresso e sessão, mais recentes primeiro; passe order='oldest' para ordem crescente
get retorna a questão, o resultado, os totais, a divisão por partido e o projeto/nomeação/emenda associado
members retorna a posição registrada de cada membro

`congressgov_bill_summaries`

Navegue por resumos recentes de projetos de lei do CRS.

Filtre por congresso e tipo de projeto
Navegue cronologicamente para ver o que está em tramitação no Congresso

`congressgov_crs_reports`

Navegue e recupere relatórios do CRS — análises de políticas não partidárias escritas por especialistas da Biblioteca do Congresso.

Navegue pelo catálogo completo de relatórios
Recupere relatórios individuais por número de produto

`congressgov_daily_record`

Navegue pelo Congressional Record diário — discursos, debates e textos legislativos publicados a cada dia em que o Congresso está em sessão.

Navegue por volumes por número do congresso
Recupere artigos específicos de edições
content lê o texto real de um artigo, selecionado por articleIndex e limitado por characterOffset/characterLimit

`congressgov_search_bills`

Pesquise por palavras-chave em títulos de projetos e resumos do CRS contra um espelho local de texto completo — o caminho de descoberta que a própria API do Congress.gov não oferece.

Opt-in: desativado por padrão, e não oferecido aos clientes até CONGRESS_MIRROR_ENABLED=true. Com a flag definida mas o índice ainda não construído (bun run mirror:init), a ferramenta é chamável e responde com um resultado vazio e um aviso para construir o índice
Refine com filtros congress, billType e originChamber
Retorna correspondências classificadas por BM25 com o id derivado de cada projeto, pronto para uma chamada de acompanhamento congressgov_bill_lookup

Recursos

Padrão de URI	Descrição
`congress://current`	Número atual do congresso, datas de sessão, informações da câmara
`congress://bill-types`	Tabela de referência de códigos válidos de tipo de projeto
`congress://member/{bioguideId}`	Perfil de membro por ID bioguide
`congress://bill/{congress}/{billType}/{billNumber}`	Detalhes do projeto por congresso, tipo e número
`congress://committee/{committeeCode}`	Detalhes do comitê por código do comitê

Prompts

Prompt	Descrição
`congressgov_bill_analysis`	Estrutura organizada para analisar um projeto de lei
`congressgov_legislative_research`	Estrutura de pesquisa para uma área de políticas no Congresso

Recursos

Construído sobre @cyanheads/mcp-ts-core:

Definições declarativas de ferramentas — um arquivo por ferramenta, o framework cuida do registro e da validação
Tratamento unificado de erros em todas as ferramentas
Autenticação plugável (none, jwt, oauth)
Backends de armazenamento intercambiáveis: in-memory, filesystem, Supabase
Logging estruturado com rastreamento opcional via OpenTelemetry
Executa localmente (stdio/HTTP) ou em Docker a partir do mesmo código

Específicos do Congress.gov:

Cliente type-safe para a API REST v3 do Congress.gov
Chave de API opcional de api.data.gov — padrão DEMO_KEY (30 req/h); chave própria obtém 5.000 req/h
Paginação automática e normalização de respostas
Consciência de limites de taxa
Todas as ferramentas são somente leitura e idempotentes

Primeiros passos

Instância Pública Hospedada

Uma instância pública está disponível em https://congressgov.caseyjhand.com/mcp — sem necessidade de instalação. Aponte qualquer cliente MCP para ela via Streamable HTTP:

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

Auto-hospedado / Local

Adicione o seguinte ao arquivo de configuração do seu cliente MCP.

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

Ou com npx (sem necessidade de Bun):

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

Obtenha uma chave de API gratuita em api.data.gov/signup para 5.000 req/h. Sem chave, o servidor usa o padrão DEMO_KEY (30 req/h).

Pré-requisitos

Bun v1.3.2 ou superior.

Instalação

Clone o repositório:

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

Navegue até o diretório:

cd congressgov-mcp-server

Instale as dependências:

bun install

Configuração

Toda a configuração é validada na inicialização via esquemas Zod em src/config/server-config.ts. Principais variáveis de ambiente:

Variável	Descrição	Padrão
`CONGRESS_API_KEY`	Opcional. Chave de API de api.data.gov. Omita para usar `DEMO_KEY` (30 req/h); chave própria: 5.000 req/h.	`DEMO_KEY`
`CONGRESS_API_BASE_URL`	URL base da API do Congress.gov	`https://api.congress.gov/v3`
`MCP_TRANSPORT_TYPE`	Transporte: `stdio` ou `http`	`stdio`
`MCP_HTTP_PORT`	Porta do servidor HTTP	`3010`
`MCP_AUTH_MODE`	Autenticação: `none`, `jwt` ou `oauth`	`none`
`MCP_SESSION_MODE`	Modo de sessão HTTP: `auto`, `stateful` ou `stateless`. Este servidor não mantém estado por sessão; a imagem Docker executa `stateless`.	`auto` (resolve para `stateful`)
`MCP_LOG_LEVEL`	Nível de log (`debug`, `info`, `warning`, `error`, etc.)	`info`
`LOGS_DIR`	Diretório para arquivos de log (somente Node.js).	`<project-root>/logs`
`STORAGE_PROVIDER_TYPE`	Backend de armazenamento	`in-memory`
`OTEL_ENABLED`	Ativar instrumentação OpenTelemetry (spans, métricas, logs de conclusão)	`false`

Executando o servidor

Desenvolvimento local

Compile e execute a versão de produção:

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

Execute verificações e testes:

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

Estrutura do projeto

Diretório	Finalidade
`src/mcp-server/tools/definitions/`	Definições de ferramentas (`*.tool.ts`). Onze ferramentas do Congress.gov.
`src/mcp-server/resources/definitions/`	Definições de recursos. Recursos de congresso, projeto, membro e comitê.
`src/mcp-server/prompts/definitions/`	Definições de prompts. Prompts de análise de projetos e pesquisa legislativa.
`src/services/congress-api/`	Cliente da API do Congress.gov — autenticação, paginação, limites de taxa.
`src/config/`	Análise e validação de variáveis de ambiente específicas do servidor com Zod.
`tests/`	Testes unitários e de integração, espelhando a estrutura de `src/`.

Guia de desenvolvimento

Consulte CLAUDE.md para diretrizes de desenvolvimento e regras arquiteturais. A versão resumida:

Handlers lançam exceções, o framework captura — sem try/catch na lógica das ferramentas
Use ctx.log para logging, ctx.state para armazenamento
Todas as ferramentas são somente leitura com readOnlyHint: true e idempotentHint: true

Contribuindo

Issues e pull requests são bem-vindos. Execute verificações e testes antes de enviar:

bun run devcheck
bun run test

Licença

Este projeto é licenciado sob a Licença Apache 2.0. Consulte o arquivo LICENSE para detalhes.