# Requisitos: MCP v4 — Deep Agent Tools

## Descrição

Redesenhar as tools do MCP TecJustiça seguindo padrões de Deep Agents (Claude Code, LangChain) e best practices da comunidade MCP. As 4 tools genéricas com dispatch-by-params são substituídas por 10 tools focadas com responsabilidade única, seguindo o padrão filesystem: `ls`, `read`, `grep`, `glob`. Busca full-text via PostgreSQL FTS (tsvector + GIN index) substitui o `ilike` lento. O agente controla tamanho de resposta via `max_chars`/`offset`.

### Por que é necessária

1. **Tools genéricas confundem o agente** — `consultar_documentos` faz 4 coisas diferentes dependendo dos params
2. **Busca lenta** — `ilike` em 17k docs faz scan sequencial (2-5s). FTS com GIN index responde em 10-50ms
3. **Eviction por LLM é caro e imprevisível** — Cada read de doc grande gasta tokens de Gemini. No v4, o agente decide quanto ler
4. **Sem snippets de busca** — O agente não sabe ONDE o termo aparece. FTS retorna `ts_headline` com highlight
5. **Padrão da comunidade** — Philipp Schmid, Anthropic, LangChain, Tinybird todos recomendam tools focadas com paginação

### Referências de Design

- Philipp Schmid (HuggingFace): "MCP is a User Interface for AI agents, not a REST API wrapper"
- Anthropic Engineering: Code execution with MCP — agents scale better with focused tools
- LangChain Deep Agents: Padrão filesystem (ls, read, grep, glob)
- Claude Code: TodoWrite + grep/glob/read como tools core
- Tinybird: Paginação com metadados, descriptions como instruções

## Critérios de Aceitação

### Database

- [ ] Coluna `fts tsvector` GENERATED em `documents` com índice GIN
- [ ] Coluna `fts tsvector` GENERATED em `movimentacoes` com índice GIN
- [ ] RPC `buscar_documentos` com 3 modos (fulltext, regex, ilike) + snippets + relevância
- [ ] RPC `buscar_movimentacoes` com full-text + snippets
- [ ] RPC `stats_documentos` retorna contagens sem nenhum conteúdo
- [ ] RPC `localizar_no_documento` retorna posições + snippets de um termo em 1 documento
- [ ] `grep_documentos` modo fulltext responde em < 2s (usa índice GIN)
- [ ] RPCs respeitam segurança (SECURITY DEFINER + GRANT authenticated)

### Tools (12 no total)

- [ ] `listar_processos` — lista processos disponíveis e busca por parte
- [ ] `visao_geral_processo` — entrada consolidada (metadados + partes + stats + movs recentes)
- [ ] `ls_documentos` — lista docs SEM conteúdo, com paginação
- [ ] `ls_movimentacoes` — timeline com paginação
- [ ] `read_documento` — leitura parcial controlada via `max_chars` + `offset`
- [ ] `grep_documentos` — busca FTS/regex/ilike, retorna snippets com highlight
- [ ] `grep_movimentacoes` — busca FTS em movimentações
- [ ] `glob_documentos` — filtro por nome/tipo/sigilo (ILIKE)
- [ ] `localizar_no_documento` — mapeia posições de termo em 1 doc
- [ ] `stats_documentos` — contagens agregadas, zero texto
- [ ] `analisar` — mantida como está (LLM analysis)
- [ ] `whoami` — mantida como está

### Padrões

- [ ] Toda lista retorna `paginacao: {total, limit, offset, has_more}`
- [ ] Erros retornam `{erro: "...", dica: "..."}`, nunca exceções
- [ ] Descriptions incluem QUANDO USAR e QUANDO NÃO USAR
- [ ] Nenhuma tool (exceto `read_documento`) retorna campo `conteudo` completo
- [ ] `read_documento` nunca usa eviction LLM — agente controla tamanho
- [ ] Usage logging (fire-and-forget) em todas as tools novas
- [ ] Annotations `readOnlyHint: true`, `openWorldHint: false` em todas

### Prompts e Resources

- [ ] Prompts atualizados com nomes das novas tools
- [ ] Prompt `guia_ferramentas` reescrito com as 12 tools
- [ ] Resources `processo://` e `documento://` mantidos

### Cleanup

- [ ] Tools antigas (explorar_processo, consultar_documentos, consultar_movimentacoes) removidas
- [ ] Arquivos antigos movidos para `tools/_legacy/`
- [ ] `tools/__init__.py` atualizado com novos exports
- [ ] Versão do servidor atualizada para 4.0.0

## Dependências

- FastMCP >= 2.14.0 (já instalado)
- Supabase PostgreSQL com extensão `pg_trgm` (para busca fuzzy opcional)
- Supabase MCP tools para aplicar migrations
- RPC `buscar_processos_por_parte` (já existe)

## Features Relacionadas

- `specs/consolidar-tools-mcp-v2/` — refatoração anterior das tools (v3 atual)
- `specs/otimizar-mcp-contexto/` — otimização de contexto (parcialmente incorporada)
- `specs/filtros-inteligentes-documentos/` — filtros inteligentes (incorporado via glob_documentos)
