Courtlistener ++ MCp Server

Servidor MCP CourtListener ++

Um servidor Model Context Protocol (MCP) que fornece acesso amigável a LLMs ao banco de dados jurídico CourtListener por meio da API oficial CourtListener v4, além de consulta de estatutos dos Estados Unidos por meio da API oficial GovInfo e busca de documentos de regulamentação federal por meio da API oficial Regulations.gov. Este servidor permite pesquisar e recuperar pareceres jurídicos, casos judiciais, juízes, documentos legais, estatutos federais promulgados e documentos de regulamentação federal para pesquisa jurídica precisa e verificação de citações.

🎯 Propósito

O Servidor MCP CourtListener ++ fornece acesso abrangente a dados de casos jurídicos, pareceres judiciais, estatutos federais e documentos de regulamentação federal por meio dos extensos bancos de dados CourtListener, GovInfo e Regulations.gov. O CourtListener contém milhões de pareceres jurídicos de tribunais federais e estaduais, o GovInfo fornece o Código dos Estados Unidos, Estatutos Gerais e Leis Públicas e Privadas, e o Regulations.gov indexa processos de regulamentação federal, regras propostas e regras finais.

📋 Principais Vantagens

• Banco de Dados Jurídico Abrangente:
  • Acesso a milhões de pareceres judiciais e decisões legais
  • Cobertura de tribunais federais e estaduais
  • Atualizações em tempo real dos sistemas judiciais
• Conteúdo de Texto Completo:
  • Texto completo de pareceres para verificação de citações
  • Organização estruturada de documentos legais
  • Metadados ricos incluindo juízes, tribunais e datas
• Pesquisa Estatutária:
  • Pesquisa em USC, Estatutos Gerais, Leis Públicas/Privadas e Compilações
  • Encontre seções, capítulos e subcapítulos da USC dentro de um título
  • Recupere resumos de pacotes de estatutos ou links de download XML/PDF/texto
• Pesquisa de Regulamentação Federal:
  • Pesquise documentos de regulamentação federal por palavra-chave, agência, tipo ou data de publicação
  • Recupere detalhes completos de documentos, opcionalmente com anexos
• Pesquisa Jurídica:
  • Pesquise por juiz, tribunal, nome do caso ou conteúdo
  • Verifique linguagem jurídica exata e precedentes
  • Valide citações e referências legais

🔑 Obtendo uma Chave de API CourtListener

Uma chave de API é obrigatória para acesso autenticado à API CourtListener. Embora alguns endpoints funcionem sem autenticação, você será severamente limitado em taxa (usuários anônimos são limitados rapidamente).

Por que Você Precisa de uma Chave de API

• Limites de Taxa Mais Altos: Usuários autenticados recebem 5.000 consultas por hora
• Acesso Completo à API: Alguns endpoints exigem autenticação
• Melhor Desempenho: Evite limitação anônima
• Rastreamento de Uso: Monitore seu uso da API no seu perfil

Como Obter Sua Chave de API

1. Crie uma Conta: Vá para Cadastro CourtListener e crie uma conta gratuita.

2. Entre: Faça login na sua conta em Login CourtListener.

3. Obtenha Seu Token: Navegue até Ajuda da API - REST enquanto estiver logado. Seu token de autorização será exibido nessa página.

4. Copie Seu Token: Seu token será algo como: abcd1234567890efghij1234567890abcd123456

5. Configure o Servidor: Adicione seu token ao seu arquivo .env:

   COURT_LISTENER_API_KEY=your-token-here
   

Formato de Autenticação do Token

Ao fazer solicitações à API, o token é enviado no cabeçalho HTTP Authorization:

Authorization: Token your-token-here

Importante: Não esqueça a palavra "Token" antes do valor real do seu token!

🏛️ Obtendo uma Chave de API GovInfo

As ferramentas de consulta de estatutos (statutes_*) usam a API GovInfo do Escritório de Publicações do Governo dos EUA e exigem um GOVINFO_API_KEY.

1. Obtenha uma chave gratuita: Cadastre-se em api.data.gov — a mesma chave funciona para api.govinfo.gov.

2. Configure o Servidor: Adicione a chave ao seu arquivo .env:

   GOVINFO_API_KEY=your-api-data-gov-key-here
   

As solicitações GovInfo autenticam com um cabeçalho HTTP X-Api-Key. Se GOVINFO_API_KEY estiver ausente na inicialização, o servidor registra um aviso e desativa automaticamente todas as ferramentas que o exigem — as ferramentas statutes_* ficam ocultas dos clientes até que a chave seja definida e o servidor seja reiniciado. O mesmo comportamento de inicialização se aplica a COURT_LISTENER_API_KEY e às ferramentas search_*, get_* e citation_*. Como fallback, chamar uma ferramenta que exige chave sem ela ainda gera um erro solicitando que a chave seja definida.

