Courtlistener ++ MCp Server

proporciona acceso integral a datos de casos legales, opiniones judiciales, estatutos federales y documentos de elaboración de normas federales

GitHub
12
Prueba este MCPPatrocinado

Documentación

Servidor MCP CourtListener ++

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona acceso amigable para LLM a la base de datos legal de CourtListener a través de la API oficial de CourtListener v4, además de la búsqueda de estatutos de los Estados Unidos a través de la API oficial de GovInfo y la búsqueda de documentos de elaboración de reglas federales a través de la API oficial de Regulations.gov. Este servidor permite buscar y recuperar opiniones legales, casos judiciales, jueces, documentos legales, estatutos federales promulgados y documentos de elaboración de reglas federales para investigación legal precisa y verificación de citas.

🎯 Propósito

El Servidor MCP CourtListener ++ proporciona acceso integral a datos de casos legales, opiniones judiciales, estatutos federales y documentos de elaboración de reglas federales a través de las extensas bases de datos de CourtListener, GovInfo y Regulations.gov. CourtListener contiene millones de opiniones legales de tribunales federales y estatales, GovInfo proporciona el Código de los Estados Unidos, Statutes at Large y Leyes Públicas y Privadas, y Regulations.gov indexa expedientes de elaboración de reglas federales, reglas propuestas y reglas finales.

📋 Ventajas Clave

  • Base de Datos Legal Integral:
    • Acceso a millones de opiniones judiciales y decisiones legales
    • Cobertura de tribunales federales y estatales
    • Actualizaciones en tiempo real de los sistemas judiciales
  • Contenido de Texto Completo:
    • Texto completo de opiniones para verificación de citas
    • Organización estructurada de documentos legales
    • Metadatos enriquecidos que incluyen jueces, tribunales y fechas
  • Investigación Estatutaria:
    • Búsqueda en USC, Statutes at Large, Leyes Públicas/Privadas y Compilaciones
    • Encuentre secciones, capítulos y subcapítulos de USC dentro de un título
    • Recupere resúmenes de paquetes de estatutos o enlaces de descarga XML/PDF/texto
  • Investigación de Elaboración de Reglas Federales:
    • Busque documentos de elaboración de reglas federales por palabra clave, agencia, tipo o fecha de publicación
    • Recupere detalles completos de documentos, opcionalmente con archivos adjuntos
  • Investigación Legal:
    • Búsqueda por juez, tribunal, nombre de caso o contenido
    • Verifique el lenguaje legal exacto y los precedentes
    • Valide citas y referencias legales

🔑 Obtención de una Clave de API de CourtListener

Se requiere una clave de API para el acceso autenticado a la API de CourtListener. Aunque algunos endpoints funcionan sin autenticación, se le limitará severamente la tasa (los usuarios anónimos son limitados rápidamente).

Por Qué Necesita una Clave de API

  • Límites de Tasa Más Altos: Los usuarios autenticados obtienen 5,000 consultas por hora
  • Acceso Completo a la API: Algunos endpoints requieren autenticación
  • Mejor Rendimiento: Evite la limitación anónima
  • Seguimiento de Uso: Monitoree su uso de la API en su perfil

Cómo Obtener su Clave de API

  1. Cree una Cuenta: Vaya a Registro de CourtListener y cree una cuenta gratuita.

  2. Inicie Sesión: Acceda a su cuenta en Inicio de Sesión de CourtListener.

  3. Obtenga su Token: Navegue a Ayuda de API - REST mientras está conectado. Su token de autorización se mostrará en esa página.

  4. Copie su Token: Su token se verá algo así como: abcd1234567890efghij1234567890abcd123456

  5. Configure el Servidor: Agregue su token a su archivo .env:

    COURT_LISTENER_API_KEY=your-token-here

Formato de Autenticación de Token

Al realizar solicitudes a la API, el token se envía en el encabezado HTTP Authorization:

Authorization: Token your-token-here

Importante: ¡No olvide la palabra "Token" antes del valor real de su token!

🏛️ Obtención de una Clave de API de GovInfo

Las herramientas de búsqueda de estatutos (statutes_*) utilizan la API de GovInfo de la Oficina de Publicaciones del Gobierno de los EE. UU. y requieren una GOVINFO_API_KEY.

  1. Obtenga una clave gratuita: Regístrese en api.data.gov — la misma clave funciona para api.govinfo.gov.

  2. Configure el Servidor: Agregue la clave a su archivo .env:

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

Las solicitudes de GovInfo se autentican con un encabezado HTTP X-Api-Key. Si GOVINFO_API_KEY falta al inicio, el servidor registra una advertencia y deshabilita automáticamente cada herramienta que lo requiere — las herramientas statutes_* están ocultas para los clientes hasta que la clave se establezca y el servidor se reinicie. El mismo comportamiento de inicio se aplica a COURT_LISTENER_API_KEY y las herramientas search_*, get_* y citation_*. Como respaldo, llamar a una herramienta que requiere clave sin su clave aún genera un error solicitando que se establezca la clave.

La herramienta status informa qué grupos de herramientas están activos bajo tools_available y cuáles están deshabilitados (con la clave faltante) bajo tools_disabled.

