first commit

docs/MCP_EXTERNAL_SERVICES_IMPLEMENTATION.md

@@ -0,0 +1,44 @@
+# Implementação MCP dos serviços externos
+
+Esta versão adiciona um MCP Server `legacy_tim_mcp` para adaptar os comandos externos do legado ao contrato do `agent_framework_oci`.
+
+## Contrato
+
+O framework chama:
+
+```text
+POST /mcp/tools/call
+```
+
+Payload:
+
+```json
+{"tool_name":"consultar_fatura","arguments":{"msisdn":"11999999999"}}
+```
+
+## Onde configurar
+
+- Backend: `config/mcp_servers.yaml`
+- Tools: `config/tools.yaml`
+- Mapeamento: `config/mcp_parameter_mapping.yaml`
+- MCP Server: `mcp_servers/legacy_tim_mcp/.env`
+
+## Serviços cobertos
+
+- Fatura completa / perfil de fatura
+- Pagamentos
+- Contrato/plano
+- VAS/SVA/listagem de serviços
+- PDF/segunda via
+- Protocolo
+- Contestação/SR
+- Status/atualização de SR
+- Cancelamento/bloqueio VAS
+- SMS
+- Tracking activities
+
+## Modo mock vs real
+
+`TIM_MCP_USE_MOCK=true` devolve respostas simuladas.
+
+`TIM_MCP_USE_MOCK=false` exige endpoints reais `TIM_*_URL`.