# 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.