Triagem de Propostas — AgDev

Skill Claude + servidor MCP Python para triagem determinística de crédito rural.

🌐 Servidor MCP Online (Pronto para Uso em Teste):
Um servidor MCP já está implantado e disponível na nuvem para avaliação imediata:

• Endpoint: https://mcp-triagem.anotae.app.br/mcp

• Transporte: Streamable HTTP (padrão recomendado pela Anthropic)

• Autenticação: Sem autenticação (None) (aberto temporariamente para facilitar a avaliação deste teste prático)

• Healthcheck no navegador: https://mcp-triagem.anotae.app.br/

Como Conectar no Claude Web (claude.ai)

A melhor prática para agentes no Claude Web é combinar uma Skill (Instrução/Guardrail) com um Conector (MCP Tool):

• O Conector (MCP Tool): Executa o código Python determinístico na nuvem.

• A Skill (Instrução): Atua como governança, garantindo que o Claude nunca alucine regras de negócio e acione obrigatoriamente a ferramenta triar_proposta.

Passo 1: Cadastrar o Conector MCP

1. Acesse claude.ai ➔ menu lateral Customize ➔ aba Connectors.

2. Clique no botão + Add ▾ ➔ Add custom connector.

3. Preencha:

   • Name: triagem-proposta (ou triagem-agdev)

   • URL: https://mcp-triagem.anotae.app.br/mcp

4. Ao avançar (ou em Continue anyway):

   • Transport: Streamable HTTP

   • Authentication: None (sem autenticação para testes)

5. Salve o conector.

Passo 2: Cadastrar a Skill de Orquestração

1. Na mesma tela de Customize, clique na aba Skills ➔ botão + Add ▾ ➔ Add skill.

2. Preencha o nome: triagem-proposta.

3. No conteúdo da instrução da Skill (SKILL.md), cole a diretriz:

   Você atua na triagem de propostas da AgDev. Quando o usuário fornecer dados de uma proposta (em JSON ou texto), acione obrigatoriamente a ferramenta triar_proposta. Não avalie as regras de negócio por conta própria. Aguarde o retorno da ferramenta e apresente ao usuário exatamente o resumo em Markdown gerado por ela, contendo título, parecer, motivos e pendências.

4. Salve e deixe a Skill ativada.

Passo 3: Utilização pelo Analista

Abra um novo chat (+ New) e envie a proposta (em JSON ou texto livre):

"Trie a proposta P-001: {"id": "P-001", "area_degradada_ha": 850, "area_matricula_ha": 1200, "area_car_ha": 1190, "alerta_desmatamento": null, "situacao_car": "Ativo", "situacao_cadastral": "Regular"}"

O Claude ativará a Skill, acionará a ferramenta remota e entregará o card Markdown com parecer determinístico.

Related MCP server: Cronhaus Inbox MCP Server

Pré-requisitos (Execução Local)

• Python 3.11+

• (opcional) uv — acelera a instalação

Instalação e execução (< 5 minutos)

# 1. Clone e entre no repositório
cd agdev

# 2. Crie o ambiente e instale (com extras de teste)
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS/Linux
# source .venv/bin/activate

pip install -e ".[dev]"

# 3. Rode os testes
pytest -q

# 4. Triagem rápida via CLI (exemplos do enunciado)
python -m triagem_proposta.cli examples/propostas.json --somente-parecer

Saída esperada:

P-001	SEGUE
P-002	RECUSADA
P-003	REVISÃO HUMANA
P-004	RECUSADA
P-005	REVISÃO HUMANA

Uma proposta isolada

python -m triagem_proposta.cli --json "{\"id\":\"P-001\",\"area_degradada_ha\":850,\"area_matricula_ha\":1200,\"area_car_ha\":1190,\"alerta_desmatamento\":null,\"situacao_car\":\"Ativo\",\"situacao_cadastral\":\"Regular\"}"

Configuração no Claude Desktop

1. Abra o arquivo de configuração

• Pelo próprio aplicativo: Abra o Claude Desktop, clique no menu superior esquerdo (ou ícone de engrenagem) ➔ Settings ➔ Developer ➔ clique no botão Edit Config.

• Ou pelo Explorador de Arquivos:

  • Windows: Pressione Win + R, digite %APPDATA%\Claude e abra o arquivo claude_desktop_config.json com o Bloco de Notas ou VS Code.

  • macOS: Abra ~/Library/Application Support/Claude/claude_desktop_config.json.

2. Cole a configuração

A) Conectando ao Servidor Online na Nuvem (Recomendado):

{
  "mcpServers": {
    "triagem-proposta": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-triagem.anotae.app.br/mcp"
      ]
    }
  }
}

B) Ou rodando o Python Local:

⚠️ Atenção no Windows (Barras no caminho): No formato JSON, use barras normais (/) ou barras duplas (\\).

{
  "mcpServers": {
    "triagem-proposta-local": {
      "command": "D:/agdev/.venv/Scripts/python.exe",
      "args": ["-m", "triagem_proposta.server"]
    }
  }
}

(No macOS/Linux, substitua o comando por /caminho/para/agdev/.venv/bin/python).

3. Reinicie o Claude Desktop

Feche completamente o aplicativo e abra-o novamente.

4. Validação Visual

No canto inferior direito da caixa de mensagem de um novo chat, verifique o ícone de ferramentas/martelo (🔨) com a tool triar_proposta.

Configuração no Claude Code (CLI)

No terminal:

# Conectando ao servidor em nuvem:
claude mcp add triagem-proposta -- npx -y mcp-remote https://mcp-triagem.anotae.app.br/mcp

# Ou conectando localmente:
claude mcp add triagem-proposta-local -- .venv/Scripts/python.exe -m triagem_proposta.server

Estrutura

src/triagem_proposta/
  models.py           # Parecer, Proposta, Motivo
  rules.py            # R1–R6 isoladas (sem I/O)
  engine.py           # Orquestração + resolução de conflitos
  markdown_report.py  # Card Markdown
  server.py           # Servidor MCP (FastMCP / stdio)
  cli.py              # CLI local
tests/                # Casos negativos e de borda
examples/             # JSON do enunciado

Regras (resumo)

Conflito: RECUSADA prevalece sobre REVISÃO HUMANA; todos os motivos são listados.

Execução via Docker (Contêiner)

Para rodar o servidor MCP encapsulado em contêiner com suporte a rede (Streamable HTTP na porta 8001/8000):

docker compose up -d --build

O endpoint MCP fica disponível em http://localhost:8001/mcp (e em produção via Cloudflare em https://mcp-triagem.anotae.app.br/mcp).
Um endpoint informativo de healthcheck responde em http://localhost:8001/.

Documentação

• SKILL.md — quando usar a skill

• DESIGN.md — revisão humana, dados reais, versionamento e adoção

• DEPLOY_ORACLE_CLOUD.md — guia completo de deploy em contêiner na Oracle Cloud (OCI)