first commit

docs/MCP_DIAGNOSTIC_FIX_V6.md

@@ -0,0 +1,129 @@
+# Correção V6 — Diagnóstico MCP e Judges
+
+## Problema observado
+
+No teste, o `agent_framework_oci` acionava o MCP Router, mas os resultados das tools vinham como:
+
+```text
+ok: False
+result: None
+error: ''
+metadata: {}
+cached: False
+```
+
+Isso impedia saber se a falha era URL, autenticação, payload, timeout, status HTTP, rede ou bug no adapter.
+
+Também apareceu:
+
+```text
+Judge calibrado declarado em judges.yaml, mas nenhum LLM foi fornecido ao pipeline.
+```
+
+## Correções aplicadas
+
+### 1. MCP server preserva erro real
+
+Arquivo alterado:
+
+```text
+mcp_servers/legacy_tim_mcp/main.py
+```
+
+Agora toda falha HTTP ou de rede retorna `metadata` com:
+
+- `server`
+- `tool`
+- `mock`
+- `prefix`
+- `method`
+- `url`
+- `status_code`, quando houver resposta HTTP
+- `response_content_type`
+- `response_body_preview`
+- `exception_type`
+- `timeout_seconds`
+- `request_payload_keys`
+- headers sanitizados, sem segredo
+
+Exemplo esperado:
+
+```json
+{
+  "ok": false,
+  "result": null,
+  "error": "TIM_COMPLETE_INVOICES falhou: status=400 body=...",
+  "metadata": {
+    "server": "legacy_tim",
+    "tool": "consultar_fatura",
+    "mock": false,
+    "method": "POST",
+    "url": "http://10.151.3.100:8000/customers/v1/completeInvoices",
+    "status_code": 400,
+    "exception_type": "HTTPStatusError",
+    "response_body_preview": "..."
+  }
+}
+```
+
+### 2. Judges recebem LLM do framework
+
+Arquivo alterado:
+
+```text
+app/workflows/agent_graph.py
+```
+
+Antes:
+
+```python
+self.judges = JudgePipeline()
+```
+
+Depois:
+
+```python
+self.judges = JudgePipeline(llm=llm, settings=settings)
+```
+
+Assim o `judges.yaml` usa o LLM criado pelo backend e o profile `judge` do `llm_profiles.yaml`.
+
+### 3. `.env` corrigido para uso com `source .env`
+
+Valores com espaço, como `Basic ...` e `Bearer ...`, foram colocados entre aspas.
+
+Exemplo:
+
+```env
+TIM_COMPLETE_INVOICES_AUTH="Basic ..."
+```
+
+## Como validar
+
+Suba o MCP:
+
+```bash
+./scripts/start_legacy_tim_mcp.sh
+```
+
+Teste direto:
+
+```bash
+./tests/curl_mcp_consultar_fatura.sh
+```
+
+Depois teste pelo backend:
+
+```bash
+./tests/curl_gateway_fatura.sh
+```
+
+No log, procure por:
+
+```text
+mcp_results
+metadata
+status_code
+response_body_preview
+mock: false
+```