# MCP Server: IA na Analise Processual Juridica

*Conectando modelos de linguagem diretamente a dados de processos judiciais brasileiros*

---

## O Problema

Se voce e advogado, conhece bem esta rotina: chega um novo processo com centenas de paginas de documentos. Voce precisa entender o caso, identificar os pedidos, mapear os riscos, e preparar uma estrategia. Isso significa horas — as vezes dias — lendo peticoes, decisoes, e movimentacoes.

**Os problemas sao claros:**

- **Due diligence manual** leva dias por processo
- **Analises superficiais** quando o tempo aperta
- **Inconsistencia** entre analises de diferentes advogados
- **Custos elevados** repassados ao cliente

E se existisse uma forma de ter um assistente que le todos os documentos, entende o contexto juridico brasileiro, e responde perguntas em linguagem natural?

---

## A Solucao: TecJustica MCP Server

O TecJustica e um **MCP Server** (Model Context Protocol) especializado em analise de processos judiciais brasileiros. Ele conecta modelos de linguagem como Claude diretamente aos seus dados processuais armazenados no Supabase.

**O que ele oferece:**

- **13 ferramentas especializadas** para direito brasileiro (padrao "deep agent")
- **Suporte a processos CIVEIS e CRIMINAIS** com deteccao automatica
- **6 prompts profissionais** guiados para analises complexas
- **Selecao inteligente de modelo** (Gemini Flash / Grok Fast) via OpenRouter
- **Autenticacao OAuth 2.1** via Supabase (SupabaseProvider DCR) + API Keys
- **Contexto de ate 1.8M tokens** para processos grandes
- **Busca de precedentes** no Banco Nacional de Precedentes (BNP/CNJ)

**Usuarios atendidos:** Advogados, juizes, assessores juridicos, promotores, defensores publicos.

---

## O que e MCP (Model Context Protocol)?

### O Padrao Aberto da Anthropic

O **Model Context Protocol (MCP)** e um padrao aberto criado pela Anthropic para permitir que modelos de linguagem acessem dados externos de forma estruturada e segura. Diferente de plugins ou APIs tradicionais, o MCP define um protocolo padronizado para:

- **Tools**: Funcoes que o LLM pode executar
- **Resources**: Dados que o LLM pode acessar diretamente
- **Prompts**: Templates guiados para tarefas complexas

### Por que MCP e Superior ao RAG para Direito?

| Aspecto | RAG Tradicional | MCP |
|---------|-----------------|-----|
| **Busca** | Semantica (pode trazer docs irrelevantes) | Estruturada (campos especificos) |
| **Contexto** | Chunks fragmentados | Documentos completos |
| **Acoes** | Apenas responde | Executa funcoes especificas |
| **Precisao** | Depende da qualidade dos embeddings | Dados diretos do banco |
| **Auditoria** | Dificil rastrear fontes | Logs completos de cada tool |

Com MCP, quando voce pergunta "qual o valor da causa?", o sistema nao busca em chunks de texto — ele executa uma funcao especifica que retorna exatamente esse dado do banco.

### Diagrama de Arquitetura

```
+----------------+     +-------------------+     +------------------+
|                |     |                   |     |                  |
|  Claude/LLM    +---->+   MCP Server      +---->+   Supabase       |
|  (Claude Web,  |     |   (FastMCP 4.0)   |     |   (PostgreSQL)   |
|   Claude Code) |     |                   |     |                  |
+----------------+     +--------+----------+     +------------------+
                                |
                                v
                       +--------+----------+
                       |                   |
                       |   OpenRouter      |
                       |   (LLM Gateway)   |
                       |                   |
                       +-------------------+
```

---

## Arquitetura Tecnica

### Stack

- **FastMCP 2.14+**: Framework Python para servidores MCP
- **Supabase**: PostgreSQL gerenciado com RLS e OAuth Server
- **OpenRouter**: Gateway multi-modelo (Gemini Flash, Grok Fast)
- **Railway**: Deploy automatico com SSL
- **Python 3.11+**: Tipagem moderna, async/await

### Autenticacao: SupabaseProvider + DualTokenVerifier

O TecJustica v4 usa o `SupabaseProvider` do FastMCP com DCR (Dynamic Client Registration):

