first commit

docs/CORRECAO_PROTOCOL_ID_MCP_MAPPING.md

@@ -0,0 +1,81 @@
+# Correção: protocol_id ausente nas tools MCP
+
+## Problema
+
+O backend retornava mensagens como:
+
+```text
+[BackofficeAgent] Não foi possível consultar os dados do cliente. As ferramentas retornaram erro de protocolo ausente na requisição.
+```
+
+A causa principal era o arquivo `config/mcp_parameter_mapping.yaml` com o mapeamento invertido.
+
+O `MCPParameterMapper` do framework interpreta o mapa como:
+
+```yaml
+canonical_key: tool_argument_name
+```
+
+Mas o pacote estava usando:
+
+```yaml
+protocol_id: interaction_key
+```
+
+Como `protocol_id` não é uma chave canônica de `BusinessContext`, o mapper não enviava `protocol_id` para o MCP Server.
+
+## Correção
+
+O mapeamento foi corrigido para:
+
+```yaml
+interaction_key: protocol_id
+customer_key: customer_key
+contract_key: contract_key
+session_key: session_key
+```
+
+Também foram adicionadas fontes no `config/identity.yaml` para resolver `interaction_key` a partir de contratos legados do backoffice:
+
+- `protocol_id`
+- `protocolo`
+- `complaint_id`
+- `complaintProtocol`
+- `complaint.complaintProtocol`
+- `complaint.protocol`
+- `complaint.protocol_id`
+- `complaint.id`
+- `transactionId`
+- `transaction_id`
+- `ticket_id`
+
+Além disso, `app/agents/backoffice_agent.py` passou a enviar aliases defensivos (`protocol_id`, `interaction_key`, `customer_key`, `contract_key`, `session_key`) em `extra_args` para o `MCPToolRouter`, sem substituir o mapper do framework.
+
+## Resultado esperado
+
+Chamadas como:
+
+```json
+{
+  "channel": "web",
+  "payload": {
+    "message": "consultar cliente",
+    "protocol_id": "12345",
+    "customer_key": "11999999999"
+  }
+}
+```
+
+ou payloads legados como:
+
+```json
+{
+  "payload": {
+    "transactionId": "12345",
+    "complaint": {"complaintProtocol": "12345"},
+    "customer": {"msisdn": "11999999999"}
+  }
+}
+```
+
+agora alimentam `BusinessContext.interaction_key` e chegam nas tools MCP como `protocol_id`.