first commit

docs/MCP_LEGACY_COMMAND_MIGRATION_V7.md

@@ -0,0 +1,104 @@
+# V7 — MCP legado TIM/FIRST com padrão Command + ApiGateway
+
+Esta versão corrige a camada MCP do `agent_contas_first` para ficar mais próxima do projeto original.
+
+## O que mudou
+
+A versão anterior ainda fazia chamadas HTTP muito genéricas. A V7 implementa no MCP Server local uma camada inspirada no legado:
+
+```text
+MCP Tool
+  -> LegacyTimCommand
+  -> EndpointConfig
+  -> HttpApiGateway
+  -> GatewayError rico
+  -> retorno MCP com error/metadata preservados
+```
+
+## Evidência esperada nos logs
+
+Em caso de erro real do backend TIM, o `mcp_results` deve aparecer assim:
+
+```json
+{
+  "tool_name": "consultar_fatura",
+  "server_name": "legacy_tim",
+  "ok": false,
+  "error": "TIM_COMPLETE_INVOICES falhou: status=400 body=...",
+  "metadata": {
+    "server": "legacy_tim",
+    "tool": "consultar_fatura",
+    "mock": false,
+    "endpoint": "TIM_COMPLETE_INVOICES",
+    "method": "POST",
+    "url": "http://10.151.3.100:8000/customers/v1/completeInvoices",
+    "status_code": 400,
+    "error_code": "HTTP_400",
+    "provider_service": "...",
+    "provider_error_code": "...",
+    "provider_error_message": "...",
+    "message_id": "...",
+    "kong_request_id": "...",
+    "latency_ms": 123,
+    "exception_type": "HTTPStatusError",
+    "response_body_preview": "..."
+  },
+  "cached": false
+}
+```
+
+Se ainda aparecer:
+
+```json
+{"ok": false, "error": "", "metadata": {}}
+```
+
+então provavelmente uma janela antiga do `legacy_tim_mcp` ainda está rodando ou o backend não foi reiniciado depois da troca do pacote.
+
+## Tools migradas para Commands
+
+| MCP Tool | Command V7 | Endpoint |
+|---|---|---|
+| `consultar_fatura` | `CompleteInvoicesCommand` | `TIM_COMPLETE_INVOICES` |
+| `consultar_pagamentos` | `ProfileBillCommand` | `TIM_PROFILE_BILL` |
+| `consultar_plano` | `ContractInformationCommand` | `TIM_CONTRATO` |
+| `listar_servicos` | `QueryVasCommand` | `TIM_QUERY_VAS` |
+| `recuperar_pdf_fatura` | `InvoiceRecoverCommand` | `TIM_BILL_PDF` |
+| `registrar_protocolo` | `ProtocolCommand` | `TIM_PROTOCOL` |
+| `abrir_contestacao` | `CustomerContestationCommand` | `TIM_CUSTOMER_CONTESTATION` |
+| `consultar_status_sr` | `ServiceRequestStatusCommand` | `TIM_SERVICE_REQUEST_STATUS` |
+| `cancelar_vas` | `CancelVasCommand` | `TIM_CANCEL_VAS` |
+| `bloquear_vas` | `BlockVasCommand` | `TIM_BLOCK_VAS` |
+| `enviar_sms` | `SmsCommand` | `TIM_SMS` |
+| `registrar_tracking` | `TrackingActivitiesCommand` | `TIM_TRACKING_ACTIVITIES` |
+
+## Como testar só o MCP
+
+```bash
+cd mcp_servers/legacy_tim_mcp
+set -a
+source .env
+set +a
+uvicorn main:app --host 0.0.0.0 --port 8100 --reload
+```
+
+Em outro terminal:
+
+```bash
+curl -s http://localhost:8100/health | jq
+
+curl -s -X POST http://localhost:8100/mcp/tools/call \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "tool_name":"consultar_fatura",
+    "arguments":{"msisdn":"11999999999","invoice_id":"3000131180"}
+  }' | jq
+```
+
+## Checklist de execução
+
+1. Pare qualquer processo antigo do MCP na porta `8100`.
+2. Suba o MCP V7.
+3. Reinicie o backend do agente.
+4. Rode o curl do gateway.
+5. Verifique se `mcp_results[].metadata.endpoint`, `status_code`, `url` e `response_body_preview` aparecem.