```python
from fastmcp import FastMCP
from fastmcp.server.auth.providers.supabase import SupabaseProvider
from fastmcp.server.auth.providers.jwt import JWTVerifier

# Validacao JWT via JWKS (chaves publicas, ES256)
jwt_verifier = JWTVerifier(
    jwks_uri=f"{supabase_url}/auth/v1/.well-known/jwks.json",
    issuer=f"{supabase_url}/auth/v1",
    algorithm="ES256",
)

# DualTokenVerifier: aceita JWT Supabase OU API Keys (tk_...)
dual_verifier = DualTokenVerifier(jwt_verifier)

# SupabaseProvider: DCR automatico, sem client_id/secret manuais
auth = SupabaseProvider(
    project_url=supabase_url,
    base_url="https://mcp.tecjustica.com",
    token_verifier=dual_verifier,
)

mcp = FastMCP(name="TecJustica MCP Server", version="4.0.0", auth=auth)
```

**Pontos importantes:**
1. **ES256 via JWKS** — nao precisa de `SUPABASE_JWT_SECRET`
2. **DCR automatico** — clientes MCP se registram sozinhos
3. **API Keys** como alternativa para acesso programatico

---

## As 13 Ferramentas (Padrao Deep Agent)

O TecJustica segue o padrao **deep agent**: descobrir → navegar → buscar → analisar.

### Navegacao (5 tools)

| Tool | Descricao |
|------|-----------|
| `listar_processos()` | Descobrir processos, buscar por parte |
| `visao_geral_processo(cnj)` | Metadados + partes + stats + movs recentes |
| `ls_documentos(cnj)` | Listar documentos sem conteudo |
| `ls_movimentacoes(cnj)` | Timeline de movimentacoes |
| `read_documento(id)` | Ler conteudo controlado (com offset/max_chars) |

### Busca (4 tools)

| Tool | Descricao |
|------|-----------|
| `grep_documentos(padrao)` | Full-text search no conteudo |
| `grep_movimentacoes(padrao)` | Full-text em movimentacoes |
| `glob_documentos(cnj, padrao_tipo)` | Filtrar por nome/tipo |
| `localizar_no_documento(id, termo)` | Posicoes exatas em 1 doc |

### Analise (3 tools)

| Tool | Descricao |
|------|-----------|
| `stats_documentos(cnj)` | Contagens agregadas, zero texto |
| `analisar(cnj, pergunta)` | Analise com LLM (selecao automatica de modelo) |
| `buscar_precedentes(busca)` | Sumulas, temas repetitivos, IRDR (BNP/CNJ) |

### Utilidade (1 tool)

| Tool | Descricao |
|------|-----------|
| `whoami()` | Identidade do usuario autenticado |

### Fluxo Tipico

```
listar_processos → visao_geral → grep_documentos → localizar → read_documento → analisar
```

### Deteccao Civel vs Criminal

Todas as ferramentas de analise detectam automaticamente o tipo de processo e adaptam seus prompts:

| Civel (CPC) | Criminal (CPP) |
|-------------|----------------|
| Fases: Postulatoria > Saneadora > Instrutoria > Decisoria | Fases: Investigacao > Denuncia > Instrucao > Julgamento |
| Partes: Autor, Reu | Partes: Acusado, MP, Defensor |
| Pedidos: Tutelas, valores, merito | Pedidos: Tipificacao, penas, cautelares |

### Busca de Precedentes

A tool `buscar_precedentes` consulta a API publica do Banco Nacional de Precedentes (BNP/CNJ) para encontrar:

- Sumulas e sumulas vinculantes
- Temas de repercussao geral
- Recursos repetitivos
- IRDR, IAC, controversias trabalhistas
- Orientacoes jurisprudenciais

```python
resultado = await client.call_tool(
    "buscar_precedentes",
    {
        "busca": "dano moral consumidor",
        "orgaos": ["STJ", "STF"],
        "tipos": ["SUM", "RR"]
    }
)
```

---

## Os 6 Prompts Profissionais

Prompts guiados que orquestram multiplas ferramentas para analises complexas:

| Prompt | Uso |
|--------|-----|
| `analise_completa` | Analise sistematica em 4 fases |
| `parecer_tecnico` | Parecer juridico formal |
| `due_diligence` | Analise para acordo/M&A |
| `preparar_audiencia` | Briefing para audiencia |
| `estrategia_recursal` | Avaliar recursos |
| `guia_ferramentas` | Guia completo das 13 tools |

### Exemplo: Due Diligence

