first_contas/docs/MCP_REAL_INTEGRATION_NOTES.md

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:

TIM_MCP_USE_MOCK=false

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

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

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