📜 Obtención de una Clave de API de Regulations.gov

Las herramientas de elaboración de reglas federales (regulations_*) utilizan la API oficial de Regulations.gov y requieren una REGULATIONS_API_KEY.

  1. Obtenga una clave gratuita: Regístrese en api.data.gov — la misma clave funciona para api.regulations.gov.

  2. Configure el Servidor: Agregue la clave a su archivo .env:

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

Las solicitudes de Regulations.gov se autentican con un encabezado HTTP X-Api-Key. Se aplica el mismo comportamiento automático de inicio: si REGULATIONS_API_KEY falta, las herramientas regulations_* se deshabilitan y ocultan de los clientes hasta que la clave se establezca y el servidor se reinicie.

Nota: la API de Regulations.gov rechaza valores de page[size] inferiores a 5, por lo que regulations_search_documents aplica un tamaño de página entre 5 y 250.

⚙️ Tareas en Segundo Plano (Extensión de Tareas MCP)

El servidor registra la extensión de tareas en segundo plano de MCP (SEP-2663). Las herramientas de larga duración — citation_batch_lookup, citation_batch_lookup_citations y statutes_get_statute_content — están marcadas como task=True, por lo que los clientes que optan por la capacidad de tareas pueden ejecutarlas en segundo plano con sondeo de progreso en lugar de bloqueo. Las llamadas de clientes ordinarios aún se ejecutan sincrónicamente, por lo que nada cambia para las integraciones existentes. FastMCP utiliza un backend de tareas en memoria por defecto; establezca FASTMCP_DOCKET_URL (por ejemplo, redis://localhost:6379/0) para una implementación persistente y horizontalmente escalable.

🐳 Inicio Rápido con Docker (Recomendado)

La forma más rápida de comenzar es con Docker. Las imágenes preconstruidas están disponibles en múltiples registros.

Descargar la Imagen

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

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

Ejecutar con 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

Ejecutar con Docker Compose

  1. Cree un archivo .env en el directorio de su proyecto:

    # 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. Cree un docker-compose.yml (o use el que está en este repositorio):

    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 el servidor:

    docker-compose up -d

  4. Vea los registros:

    docker-compose logs -f

  5. Detenga el servidor:

    docker-compose down

Construya su Propia Imagen

Si prefiere construir la imagen 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

Conexión al Contenedor Docker

Una vez en ejecución, el servidor MCP está disponible en:

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

Ejemplo de conexión 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)

Verificaciones de Salud

El servidor expone un endpoint de actividad sin autenticación para balanceadores de carga, sistemas de monitoreo y orquestadores de contenedores:

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

La imagen Docker incluye un HEALTHCHECK contra este endpoint y el docker-compose.yml proporcionado lo refleja, por lo que docker ps y docker compose ps informan la salud del contenedor automáticamente.

Notas de Implementación HTTP

Siguiendo la guía de implementación HTTP de FastMCP, el servidor utiliza el enfoque de servidor HTTP directo (mcp.run_async(transport="http")), que la guía recomienda para implementaciones independientes de instancia única. Para implementaciones más grandes, hay opciones opcionales (todas configurables por entorno):

  • Escalado horizontal: establezca FASTMCP_STATELESS_HTTP=true al ejecutar múltiples réplicas detrás de un balanceador de carga (las sesiones HTTP transmisibles son por instancia y las sesiones fijas no son confiables para clientes MCP). Combine con FASTMCP_DOCKET_URL para que el backend de tareas sea compartido.
  • Protección de host/origen: establezca FASTMCP_HTTP_HOST_ORIGIN_PROTECTION=true con listas de permitidos explícitas (FASTMCP_HTTP_ALLOWED_HOSTS, FASTMCP_HTTP_ALLOWED_ORIGINS) al exponer un nombre de host público.
  • Herramientas de larga duración detrás de proxies: para herramientas que pueden exceder los tiempos de espera del proxy, la guía recomienda un EventStore para sondeo SSE; y al usar nginx como frontend, establezca proxy_buffering off más un proxy_read_timeout generoso (300s+) para que las respuestas de transmisión lleguen a los clientes.

🛠️ Herramientas MCP Disponibles

