KLINGO-CLINICAL-SYSLIFE-GCHAT/docs/superpowers/specs/2026-08-11-klingo-tools-de-apoio-design.md

Design — Tools de apoio do Klingo (especialidade, profissional, convenio, unidade, preco)

Data: 2026-08-11 Status: Aprovado pelo usuário, aguardando plano de implementação.

Objetivo

Adicionar ao MCP Server nativo do Klingo (já existente, ver docs/superpowers/specs/2026-08-11-mcp-server-nativo-n8n-klingo-design.md) as tools de apoio necessárias para um agendamento completo e correto — mesmo raciocínio já aplicado ao SysLife nesta sessão: o agente precisa conseguir perguntar/confirmar especialidade, médico, convênio/plano e valor com o paciente usando dados reais e atuais da clínica, não dados memorizados no prompt (que ficam desatualizados assim que um médico muda, um convênio é descredenciado, ou um preço é reajustado).

Contexto verificado

Exploração do Swagger completo (gti-scheduling-mcp/docs/klingo-openapi.json, não usado integralmente até agora — o KlingoAdapter original só cobria /paciente/identificar, /agenda/horarios, /agenda/reservar) revelou 6 endpoints de apoio não usados:

Endpoint	Parâmetros	Retorna	Autenticação
GET /agenda/especialidades	cnes, id_plano, cbos, consultas (todos opcionais)	lista de {codigo, nome, cbos, subespecialidade[]}	X-APP-TOKEN ou Bearer
GET /profissionais	especialidade ou id_especialidade, cnes (todos opcionais)	lista de {id, tratamento, numero (CRM), uf, conselho, nome, subespecialidade, foto}	X-APP-TOKEN ou Bearer
GET /agenda/profissionais	id_procedimento (obrigatório), id_plano (obrigatório), cnes	mesma lista de profissionais	X-APP-TOKEN ou Bearer
GET /convenios	cnes (opcional)	lista de {id, nome, reg_ans, planos: [{id, nome, codigo}]}	X-APP-TOKEN ou Bearer
GET /convenio/{cnpj}	cnpj (path, obrigatório)	mesmo formato de /convenios	X-APP-TOKEN ou Bearer
GET /unidades	classe_unidade (opcional)	lista de {nome, cep, cnes, local}	X-APP-TOKEN ou Bearer
GET /precos	id_plano (obrigatório), id_medico, id_unidade, page (opcionais)	lista paginada de {id_item_tabela, valor}	X-APP-TOKEN ou Bearer
GET /preco	id_procedimento (obrigatório), id_plano (obrigatório), id_medico, id_unidade (opcionais)	{id_item_tabela, valor}	X-APP-TOKEN ou Bearer

Todos aceitam autenticação por X-APP-TOKEN (mesma credencial já criada, Klingo APP Token - clínica pendente) ou Bearer de sessão — ou seja, diferente do agendar (que precisa da sessão do paciente via /paciente/identificar), estas consultas não dependem de identificar ninguém primeiro.

Existem dois endpoints de profissionais. /agenda/profissionais exige id_procedimento, que não temos como resolver (ver lacuna abaixo). /profissionais filtra só por especialidade/unidade, sem essa dependência — é o escolhido para a tool profissional.

Existem dois endpoints de preço. /precos (plural, paginado, sem exigir id_procedimento) e /preco (singular, exige id_procedimento — mesma lacuna). Optamos por expor /preco mesmo assim, documentando claramente na descrição da tool que só funciona se o chamador já souber o idProcedimento por algum outro meio (ex.: informado manualmente por um atendente) — não inventamos uma forma de obtê-lo, mesmo espírito de consultar_horarios/SLOT_MAPPING_UNAVAILABLE já registrado.

Lacuna que continua sem solução: specialtyId/procedimento