A ferramenta status informa quais grupos de ferramentas estão ativos em tools_available e quais estão desativados (com a chave ausente) em tools_disabled.

📜 Obtendo uma Chave de API Regulations.gov

As ferramentas de regulamentação federal (regulations_*) usam a API oficial Regulations.gov e exigem um REGULATIONS_API_KEY.

1. Obtenha uma chave gratuita: Cadastre-se em api.data.gov — a mesma chave funciona para api.regulations.gov.

2. Configure o Servidor: Adicione a chave ao seu arquivo .env:

   REGULATIONS_API_KEY=your-api-data-gov-key-here
   

As solicitações Regulations.gov autenticam com um cabeçalho HTTP X-Api-Key. O mesmo comportamento automático de inicialização se aplica: se REGULATIONS_API_KEY estiver ausente, as ferramentas regulations_* são desativadas e ocultadas dos clientes até que a chave seja definida e o servidor seja reiniciado.

Nota: a API Regulations.gov rejeita valores de page[size] abaixo de 5, então regulations_search_documents aplica um tamanho de página entre 5 e 250.

⚙️ Tarefas em Segundo Plano (Extensão de Tarefas MCP)

O servidor registra a extensão de tarefas em segundo plano do MCP (SEP-2663). Ferramentas de longa duração — citation_batch_lookup, citation_batch_lookup_citations e statutes_get_statute_content — são marcadas como task=True, para que clientes que optem pela capacidade de tarefas possam executá-las em segundo plano com sondagem de progresso em vez de bloqueio. Chamadas de clientes comuns ainda são executadas de forma síncrona, então nada muda para integrações existentes. O FastMCP usa um backend de tarefas em memória por padrão; defina FASTMCP_DOCKET_URL (por exemplo, redis://localhost:6379/0) para uma implantação persistente e horizontalmente escalável.

🐳 Início Rápido com Docker (Recomendado)

A maneira mais rápida de começar é com Docker. Imagens pré-construídas estão disponíveis em vários registros.

Baixe a Imagem

# From Docker Hub
docker pull vesha/court-listener-mcp:latest

# From GitHub Container Registry
docker pull ghcr.io/travis-prall/court-listener-mcp:latest

Execute com Docker

# Quick start (minimal configuration)
docker run -d \
  --name court-listener-mcp \
  -p 8785:8785 \
  -e COURT_LISTENER_API_KEY=your-api-key-here \
  vesha/court-listener-mcp:latest

# With all configuration options
docker run -d \
  --name court-listener-mcp \
  -p 8785:8785 \
  -e COURT_LISTENER_API_KEY=your-api-key-here \
  -e COURTLISTENER_BASE_URL=https://www.courtlistener.com/api/rest/v4/ \
  -e COURTLISTENER_TIMEOUT=30 \
  -e COURTLISTENER_LOG_LEVEL=INFO \
  -e ENVIRONMENT=production \
  vesha/court-listener-mcp:latest

Execute com Docker Compose

1. Crie um arquivo .env no diretório do seu projeto:

   # Required: Your CourtListener API Key
   COURT_LISTENER_API_KEY=your-api-key-here
   
   # Required for statute lookup: Your GovInfo (api.data.gov) API Key
   GOVINFO_API_KEY=your-govinfo-api-key-here
   
   # Optional: Regulations.gov federal rulemaking tools (auto-disabled if missing)
   REGULATIONS_API_KEY=your-api-data-gov-key-here
   
   # Optional: Override defaults
   COURTLISTENER_LOG_LEVEL=INFO
   ENVIRONMENT=production
   

2. Crie um docker-compose.yml (ou use o existente neste repositório):

   services:
     court-listener-mcp:
       image: vesha/court-listener-mcp:latest
       container_name: court-listener-mcp-server
       ports:
         - "8785:8785"
       env_file:
         - .env
       environment:
         - LOG_LEVEL=INFO
         - API_BASE_URL=https://www.courtlistener.com/api/rest/v4
       restart: unless-stopped
   

3. Inicie o servidor:

   docker-compose up -d
   

4. Veja os logs:

   docker-compose logs -f
   

5. Pare o servidor:

   docker-compose down
   

Construa Sua Própria Imagem

Se preferir construir a imagem localmente:

# Clone the repository
git clone https://github.com/Travis-Prall/court-listener-mcp.git
cd court-listener-mcp

# Build the image
docker build -t court-listener-mcp:latest .

# Run your local build
docker run -d \
  --name court-listener-mcp \
  -p 8785:8785 \
  -e COURT_LISTENER_API_KEY=your-api-key-here \
  court-listener-mcp:latest

Conectando-se ao Contêiner Docker

Uma vez em execução, o servidor MCP está disponível em:

• URL: http://localhost:8785/mcp/
• Protocolo: HTTP Streamable (FastMCP)

Exemplo de conexão de cliente:

from fastmcp import Client

async with Client("http://localhost:8785/mcp/") as client:
    # Check server status
    result = await client.call_tool("status")
    print(result)

    # Search for legal opinions
    result = await client.call_tool(
        "search_opinions", {"query": "first amendment", "court": "scotus"}
    )
    print(result)

Verificações de Saúde

O servidor expõe um endpoint de vivacidade não autenticado para balanceadores de carga, sistemas de monitoramento e orquestradores de contêineres:

curl http://localhost:8785/health
# {"status":"healthy","service":"CourtListener ++ MCP Server","version":"0.2.1",...}

A imagem Docker inclui um HEALTHCHECK contra este endpoint e o docker-compose.yml fornecido o espelha, então docker ps e docker compose ps relatam a saúde do contêiner automaticamente.

Notas de Implantação HTTP

Seguindo o guia de implantação HTTP do FastMCP, o servidor usa a abordagem de servidor HTTP direto (mcp.run_async(transport="http")), que o guia recomenda para implantações autônomas de instância única. Para implantações maiores, opções opcionais (todas configuráveis por ambiente):

• Escalonamento horizontal: defina FASTMCP_STATELESS_HTTP=true ao executar múltiplas réplicas atrás de um balanceador de carga (sessões HTTP streamable são por instância, e sessões adesivas não são confiáveis para clientes MCP). Combine com FASTMCP_DOCKET_URL para que o backend de tarefas seja compartilhado.
• Proteção de host/origem: defina FASTMCP_HTTP_HOST_ORIGIN_PROTECTION=true com listas de permissão explícitas (FASTMCP_HTTP_ALLOWED_HOSTS, FASTMCP_HTTP_ALLOWED_ORIGINS) ao expor um nome de host público.
• Ferramentas de longa duração atrás de proxies: para ferramentas que podem exceder tempos limite de proxy, o guia recomenda um EventStore para sondagem SSE; e ao usar nginx na frente, defina proxy_buffering off além de proxy_read_timeout generoso (300s+) para que respostas de streaming cheguem aos clientes.

🛠️ Ferramentas MCP Disponíveis

O Servidor MCP CourtListener ++ fornece estas ferramentas prontas para produção (veja app/README.md para detalhes completos e parâmetros):

• Pesquisa de Pareceres e Casos:
  • search_opinions — Pesquise pareceres jurídicos e decisões judiciais
  • search_dockets — Pesquise casos judiciais e dossiês
  • search_dockets_with_documents — Pesquise dossiês com documentos aninhados
  • search_recap_documents — Pesquise documentos de arquivamento RECAP
  • search_audio — Pesquise áudio de argumentos orais
  • search_people — Pesquise juízes e profissionais jurídicos
• Recuperação de Entidades:
  • get_opinion, get_docket, get_audio, get_court, get_person, get_cluster
• Ferramentas de Citação (API CourtListener + citeurl):
  • citation_lookup_citation — Encontre o parecer ao qual uma citação se refere (chave de API obrigatória)
  • citation_batch_lookup_citations — Consulte múltiplas citações em uma única solicitação (chave de API obrigatória)
  • citation_batch_lookup — Consulta em lote de citações com detalhes (chave de API obrigatória)
  • citation_get_citations — Consulte citações encontradas em um bloco de texto (chave de API obrigatória)
  • citation_get_citation_details — Informações detalhadas para um ID de citação (chave de API obrigatória)
  • citation_enhanced_citation_lookup — Análise citeurl combinada com dados CourtListener (chave de API opcional)
  • citation_parse_citation / citation_parse_citation_with_citeurl — Analise citações offline com citeurl
  • citation_validate_citation / citation_verify_citation_format — Valide formato de citação offline
  • citation_extract_citations_from_text — Extraia todas as citações de um bloco de texto (offline)
• Ferramentas de Estatutos (API GovInfo — GOVINFO_API_KEY obrigatório):
  • statutes_search_statutes — Pesquise em USC, Estatutos Gerais, Leis Públicas/Privadas e Compilações
  • statutes_get_uscode_title — Encontre seções, capítulos e subcapítulos da USC dentro de um título
  • statutes_get_statute_content — Recupere resumos de pacotes/grânulos ou links de download XML/PDF/texto
  • statutes_list_statute_collections — Liste coleções de estatutos disponíveis (sem chamada de API)
• Ferramentas Regulations.gov (Regulamentação Federal — REGULATIONS_API_KEY obrigatório):
  • regulations_search_documents — Pesquise documentos de regulamentação federal por palavra-chave, agência, tipo ou data de publicação
  • regulations_get_document — Obtenha detalhes completos do documento, opcionalmente com anexos

Veja app/README.md para uma referência completa de todas as ferramentas, parâmetros e exemplos de uso.

📦 Instalação Local (Alternativa)

Se preferir executar sem Docker:

Pré-requisitos

• Python 3.14+
• uv para gerenciamento de dependências
• Conexão com a internet para acesso à API CourtListener

Instale com uv

# Clone the repository
git clone https://github.com/Travis-Prall/court-listener-mcp.git
cd court-listener-mcp

# Install dependencies
uv sync

# Activate the environment (optional)
uv shell

Configuração de Ambiente

Crie um arquivo .env na raiz do projeto (veja example.env para todas as opções):

# Required
COURT_LISTENER_API_KEY=your-api-key-here

# Required for statute lookup tools
GOVINFO_API_KEY=your-api-data-gov-key-here

# Optional: Regulations.gov federal rulemaking tools (auto-disabled if missing)
REGULATIONS_API_KEY=your-api-data-gov-key-here

# Optional (defaults shown)
COURTLISTENER_BASE_URL=https://www.courtlistener.com/api/rest/v4/
COURTLISTENER_TIMEOUT=30
COURTLISTENER_LOG_LEVEL=INFO
COURTLISTENER_DEBUG=false
HOST=0.0.0.0
MCP_PORT=8785
ENVIRONMENT=production

Executando o Servidor

uv run python -m app.server

Isso iniciará o servidor em:

• Host: 0.0.0.0 (acessível de conexões externas)
• Porta: 8785
• Endpoint: http://localhost:8785/mcp/

Ou use a tarefa do VS Code: Executar Servidor MCP

💡 Exemplos de Uso

Veja app/README.md para uso detalhado das ferramentas e exemplos, incluindo consultas de pesquisa, citação, estatutos e regulamentações.

🧪 Testes

uv run pytest
uv run pytest --cov=app --cov-report=term-missing

Veja tests/README.md para detalhes da suíte de testes, cobertura e solução de problemas.

🔧 Desenvolvimento

uv run ruff format .
uv run ruff check .
uv run mypy app/
uv run pip-audit

🚨 Solução de Problemas

Problemas Comuns

Erros de "não autorizado" ou "limitado":

• Certifique-se de que sua chave de API está definida corretamente em .env
• Verifique se você está usando autenticação Token (não apenas o token bruto)
• Verifique seu uso da API no seu perfil CourtListener

O contêiner não inicia:

• Verifique os logs: docker logs court-listener-mcp
• Verifique se o arquivo .env existe e é legível
• Certifique-se de que a porta 8785 não está em uso

Conexão recusada:

• Aguarde alguns segundos para o servidor iniciar
• Verifique se o contêiner está em execução: docker ps
• Verifique o mapeamento de porta correto

Veja app/README.md e tests/README.md para solução de problemas adicional.

📚 Documentação

• Documentação do Código Fonte
• Documentação de Testes
• Documentação da API do CourtListener
• Ajuda da API do CourtListener
• Documentação da API do GovInfo
• Framework FastMCP
• Protocolo de Contexto do Modelo

🐳 Registros de Imagens Docker

Imagens pré-construídas estão disponíveis em:

Registro	Imagem
Docker Hub	vesha/court-listener-mcp:latest
GitHub Container Registry	ghcr.io/travis-prall/court-listener-mcp:latest
Registro Privado	docker.vesha.net/court-listener-mcp:latest

As imagens são publicadas no GitHub Container Registry automaticamente por GitHub Actions a cada push para main e em tags de versão v*. Builds multi-arquitetura (linux/amd64 e linux/arm64) são suportados. O Docker Hub e o registro privado docker.vesha.net são publicados manualmente com a mesma imagem multi-arquitetura (docker buildx build --platform linux/amd64,linux/arm64), e as tags versionadas seguem as convenções X.Y.Z + latest + git-short-SHA.

⚖️ Licença

Este projeto está licenciado sob a Licença Não Comercial PolyForm. Você é livre para usar, modificar e hospedar este servidor MCP para pesquisa jurídica pessoal, acadêmica ou não comercial.

A integração em um produto comercial, serviço hospedado ou aplicativo pago é estritamente proibida sem permissão explícita.

💖 Suporte

Se você achar este projeto útil, considere apoiar seu mantenedor. É completamente opcional, mas sempre apreciado:

Prefere criptomoedas? Veja DONATE.md para endereços de doação.

---

Pronto para usar! O CourtListener ++ MCP Server fornece acesso pronto para produção a dados jurídicos, estatutos federais e documentos de regulamentação federal por meio de 30 ferramentas abrangentes do MCP.