```
Voce: Use o prompt due_diligence para o processo 0001234-56.2023.5.02.0001

Claude:
Vou realizar due diligence processual em 4 etapas.

## ETAPA 1: EXPLORACAO
[Executa visao_geral_processo — metadados, partes, stats]

## ETAPA 2: COLETA
[Executa glob_documentos, grep_documentos, ls_movimentacoes]

## ETAPA 3: ANALISE
[Executa analisar com perguntas especificas]

## ETAPA 4: VALORACAO

### FICHA TECNICA
| Item | Valor |
|------|-------|
| Classe | Procedimento Comum Civel |
| Valor da Causa | R$ 150.000,00 |
| Fase Atual | Decisoria |

### ANALISE DE CONTINGENCIA
Classificacao de Risco: Provavel
Valor Provisionado Sugerido: R$ 95.000

### CENARIOS
| Cenario | Probabilidade | Impacto |
|---------|---------------|---------|
| Melhor | 10% | R$ 40.000 |
| Provavel | 70% | R$ 90.000 |
| Pior | 20% | R$ 150.000 |

### RECOMENDACAO
Aceitar acordo de R$ 80.000 — valor 15% abaixo do cenario provavel.
```

---

## Selecao Inteligente de Modelo

O TecJustica escolhe automaticamente o melhor modelo LLM baseado no tamanho do contexto:

| Modelo | Contexto Maximo | Uso |
|--------|-----------------|-----|
| Gemini 2.5 Flash | ~800K tokens (1M no modelo) | Default para a maioria dos casos |
| Grok 4.1 Fast | ~1.8M tokens (2M no modelo) | Processos muito grandes |
| Claude Haiku 4.5 | ~200K tokens | Disponivel via parametro explicito |

### Eviction Inteligente

Quando o conteudo excede 10k caracteres, o sistema usa Gemini Flash para criar um **resumo inteligente** em vez de truncar brutalmente. Isso preserva informacoes criticas que seriam perdidas com truncamento simples.

---

## Row-Level Security

Cada usuario so ve seus proprios processos gracas ao RLS do Supabase:

```sql
-- Politica de seguranca
CREATE POLICY "Users can only see their own processes"
ON processos
FOR SELECT
USING (user_id = auth.uid());
```

---

## Como Usar o TecJustica

### Via Claude Web (Recomendado)

1. Acesse **Settings > Connectors** no Claude.ai
2. Clique em **Add**
3. Cole a URL: `https://mcp.tecjustica.com/mcp`
4. O fluxo OAuth inicia automaticamente
5. Faca login com sua conta TecJustica
6. Pronto! Pergunte sobre seus processos.

### Via Claude Code (CLI)

Adicione ao `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "tecjustica": {
      "url": "https://mcp.tecjustica.com/mcp"
    }
  }
}
```

### Via API Key (curl)

```bash
TOKEN="tk_sua_api_key_aqui"

# Initialize
SID=$(curl -s -D- -X POST https://mcp.tecjustica.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test-cli","version":"1.0"}}}' \
  | grep -i 'mcp-session-id' | tr -d '\r' | awk '{print $2}')

# Notification initialized (obrigatorio)
curl -s -X POST https://mcp.tecjustica.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}'

# Chamar tools
curl -s -X POST https://mcp.tecjustica.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"listar_processos","arguments":{}}}'
```

---

## O Futuro: Augmented Lawyers, Not Replaced

O TecJustica nao substitui advogados — ele os potencializa.

A IA faz o que ela faz melhor:
- Ler milhares de paginas rapidamente
- Identificar padroes em dados
- Estruturar informacoes
- Manter consistencia

O advogado faz o que ele faz melhor:
- Tomar decisoes estrategicas
- Negociar acordos
- Construir relacoes com clientes
- Exercer julgamento etico

**O futuro da advocacia e aumentado, nao automatizado.**

---

## Referencias Tecnicas

- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) - Especificacao oficial
- [FastMCP](https://gofastmcp.com) - Framework Python para MCP
- [Supabase Auth](https://supabase.com/docs/guides/auth) - Autenticacao
- [OpenRouter](https://openrouter.ai) - Gateway multi-modelo
- [BNP - Banco Nacional de Precedentes](https://bnp.pdpj.jus.br/) - API de precedentes

---

*TecJustica MCP Server v4.0.0 — Transformando a pratica juridica com inteligencia artificial.*

**URL de Producao:** `https://mcp.tecjustica.com/mcp`
