MCP-CENDOJ

Sobre o servidor MCP para o CENDOJ 🇪🇸 — Acesso automatizado a decisões judiciais da Espanha, filtros avançados de jurisprudência e leitura de sentenças por meio do Model Context Protocol e API REST

GitHub
13

Documentação

MCP-CENDOJ: Servidor MCP e API para o Buscador de Jurisprudência

MCP-CENDOJ

Este projeto fornece uma API REST (FastAPI) e um Servidor MCP (Model Context Protocol) para buscar e consultar sentenças e resoluções judiciais do CENDOJ (Centro de Documentação Judicial da Espanha).

Como o CENDOJ não dispõe de uma API pública e protege suas buscas com JavaScript interativo e validações de autocompletar, este serviço utiliza Playwright para simular buscas reais de forma automatizada e robusta, retornando resultados limpos em formato JSON e abstraindo o download e a extração de texto dos PDFs de sentenças.

Características

  • Buscador Automatizado (Playwright): Automatiza a navegação, a aceitação do Aviso Legal, a simulação de digitação sequencial para ativar o buscador e a seleção da sugestão do CENDOJ para evitar as limitações de busca.
  • API REST com FastAPI:
    • GET /api/status: Verifica a saúde e a configuração do serviço.
    • GET /api/search: Realiza buscas avançadas com parâmetros:
      • query: Texto livre opcional.
      • fecha_desde / fecha_hasta: Intervalo de datas (AAAA-MM-DD ou DD/MM/AAAA).
      • jurisdiccion: Civil, Penal, Contencioso-Administrativo, Social, Militar.
      • roj: Identificador ROJ (ex.: STS 2849/2026).
      • ecli: Código ECLI (ex.: ES:TS:2026:2849).
      • n_resolucion: Número da resolução.
      • n_recurso: Número do recurso.
      • ponente: Nome do magistrado relator.
      • norma: Legislação ou norma de interesse.
      • localizacion: Lista de localizações ou Comunidades Autônomas (ex.: Andalucía, Cataluña, Madrid).
    • GET /api/decision: Resolve o contêiner de documentos do CENDOJ, baixa o arquivo PDF e extrai seu texto simples em espanhol.
  • Servidor MCP (Model Context Protocol):
    • Suporte para modo Stdio (para clientes locais de desktop, como Cursor e Claude Desktop).
    • Suporte para modo SSE (Server-Sent Events) montado de forma nativa no FastAPI sob o prefixo /mcp (para clientes remotos ou web).
    • Ferramentas expostas:
      • buscar_jurisprudencia: Realiza buscas com todos os filtros detalhados (query, roj, ecli, relator, recurso, resolução, norma, etc.).
      • obtener_texto_resolucion: Baixa um PDF e extrai seu texto completo.
  • Compatibilidade com Windows: Corrigido para evitar problemas com a política do loop de eventos (NotImplementedError em subprocess) em ambientes Windows.

Pré-requisitos

  • Python 3.10 ou superior instalado.
  • Navegador Chromium do Playwright instalado no sistema.

Instalação e Configuração (Rápida)

Para facilitar a configuração no Windows, incluímos scripts que automatizam todo o processo:

  1. Executar configuração automática: Clique duas vezes no arquivo setup.bat (ou execute-o no seu terminal). Este script será responsável por:

    • Criar o ambiente virtual .venv.
    • Instalar e atualizar todas as dependências (requirements.txt).
    • Instalar o navegador Chromium exigido pelo Playwright.
    • Criar o arquivo de configuração .env padrão.

  2. Registrar em Clientes MCP (Automático): Após a conclusão da configuração, execute o utilitário de instalação automática para vincular o servidor MCP aos seus clientes locais:

    .venv\Scripts\python.exe install_mcp.py

    Este comando detectará o caminho absoluto do seu repositório e registrará automaticamente o servidor CENDOJ nas configurações globais de:

    • Claude Desktop (claude_desktop_config.json)
    • Antigravity IDE (mcp_config.json)

Instalação e Configuração Manual (Alternativa)

Se você não deseja usar os scripts de automação, pode inicializar o projeto manualmente seguindo estes passos:

  1. Criar o ambiente virtual Python:

    python -m venv .venv

  2. Ativar o ambiente virtual:

    • No Windows (PowerShell): 
      .venv\Scripts\Activate.ps1
    • No macOS/Linux ou Git Bash: 
      source .venv/bin/activate

  3. Instalar dependências:

    pip install --upgrade pip
