# MCP Legacy TIM/FIRST — integração real

Esta versão troca o MCP puramente mockado por um adapter HTTP real baseado nos contratos encontrados no projeto original `agent_contas_first`.

## Modo de execução

Por padrão:

```env
TIM_MCP_USE_MOCK=false
```

Com isso, as tools chamam os backends externos configurados no `.env`. Para testes locais sem rede TIM, use:

```env
TIM_MCP_USE_MOCK=true
```

## Contratos implementados a partir do legado

| Tool MCP | Endpoint/env | Método | Contrato legado usado |
|---|---|---:|---|
| `consultar_fatura` | `TIM_COMPLETE_INVOICES_URL` | POST | `CompleteInvoicesCommand`: `{"msisdn": "..."}` |
| `consultar_pagamentos` | `TIM_PROFILE_BILL_URL` | POST | `QueryProfileBillCommand`: `{"msisdn": "..."}` |
| `consultar_plano` | `TIM_CONTRATO_URL/{msisdn}` | GET | `ContratoCommand` |
| `listar_servicos` | `TIM_QUERY_VAS_URL/{msisdn}` | GET | `QueryVasCommand` |
| `recuperar_pdf_fatura` | `TIM_BILL_PDF_URL?invoiceId=&msisdn=&customerId=` | GET | `InvoiceRecoverCommand` / `BillPdfCommand` |
| `explicar_fatura` | `TIM_INVOICE_EXPLANATION_URL/{msisdn}?channel=APP` | GET | `InvoiceExplanationCommand` |
| `registrar_protocolo` | `TIM_PROTOCOL_URL` | POST | `RegisterProtocolV2Command` |
| `abrir_contestacao` | `TIM_CUSTOMER_CONTESTATION_URL` | POST | `CustomerContestationCommand` |
| `consultar_status_sr` / `atualizar_status_sr` | `TIM_SERVICE_REQUEST_STATUS_URL` | POST | `UpdateServiceRequestStatusCommand` |
| `cancelar_vas` | `TIM_CANCEL_VAS_URL` | DELETE | `CancellationVasCommand` |
| `bloquear_vas` | `TIM_BLOCK_VAS_URL` | POST | `BlockVasCommand` |
| `enviar_sms` | `TIM_SMS_URL` | POST | `SendSmsCommand` |
| `registrar_tracking` | `TIM_TRACKING_ACTIVITIES_URL` | POST | `TrackingActivitiesCommand` |

## Observação importante

O projeto original não trazia secrets reais. O adapter usa os nomes de variáveis do legado e aliases compatíveis, mas os valores de autenticação precisam ser preenchidos no `.env` do ambiente.

## Validação rápida

```bash
./scripts/start_legacy_tim_mcp.sh
curl http://localhost:8100/health
curl -s -X POST http://localhost:8100/mcp/tools/call \
  -H 'Content-Type: application/json' \
  -d '{"tool_name":"consultar_fatura","arguments":{"msisdn":"11999999999"}}' | jq
```