# Ferramentas MCP - TecJustica (Referencia Rapida)

Catalogo das **15 ferramentas** do MCP Server TecJustica v4.

> Para documentacao detalhada com exemplos, parametros completos e cenarios de uso, veja o [Guia de Desenvolvimento de Agentes](./guia-desenvolvimento-agentes.md).

---

## Resumo

| # | Categoria | Tool | Descricao |
|---|-----------|------|-----------|
| 1 | Navegacao | `listar_processos` | Descobrir processos, buscar por parte |
| 2 | Navegacao | `visao_geral_processo` | Metadados + partes + stats + catalogo de docs com IDs + movs recentes |
| 3 | Navegacao | `ls_documentos` | Listar docs sem conteudo (metadados) |
| 4 | Navegacao | `ls_movimentacoes` | Timeline de movimentacoes |
| 5 | Navegacao | `read_documento` | Ler conteudo com controle de tamanho |
| 6 | Busca | `grep_documentos` | Full-text/regex/ilike no conteudo |
| 7 | Busca | `grep_movimentacoes` | Full-text em movimentacoes |
| 8 | Busca | `glob_documentos` | Filtrar por nome/tipo/sigilo |
| 9 | Busca | `localizar_no_documento` | Posicoes de um termo em 1 doc |
| 10 | Estatisticas | `stats_documentos` | Contagens agregadas, zero texto |
| 11 | Analise | `analisar` | Analise com LLM (map-reduce, modelo unico Gemini Flash) |
| 12 | Precedentes | `buscar_precedentes` | Busca no BNP (sumulas, RG, IRDR, etc.) |
| 13 | Utilidades | `calculadora` | Calculos matematicos e prazos processuais (CPC/CPP) |
| 14 | Utilidades | `data_hora_atual` | Data/hora atual com dia da semana |
| 15 | Identidade | `whoami` | Dados do usuario autenticado |

---

## Navegacao

### 1. `listar_processos`
```
busca?: str         # Nome da parte (omitir = listar todos)
limite: int = 20    # max 50
offset: int = 0
```
**Retorno:** `{total, limite, offset, has_more, resultados: [{numero_processo, classe_descricao, sigla_tribunal, data_ajuizamento, valor_causa, partes}]}`

### 2. `visao_geral_processo`
```
numero_processo: str   # Formato CNJ
```
**Retorno:** Metadados, partes, assuntos, stats_documentos, **documentos** (catalogo com IDs, ate 200), ultimas_movimentacoes (10).

O campo `documentos` retorna `[{id, nome, tipo_nome, data_juntada, tamanho_texto, fonte, confianca}]`. Use os IDs com `analisar(document_ids='id1,id2')` para analise cirurgica ou `read_documento(id)` para ler conteudo.

### 3. `ls_documentos`
```
numero_processo: str
limite: int = 30       # max 100
offset: int = 0
ordem: "recentes" | "antigos" = "recentes"
fonte?: str            # "api" ou "segmentation"
```
**Retorno:** Lista paginada de metadados (id, tipo_nome, nome, sequencia, data_juntada, tamanho_texto, source, confianca). Sem conteudo.

### 4. `ls_movimentacoes`
```
numero_processo: str
limite: int = 30       # max 100
offset: int = 0
ordem: "recentes" | "antigos" = "recentes"
fonte?: str            # "api" ou "segmentation"
```
**Retorno:** Lista paginada (id, data_hora, tipo_nome, descricao, magistrado_nome, fonte).

### 5. `read_documento`
```
document_id: str       # UUID
max_chars: int = 10000
offset: int = 0        # Posicao no texto
```
**Retorno:** Metadados + conteudo + leitura {offset, chars_retornados, tamanho_total, tem_mais, proximo_offset}.

---

## Busca

### 6. `grep_documentos`
```
padrao: str            # Termo de busca
modo: "fulltext" | "regex" | "ilike" = "fulltext"
numero_processo?: str
tipo_nome?: str        # Parcial, ex: "Sentenca"
fonte?: str            # "api" ou "segmentation"
limite: int = 20
offset: int = 0
```
**Retorno:** Lista paginada com snippet (>>>highlight<<<), relevancia, fonte, confianca.