pip install -r requirements.txt

  4. Instalar o navegador Chromium para Playwright:

    playwright install chromium

  5. Criar o arquivo de configuração .env: Crie um arquivo chamado .env na raiz do projeto e escreva a seguinte linha:

    CENDOJ_HEADLESS=true

Guia de Execução

O script run.py é o ponto de entrada unificado:

1. Executar como API REST e Servidor SSE (FastAPI)

Para iniciar o servidor web:

.venv\Scripts\python.exe run.py api

O servidor será iniciado em http://localhost:8000.

2. Executar como Servidor MCP Stdio (Console/Entrada Padrão)

Para iniciar o servidor MCP usando entrada e saída padrão (ideal para integrar em ferramentas de desktop locais):

.venv\Scripts\python.exe run.py mcp

Integração Manual com Clientes MCP (Opcional)

Se você preferir fazer o registro manualmente em vez de usar install_mcp.py:

Claude Desktop

Para conectar este servidor MCP ao Claude Desktop, edite seu arquivo de configuração claude_desktop_config.json (geralmente em %APPDATA%\Claude\claude_desktop_config.json no Windows) e adicione a configuração do servidor:

{
  "mcpServers": {
    "cendoj-jurisprudencia": {
      "command": "c:/workspace-github/MCP-CENDOJ/.venv/Scripts/python.exe",
      "args": ["c:/workspace-github/MCP-CENDOJ/run.py", "mcp"],
      "env": {
        "CENDOJ_HEADLESS": "true"
      }
    }
  }
}

Cursor

Para usar o servidor no Cursor:

  1. Vá para Settings > Features > MCP.
  2. Clique em + Add New MCP Server.
  3. Configure os seguintes valores:
    • Name: CENDOJ
    • Type: command
    • Command: c:/workspace-github/MCP-CENDOJ/.venv/Scripts/python.exe c:/workspace-github/MCP-CENDOJ/run.py mcp

Guia de Prompts em Linguagem Natural (CENDOJ MCP)

Este guia mostra como você pode falar com o assistente em linguagem natural e conversacional (como se estivesse falando com um colega ou advogado), e como a IA se encarrega de traduzir seu pedido em consultas técnicas para o buscador do CENDOJ.

💬 Exemplos Práticos de Interação Conversacional

  1. Consultar dúvidas sobre acidentes em situações modernas

    • Seu prompt em linguagem natural: "Ei, me busca casos de teletrabalhadores que tropeçaram na própria cozinha durante o horário de trabalho e se os tribunais aceitaram isso como acidente de trabalho."
    • Como a IA processa nos bastidores: Busca termos como "accidente de trabajo", "teletrabajo", "cocina" ou "domicilio" na jurisdição social, baixa os textos das sentenças e analisa os fatos comprovados.
    • Resposta que você recebe: Um resumo de se os tribunais consideram a cozinha como "local de trabalho" durante a jornada e quais requisitos exigem.

  2. Investigar decisões em uma área geográfica específica

    • Seu prompt em linguagem natural: "Preciso ver sentenças recentes daqui de Valladolid sobre demissões disciplinares de funcionários que dormiram durante o turno de vigilância."
    • Como a IA processa nos bastidores: Filtra pela sede de Valladolid (localizacion: ["Valladolid"]), busca os termos "despido disciplinario" e "quedarse dormido" ou "vigilante" na jurisdição social, ordenando por data recente.
    • Resposta que você recebe: A lista das últimas sentenças proferidas pelo TSJ de Castela e Leão em Valladolid sobre esse tema e se as demissões foram declaradas procedentes ou improcedentes.

  3. Analisar a doutrina do Tribunal Supremo sobre temas familiares

    • Seu prompt em linguagem natural: "Me diga o que diz o Tribunal Supremo sobre se pais separados são obrigados a continuar pagando a faculdade de filhos maiores de 25 anos que não mostram muito interesse em estudar."
    • Como a IA processa nos bastidores: Filtra pela jurisdição civil e localização Madri (onde fica o TS), buscando "pensión de alimentos", "hijos mayores de edad", "estudios", "aprovechamiento".
    • Resposta que você recebe: Uma explicação do critério de "falta de aproveitamento acadêmico" e a idade limite segundo a jurisprudência do Tribunal Supremo.

  4. Reclamações contra administrações locais

    • Seu prompt em linguagem natural: "Quero reclamar da prefeitura porque coloquei o pé em um buraco na calçada enquanto corria. Existem sentenças em Castela e Leão em que condenaram a prefeitura por isso ou costumam culpar o pedestre?"
    • Como a IA processa nos bastidores: Busca na ordem Contencioso-Administrativo da região por "responsabilidad patrimonial", "caída peatón", "socavón" ou "bache", analisando a concorrência de culpas.
    • Resposta que você recebe: Uma análise da probabilidade de sucesso com base em se os juízes locais consideram que o pedestre deveria ter sido mais diligente ou se a falta de manutenção da prefeitura é a causa exclusiva.

  5. Resumir e explicar sentenças de grande repercussão

    • Seu prompt em linguagem natural: "Ouvi dizer que há uma sentença famosa do Supremo sobre os juros abusivos dos cartões revolving da Wizink. Busque-a, leia-a inteira e me explique em dois parágrafos simples o que o tribunal decidiu sobre a porcentagem de juros."
    • Como a IA processa nos bastidores: Localiza a sentença-chave (ex.: usando palavras-chave como "Wizink", "revolving", "usura"), baixa o PDF completo usando obtener_texto_resolucion, lê os fundamentos de direito e redige o resumo executivo.
    • Resposta que você recebe: Uma explicação simples, livre de tecnicismos complexos, sobre o limite a partir do qual o juro é considerado usurário e nulo.

