Servidor MCP DataJud TJMA

Servidor MCP (Model Context Protocol) para integração com a API DataJud do CNJ, específico para o Tribunal de Justiça do Maranhão (TJMA).

Desenvolvido para facilitar o acesso automatizado aos dados processuais do TJMA, permitindo consultas, análises e predições baseadas em inteligência artificial para otimização da atividade judicial.

🎯 Características Principais

• ✅ Integração completa com a API DataJud do CNJ para TJMA

• 🔍 Consulta de processos por número único

• 📊 Busca avançada com múltiplos filtros

• 📋 Movimentações processuais detalhadas

• 📈 Estatísticas por comarca e período

• 🧠 Análise de produtividade judicial

• 🔮 Predições de tempo de julgamento

• 🚀 Deploy automatizado no Render.com

• 🔒 Segurança com autenticação via API Key

• ⚡ Performance otimizada com cache e retry automático

Related MCP server: Python Jira MCP Server

🛠️ Tecnologias Utilizadas

• Python 3.11+

• aiohttp - Cliente HTTP assíncrono

• MCP (Model Context Protocol) - Protocolo de comunicação

• FastAPI - Framework web moderno

• Pydantic - Validação de dados

• asyncio - Programação assíncrona

• Docker - Containerização

• Render.com - Plataforma de deploy

📋 Pré-requisitos

1. Python 3.11 ou superior

2. Chave de API DataJud (obtida no CNJ)

3. Conta no Render.com (para deploy)

4. Git para versionamento

🚀 Instalação Local

1. Clone o repositório

git clone https://github.com/seu-usuario/datajud-mcp-tjma.git
cd datajud-mcp-tjma

2. Crie um ambiente virtual

python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate  # Windows

3. Instale as dependências

pip install -r requirements.txt

4. Configure as variáveis de ambiente

cp .env.example .env
# Edite o arquivo .env com suas configurações

5. Execute o servidor

python datajud_mcp_server.py

☁️ Deploy no Render.com

Método 1: Deploy Automático (Recomendado)

1. Faça fork deste repositório

2. Conecte sua conta GitHub ao Render.com

3. Crie um novo Web Service:

   • Repository: Selecione seu fork

   • Environment: Python 3

   • Build Command: pip install -r requirements.txt

   • Start Command: python datajud_mcp_server.py

4. Configure as variáveis de ambiente:

   • DATAJUD_API_KEY: Sua chave da API DataJud

Método 2: Deploy via render.yaml

1. Suba o código para seu repositório

2. No Render.com, crie um serviço a partir do arquivo render.yaml

3. Configure a variável DATAJUD_API_KEY

🔧 Configuração da API DataJud

Obtendo a Chave de API

1. Acesse o Portal CNJ DataJud

2. Siga as instruções para obter acesso à API Pública

3. A chave será fornecida pelo Departamento de Pesquisas Judiciárias (DPJ)

Configuração no Servidor

# No arquivo .env
DATAJUD_API_KEY=sua_chave_aqui

# Ou como variável de ambiente no Render.com
DATAJUD_API_KEY=sua_chave_aqui

📖 Uso do Servidor MCP

Ferramentas Disponíveis

1. consultar_processo

Consulta dados detalhados de um processo específico.

{
  "name": "consultar_processo",
  "arguments": {
    "numero_processo": "0001234-56.2023.8.10.0001"
  }
}

2. buscar_processos

Busca processos com filtros avançados.

{
  "name": "buscar_processos",
  "arguments": {
    "query": "João da Silva",
    "classe_processual": "318",
    "instancia": "PRIMEIRO_GRAU",
    "data_inicio": "2023-01-01",
    "data_fim": "2023-12-31",
    "tamanho": 20
  }
}

3. obter_movimentacoes

Obtém movimentações de um processo.

{
  "name": "obter_movimentacoes",
  "arguments": {
    "numero_processo": "0001234-56.2023.8.10.0001",
    "data_inicio": "2023-06-01"
  }
}

4. estatisticas_comarca

Gera estatísticas por comarca.