### 7. `grep_movimentacoes`
```
padrao: str            # Termo (full-text)
numero_processo?: str
tipo_nome?: str
fonte?: str
limite: int = 30
offset: int = 0
```
**Retorno:** Lista paginada com snippet, data_hora, tipo_nome, fonte.

### 8. `glob_documentos`
```
numero_processo: str
padrao_nome?: str      # Case-insensitive, parcial
padrao_tipo?: str      # Case-insensitive, parcial
nivel_sigilo?: str     # Exato: "PUBLICO", "SEGREDO_DE_JUSTICA"
fonte?: str            # "api" ou "segmentation"
limite: int = 50       # max 100
offset: int = 0
```
**Retorno:** Documentos filtrados com metadados (sem conteudo).

### 9. `localizar_no_documento`
```
document_id: str       # UUID
termo: str             # Case-insensitive
contexto_chars: int = 100
max_ocorrencias: int = 30
```
**Retorno:** `{document_id, termo, fonte, confianca, total_ocorrencias, tamanho_documento, ocorrencias: [{posicao, snippet}]}`.

---

## Estatisticas

### 10. `stats_documentos`
```
numero_processo: str
fonte?: str            # "api" ou "segmentation"
```
**Retorno:** total_documentos, por_tipo, por_sigilo, por_fonte, tamanhos, periodo.

---

## Analise

### 11. `analisar`
```
numero_processo: str
pergunta: str = "Faca uma analise completa deste processo"
document_ids?: str     # UUIDs separados por virgula (obter via visao_geral_processo ou ls_documentos)
perspectiva?: str      # autor, reu, juiz, acusado, ministerio_publico, defensor, vitima, terceiro, assessor
```
**Modelo:** Gemini 2.5 Flash (unico). Processos grandes usam estrategia map-reduce automatica.

**Retorno:** `{sucesso, numero_processo, tipo_processo, modelo, estrategia, resposta}`.

---

## Precedentes

### 12. `buscar_precedentes`
```
busca: str             # Termo em linguagem natural
orgaos?: list[str]     # STF, STJ, TST, TJxx, TRFxx, TRTxx...
tipos?: list[str]      # SUM, SV, RG, RR, IRDR, IAC, CT, ADI, ADPF, OJE, OJSDI1, OJSDI2, OJSDI1T
pagina: int = 1
tamanho_pagina: int = 20  # max 100
```
**Retorno:** Lista paginada com tese, orgao, tipo, situacao, processos_paradigma, agregacoes.

---

## Utilidades

### 13. `calculadora`
```
modo: "expressao" | "prazo"
expressao?: str        # Expressao matematica (modo "expressao")
data_intimacao?: str   # Data ISO 8601 (modo "prazo")
dias?: int             # Dias do prazo (modo "prazo")
```
**Retorno:** Resultado do calculo ou data final do prazo processual (CPC/CPP).

### 14. `data_hora_atual`
```
timezone?: str         # Default: "America/Sao_Paulo"
```
**Retorno:** Data/hora atual com dia da semana.

---

## Identidade

### 15. `whoami`
```
(sem parametros)
```
**Retorno:** `{autenticado, user_id, email, role, scopes, client_id, token_emitido_em, token_expira_em}`.

---

## Padrao Deep Agent

```
listar_processos -> visao_geral_processo (com catalogo de docs + IDs) -> analisar(document_ids) ou grep/read -> analisar
```

## Formato CNJ

```
NNNNNNN-DD.AAAA.J.TR.OOOO
Exemplo: 1234567-89.2024.8.26.0100
```

## Modelo LLM

Modelo unico: **Gemini 2.5 Flash** (`google/gemini-2.5-flash`) via OpenRouter.
- Contexto: ~1M tokens (~3.2M chars)
- Processos grandes: map-reduce automatico (lotes de ~800K chars)
