# Plano de Implementacao: Tool BNP - Banco Nacional de Precedentes

## Visao Geral

Criar modulo `tools/precedentes.py` com a tool `buscar_precedentes`, registra-la no MCP server e validar em producao. Segue o padrao exato de `tools/estatisticas.py`.

## Fase 1: Criar modulo da tool

Criar `tools/precedentes.py` com constantes, helper de limpeza HTML e tool `buscar_precedentes`.

### Tarefas

- [ ] Criar `tools/precedentes.py` com constantes BNP (URL, headers, orgaos, tipos) [complexo]
  - [ ] Definir `_BNP_BASE_URL`, `_BNP_HEADERS` (anti-WAF), `_BNP_TIMEOUT`
  - [ ] Definir `_TODOS_ORGAOS` (60 orgaos) e `_TODOS_TIPOS` (11 tipos)
  - [ ] Criar `_limpar_html(texto)` com regex para remover tags HTML
- [ ] Implementar `register_precedentes_tools(mcp)` com tool `buscar_precedentes` [complexo]
  - [ ] Docstring com QUANDO USAR / QUANDO NAO USAR
  - [ ] Parametros: `busca: str`, `orgaos: list[str] | None`, `tipos: list[str] | None`, `pagina: int = 1`, `tamanho_pagina: int = 20`
  - [ ] Montar payload `{"filtro": {...}}` com strings vazias nos opcionais
  - [ ] Chamada async httpx com `AsyncClient` context manager
  - [ ] Processar response: limpar HTML das teses, simplificar processos paradigma
  - [ ] Retornar `paginar_resultado()` + agregacoes (tipos e orgaos)
  - [ ] Logging e error handling padrao

### Detalhes Tecnicos

**Imports (sem `from __future__ import annotations`):**
```python
import logging
import re
import time
from typing import Any

import httpx
from fastmcp import FastMCP

from services.usage_logger import get_usage_logger, ms_since
from tools._helpers import _get_current_user, erro_instrutivo, paginar_resultado
```

**Headers anti-WAF (obrigatorios):**
```python
_BNP_HEADERS = {
    "Accept": "application/json, text/plain, */*",
    "Content-Type": "application/json",
    "Origin": "https://bnp.pdpj.jus.br",
    "Referer": "https://bnp.pdpj.jus.br/",
    "User-Agent": (
        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
        "AppleWebKit/537.36 (KHTML, like Gecko) "
        "Chrome/137.0.0.0 Safari/537.36"
    ),
}
```

**Payload obrigatorio (envelope `filtro`):**
```python
payload = {
    "filtro": {
        "buscaGeral": busca,
        "todasPalavras": "",
        "quaisquerPalavras": "",
        "semPalavras": "",
        "trechoExato": "",
        "atualizacaoDesde": "",
        "atualizacaoAte": "",
        "cancelados": False,
        "ordenacao": "Text",
        "nr": "",
        "pagina": pagina,
        "tamanhoPagina": tamanho_pagina,
        "orgaos": orgaos if orgaos is not None else _TODOS_ORGAOS,
        "tipos": tipos if tipos is not None else _TODOS_TIPOS,
    }
}
```

**Gotchas da API:**
- Sem envelope `{"filtro": ...}` = erro 500
- Campo chama-se `buscaGeral` (nao `busca`)
- Campos opcionais devem ser `""` (nao `null`)
- `tese` vem com HTML (`<p>`, `<br>`, `<mark>`) — limpar com regex
- Timeout 30s (API pode levar 2-5s em buscas amplas)
- `highlight` usa `<mark>` — nao incluir na resposta (ruido para o agent)

**Annotation `openWorldHint: True`** porque acessa API externa (BNP), diferente das tools internas (Supabase).

**Default `tamanho_pagina=20`** (nao 100) — precedentes tem textos longos; 20 e suficiente para o agent.

**Formato de cada resultado retornado:**
```python
{
    "id": "stj-sum-387",
    "orgao": "STJ",
    "tipo": "SUM",
    "nr": 387,
    "situacao": "Vigente",
    "tese": "E licita a cumulacao das indenizacoes de dano estetico e dano moral.",
    "ultima_atualizacao": "01/04/2025",
    "processos_paradigma": [{"nome": "REsp XXXXXXX/UF", "numero": "NNNNNNN-NN.NNNN.N.NN.NNNN"}],
    "missing": ["banco", "consignado"]
}
```

## Fase 2: Registrar no MCP server

Integrar o novo modulo no sistema de registro de tools.

### Tarefas

- [ ] Adicionar import e export em `tools/__init__.py`
- [ ] Adicionar `register_precedentes_tools(mcp)` em `server.py`

### Detalhes Tecnicos

**`tools/__init__.py`** — adicionar:
```python
from .precedentes import register_precedentes_tools
# __all__ += ["register_precedentes_tools"]
```

**`server.py`** — apos `register_user_tools(mcp)` (linha ~179):
```python
register_precedentes_tools(mcp)
```

## Fase 3: Lint e validacao

### Tarefas

- [ ] Rodar `uv run ruff check --fix . && uv run ruff format . && uv run mypy .`
- [ ] Corrigir eventuais erros de tipagem

### Detalhes Tecnicos

```bash
uv run ruff check --fix . && uv run ruff format . && uv run mypy .
```

## Fase 4: Teste em producao

Apos deploy (automatico via `git push origin master`), testar via curl.

### Tarefas

- [ ] Verificar `tools/list` retorna 13 tools (incluindo `buscar_precedentes`)
- [ ] Testar `buscar_precedentes` com busca simples ("dano moral")
- [ ] Testar com filtros (`orgaos=["STJ"]`, `tipos=["SUM"]`)

### Detalhes Tecnicos

```bash
TOKEN="tk_0bd3797d2b16d47471b4454418f7f8e378ac79635b8316e31eb47c910fe611dd"

# 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","version":"1.0"}}}' \
  | grep -i 'mcp-session-id' | tr -d '\r' | awk '{print $2}')

# Notification
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":{}}'

# tools/list (verificar 13 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/list","params":{}}'

# buscar_precedentes (busca simples)
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":3,"method":"tools/call","params":{"name":"buscar_precedentes","arguments":{"busca":"dano moral"}}}'

# buscar_precedentes (com filtros)
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":4,"method":"tools/call","params":{"name":"buscar_precedentes","arguments":{"busca":"dano moral banco consignado","orgaos":["STJ"],"tipos":["SUM"]}}}'
```