Testes e Verificação

O projeto inclui scripts no diretório temporário ou de rascunho para testes rápidos de desenvolvimento:

  • Teste de Scraper Direto: test_scraper.py busca um termo e tenta baixar o primeiro PDF.
  • Teste de API REST e Integração SSE: test_api.py verifica o status, realiza uma consulta e executa o download do PDF através do servidor FastAPI em execução.
  • Teste de Cliente MCP Stdio: test_mcp_stdio_client.py inicia o servidor MCP em um subprocesso e realiza as chamadas JSON-RPC oficiais simulando um cliente real.

Aviso de Isenção de Responsabilidade e Termos de Uso

[!WARNING] LEIA ATENTAMENTE ANTES DE USAR A FERRAMENTA

Este software é um utilitário de automação de código aberto fornecido exclusivamente para fins educacionais, de pesquisa acadêmica e para consultas individuais de caráter privado.

1. Cumprimento das Normativas do CENDOJ e CGPJ

O site do portal do CENDOJ (Centro de Documentação Judicial do Conselho Geral do Poder Judiciário da Espanha) estabelece termos de acesso específicos. Ao usar este software, o usuário assume toda a responsabilidade de cumprir tais políticas:

  • Uso Particular: O acesso ao buscador do CENDOJ é restrito exclusivamente a consultas individuais e particulares de caráter não comercial.
  • Proibição de Download em Massa e Fins Comerciais: De acordo com as diretrizes do CGPJ, é terminantemente proibido o uso de ferramentas automáticas para extração em massa de jurisprudência (web scraping em massa) e a exploração comercial de sua base de dados. Se você precisar reutilizar os dados para fins comerciais ou em massa, deve solicitar uma licença formal de reutilização diretamente ao CENDOJ.
  • Frequência de Consultas: Recomenda-se fortemente usar esta ferramenta com moderação e pausas razoáveis para não sobrecarregar os servidores públicos do CENDOJ nem violar seus limites razoáveis de serviço.

2. Proteção de Dados Pessoais (RGPD / LOPDGDD)

As sentenças publicadas pelo CENDOJ foram previamente submetidas a um processo de anonimização/seudonimização. O Regulamento Geral de Proteção de Dados (RGPD) e a Lei Orgânica 3/2018 (LOPDGDD) proíbem estritamente o uso dessas informações para a reidentificação de pessoas físicas envolvidas nos procedimentos judiciais. O usuário final é o único responsável legal pelo tratamento que der aos textos extraídos por este software.

3. Isenção de Responsabilidade Legal

Os desenvolvedores e contribuidores deste projeto:

  • Não se responsabilizam pelo uso indevido, fraudulento ou ilegal que o usuário final possa fazer desta API ou servidor MCP.
  • Não assumem nenhuma responsabilidade diante de possíveis bloqueios de endereços IP, ações legais, advertências judiciais ou qualquer medida que o CGPJ pudesse adotar contra o usuário final como consequência do uso deste software.
  • Fornecem a ferramenta "tal qual" (as is), sem garantias de qualquer tipo quanto à sua continuidade, disponibilidade técnica ou exatidão dos resultados retornados se o site do CENDOJ modificar sua estrutura ou design.