Nenhuma das tools desta rodada resolve o código de procedimento (specialtyId no domínio genérico, procedimento/id_procedimento na API do Klingo) exigido por agendar() e usado opcionalmente por preco. O Swagger público não documenta nenhum endpoint GET de listagem de procedimentos — o único endpoint relacionado (PUT /agenda/procedimento) altera o procedimento de uma marcação já existente, não lista os disponíveis. Isso é a mesma classe de lacuna já registrada para consultarHorarios() (SLOT_MAPPING_UNAVAILABLE) — não é resolvida aqui, nem inventamos uma solução. Fica registrado como limitação conhecida, herdada do provider, não desta rodada de trabalho.

Escopo

5 tools novas, adicionadas ao servidor já existente MCP Server - Klingo (3eiFEnfOTLnutP78) — não cria um servidor novo:

• especialidade → GET /agenda/especialidades
• profissional → GET /profissionais
• convenio → GET /convenios
• unidade → GET /unidades
• preco → GET /preco

Total de workflows do Klingo passa de 3 (servidor + agendar + consultar_horarios) para 8.

Arquitetura

[MCP Server Trigger] ──Tools──┬── agendar              (já existe, 5ZEOqTOk4Xex6jUQ)
  ("MCP Server - Klingo")     ├── consultar_horarios   (já existe, 7ikOIk6mdoBwClC3)
  (3eiFEnfOTLnutP78)          ├── especialidade      ──▶ novo sub-workflow
                               ├── profissional       ──▶ novo sub-workflow
                               ├── convenio           ──▶ novo sub-workflow
                               ├── unidade            ──▶ novo sub-workflow
                               └── preco              ──▶ novo sub-workflow

Componentes: as 5 tools de apoio (mesmo esqueleto)

[Execute Workflow Trigger] → [Config Klingo] → [Montar query]* → [GET <endpoint>] → [Classificar resultado]

(*Montar query só existe nas tools com parâmetro de entrada — especialidade, convenio e unidade não recebem nenhum parâmetro obrigatório nesta implementação, então pulam direto pro GET, mesmo padrão usado no especialidade/convenio do SysLife.)

• Execute Workflow Trigger: parâmetros por tool —
  • especialidade: nenhum.
  • profissional: idEspecialidade (opcional — sem ele lista todos).
  • convenio: nenhum.
  • unidade: nenhum.
  • preco: idProcedimento (obrigatório), idPlano (obrigatório), idMedico/idUnidade (opcionais).
• Config Klingo (Set): baseUrl desta clínica (placeholder, mesmo já usado no agendar/consultar_horarios).
• Montar query (Code, quando aplicável): monta o corpo/query da requisição só com os campos documentados, sem inventar campo.
• GET <endpoint> (HTTP Request): authentication: genericCredentialType, genericAuthType: httpHeaderAuth (X-APP-TOKEN, credencial já existente), neverError: true + fullResponse: true.
• Classificar resultado (Code): 2xx → devolve o corpo cru como veio (sem reformatar — mesmo raciocínio do SysLife: sem exemplo de resposta real capturado pra validar contra, então não inventamos nenhum envelope). Fora de 2xx → mesma taxonomia genérica já usada no agendar/consultar_horarios do Klingo (AUTHENTICATION_ERROR 401/403, NOT_FOUND 404, VALIDATION_ERROR 400/422, KLINGO_API_ERROR demais).

Fora de escopo (adiado)

• Resolver o specialtyId/procedimento de verdade (ver lacuna acima) — seria necessário documentação adicional do Klingo não disponível agora.
• /agenda/profissionais (a variante que exige id_procedimento) e /convenio/{cnpj} (variante por CNPJ específico de /convenios) — redundantes com as tools já escolhidas para este escopo.
• /precos (plural, paginado) — optamos só por /preco (singular) nesta rodada; adicionar paginação de catálogo completo de preços fica pra quando houver necessidade real.
• Workflow de agente cliente para o Klingo — continua adiado (mesma decisão já tomada), sem clínica real nem canal definido.

Testes

Mesma disciplina já usada no restante do Klingo: sem clínica real disponível, validação estrutural apenas (n8n_validate_workflow), nenhuma chamada HTTP real nesta etapa.