El Servidor MCP CourtListener ++ proporciona estas herramientas listas para producción (consulte app/README.md para detalles completos y parámetros):

  • Búsqueda de Opiniones y Casos:
    • search_opinions — Busque opiniones legales y decisiones judiciales
    • search_dockets — Busque casos judiciales y expedientes
    • search_dockets_with_documents — Busque expedientes con documentos anidados
    • search_recap_documents — Busque documentos de presentación RECAP
    • search_audio — Busque audio de argumentos orales
    • search_people — Busque jueces y profesionales legales
  • Recuperación de Entidades:
    • get_opinion, get_docket, get_audio, get_court, get_person, get_cluster
  • Herramientas de Citas (API de CourtListener + citeurl):
    • citation_lookup_citation — Encuentre la opinión a la que referencia una cita (se requiere clave de API)
    • citation_batch_lookup_citations — Consulte múltiples citas en una sola solicitud (se requiere clave de API)
    • citation_batch_lookup — Consulta de citas por lotes con detalles (se requiere clave de API)
    • citation_get_citations — Consulte citas encontradas en un bloque de texto (se requiere clave de API)
    • citation_get_citation_details — Información detallada para un ID de cita (se requiere clave de API)
    • citation_enhanced_citation_lookup — Análisis de Citeurl combinado con datos de CourtListener (clave de API opcional)
    • citation_parse_citation / citation_parse_citation_with_citeurl — Analice citas sin conexión con citeurl
    • citation_validate_citation / citation_verify_citation_format — Valide el formato de citas sin conexión
    • citation_extract_citations_from_text — Extraiga todas las citas de un bloque de texto (sin conexión)
  • Herramientas de Estatutos (API de GovInfo — se requiere GOVINFO_API_KEY):
    • statutes_search_statutes — Busque en USC, Statutes at Large, Leyes Públicas/Privadas y Compilaciones
    • statutes_get_uscode_title — Encuentre secciones, capítulos y subcapítulos de USC dentro de un título
    • statutes_get_statute_content — Recupere resúmenes de paquetes/gránulos o enlaces de descarga XML/PDF/texto
    • statutes_list_statute_collections — Liste las colecciones de estatutos disponibles (sin llamada a la API)
  • Herramientas de Regulations.gov (Elaboración de Reglas Federales — se requiere REGULATIONS_API_KEY):
    • regulations_search_documents — Busque documentos de elaboración de reglas federales por palabra clave, agencia, tipo o fecha de publicación
    • regulations_get_document — Obtenga detalles completos de documentos, opcionalmente con archivos adjuntos

Consulte app/README.md para una referencia completa de todas las herramientas, parámetros y ejemplos de uso.

📦 Instalación Local (Alternativa)

Si prefiere ejecutar sin Docker:

Requisitos Previos

  • Python 3.14+
  • uv para gestión de dependencias
  • Conexión a Internet para acceso a la API de CourtListener

Instalar con 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

Configuración del Entorno

Cree un archivo .env en la raíz del proyecto (consulte example.env para todas las opciones):

# 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

Ejecutar el Servidor

uv run python -m app.server

Esto iniciará el servidor en:

  • Host: 0.0.0.0 (accesible desde conexiones externas)
  • Puerto: 8785
  • Endpoint: http://localhost:8785/mcp/

O use la tarea de VS Code: Ejecutar Servidor MCP

💡 Ejemplos de Uso

Consulte app/README.md para uso detallado de herramientas y ejemplos, incluyendo consultas de búsqueda, citas, estatutos y regulaciones.

🧪 Pruebas

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

Consulte tests/README.md para detalles del conjunto de pruebas, cobertura y solución de problemas.

🔧 Desarrollo

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

🚨 Solución de Problemas

Problemas Comunes

Errores de "no autorizado" o "limitado":

  • Asegúrese de que su clave de API esté configurada correctamente en .env
  • Verifique que está usando autenticación de Token (no solo el token crudo)
  • Consulte su uso de API en su perfil de CourtListener

El contenedor no se inicia:

  • Consulte los registros: docker logs court-listener-mcp
  • Verifique que el archivo .env exista y sea legible
  • Asegúrese de que el puerto 8785 no esté ya en uso

Conexión rechazada:

  • Espere unos segundos para que el servidor se inicie
  • Verifique que el contenedor esté en ejecución: docker ps
  • Compruebe la asignación de puertos correcta

Consulte app/README.md y tests/README.md para solución de problemas adicional.

📚 Documentación

🐳 Registros de Imágenes Docker

Las imágenes precompiladas están disponibles en:

RegistroImagen
Docker Hubvesha/court-listener-mcp:latest
Registro de Contenedores de GitHubghcr.io/travis-prall/court-listener-mcp:latest
Registro Privadodocker.vesha.net/court-listener-mcp:latest

Las imágenes se publican automáticamente en el Registro de Contenedores de GitHub mediante GitHub Actions en cada push a main y en etiquetas de versión v*. Se admiten compilaciones multi-arquitectura (linux/amd64 y linux/arm64). Docker Hub y el registro privado docker.vesha.net se publican manualmente con la misma imagen multi-arquitectura (docker buildx build --platform linux/amd64,linux/arm64), y las etiquetas versionadas siguen las convenciones de X.Y.Z + latest + git-short-SHA.

⚖️ Licencia

Este proyecto está licenciado bajo la Licencia No Comercial PolyForm. Eres libre de usar, modificar y autoalojar este servidor MCP para investigación legal personal, académica o no comercial.

La integración en un producto comercial, servicio alojado o aplicación de pago está estrictamente prohibida sin permiso explícito.

💖 Soporte

Si encuentras útil este proyecto, considera apoyar a su mantenedor. Es completamente opcional, pero siempre se agradece:

Buy travisprall a coffee

¿Prefieres criptomonedas? Consulta DONATE.md para direcciones de donación.

¡Listo para usar! El servidor MCP CourtListener ++ proporciona acceso de nivel de producción a datos legales, estatutos federales y documentos de reglamentación federal a través de 30 herramientas integrales de MCP.