knowledge-base/records/plugin-dev/KB-PLUGIN-019-mcprotocol-bff-architecture.md

KB-PLUGIN-019: Arquitetura BFF (Backend For Frontend) e Segurança via API no GLPI 11 (Plugin MCProtocol)

Domain: plugin-dev Tags: glpi, glpi11, mcp, api, rbac, security, bff

1. Segurança e Escopo de Dados (RBAC)

O uso obrigatório da API REST para listagens de dados (ao invés de consultas SQL diretas via global $DB) garante a aplicação das restrições de permissão nativas do GLPI.

• Risco do SQL Direto: Ignora regras de Entidades, Perfis, e Direitos do GLPI (getEntitiesRestrictCriteria()). Pode causar vazamento de dados sensíveis (ex: chamados confidenciais) em clientes MCP.
• Vantagem da API: O cliente MCP usa o próprio token OAuth vinculado à sessão de um usuário. O motor da API V2 obrigatoriamente aplica as restrições de Entidade e Perfil, e resolve relacionamentos (HATEOAS).

2. A Camada "Backend For Frontend" (BFF)

Ferramentas MCP genéricas (ex: glpi_get_items) forçam o LLM a "adivinhar" rotas exatas (/Assistance/Ticket), consumindo tokens extras e elevando o risco de alucinações.

• Solução (View Semântica): O plugin GLPI exporta ferramentas altamente especializadas (ex: glpi_ticket_search_by_status).
• Implementação: O LLM envia parâmetros simples (status: 4), enquanto o código PHP da ferramenta empacota isso na sintaxe estrita da API do GLPI (ex: ['searchText' => ['status' => 4]]), direcionando o request cURL internamente.

3. Roteamento e HTTP Loopback no cURL Interno

Para que o plugin consiga consumir a própria API REST do GLPI sem passar pelo proxy/firewall de borda, o request cURL interno do plugin exige tratamentos:

1. Host Correto: Deve usar o $CFG_GLPI['url_base'] (ex: 127.0.0.1 associado ao virtual host) em vez de domains externos que causariam gargalo de NAT.
2. Redirecionamento: CURLOPT_FOLLOWLOCATION => true deve estar ativo para prever ambientes onde Apache/Nginx force 301 de HTTP para HTTPS.
3. SSL Local: CURLOPT_SSL_VERIFYPEER => false é obrigatório para não falhar caso os certificados locais/SNI não correspondam à interface loopback.

4. O Sistema de Buscas do GLPI (V2 API)

Para realizar buscas exatas em colunas específicas (ex: "Apenas chamados com status X"), o parâmetro searchText genérico da API V2 tem limitações. Enviar searchText=status=4 gera uma busca texto genérica. A solução correta via código PHP é enviar o searchText em formato array ('searchText' => ['status' => 4]), o que induz o GLPI a procurar a correspondência exata.