compass_backoffice/docs/CORRECAO_PROTOCOL_ID_MCP_MAPPING.md

Correção: protocol_id ausente nas tools MCP

Problema

O backend retornava mensagens como:

[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:

canonical_key: tool_argument_name

Mas o pacote estava usando:

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:

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:

{
  "channel": "web",
  "payload": {
    "message": "consultar cliente",
    "protocol_id": "12345",
    "customer_key": "11999999999"
  }
}

ou payloads legados como:

{
  "payload": {
    "transactionId": "12345",
    "complaint": {"complaintProtocol": "12345"},
    "customer": {"msisdn": "11999999999"}
  }
}

agora alimentam BusinessContext.interaction_key e chegam nas tools MCP como protocol_id.