{
  "name": "estatisticas_comarca",
  "arguments": {
    "comarca": "Tuntum",
    "periodo": "90d",
    "incluir_detalhes": true
  }
}

5. analise_produtividade

Análise de produtividade judicial.

{
  "name": "analise_produtividade",
  "arguments": {
    "periodo": "6m",
    "orgao_julgador": "1ª Vara Cível",
    "tipo_analise": "tramitacao"
  }
}

6. predicao_julgamento

Predição de tempo de julgamento.

{
  "name": "predicao_julgamento",
  "arguments": {
    "classe_processual": "318",
    "orgao_julgador": "1ª Vara Cível",
    "complexidade": "media",
    "incluir_historico": true
  }
}

🔍 Estrutura do Projeto

datajud-mcp-tjma/
├── datajud_mcp_server.py     # Servidor MCP principal
├── requirements.txt          # Dependências Python
├── Dockerfile               # Configuração Docker
├── render.yaml              # Configuração Render.com
├── .env.example            # Exemplo de variáveis de ambiente
├── README.md               # Documentação
├── tests/                  # Testes unitários
│   ├── test_server.py
│   └── test_api.py
└── docs/                   # Documentação adicional
    ├── api_reference.md
    └── deployment_guide.md

🧪 Testes

Executar testes localmente

python -m pytest tests/ -v

Testar conexão com a API

python -c "
import asyncio
from datajud_mcp_server import DataJudMCPServer
async def test():
    server = DataJudMCPServer()
    # Teste básico de conexão
    print('Servidor MCP iniciado com sucesso!')
asyncio.run(test())
"

📊 Monitoramento

Logs

O servidor gera logs detalhados para monitoramento:

• Requisições à API DataJud

• Erros e exceções

• Performance e timeouts

• Uso das ferramentas MCP

Métricas no Render.com

• CPU e memória utilizadas

• Número de requisições

• Tempo de resposta

• Uptime do serviço

🔒 Segurança

• ✅ Autenticação via API Key

• ✅ Rate limiting automático

• ✅ Timeout configurável

• ✅ Retry com backoff exponencial

• ✅ Logs sanitizados (sem dados sensíveis)

• ✅ HTTPS obrigatório em produção

🤝 Contribuição

Como contribuir

1. Fork o projeto

2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)

3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')

4. Push para a branch (git push origin feature/AmazingFeature)

5. Abra um Pull Request

Diretrizes

• Siga o padrão de código Python (PEP 8)

• Adicione testes para novas funcionalidades

• Atualize a documentação quando necessário

• Use mensagens de commit descritivas

📝 Changelog

v1.0.0 (2025-06-18)

• ✨ Implementação inicial do servidor MCP

• 🔧 Integração com API DataJud CNJ

• 📊 Ferramentas de consulta e análise

• 🚀 Configuração para deploy no Render.com

• 📖 Documentação completa

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🆘 Suporte

Problemas Comuns

Erro de autenticação API DataJud:

• Verifique se a DATAJUD_API_KEY está configurada corretamente

• Confirme se a chave não expirou no sistema CNJ

Timeout nas requisições:

• Aumente o valor de API_TIMEOUT nas variáveis de ambiente

• Verifique conectividade com a API DataJud

Deploy no Render.com falha:

• Verifique se todas as variáveis de ambiente estão configuradas

• Consulte os logs de build do Render.com

Contato

Para questões específicas sobre implementação judicial ou melhorias:

• Email: contato@exemplo.com

• Issues: GitHub Issues

🏛️ Contexto Judicial

Este servidor foi desenvolvido considerando as especificidades do Sistema de Justiça brasileiro e as necessidades do TJMA, oferecendo ferramentas de análise e predição que podem auxiliar na gestão e otimização da atividade judicial.

Casos de Uso:

• 📈 Análise de produtividade de varas e comarcas

• 🔮 Predição de tempo de tramitação processual

• 📊 Estatísticas para planejamento judicial

• 🤖 Automação de consultas processuais

• 📋 Relatórios gerenciais automatizados

Desenvolvido com 💙 para a Justiça Brasileira